Transformers

Description

The Endpoint Transformers can be used to hook into different events that happen when a user sends a message. This makes it possible to change the request payload from an Endpoint before being sent to the Flow, changing outputs from a Flow before they are sent to the user etc. Use-cases for the transformer include but are not limited to:

  • Creating an integration with a custom built endpoint
  • Transforming the output of one tab in the Say Node to work on another Endpoint
  • Handling Webhook events from custom services
  • Translate the messages from a user into the language of the Flow

The Transformers have full TypeScript support, meaning that the variables and NPM modules are typed, and it is possible to write custom interfaces in the Transformer. However, TypeScript knowledge is not required and plain JavaScript can be used as well.

Transformer Functions

The list below gives an overview of all the Transformer functions that are available. Each Transformer function has its own chapter that goes much more into detail.

Transformer Function

Description

handleInput

This Transformer function is executed when a user sends a message to an Endpoint, before the Flow is executed. The return value of the function will be sent to the Flow.

handleOutput

This Transformer function is executed on each output from the Flow. For Webhook and Socket based Endpoints, the return value will be sent to the user. Read more here.

handleExecutionFinished

This Transformer function is executed when the Flow execution has finished. For REST based Endpoints, the return value will be sent to the user. Read more here.

handleNotify

This Transformer function is executed when the Endpoint Notify API is used. The return value of the function will be sent directly to the user as a notification.

handleInject

This Transformer function is executed when the Endpoint Inject API is used. The return value of the function will be sent to the Flow.

Creating a Transformer

Transformer Functions in an EndpointTransformer Functions in an Endpoint

Transformer Functions in an Endpoint

To create a Transformer for an Endpoint, open the Transformer Functions tab in the Endpoint. Here are the different Transformer Settings that can be configured, as well as the Transformer code editor.

๐Ÿšง

Enabling Transformer Functions

Every Transformer function is disabled per default and has to be enabled separately in the Transformer Settings section.

The Transformer code editor has a default value for new Endpoints, which explains in brief how each Transformer function should be used. As soon as a specific Transformer has been enabled, the code in the corresponding Transformer function will be executed.

Transformer Code EditorTransformer Code Editor

Transformer Code Editor

For Endpoints created prior to the 3.5.0 release, the Transformer code editor will be empty.

๐Ÿšง

Transformers in existing Endpoints

Endpoints that were created prior to the 3.5.0 release do not have any default Transformer stored, and the code window is therefore empty. If you want to add a Transformer to a pre-existing Endpoint, it is advised to create a temporary new Endpoint of the same type and copy the defined Transformer function over to the other Endpoint.


## Transformer Settings
Transformer SettingsTransformer Settings

Transformer Settings

In order to use a specific Transformer function, it has to be enabled in the Transformer Settings section. There is a toggle to enable each individual Transformer function. Transformer functions can thereby also be temporarily disabled without having to delete the code.

Error handling in Transformers

The default error handling for Transformers is to log the error on the logs page and then continue with the normal execution. This means that if something fails in the Transformer function, the message will still be processed as if the Transformer function wouldn't exist.

If the Transformer is a vital part of the pipeline, for instance when building a custom Endpoint integration, then it might not make sense to execute the underlying Endpoint in case of an error. There is a setting called Abort On Error, which can be turned on to stop the execution fully after the Transformer has thrown an error.

๐Ÿšง

Line Number in Error Logs

When an error is thrown in a Transformer during execution, the line number where the error occurred will be listed in the log. The line number can be a bit incorrect, since it does not take lines occupied by interfaces and comments into account.

Also note that if the error is caused by a return value validation error, no line number will be shown.

Stopping Transformer Execution

Every Transformer function expects a certain return value, which it will then use in different ways depending on the specific Transformer function. In some cases, it might be desired to stop the execution completely, e.g. if the output from the Flow was already forwarded to another platform. In order to achieve this, the Transformer function can return a falsy value, e.g. null or void.

Available Modules

NPM Modules

The following NPM modules are available in the Transformer:

NPM Modules

uuid

crypto

_ (Lodash)

moment

xmljs

Logging

It is possible to use the exposed modules console.log, console.info and console.error in the Transformers. This will make the log appear on the Project Logs page as a debug log, info log and error log respectively.

Sending HTTP Requests

It is possible to send HTTP requests to external services from within a Transformer. All Transformer functions can access the httpRequest module for this purpose. The module is invoked as a function which takes a single configuration object as arguments. This object has the same format as the options object for the NPM module Request. Example:

handleInput: async () => {
  const result = await httpRequest({
    uri: "some-uri",
    method: "POST",
    body: {},
    json: true
  });
  
  console.log(result);
  return result;
}

๐Ÿšง

Limitations for the httpRequest module

It is per default only possible to send one HTTP request per Transformer execution, and it is per default not possible to send HTTP requests to other Endpoints.

Session Storage

The Session Storage is a storage object available to all Transformer functions and which will be available throughout the session. This can be used to store variables that have to be used later, in other Transformer functions, or to store conversation state. There is a function called getSessionStorage exposed to the Transformer functions, which takes the userId and sessionId as arguments. It will return a Promise, which resolves with the sessionStorage object, which can be manipulated as a normal object. Example:

const handleOutput: async ({ userId, sessionId }) => {
    const sessionStorage = await getSessionStorage(userId, sessionId);

    sessionStorage.test = "test";
}

Different Base Transformer Types

There are three different types of Transformers, and each Endpoint will implement one of them. Each Transformer type will have a slightly different way of handling the specific Transformer Functions.

The sections below give a quick overview of the different Transformer types. How every Transformer function works differently for every Transformer type is explained in the sub chapters for the individual Transformer functions.

REST Transformer

The REST Transformer is implemented for all Endpoints that are REST based, which means that they receive one message from the user and send one reply back. For these Endpoints, it is possible to have more Say Nodes in the Flow, but all outputs will be concatenated into one output which will then be sent to the user.

The REST based endpoints are:

REST Endpoints

Alexa

Google Actions

Dialogflow

Twilio

Twilio SMS

Twilio Autopilot

Microsoft Teams

Userlike

AudioCodes

REST

Webhook Transformer

The Webhook Transformer is implemted for all Endpoints that are webhook based, which means that they receive one message from the user, but can reply to the user multiple times via a webhook URL.

The Webhook based Transformers are:

Webhook Endpoints

Facebook Messenger

Slack

Microsoft Bot Framework

Sunshine Conversations

LINE

RingCentral Engage

Intercom

Webhook

Socket Transformer

The Socket Transformer is implemented for all Endpoints that use sockets to communicate. These Endpoints are:

Socket Endpoints

Webchat

Webchat [LEGACY]

Socket

Creating a Custom Endpoint

To create an integration with a custom channel, the first step is to figure out which type of Endpoint this custom channel is. When it is known whether the custom integration uses a REST based API, a Webhook API or is socket based, then the corresponding Endpoint can be created in Cognigy.AI.

There is an example of a custom built integration in the Example repository (see below).

Example Repository

Please find example implementations for various transformers in our new GitHub repository:

https://github.com/Cognigy/TransformersSamples


Did this page help you?