10.9 Rest Activity

The Rest activity enables users to call REST endpoints or resources when processing workflow data. The activity allows workflows to exchange data with arbitrary REST services. Data sent to a REST service can integrate a workflow with other systems inside and outside the organization. Data received from a REST service can provide decision support information on approval forms. You create flowdata variables to move data between the workflow and the REST service.

10.9.1 Properties

The Rest activity has the following properties. Most of the Rest activity properties are ECMAScript expressions, so ensure that you configure each property by clicking the edit icon in the property field to open the expression builder modal window.

Table 10-21 Rest Activity Properties

Property Name

Description

Input properties

Identifier

A unique string value that identifies the activity. Workflow Builder auto-generates this value in Rest_<N> format, where <N> represents an alphanumeric value that contains 7 characters.

Name

Specifies a name for the activity.

API url

Specifies the encoded URL path that the activity uses when calling the REST server. If the path includes any reserved characters, you must URL encode the path. For example, you can use the following sample expression:

encodeURIComponent({api_url_path})

For more information about URL encoding, see https://en.wikipedia.org/wiki/Percent-encoding.

HTTP method

Specifies the method the activity uses to retrieve data from or modify data on the REST server. The choices are:

  • get

  • put

  • post

  • delete

Authentication type

Specifies the authentication method used by the activity when calling the REST server. You can specify any one of the following:

  • Basic Authentication: Authenticates by providing the user ID and password within an HTTP header. Click the edit icon in the Username and Password properties to define the expressions for the header in the expression builder.

    In many cases, the REST server expects the header to be in the “Basic Authentication” format. For more information about the “Basic Authentication” format, see https://en.wikipedia.org/wiki/Basic_authentication.

  • OAuth: The activity uses Oauth-based authentication to communicate with the REST server. In the Oauth authorization url property, specify the expression URL to the authorization server that issues the access token. The access token generated by the specified authorization server enables the activity to authenticate future requests.

    The OAuth protocol provides the following authorization Grant type to obtain the access tokens for accessing the OAuth protected REST endpoints or resources:

    • Client credentials: The activity authenticates through client credentials. Specify the Client Id and Client secret of the registered client.

    • Resource owner password: The activity authenticates through both client and user credentials. Specify the Client Id, Client secret, Username, and Password for authentication.

Accept Header

Specifies the Accept header that the activity uses when receiving data from the REST server. The Accept header tells the REST server the format in which it should return data. You can specify an acceptable header, such as application/json and application/xml.

Content type

When you use a PUT or POST request to call the REST service, you may need to specify the content type in the payload data. Click the edit icon to specify an expression. The value of this type of expression is normally either application/json or application/xml.

Request Content

When you use a PUT or POST request to call the REST service, you may need to specify the content in the payload data. Click the edit icon to specify an expression for getting the data for a particular REST server input field.

Http Headers

Specifies any additional HTTP headers the activity uses when calling the REST server. Specify both header name and value expressions, as necessary, using quotation marks around each expression.

Timeout

Specifies a dynamic expression that defines the period of time, in milliseconds, allotted for the Rest activity to complete. The timeout interval applies each time the activity is executed by the addressee.

Trust Managers

Specifies one or more trust managers used to authenticate the connection to the REST server. The property expression must evaluate to TrustManager, TrustManager[], or List<TrustManager>.

The default choices available in the ECMA expression builder are:

  • Trust All Certs

  • Trust Certs in default keystore

  • Trust Certs in specified keystore

Map Output

If the REST service returns data you want to capture, you need to specify the mapping. This is normally the case for most requests.

Click Map Output and specify where the data from REST server output field should be copied after the form has been processed. In particular, you can set the expression for Status Code, Content Type, and Response Content, as follows:

  • Status code: The value of this expression is the HTTP status code from the REST call.

  • Content type: The value of this type of expression is normally either application/json or application/xml, depending on the format of the data the server returns. REST services typically return responses in a JSON format for the majority of requests.

  • Response content: This type of expression evaluates to a JSON- or XML-formatted string depending on the returned data. REST services typically return a JavaScript Object Notation (JSON) in response to the majority of requests.

The Auto map button in the REST activity can be used to map the Status code, Content type, and Response content fields into the flowdata automatically. You can then read these flowdata variables by extracting the fields in a subsequent activity using the Expression Builder’s utility functions with either get() or getObject() functions.

For example, in a workflow where you have mapped the response returned from the REST call to the flowdata.REST_<N>/content, you can use the get() function in the following expression to retrieve the values of the flowdata variable in a Log activity’s Author field:

function parseIt() {
//get JSON value
var parsedjson = JSON.parse(flowdata.get('Rest_<N>/content'));
return parsedjson;
}; parseIt();

where, JSON.parse is a utility function in Expression Builder that parses a string into an JavaScript object.

 

Alternatively, you can use the getObject() function to retrieve a JavaScript object as above. See the following example for one such expression used to retrieve the values of the same flowdata variable in the Message field of a Log activity:

function parseIt() {
var responseObject = flowdata.getObject('Rest_<N>/content');
var childNodes = responseObject.get(0).getChildNodes();
for ( var i=0; i<childNodes.getLength(); i )
{
try
{
var field = childNodes.item(i);
var parsedJSON = JSON.parse(String(field.getTextContent()));
return parsedJSON;
} catch( e )
{
e.toString();
}
}
};parseIt();

10.9.2 Data Items

Data items are not supported with this activity.

10.9.3 Email Template

Email templates are not supported with this activity.

10.9.4 Problems

The Problems tab provides details of the errors and warnings associated with the activity in a workflow. For more information about validating workflow activities, see Validating a Workflow.