Catalyst Integration Functions

Introduction

Catalyst Integration Functions allow you to code the business logic of other Zoho or Catalyst services, and use them as a backend to establish an integration between the two . When a particular feature is accessed in the associated service, it will automatically invoke the execution of the Integration function coded in Catalyst through a HTTP call. You can code the business logic of the backend feature of the service in the following platforms supported by Catalyst:

• Java
• Node.js
• Python

The business logic you build with Catalyst functions for your ConvoKraft bots is called bot logic, and it is of the Integration function type. You can initialize a Catalyst Integration Function from the CLI, work on it in your local environment, serve to test it, or deploy it to the remote console. The function can then be associated with the bot you create.

While using Catalyst Integration functions, you will also be able to avail of other Catalyst features that allows you to view the logs or reports of the function executions through Catalyst Logs or Application Performance Monitoring.

You can learn more about Catalyst Integration functions in detail from this page.

ConvoKraft Integration

ConvoKraft Integration functions enables you to code the business logic of your ConvoKraft bots and bundles it through the following ConvoKraft handlers :

1. Welcome Message Handler: Enables you to configure the response to be displayed on opening a fresh chat session.

2. Fallback Handler: Enables you to configure the response to be displayed when the bot fails to understand user’s inputs.

3. Failure Handler: Enables you to configure the response to be displayed when an exception occurs in the user’s message in the conversation.

Function Structure

When you create an Integration Function, Catalyst provides a boilerplate template code upon which you could build your business logic. You can use the respective templates to build your business logic in Java, Node.js and Python programming environments. To learn more about the complete function directory structure for all supported stacks in Catalyst, please refer to this page.

We will be discussing more about how to create an integration function in Catalyst later in this page.

Java

The Java file structure contains the main java file, the ExecuteHandler file which holds the core business logic of action executions, and also the other handler and configuration files.

The above mentioned files and boilerplate template code will automatically be available in your functions directory, when you initialize a Java Integration Function of type ConvoKraft, from the CLI. To learn more about initializing a Catalyst function from CLI, refer here.

Once initialization is done, you can proceed to code your bot logic, test them locally and then deploy the Catalyst function.

Node.js

The Node file structure contains a main function file along with the handler files, the node modules and the configuration files.

The above mentioned files and boilerplate template code will automatically be available in your functions directory, when you initialize a Node.js Integration Function of type ConvoKraft, from the CLI or the console. You can create a ConvoKraft integration function from the Catalyst console by following the steps mentioned here.

To learn more about initializing a Catalyst function from CLI, refer here.

Once initialization is done, you can proceed to code your bot logic, test them locally and then deploy the Catalyst function.

Python

Similar to Java and Node.js, the Python file structure contains a main function files, handler function files, the configuration files and additionally the python module files.

The requirements.txt file contains the list of installed dependencies that are needed to implement the Catalyst Python function. You can learn more about the usage of requirements.txt file from this page.

Similar to Java functions, you can initialize a python function from the Catalyst CLI. Once you initialize a Python Integration Function of type ConvoKraft, the above mentioned files and boilerplate template code will automatically be available in the corresponding functions directory in your local environment.

Once initialization is done, you can proceed to code your bot logic, test them locally and then deploy the Catalyst function.

Request format

ConvoKraft sends the request in the following format to the Catalyst Integration function :

    

        
copy
        

            

        
    
    

         {
    "todo": "prompt || execute || fallback || button",
    "bot" : "",
    "action" : "",
    "button_id" : "",
    "environment" : "development || production"
    "params":{
    },
    "userInput" : "",
    "previousParam" : "",
    "user" : {},
    "org" : {},
    "broadcast" : {},
    "cache" : {},
    "sessionData" : {}
    "clientData" : {} 
}

    

Response format

ConvoKraft expects the response to be in the following format from the Catalyst Integration function, so that it understands and conveys the intended response to the user.

Case 1: When an input param has to be prompted to the user

    

        
copy
        

            

        
    
    

         {
"status" : "prompt",
    "prompt" : {
        "param_name" : "leave_type",
        "options":[  
                    { "id" : "111" ,"label" : "", "image" : "image_url"},
                    {"id" : "112" ,"label" :"" ,"image" : "image_url"}
        ],
"buttons" : []
    },
    "message" : "You don't have enough casual leaves. Please choose some other leave type.",
    "data" : {}  
}

    

Case 2: When an output message has to be displayed to the user

    

        
copy
        

            

        
    
    

         {
    "status" : "execution",
    "message":"Please check your screen.",
    "card":[],
    "data":{},
    "broadcast":{},
    "trigger":{},
    "followup" : {}    
}

    

There are a few restrictions to be considered with the responses received from the Catalyst Integration function, such as :

• The maximum size of the response is 3 MB.
• The maximum duration of request timeout is 15 seconds.

If the response doesn’t comply with the above guidelines, a failure message will be sent as a response to the user.

Implementation

You can create a Catalyst Integration function either from the Catalyst console or CLI. Please make sure to follow the steps given below to create an Integration Function from the console. You can refer to this page, for the steps to create a function from the CLI.

1. To create a Catalyst Integration function directly from the Catalyst console, navigate to the Serverless icon in the left pane of the Catalyst console and click Create Function.

2. Provide a meaningful function name and choose Integration as the Function Type and select ConvoKraft as the Zoho Service. You can choose to code your logic in either Java, Node.js or Python programming environments. Click Create to create a new Catalyst Integration Function.

3. You can switch over to the Code tab to start writing your bot’s business logic.

After you code the business logic, click Save.

Once you have developed the business logic of your ConvoKraft bot, you can map the appropriate Catalyst Integration Function as the development platform while creating a bot or even later from the Bots details page. The associated Integration function will be executed on invocation of the configured actions in the bot.