ThingWorx Flow > Custom Actions
  
Custom Actions
You can create your own custom action besides the actions provided by ThingWorx Flow.
ThingWorx Flow provides the ability to create custom actions to use in workflows like the other predefined actions. All custom actions are available for use under the Custom tab in the Actions panel of the Workflow Editor.
Creating a Custom Action
Create custom actions in the Global Flow Settings page or in a workflow from the Custom tab in the Actions panel.
1. To create a new custom action, do the following:
a. On the Global Settings page, go to the Custom Actions section, and then click .
b. From the actions panel, under the Custom tab, click .
An action builder dialog box opens consisting of 2 sections, the console to write code for the action and a basic code structure in the console for your reference.
2. In the Custom Action dialog box, enter the details that follow:
Label—Provide a suitable name for your action. This is required.
Console Editor—Write the code for the action by updating the prepopulated template. For details on how to define the various parts of the action, refer to the section that follows, Defining a Custom Action.
3. Click COMPILE next to the Label field. If there are any errors in the code, they are highlighted in the code editor. After a successful compilation, all the input fields defined in the input section of the custom action appear in the left panel of the window. The user can then preview what the configuration dialog window will look like when using the custom action in a workflow.
4. Click SAVE. After saving, the action is added to the list of available actions under the Custom tab of the Actions panel and can be dragged onto the Workflow canvas for use just like any other action. You can also manage custom actions from the Custom Actions section in the Global Settings page.
Defining a Custom Action
A Custom Action is made up of a Node.js JavaScript function that defines the action. When creating a new custom action, a sample template is prepopulated in the code editor. You can use this template as a starting point to build the action. The various sections of the action are described below.
Number
Description
1
Use the require() function at the start of the code to import Node.js modules for use in the custom action. In the sample code, the action is imports the request module to make simple HTTP calls to third-party systems.
* 
To safeguard against possible misuse, only the following Node.js modules can be imported for use in custom actions:
assert, buffer, crypto, events, http, https, lodash, path, punycode, querystring, request, soap, string_decoder, url, ws, xml2js, zlib
2
this.id—An attribute that is used as a unique identifier for the custom action.
3
this.id—An attribute that specifies the name of the custom action.
* 
If you use this.label to set the title for the action, it automatically overrides the action label you entered in the custom action window.
4
this.input—A JSON attribute that defines the input fields to display when configuring the action in a workflow. There are three JSON keys for which you need to assign values:
title—(required) Used internally as an identifier
type—(required) Used internally. The value for this key should always be set to object and should not be changed.
properties—required) A JSON attribute that defines the input fields and validation conditions, if any, that appear for the action. Each input field should have a unique key such as first_name and define values for the following items:
title—(required) The label that appears for the field such as First Name.
type—(required) The type of the field. Valid types are string, object, array, and any
description—(optional) A message that appears as a tooltip.
minLength—(optional) Specifies the minimum number of characters that must be specified.
* 
To make a field mandatory, set the value of minLength to 1.
5
this.output— A JSON attribute that defines the output fields that the action returns and makes available in the rest of the workflow. There are three JSON keys for which you need to assign values:
title—(required) Used internally as an identifier.
type—(required) Used internally. The value for this key should always be set to object and should not be changed.
properties—(required) A JSON attribute that defines the output fields. Each output field should have a unique key such as status and define values for the following items:
title—(required) The label that appears for the field, such as status.
type—(required) The type of the field. Valid types are string, object, array, and any.
6
this.output—A function that defines the program logic that runs when the action is executed within a workflow. The function must define the following two function parameters:
input—A JSON object that contains the values of the input parameters at workflow execution time. The values can be referenced using the input field keys as defined in the this.input attribute of the action.
output—A callback function that must be called to pass the output values to the workflow. It indicates that the action is completed. The function is in the form callback(err,output):
err—Used to report any errors that may have occurred to the workflow. If no errors occur, then use null.
output—A JSON object with values for each of the keys defined in the this.output attribute of the action.
Using Custom Actions in a Workflow
A list of the custom actions created in the system is shown under the Custom tab of the Actions panel and can be dragged onto the workflow canvas for use like any other action.
When a custom action is added to a workflow, a copy of the action is added. The copied action can be edited from the action’s configuration window in the workflow without affecting any other use of the action in other workflows. Refer to the section that follows Editing Custom Actions in a Workflow.
Similarly, editing or deleting a custom action from the Global Settings window does not affect any copies that are added to the workflows. Refer to the section Custom Actions under the topic Global Flow Settings. Edits to the custom action are only reflected in newly added copies of that custom action.
Editing Custom Actions in a Workflow
To edit a custom action in the workflow, click for the action, and then click Edit Action. The code editor appears to edit the action. There are three options when editing the action, Revert, Hide, and Compile.
To revert the changes, you made in the code, click Revert.
To dismiss the code editor, click Hide.
To compile the code, click Compile.
After you make the required changes to the code, click Done. A prompt appears indicating that the changes are only applicable to an action. Click YES to save the changes.