Work with scripts in custom steps

Flow Designer is designed so you don't need to write a single line of code. However, to make it as flexible as possible, it also allows you to create custom steps where you can add a little code — or a lot — to define the logic of the step.

Scripting Language

Flow Designer scripts are written in JavaScript (JDK version 11) and should be compliant with ECMAScript 6. For security reasons, the instantiation of Java classes from within the scripting runtime is explicitly disallowed for all scripts running in the cloud. (Instantiation is allowed for scripts running on the xMatters Agent, which must be compliant with JDK version 8 and ECMAScript 5.1.)

In this topic

• Best practices
• Flow Designer script fundamentals
  •  Map information to outputs and reference inputs, outputs, and request properties
  • Use an endpoint and the endpoint label to make requests
  • Use libraries
  • How to access constants
  • Write to the Activity panel log
• Inbound HTTP requests
• Outbound HTTP requests

Best practices

When writing scripts for steps in Flow Designer, there are some general tips to keep in mind:

• Step inputs expect strings. Make sure the information you pass into the outputs of an HTTP trigger or custom step are strings. If the information coming into Flow Designer is in an array, you'll need to index the array and parse the information into a usable string.
• Inputs can accept up to 20,000 characters. If you think the information pushed into an output will be longer than that, you might need to break it into multiple outputs.
• When creating custom steps, keep in mind anyone with permission to use the step can add it to any flow. If the script relies on an input to provide a certain type of information, you might want to include that in the input description.
• Consider being discrete when creating a custom step — don't try to do everything in one step. Focusing the step on a specific task makes it easier to create, update, and troubleshoot. It'll also be more reusable in multiple flows.

// Use the script to map what information is fed into the outputs. This is a simple example mapping a subject input to a summary output:

output.Summary = input.subject;

// You can hard-code the content of the output:

output.cluster = "Rigel Swarm";

// Use dot or bracket notation to reference inputs and outputs:

output['Incident Start'] = input.reportedTime;

// For HTTP trigger steps, you can also access the HTTP request properties:

output.Source = request.url;

// Or a query parameter appending to the trigger URL - in this example, the recipients output would be populated with 'Antares' if the request to the trigger had '&team=Antares' appended

output.recipients = request.parameters.team;

// Or a property from the payload:

output['Incident ID'] = payload.properties.ticketnumber;

// Or it can be part of the response to a request to another system:

output.id = response.ticket.id;

// Reference an endpoint using the label you provide on the Settings tab (not the name in the Endpoints dialog). This lets the step be flexible - the actual endpoint referenced by an instance of the step can vary without breaking your script. In this example, the label is 'ServiceProject':

var apiRequest = http.request({

    'endpoint': 'ServiceProject',

    'path': '\ticket\' + input.ticketId,

    'method': 'POST'

});

// To call on a library, use the reference name you set on a step's script tab in a require statement to make the library code available to the script. This is case-sensitive. 

var trimWS = require('stringCleanup');

//Sets an output to the value of an input with any leading or trailing whitespace removed

var output['string with spaces'] = trimWS.trim(input.myString);

// Constants can be directly referenced in flow scripts, but makes the steps less portable or re-usable because any workflows you want to use the step in must have the same constant defined. Instead, use constants to populate step inputs, and then reference the input in your script.

output.invariable = input['My Constant Value'];

// Built-in constants are accessible only when the script is executed, and not as outputs from previous steps. To use a built-in constant to populate a step input:

output.invariable = constants.builtin.baseUrl;

output.invariable = constants.builtin.workflowName;

// You can use console.log write simple messages to the Activity panel log:

console.log("Finished running checkID script. Ticket ID is " + checkID);

// You can also use throw to throw an error that stops the flow and writes a message to the log. This example throws an error when an HTTP request is unsuccessful: 

if (apiResponse.statusCode !== 201) 
     throw "Ticket could not be created for: " + JSON.stringify(data);

// If you want to write the value of a JavaScript object to the log, use JSON.stringify() to convert it to JSON; otherwise, it appears in the log as "[object Object]".

console.log("Posted to Management System X: " + JSON.stringify(data));

Inbound HTTP requests

HTTP triggers receive and parse the request object sent in a POST request to Flow Designer. You can reference the request properties in the script (headers, parameters, body, etc.) where you can transform the incoming information and map it to the trigger outputs so connected steps can use it.

Request properties

Example JSON request

POST /api/integration/1/functions/1443050b-067a-4666-b358-c1d8873a7db1/triggers?apiKey=f654****************************b23e HTTP/1.1

Content-Type: application/json

Host: your-company-instance.com

Content-Length: 274

{

 "subject": "CPU Avg Usage is above 75% for 1 pod",

 "description": "CPU Usage Alert \n Triggered at 2019-12-01 02:34 due to metric value above 75%.\n Documentation: https://www.example.com/cpu-overusage-remediation",

 "priority": "HIGH",

 "targets": "mcbride|Work Email,Antares"

}

Example XML request

POST /api/integration/1/functions/1443050b-067a-4666-b358-c1d8873a7db1/triggers?apiKey=f654****************************b23e HTTP/1.1

Content-Type: application/xml

Host: your-company-instance.com

Content-Length: 293

