7.16 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.

7.16.1 Properties

The Rest activity has the following properties. Note that most activity properties are ECMAScript expressions, so ensure that you configure each property by clicking the “E” icon in the property field to open the ECMA Expression Builder.

Table 7-29 Rest Activity Properties

Property Name	Description
Activity Id	Specify a unique string value that identifies the activity. Activity Ids are written to the user application’s log file. Specifying a meaningful Activity Id makes it easier to understand the data written to the logs. You can specify letters, numbers, and the underscore (_) character. If you do not specify a value, the Activity Id defaults to ActivityNN where the NN represents the order in which the activity was added to the workflow.
Name	Provides a name for the activity.
Protocol	Specifies the protocol the activity uses when calling the REST server. You can specify either http or https. NOTE:If you specify https, you must also configure the Trust Manager property for the activity.
Host	Specifies the REST server the activity calls to request or modify data.
Port	Specifies the port number the activity uses when calling the REST server.
Path	Specifies the encoded URL path the activity uses when calling the REST server. If the path includes any reserved characters, you must URL encode the path. For more information about URL encoding, see http://en.wikipedia.org/wiki/Percent-encoding. In the ECMA Expression Builder, select URL Path Encoding > URL encode the path and modify the path to include the URL path expression to encode.
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 head
Authorization Header	Specifies the Authorization header the activity uses when calling the REST server. 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 http://en.wikipedia.org/wiki/Basic_authentication. If this is the case, in the ECMA Expression Builder, select Basic Auth Header and modify the header to include the username and password used to access the REST server.
Accept Header	Specifies the Accept header 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. The activity can receive data in either XML or JSON format. The choices are: application/json application/xml
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. For details on building ECMA expressions, see Section 9.0, Working with ECMA Expressions. For descriptions of the system variables available in a workflow, see Understanding Workflow Data.
Trust Managers	If the activity uses the https protocol, this property 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

7.16.2 Data Item Mapping

To bind the data items associated with the Rest activity, you define pre-activity and post-activity mappings. The pre-activity mappings map values retrieved from the flowdata object to attributes in the Input message for the REST server that will be accessed by the Rest activity. The post-activity mappings map the response from the REST server back into the flowdata object.

Table 7-30 Rest Activity Data Item Mappings

Setting	Description
Pre-Activity	If the REST service you want to call requires payload data, you need to specify pre-activity mappings. This is normally the case when you use a PUT or POST request. When this option is selected, you can double-click a cell in the Source Expression column to specify where the Rest activity gets data for a particular REST server input field. In particular, you can set a source expression for Content Type and Content, as follows: Content Type: The value of this type of expression is normally either application/json or application/xml, depending on the data type you want to send to the server. Content: This type of expression evaluates to a JSON- or XML-formatted string for the expected payload. If the expected format is JSON, look at the helper functions in the ECMA Expression Builder, under Vault Expressions > Script Vault. In particular, the helper function Convert object to JSON may be useful, as it enables you to create a JSON string from an ECMAScript object. While you can build the JSON string using conventional expressions, the Convert object to JSON function may be easier and less prone to errors, especially for complex JSON expressions. See the following example for one possible expression using the function: ScriptVault.JSON.stringify( (function () { var test = {}; test.val = "1"; test.arrayVal = ["one","two"]; return test;} () ))
Post-Activity	If the REST service returns data you want to capture, you need to specify post-activity mappings. This is normally the case for most requests. When this radio button is selected, you can double-click a cell in the Target Expression column to specify where data from a REST server output field should be copied after the form has been processed. In particular, you can set a source expression for Status Code, Content Type, and 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. Content: This type of expression evaluates to a JSON- or XML-formatted string the returned data. If the format of the returned data is JSON, look at the helper functions in the ECMA Expression Builder, under Vault Expressions > Script Vault. In particular, the helper function Convert object to JSON may be useful, as it enables you to create a JSON string from an ECMAScript object. You can use the Map All button to map the Content field into flowdata in the Rest activity, then use the content by extracting fields in a subsequent activity using the Convert object to JSON helper function. For example, in a workflow where you have mapped the content returned from the REST call to flowdata.processInstances, you can use the following expression to obtain the JSON property totalSize: (function () { var processInstances = ScriptVault.JSON.parse( flowdata.get('processInstances') ); var size = processInstances.totalSize; return size;}) ();
Source Expression	Specifies a source expression. When you click a cell in the Source Expression column, the ECMA Expression Builder displays to help you define your expression. It is recommended that you click the Map All button to allow Designer to generate this expression for you.
Target Expression	Specifies a target expression. When you click a cell in the Target Expression column, the ECMA Expression Builder displays to help you define your expression. It is recommended that you click the Map All button to allow Designer to generate this expression for you.

7.16.3 Email Notification

Not supported with this activity.