No Code Service Creation Powerful Integrated Forms GCloud Information

REST API Steps

Last updated 9 months ago

Was this helpful?

REST API Steps

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

At the current time, only POST is supported. PUT and GET were added for future proofing purposes.

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.

You do not need to ensure there is a pre-existing field to map the API response information back to. The data will be passed into Process using the details in the response mapping and will create a Field in order to do so if it does not exist (these Fields are not visible on the Process definition). If you are using a pre existing Field then take the "Code value of your Field and enter that value when creating the mapping.

For further information on setting the JSON path more details can be found here:

PreviousBranches NextWorked example

Last updated 9 months ago

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

At the current time, only POST is supported. PUT and GET were added for future proofing purposes.

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:

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

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: