Custom Action

While Built.io Flow provides 1000+ actions for your integrations, you can also create your own custom action.

Built.io Flow provides an action builder that lets you insert custom code and create an action that looks and works exactly the way other actions do.

All your custom actions are saved under ‘Custom’ tab in 'Actions' panel. To create a new custom action, click on '+' link given under ‘Custom tab'.

When you click on it, an action builder dialog opens up. This dialogue is divided in 2 sections. In the right hand side section, you can see the console in which you need to write code for the action. The code should be in Node.js and in a format that Built.io Flow understands. We have already added a basic code structure in the console, for your reference.

When you compile this code, you can see its output as a 'Form' in the left hand side section of the dialogue box.

Let’s have a look at the elements that form the code for custom action. You can find the complete sample code here.

Getting started


Step 1: On the right hand side of the canvas, you can see the 'Custom' tab under the 'Actions' panel. Click on the tab and then click the '+' link located under it, to start building your custom action.

1.png


Step 2: In the window that appears, enter the required details in as given below:

Icon (Optional): Click on the ‘Change Icon’ button to upload an image to be used as the icon for the custom action. The image file format should be either .jpeg or .png and should be upto 5MB.  

Label (Mandatory): Provide a suitable name for your action.

Console (Mandatory): Write code for the action that you wish to build, by using the code structure present in the console and conventions mentioned in the latter part of this section.

1.jpg

Step 3: When you are done writing the code, click 'COMPILE' to compile the code. If there are any errors in the code, they will be highlighted in the console.

Step 4: Once all the errors are fixed and the code is successfully compiled, you will see a form-like action with all the required fields, on the left hand side section of the window. Click ‘SAVE’. You will be redirected to canvas. You can then use this action in your workflow just like any other action.

To delete the custom actions, go to 'Custom > Actions' panel. Click the 'Delete' icon located against the custom action as shown in the following image.

2.png

You can create, edit, and delete the custom actions from 'ACCOUNT > Globals' located at the top right-hand side corner of Built.io Flow. You can see all the custom actions of your account. Click the '+' icon located at the top right-hand side corner of the 'Globals' page to create a new custom action. If you want to edit or delete an existing custom action, hover over the custom action (named 'Sample' in the image) and click the vertical ellipsis (three tiny dots). You will get two options to edit or delete the custom action as shown here:

3.png

 Upon clicking the 'Edit' button, you will be redirect to the console page of the custom action where you can edit the code, compile it and make appropriate changes you want. Clicking on the 'Delete' button will delete the custom action from all the workflows. 

Now that we have seen how to create a new custom action, lets understand the conventions specified by Built.io Flow that you need to follow. These conventions are mainly classified into 3 main blocks of program code as given below:

1. this.input: This block includes the definition of form input fields.

2. this.output: This block includes the definition of the output parameters that your action will return.

3. this.execute: This block includes the program logic that will run inside Built.io Flow engine.

Let’s look at an example to understand how to actually go about creating a custom action.

Example


Let’s assume that you wish to create a custom action for creating a new incident in PagerDuty. We will see how to write code for this action with the help of Built.io Flow conventions. You can find the complete action code here.

Request module: This is a Node.js module that lets you make simple HTTP calls to the third party applications. You can use 'GET', 'POST', 'PUT', 'DELETE', and 'PATCH' method in request module to perform specific operations. You need to define this module at the start of the code with the help of the require() function. We will learn more about this module in a latter section.

5-require.jpg

this.id: Specify a unique id for this action.

6-this.id.jpg

this.label: Specify the name that will be used as a title for this action. Please note that if you use ‘this.label’ to set the title for the action, it will automatically override the action label you had entered in the ‘Integration’ window.

7-  label.jpg

this.input

In this block you need to define the input fields for the action. All the fields defined here should follow JSON schema structure. Know more about JSON schema here. It contains three main keys (title, type, and properties) for which you need to assign values.

1. title: This key is used to specify the title of the form.(required)

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

3. properties: Under ‘properties’, you need to specify the inputs fields (and validation conditions, if any) that you want in the form. Different types of input fields are listed below:

1. String

2. Object

3. Array

