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

Transformation 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

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.

Flow Designer script fundamentals

Both custom steps and HTTP triggers have a Script tab where you edit the script that defines the step's logic and sets its outputs. The following examples illustrate how to:

  • Map information to outputs
  • Reference inputs, outputs, and request properties
  • Use endpoints to make requests to xMatters or another system
  • Reference constants using inputs
  • Use libraries in your script
  • Write to the Activity panel log (including stringifying Javascript objects)
Map information to outputs and reference inputs, outputs, and request properties
// 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;
 
Use endpoints to make requests to xMatters or another system
// 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'
});
 

See the section on Outbound HTTP requests for more information on making requests from the script, and you can find more information on defining using the the endpoint label in our topic on creating a custom step.

Use libraries in your script
// 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);
 

See Libraries for more information on creating and using libraries.

Reference a constant by using an input
// Constants function a little differently. Unlike in Integration Builder transformation scripts, constants are not directly referenced in flow scripts. Instead, use constants to populate step inputs, and then reference the input in your script.
output.invariable = input['My Constant Value'];
 
Write messages to the Activity panel log
// 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));
 

^ Back to top

Inbound HTTP requests

HTTP triggers receive and parse the request object sent in a POST request to xMatters. 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
Property Description
body

This is the body of the request posted to the trigger URL, and usually contains the JSON or XML payload of an HTTP POST. To parse the body of the incoming request, use one of the following in the script:

  • If the body contains JSON: var payload = JSON.parse(request.body);
  • If the body contains XML: var payload = JXON.parse(request.body);
    • For information on how XML payloads are processed and how you can manipulate them, see XML manipulation.
  • If the body is in a query parameter: var payload = request.parameters; (if the body is sent as query parameters, the values appear on the Parameters tab in the Activity panel)
headers

The HTTP headers of the incoming request. This contains information about the request, which can help in troubleshooting.

param / parameters

The name and value of any query string parameters. If the body was sent as query parameters, this also contains the POST body parameters.

requestId The unique identifier (UUID) assigned to this request by xMatters when the request is received. This identifier is returned in the response to the system initiating the request so you can match a request with the trigger initiation in xMatters.
method

The method of the incoming request (for HTTP triggers, this is always POST).

url The trigger URL the request was sent to (for example, http://your-company.xmatters.com/api/integration/1/functions/1443050b-067a-4666-b358-c1d8873a7db1/triggers).

^ Back to top

Outbound HTTP requests

Custom steps can make 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.

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;
  var recipients = [];
  recipients.push({'id': 'mmcbride', 'recipientType' : 'PERSON'});
  trigger.recipients = recipients;
  form.post(trigger);
} else {
  console.log("Unable to find information for user with ID " + input['User ID']);
}
 

^ Back to top