REST API Steps
Last updated
Was this helpful?
Last updated
Was this helpful?
REST API steps enable you to call an API (or APIs) as a part of a process.
This can be hugely useful in the orchestration of process data with your middleware, CRM and line of business applications.
The following illustrates the functionality of a REST API step:
Like any process step illustrated before, you need to give the step a name and description.
There are then behaviours to handle API failures.
Failure Allocation
You can set which user, group etc. should be allocated the step if it fails. This has all of the options for a regular step e.g. specific user, round robin in a group etc.
Supervisor Allocation
You can also set a group of users which will be able to see any failures should they happen in Supervise Tasks.
Request URL
This is the URL for the API to be called
The clue is in the name but it's important to state the URL must be that of a RESTful API.
Verb
REST APIs can have data pushed/pulled from them. The options available in OpenProcess are:
POST
PUT
GET
Content type
We currently support JSON i.e. application/json at this time.
Include process fields in the request
Essentially, you're able to pass data fields from the process (including data passed from the form as fields obviously) into the JSON payload by checking this box.
When this is set to true you can see the following section in bold is added to the body of the JSON file output:
{ "SubscriptionId": "30faf4b4-c96d-4b0b-afda-5b321a043000", "ProcessId": "58155a0f-8a42-4e83-bdd7-d05f8163df7f", "ExternalReference": null, "GeoTag": null, "Documents": [ { "Name": "Example.docx", "ContentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "Links": [ { "Rel": "self", "Href": "/open-api/documents/b8733268-bae0-4e22-9584-47ee7da98915" } ] } ], "Fields": [ { "Label": "TYPE", "Code": "TYPE", "ValueAsString": "Fly Tipping" }, { "Label": "KEEPINFORMED", "Code": "KEEPINFORMED", "ValueAsString": "2" }, { "Label": "FORENAME", "Code": "FORENAME", "ValueAsString": "John" }, { "Label": "SURNAME", "Code": "SURNAME", "ValueAsString": "McMahon" }, { "Label": "EMAIL", "Code": "EMAIL", "ValueAsString": "john.mcmahon@ieg4.com" }, { "Label": "MOBILE NUMBER", "Code": "MOBILENO", "ValueAsString": "07713491749" }, { "Label": "DETAILS", "Code": "DETAILS", "ValueAsString": "Rubbish innit" } ] }
If this is not checked, this section is not present.
Using the fields in the payload directly removes the need to get an XML file from eMapper, as you can map the content from the form directly into OpenProcess Fields.
Request Headers
APIs can have 'headers' that go with the request sent to the receiving system to provide additional information. Or more fully:
"A request header is an HTTP header that can be used in an HTTP request to provide information about the request context, so that the server can tailor the response."
Request Headers can be used to provide additional security too.
You can add as many Request Headers as you like by clicking on the Add Header button and providing a Name and Value for each.
Response Mapping
This enables you to map Key Information into a process from a response returned from an API. The key thing is this requires to be in JSON format. If a response is provided in anything other than JSON this will not work.
To provide an example let's say an API response provided a response which gave a case reference i.e.
{
"response: "200",
"ID": "3953403"
}
You could use the mapping element to automatically update the Key Information tab of the process in OpenProcess with this information. So the following shows how this would be mapped:
$.details.[?(@.name=='ID')].value
Once set up, as soon as the process is started, if the API call is successful it would result in the ID of 3953403 being added to the process.
For further information on setting the JSON path more details can be found here:
