Cognigy Integration Framework


The Cognigy Integration Framework (formerly called Custom Nodes) is meant for situations where developers want to extend the systems capabilities, without losing the flexibility to have a graphical user interface for their logic.

Using the Integration Framework, developers can write modern Javascript-Code (executed on top of Node 10+) which can use modules from the NPM registry and seamlessly integrates with the Cognigy Flow Editor.

The necessary steps for implementing modules are:

Please feel free to have a look at our official Integration Framework repository on GitHub.

Creating your own Custom Modules


Limitations to uploading Custom Modules

Users can upload their own custom modules to Cognigy.AI from version 3.3.0 and up.
Older versions only allow uploading if you have your own hosted environment.

1 Create the Module Structure


Figure 1: Directory Structure

The structure of a module is similar to the one of a npm package.

Required Files:

  • package.json (contains module name, version, description, keywords, etc.)
  • package-lock.json
  • javascript (your actual code)
  • icon.png (used as the module icon)


File Requirements

  • The icon must be of type PNG with a size of 64x64 pixels
  • The filename of the file must be written in upper case

2 Define your Module

A module is defined by a package.json file, which should have at least the following properties:

  • name:
    This is the name of your package, which will also get displayed within the Cognigy Flow Editor. The name must be unique amongst all installed modules - similar to modules within the NPM registry.
  • version:
    The version of the package. Displayed on the overview page of the module. The version of the module should get increased as soon as the module was changed. Feel free to use SEMVER.
  • description:
    The description should contain meaningful information about the module itself and about its use-cases. It is limited to 200 characters and should not contain any implementation-specific information.
  • main:
    This is probably the most important field within the package.json that will get generated after the interactive question-answer process was finished: The entry-point defines the JavaScript file that exposes your Nodes. You can structure your custom-module in a completely free way, as long as all Nodes are in the end exposed from a single file - and the entry-point needs to point to this file.
  • keywords:
    A comma-separated list of important keywords you want to add to your module. We will use this in the future for filtering, searching and indexing. The keywords will get displayed within the details page of your module.
  • author:
    That should be quite self-explanatory! Put in your name and/or the name of your company. This helps if users of your module have issues and need support.


The following package.json defines an example module called Crypto:

    "name": "Crypto",
    "version": "1.0.0",
    "description": "Exposes crypto",
    "main": "src/module.js",
    "author": "Cognigy GmbH",
    "license": "MIT",
    "devDependencies": {

which is rendered to the following view in the COGNIGY.AI UI:


Figure 2: Module Information in COGNIGY.AI UI

3 Write the Module Nodes

The next step is to write the functionality of your module. A module can contain multiple nodes, which can be placed in the Flow Editor. The nodes of a module are ordinary JavaScript methods exported from your JavaScript file. Please ensure that your main field within the package.json points to your main JavaScript file within the module directory structure.


Figure 3: Module Nodes

Node Requirements

Your code needs to follow these rules in order to be picked up by our Node parser and work within the Cognigy Flow Editor:

  • the function has to be async
  • you have to export the function in order to access it in COGNIGY.AI
  • the function needs to have exactly two parameters
  • your function needs to return the first parameter given

This is an example of a function that follows these rules:

 * <Description>
async function test(input, args) {
    return input;

module.exports.test = test;

Node Rendering

The module node will be rendered in the COGNIGY.AI UI as a Flow Editor Node and therefore needs certain information:

  • a description - so users can understand what your node does
  • input fields - you can specify an input field type (e.g. dropdown or CognigyScript)

The description of the module node and how the input parameters should be gathered, is placed above the function declaration as a jsdoc-style comment. The comment should have the following format:

 * <Description>
 * @arg {CognigyScript} `key` input parameter - as args.key
 * @arg {CognigyScript} `anotherKey` another input paramter
 async function test(input, args)

Input Types

The following list shows all currently supported types you can utilize for your individual function parameters. The types need to be enclused within curly brackets (in our example: {CognigyScript}).

Type Description
JSON Takes a JSON object as an input
CognigyScript Valid CognigyScript can be entered within this field. Use whenever you want to allow dynamic content.
CognigyScriptArray The input field takes an array of CognigyScript statements. Use whenever you want to allow dynamic content.
String A simple string. Please note that you can not use CognigyScript here!
Number A simple number. Please note that you can not use CognigyScript here!
Boolean A simple boolean.
Select[Value1, ... , ValueN] A dropdown with predefined values as options.
FlowSelect A dropdown of all flows within the current project. Will be evaluated and replaced by the flowParentId of the flow.
FormSelect A dropdown of all processes within the current project. Will be evaluated and replaced by the id of the process.
StateSelect A dropdown of all states within the current flow. Will resolved to the name of the state.
SecretSelect A dropdown of all secrets within the current project. Will be replaced by the actual secret-object during runtime.

Node Parameters

All functions within the Integration Framework will receive exactly two arguments - the first one being the so called Input Object and the second one being an object that contains the custom parameters of your function (the arguments / parameters).

It is necessary to return the Input Object as a result of all of your functions!


Secret Parameter

If your module uses a Cognigy Secret, the node parameter has to be named secret.

4 Upload your Module

All the files, which belong to the module, have to be stored in a .zip file. Cognigy-provided modules are password-protected!

Open the Integration Framework section in COGNIGY.AI by clicking on your user profile icon in the upper right corner and then on the button for the Integration Framework (see Figure 4).


Figure 4: Integration Framework Menu Entry

On the left hand side you should find a list of all currently installed modules. Click on the Upload button (see Figure 5) to select and upload your new module. You can also drag-n-drop!


Figure 5: Custom Modules Upload Button

After uploading your module, you should see it in the list on the left hand side.

5 Use a Node from a Module

After successfully installing your module, you can add it's nodes to the Flow of your choice.

Switch to the Flow Editor and open the create menu. You should be able to see a new category called Modules which contains all currently installed modules (see Figure 6).


Figure 6: Custom Module Node Creation