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.
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.
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.
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:
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.
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.
this.id: Specify a unique id for this action.
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.
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:
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:
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.
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:
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:
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:
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:
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.
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'.
Once you have made all the required changes to the code, click on 'DONE'. This will take you back to canvas.
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:
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:
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:
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