How to create actions using Connector Builder

Actions define the tasks to be performed. You can create your own custom action for any particular service using the Connector Builder.
You can create custom actions using Connector Builder, by following the structure given below:

module.exports =
{
 label: "sample_action",
 description: "",
 input:
 {
   title: 'sample_action',
   type: 'object',
   properties: {}
 },
 output:
 {
   title: 'output',
   type: 'object',
   properties: {}
 },
 execute: function(input, output)
 {
   // your code here
 }
}

The action module has three main blocks:
1. input: This block includes the definition of action form input fields
2. output: This block includes the definition of the output keys your action will return
3. execute: This block includes the program logic required to execute the action

Let’s look at an example to understand more about these blocks.

Example

Let’s assume you want to create an action that can retrieve the details of any particular branch from your GitHub account. We will see how to create this action with Built.io Flow conventions.

label: Enter the display label for the action.
description: Enter a short description about the action

1. input

This block includes the definition of the input fields displayed in the action configuration window in Built.io Flow UI.

Convention for input JSON schema

input:
 {
   type: 'object',
   title: 'Sample Action',
   properties:
   {
     //input field definition
   }
},

Let us understand more about this JSON schema:

1. type (required): This key is used internally. The value for this key should always be set to 'object' and should not be changed.

2. title (required): Provide a title for the object.

3. properties: The ‘properties’ object is used to define the input fields of action configuration window. It contains the definitions for:
 

 3.1 Defining action input fields
  To define a action input field, you will need to create an object for the input field with following keys:
 
     - type (mandatory): The type of the input field. Supported input field types are: ‘String’, ‘Object’, ‘Array’, ‘Boolean’, ‘Any’
     - title (mandatory): The display name for the input field.
     - minLength (optional): Used to mark the input field as mandatory. The value for this field should always be set to ‘1’.
     - propertyOrder (optional): Used to specify the sequence of the input field in the action configuration window.
     - lookup (optional): Used to mark the input field as a lookup field. The lookup input field has two keys:
                       1. id: Enter the id of the lookup field. This id should be same as the lookup_id specified in 
                                 the lookup module.
                       2. dependencies: An array that defines the input field dependencies for the lookup field.  
        Know more about lookup here.

For our sample action, we need to define the following input fields, as per the conventions mentioned above:
  - User Name
  - Repo Name (mandatory lookup field)
  - Branch Name (mandatory lookup field)

2. output

This block lets you define the output parameters that will be returned by the action and can be used by the subsequent actions.

Convention for output JSON schema

output:
 {
   "sample_action":
   {
     type: 'object',
     properties: 
    {
     //output key definition  
    }      
   }
 },

Let us understand more about this JSON schema:

1. type (required): This key is used internally. The value for this key should always be set to 'object' and should not be changed.

2. properties (properties): The ‘properties’ object is used to define the output fields returned by your action, which can be used in the subsequent actions.

2.1 Defining action output parameters
To define a action output field, you will need to create an object for the output field with the following keys:
   - type:  The type of the output field. Supported input field types are: ‘String’, ‘Object’, ‘Array’, ‘Any’
   - title: Enter the name of the output field.
   - displayTitle: Enter the display title to be shown in the output of this action.

For our sample action we need following output fields:
   - ‘name’ (string)
   - ‘commit’ which is an object that contains ‘sha’ and ‘url’ keys

3. execute

This block lets you write the entire action logic that will be executed inside the Built.io Flow engine. The function defined in this block will have two function parameters: 'input' and 'output'.

Convention for execute block.

 execute: function(input, output)
 {
   // your code here
 }

1. input: This parameter will fetch and handle the input data provided by user in the action form.

2. output: This parameter will inform the Built.io Flow engine that the action execution is completed.

Request module: It helps you to make HTTP calls to third party applications. In order to do that, you need to provide values for following keys:

  - url: Provide the URL to which you wish to make HTTP request to fetch the branch details.

  - headers: Pass the required values to create a authorization/connection.

  - method: Specify the HTTP method to be used to make an API call.

Error handler: Specify error handler function 'function (err,response,body)' for your action. If the action throws an error, it should return 'output(err)', and if the action  is executed successfully, it should return 'output(body)'.

You can learn more about request module here.

The execution block for our sample action  is given below:

Once you have written the complete code for your action, you can proceed to create an authentication for your action using the ‘flow auth’ command. Click here to know how to create authentications using the Connector Builder.

Once you have deployed your custom app, you can start using the actions associated with the app by navigating to ‘Canvas > Actions Panel > Custom > {app_name}’