4. Any

For our sample action, we need to add the following input fields.

1. PagerDuty Connection (String) - Mandatory

2. Service Integration Key (String) - Mandatory

3. Description (String) - Mandatory

4. Details (String) - Optional

Define all these fields inside the 'properties' key as shown below:

8-input.jpg

You can use OAuth exposed by Built.io Flow, to add authorization field for your custom action. Click here to know more about it. 

It is important to note that you need set value of ‘minLength’ to 1 for all the mandatory input fields. This will ensure that user does not leave any mandatory field blank. In the above example, we have set the value of minLength to 1, for the mandatory ‘Title’ field. This means that the user will need to enter input in the ‘Title’ field or otherwise Built.io Flow will throw an error.

this.output

In this block, you need to define the output parameters that will be returned by the action. All the fields defined here should follow JSON schema structure. Know more about JSON schema here. It contains two main keys for which you need to assign values.

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

2. properties: This key is used to define all the output parameters that will be returned by the action. The different types of output parameters are listed below:

1. String

2. Object

3. Array

4. Any

Our sample action returns following output parameters:

1. Incident status

2. Incident message

3. Incident key

Define all these output parameters inside the 'Properties' key as shown below:

9-output.jpg

this.execute

In this block, you need to 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'.

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.

3. request module: As mentioned above, this module helps you to make HTTP calls to third party applications. In order to do that, you need to provide values for following keys:

- Headers: Pass the required values to create a connection.

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

- URL: Provide the URL to which you wish to make HTTP request.

- 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 this.execute block for our sample integration is given below:

10-execute.jpg

After you have completed writing the last block, 'Compile' it. The errors, if any, will be highlighted in the console. Once the action is compiled successfully, you will see the action input form in the integration window, as shown below:

11-compile.jpg


After this, click on 'Next'. You will be redirected to the 'Test Action' window where you can check if the action is working as expected. Once this is done, click 'Done'. Your custom action will now be added to the list of integrations under 'Custom' tab.

Once you have created an action, you can simply drag it to the canvas and start using it just like other built-in actions provided by Built.io Flow. You can also edit an existing custom action by clicking on 'EDIT ACTION' link, in the integration window.

11-Edit action.jpg

When you click on the 'EDIT ACTION' button, you will be redirected to the action builder window. Here you can see three options; 'REVERT', 'HIDE', and 'COMPILE'.

If you wish to revert the changes you have made in the code, click on 'REVERT'.

If you wish to hide the code console, click on 'HIDE'.

If you wish to compile the code, click on 'COMPILE'.

12-revert-compile.jpg

Once you have made all the required changes to the code, click on 'DONE'. This will take you back to canvas.

Error Description

Built.io throws an error if any of the mandatory keys are not included in your code. Let's understand it better with the help of sample code.

Suppose we have not included ‘title’ key in the ‘this.input’ block. Since ‘title’ is a mandatory key, Built.io Flow will throw an error when you compile the code. The error message is shown below:

13-error.jpg


The error message is structured as given below:

- Block in which the error is encountered: Since our error is encountered in ‘this.input’ block, the error message shows ‘Input’.

- Type of error: This states the type of the encountered error.

- Error description: Since we have not included ‘title’ key, it shows relevant error description for the same.

- Path: It shows the path where the error has occurred. Since ‘this.input’ block is defined in the root of the code, the path for this particular error returns '[]'.

Similarly, if we do not include ‘type’ key for ‘Status’ output field under ‘properties’ key, in the ‘this.output’ clock, Built.io Flow will throw an error when you compile the code. The error message is shown below:

14-error-output.jpg


Log Data

You can capture the log data of the custom action by using '$log()' inside the 'this.execute' block. For example, if you want to capture the log details of the input data in the given custom action, add '$log("formdata " + JSON.stringify(formdata));' after the 'formdata' section, as shown below:

15-logdata.jpg

Here’s the complete code for some of the sample actions to get you started:

1. PagerDuty_Create Incident - Download code

2. Salesforce_Execute SQL Query - Download code

3. AWS_ EC2 tag resources - Download code

4. PagerDuty_Create Escalation Policy - Download code