<subject>CPU Avg Usage is above 75% for 1 pod</subject>

<description>CPU Usage Alert \n Triggered at 2019-12-01 02:34 due to metric value above 75%.\n Documentation: https://www.example.com/cpu-overusage-remediation</description>

<priority>HIGH</priority>

<targets>mcbride|Work Email,Antares</targets>

Example query parameter request

POST /api/integration/1/functions/1443050b-067a-4666-b358-c1d8873a7db1/triggers?
subject=CPU%20Avg%20Usage%20is%20above%2075%25%20for%201%20pod&
description=CPU%20Usage%20Alert%20%5Cn%20Triggered%20at%202019-12-01%2002%3A34%20due%20to%20metric%20value%20above%2075%25.
%5Cn%20Documentation%3A%20https%3A%2F%2Fwww.example.com%2Fcpu-overusage-remediation&prioruty=HIGH&targets=mcbride%7CWork%20Email%2CAntares&apiKey=f654****************************b23e HTTP/1.1

Host: your-company-instance.com

^ Back to top

Outbound HTTP requests

Custom steps can make requests to the step endpoint. For example, you might want update another system or gather more information to include in the step's outputs. In the script, the outgoing request must specify an endpoint, and may include the request method (GET, POST, etc.), a path to append to the URL, and any request headers, parameters, or body data.

To make a request, use the global HTTP object's request function to create a request object, then use that object's write method to perform the request.

The endpoint label you use in the script needs to match the endpoint label set on the Settings tab (you can see the label in the list in the sidebar). Using the label lets you point the endpoint an instance of the step uses to any base URL. You can append an additional path to the URL in the script.

A successful request returns a response object you can use to feed information into outputs (for example, pulling parameter values into outputs or having a 'status' output that is set based on whether the response status is 200 or not).

If you simply want to post information to another system and only need one output with the response code, Flow Designer has a built-in Webhook step.

HTTP request object, write function and response object

The basic components of an HTTP request are the request object (sent using the write function) and the response object if the request is successful.

HTTP request object

The following function returns an HTTP request object that can later be sent using its write() function:

http.request(options)

The request function accepts a javascript object representing its options. The following table describes the available options:

Option	Type	Required	Purpose
endpoint	string	yes	Label of the endpoint (case-sensitive) for the step.
method	string		HTTP request method to use; default is GET.
path	string		Path to append to the endpoint. This can include query string parameters.
headers	object		HTTP headers to send with the request (for example, Content-Type or authorization information).
autoEncodeURI	boolean/string		By default, Flow Designer automatically encodes some characters in the URI (for example, spaces and slashes). This helps standardize the URLs and create default configurations for our built-in and packaged integrations that have the best chance of succeeding wherever they find themselves. However, if you want make sure you're sending exactly the request you intend — and not leaving it up to a machine to interpret — include the autoEncodeURI property and set it to false to override this default behavior and manually encode special characters.

// Prepare the HTTP request

var req = http.request({

  'endpoint' : 'myEndPoint',

  'method' : 'POST',

  'path' : 'path/to/my/service',

  'autoEncodeURI': false,

  'headers': {

    'Content-Type': 'application/json'

  }

});

// Prepare the HTTP request body

var data = {};

data.ticket = {};

data.ticket.subject = 'Update from Flow Designer';

// Submit the request and capture the response

var response = request.write(data);

If the HTTP request is a POST or other type that sends a request body, that body may be sent as the optional data parameter. If data is not a string, it's encoded as a string using JSON.stringify. If you don't want the data sent as JSON, transform the body into a string and set the correct Content-Type header on the request object.

HTTP request write function

The request.write() function sends the HTTP request and returns the response if the request succeeds. Success includes any completed HTTP request, even if the response is a 404 "Not Found" or 500 "Server Error". A failure means the HTTP request was not able to be made all; for example, due to an invalid host name or the connection refused by the remote server.

request.write([data])

HTTP response object

If the HTTP request is successful, the request.write() function returns an object describing the HTTP response with the following properties:

Property	Data Type	Description
httpVersion	string	HTTP version used to make the request; usually HTTP/1.1
statusCode	integer	HTTP status, such as 200, 404, or 500
statusMessage	string	The description of the statusCode, such as "OK", "Not Found", or "Server Error"
headers	object	The response headers
body	string	The response content

Example request: get a User ID from another system

The following example illustrates a request to get user information from another system and use it to populate step outputs.

// Prepare the HTTP request

var req = http.request({

  'endpoint' : 'myServiceDesk',

  'method' : 'GET',

  'path' : '/rest/api/3/user?accountId=' + input['User ID'],

  'headers' : {

    'Authorization: api-key' + input[API Key]

  }

});

// Send the request and retrieve the response

var resp = req.write();

// Post status to output, if the request succeeded, and populate other outputs

if (resp.statusCode == 200) {

  var assignedUser = JSON.parse(resp.body);

  console.log("Retrieved details for assigned user: " + assignedUser['name']);

  output.Name = assignedUser['name'];

  output[Display Name] = assignedUser['displayName'];

  output[Role] = assignedUser.applicationRoles[0].items;

} else {

  console.log("Unable to find information for user with ID " + input['User ID']);

}

^ Back to top