Creating Custom Actions with Node.js

Getting Started

All your custom actions are saved under the Custom tab in the connectors panel. To create a new custom action using the Node.js block, navigate to the Custom tab, and click on the + icon beside the Node.js action.

The Node.js block will appear on screen where you can see the basic code structure required to create the custom action.

• Label: Provide a suitable name for the custom action you want to create.

• Code: Add the relevant logic in the provided code structure. The code you add must be in Node.js and as per the code structure and conventions specified in the later part of this document. Once this is done, click Compile. If there are any errors in the code, they will be highlighted in the console.

  

  When your code is compiled successfully, you can see the configuration form for the custom action. If you want to make further modifications to this form, click on the Previous button, make relevant changes to your code, and compile it again. Once you have created the custom action as per your requirements, click Save.

  This will create the custom action and add it to the list of custom actions under the Custom tab. You can now add this custom action in any workflow and configure it like any other action.

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

Code Structure Components

Now that we have seen how to create a new custom action, let’s have a look at the elements that form the code structure for custom action. You can find the complete sample code here. Now that we have seen how to create a new custom action, let’s understand the conventions specified by Integration that you need to follow. These conventions are mainly classified into 3 main blocks of program code as given below:

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

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

• this.execute: This block includes the program logic that will run inside the Integration engine.

Supported Modules

You can use specific modules supported by Integration to create custom actions using the Node.js action. Given below is the list of allowlisted modules:

• webmethodsio/cli-sdk
• assert
• async
• aws-sdk
• bluebird
• buffer
• crypto
• evernote
• googleapis
• html-to-text
• http
• https
• json-stringify-safe
• lodash
• moment
• moment-timezone
• path
• q
• querystring
• request
• soap
• stream
• tls
• twitter
• underscore
• url
• uuid
• xml2js
• zlib

Note: We do not support C++ modules and modules that need to be compiled on binary. This is because, to make these modules work, they should be compiled based on target machine architecture.

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

Example

Let’s say, you want 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 Integration 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, or PATCH method in the request module to perform specific actions. 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 later 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.

  

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.

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

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

• properties: Under properties, specify the input fields (and validation conditions, if any) that you want in the form. Different types of input fields are listed below:

  • String

  • Object

  • Array

  • Any

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

• PagerDuty Connection (String) - Mandatory

• Service Integration Key (String) - Mandatory

• Description (String) - Mandatory

• Details (String) - Optional

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

You can use Oauth exposed by Integration, 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 the 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 Integration 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. It contains two main keys for which you need to assign values.

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

• 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:

  • String

  • Object

  • Array

  • Any

Our sample action returns following output parameters:

• Incident status

• Incident message

• Incident key

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

this.execute

In this block, you need to write the entire action logic that will be executed inside the Integration engine. The function defined in this block will have two function parameters: input and output.

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

• output: This parameter will inform the Integration engine that the action execution is completed.

• 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 workflow 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:

Click Save to create the custom action. This will now be added under the Custom tab.

Error Description

Integration throws an error if any of the mandatory keys are not included in your code. Let’s understand it better with the help of example code.

Suppose we have not included title key in the this.input block. Since title is a mandatory key, the custom action 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 the 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, Integration will throw an error when you compile the code. The error message is shown below:

Log Data

You can capture the log data of the custom actions 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 actions, 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:

• PagerDuty_Create Incident - Download code.

• Salesforce_Execute SQL Query - Download code.

• AWS_ EC2 tag resources - Download code.

• PagerDuty_Create Escalation Policy - Download code.

Editing and Deleting Custom Action

To edit a custom action, navigate to Custom tab and click the Edit icon given against the custom action name.

Make relevant changes in the Node.js block that appears on screen and Compile it.

Fix errors (if any), and Save the custom action. After this when you add this custom action in any workflow, it will contain the changes made by you.

Note: The existing instances of this custom action will continue to work as per older version, unless you replace them with the modified custom action.

To delete a custom action, navigate to Custom tab and click Delete given against the custom action name.

You will be prompted to confirm the delete request.

Click Delete. This will delete the custom action from your account.

Note: All the existing instances of this custom action which are added to workflows will not be deleted, and continue to function as before. If you want to delete the custom action from your workflows, you will have to explicitly delete them from each workflow.