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 for other systems that have a web service API. Technical note: this task type wraps the Request Module for Node.
There are 3 configuration tabs for defining your attributes and 1 for testing your configuration:
Request Configuration
This setting will accept a single URL/URI string or a JSON configuration object with the following options:
Example:
{url: "https://myservice.myco.com" method: "POST", form: {customer_name: __cname, customer_type: __customertype, active: true}
This 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 are used to fill variables in your Request Options settings. In the example above, we want to replace the strings __customerType and __cname with variable captured in a form. The screen shot below shows the configuration:
This tab allows 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 example we have been following, we want to get back the "_id" value from the response of our POST. If we want the entire body of the response, you can skip this tab. The task type allows 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 our example the POSt 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 we just want to get back the _id value, we would set our expression to body._id. The full configuration for this is shown below:
If the REST client fails, we provide the failure response codes so you can build appropriate handling rules. Here is a simplified example:
The REST Task is configured thusly:
And the subsequent milestones are configured to receive the codes. This is the example for the 400 error milestone shown above. The rest are configured similarly.
The Test tab allows you to test your configuration based on the settings you have saved. Be sure to click the Save button on each tab prior to running your test. Below is a screenshot of a test:
The Test tab will automatically generate the configuration for the Request Parameters. You will need to fill in the values for each parameter.
Clicking the Test button will get the response and parse it based on the Response Values that you have set up. In the example, we defined one Response value with the expression body._id. The raw response body looked like this:
{"__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 just the _id value from this response. Test results are returned in an array of JSON objects that has the key, label and type that were defined in the Response Values tab along with the value returned by the JSON-Query expression.