Extensions Best Practices

In order to guarantee a uniform user experience, we have set up a number of best practices for Extensions

1. Advanced Simplicity

In order to display only the required fields in Cognigy.AI, we use the principle of advanced simplicity. All optional fields should be outsourced to "sections". 

1.1 Storage Options

In most cases, an extension returns some kind of value -- e.g. an HTTP Request result. Now one needs to decide if the information should be stored in the context of the whole conversation or just in the input object of the next message. Therefore, please add the following code snippet to the fields in your extension's code:

Fields:

{
	key: "storeLocation",
	type: "select",
	label: "Where to store the result",
	params: {
		options: [
			{
				label: "Input",
				value: "input"
			},
			{
				label: "Context",
				value: "context"
			}
		],
		required: true
	},
	defaultValue: "input"
},
{
	key: "inputKey",
	type: "cognigyText",
	label: "Input Key to store Result",
	defaultValue: "httprequest",
	condition: {
		key: "storeLocation",
		value: "input"
	}
},
{
	key: "contextKey",
	type: "cognigyText",
	label: "Context Key to store Result",
	defaultValue: "httprequest",
	condition: {
		key: "storeLocation",
		value: "context"
	}
}

Section:

 {
	key: "storageOption",
	label: "Storage Option",
	defaultCollapsed: true,
	fields: [
		"storeLocation",
		"inputKey",
		"contextKey"
	]
}

Form:

 form: [
	{ type: "section", key: "storageOption" },
	],

With this choice, one can include the following code to handle the user's decision:

if (storeLocation === "context") {
	api.addToContext(contextKey, resultObject, "simple");
} else {
	// @ts-ignore
	api.addToInput(inputKey, resultObject);
}

1.2 Dependent Fields

In case some fields are only relevant depending on other field configurations, you can improve the user experience of your Node by only displaying the "necessary" fields.

Note: "nesting" conditions with { and: [ ] } and { or: [ ] } is only available from Cognigy.AI v4.1.4 on.

{
	key: "method",
	type: "select",
	label: "Request Method",
	params: {
		options: [
			{ label: "Get", value: "get" },
			{ label: "Post", value: "post" },
			{ label: "Put", value: "put" },
			{ label: "Patch", value: "patch" },
		],
		required: true,
	},
	defaultValue: "get",
},
{
	key: "bodyType",
	type: "select",
	label: "Request Body Type",
	params: {
		options: [
			{ label: "None", value: "none" },
			{ label: "Plain Text", value: "text" },
			{ label: "JSON", value: "json" },
		],
		required: true,
	},
	defaultValue: "none",
	condition: {
		key: "method",
		value: ["post", "put", "patch"],
	},
},
{
	key: "bodyText",
	type: "cognigyText",
	label: "Request Body (Text)",
	params: {
		multiline: true,
	},
	defaultValue: "",
	condition: {
		and: [
			{
				key: "method",
				value: ["post", "put", "patch"],
			},
			{
				key: "bodyType",
				value: "text",
			},
		],
	},
},
{
	key: "bodyJSON",
	type: "json",
	label: "Request Body (JSON)",
	defaultValue: "",
	condition: {
		and: [
			{
				key: "method",
				value: ["post", "put", "patch"],
			},
			{
				key: "bodyType",
				value: "json",
			},
		],
	},
},
{
	key: "bodyCompression",
	type: "checkbox",
	label: "Apply Compression to Request Payload",
	defaultValue: false,
	condition: {
		and: [
			{
				key: "method",
				value: ["post", "put", "patch"],
			},
			{
				or: [
					{
						and: [
							{
								key: "bodyType",
								value: "text",
							},
							{
								key: "bodyText",
								value: "",
                                                                negate: true
							},
						],
					},
					{
						and: [
							{
								key: "bodyType",
								value: "json",
							},
							{
								key: "bodyJSON",
								value: "",
                                                                negate: true
							},
						],
					},
				],
			},
		],
	},
}

1.3 Child Nodes

Child Nodes are generally recommended to use, as they allow the Extension users to see potential outcomes and adjust the Flow accordingly:

The Child Nodes need to be specific for each Node, this should also be reflected in potential naming conventions.

2 Modular Code

Your Extension should contain as little external logic as possible.

2.1 Outsource Helper Functions

If possible, the function of the extension should only focus on the use of the Cognigy API for configuration. All other steps should be outsourced to auxiliary functions. Accordingly, you would create your own function for an HTTP request.

2.2 Lean Nodes

Multiple Nodes that do specific tasks are more flexible to use in Flows than a single all-in-one Node. It also makes them easier to search when adding Nodes to a Flow. If one of your Nodes is becoming huge, consider splitting it up.

2.3 Credentials / Connections

Whenever your extension requires credentials for authentication a Connection should be used. This will allow the Extension users to adjust the credentials if necessary. By excluding the credentials from the code, your Extension developers won't have access to the production systems.

Fields:

{
	key: "connection",
	label: "API Key",
	type: "connection",
	params: {
		connectionType: "api-key",
		required: true
	}
},

Form:

Connections should be placed at the top, as they are essential to the Node's functionality.

form: [
	{ type: "field", key: "connection" },
]