Configure REST client for efficient web services

With the Rest Client task type, you can configure processes to consume RESTful web services. This task is commonly used to push or pull information from other systems that have a web service API.

There are three configuration tabs for defining your attributes and one for testing your configuration:

Request Configuration

This tab accepts either a single URL/URI string or a JSON configuration object with the following options:

• uri or url - Fully qualified uri or a parsed url object from url.parse()

• qs - Object containing query string values to be appended to the uri

• method - HTTP method (default: “GET”); supports all HTTP verbs (GET,POST,PUT,DELETE, etc.)

• headers - HTTP headers (default: {})

• body - Entity body for PATCH, POST and PUT requests; must be a string

• form

  • When passed an object, this sets body to a query string representation of the value and adds Content-Type: application/x-www-form-urlencoded; charset=utf-8 header

  • When passed no options, a FormData instance is returned (and is piped to the request); this is the most common way to post a JSON object

• auth - A hash containing values: user, username, password, pass, and sendImmediately; this is not a hash in the cryptographic sense

• json - Sets body to a JSON representation of the value and adds Content-type: application/json header. Additionally, it parses the response body as JSON.

• followRedirect - Follow HTTP 3xx responses as redirects (default: true)

• followAllRedirects - Follow non - GET HTTP 3xx responses as redirects (default: false)

• maxRedirects - The maximum number of redirects to follow (default: 10)

• encoding - Encoding to be used on setEncoding of response data. If null, the body is returned as a Buffer.

• timeout - Integer containing the number of milliseconds to wait for a request to respond before aborting the request

• proxy - An HTTP proxy to be used; supports proxy authentication with Basic Auth

• oauth - Options for OAuth HMAC-SHA1 signing

• strictSSL - If true, requires SSL certificates to be valid

• jar - If true, remember cookies for future use (or define your custom cookie jar; see examples below)

• aws - Object containing AWS signing information; should have the properties key, secret, and bucket, unless it’s specified in the path, or the request doesn’t use a bucket (i.e. GET Services)

• httpSignature - Options for the HTTP Signature Scheme using Joyent’s library; the keyId and key properties must be specified

Example

{url: "https://myservice.myco.com" method: "POST", form: {customer_name: __cname, customer_type: __customertype, active: true}

The following example uses the auth, and json options to make a request:

{  
"uri": "http://somecompany.com/ws/simple/createProject",  
"method": "POST",  
"auth" : {  
"user" : "MyUserName",  
"pass": "123455",  
"sendImmediately" : false  
},  
"json" : true,  
"body": {  
"customer_type": __customerType  
"customer_name": __cname

}

}

Request Parameters

This tab enables you to configure request parameters to fill variables in your Request Configuration -> Request Options settings. For example, in the above request configuration, to replace the strings __customerType and __cname with variables captured in a form, use the below configuration:

Response Values

This tab enables you to map values returned from the request to task variables. These variables are then exposed to rules, prefill values, reports. When the task executes, the values are saved to the database.

In the previous example, you can retrieve the _id value from the response of your POST request. If you want the entire body of the response, you can skip this tab. The task type enables you to create expressions based on the JSON-Query module for Node. The context is set to the response and the response.body is JSON.parsed. In the previous example, the POSt request would return the record for the customer that was saved:

{"__v":0,"active":true,"name":"test customer","_id":"52b353d88bd1a1954c01231b","licenses":[],"users":[],"supportContracts":[],"created":"2013-12-19T20:15:20.320Z","supportTier":"standard","customerType":"Prospect"}

If you want to retrieve the _id value from the response of a POST request, configure an expression to extract body._id. The full configuration includes:

• Key - A string used to uniquely identify the value for this task instance.

• Label - The label used when displaying the variable in the Request Detail, Rules, Prefills, and Reports.

• Data Type - The data type being captured.

• Expression - The JSON-Query expression used to parse the raw response and get the value for this variable.

REST error handling

If the REST client fails, use the failure response codes provided to build appropriate handling rules. Below is a simplified example:

The REST task is configured accordingly:

Subsequent milestones are set to receive the error codes. Below is an example for the 400 error milestone shown above. The rest error codes are configured in a similar manner.

Test

This tab enables you to validate and test your configuration based on the settings you have saved. Be sure to click the Save button in the lower-right corner on each tab prior to running your test. Below is a screenshot of a test:

This tab automatically generates the configuration for the Request Parameters. You will need to enter values for each parameter before testing.

Clicking the Test button sends the request and processes the response based on the Response Values configuration. In the example, one Response value was defined with the expression body._id. The raw response body appears as shown below:

{"__v":0,"active":true,"name":"ACME Anvils Incorporated2","_id":"52b4a1b922102e315700000e","licenses":[],"users":[],"supportContracts":[],"created":"2013-12-20T19:59:53.259Z","supportTier":"standard","customerType":"Prospect"}

The expression body._id extracts only the _id value from the response. Test results are returned in an array of JSON objects, including the key, label, type, and the value returned by the JSON-Query expression.