RESTAPICLIENT Workflow Application
Overview
The RESTAPICLIENT workflow application allows you to call REST API endpoints to exchange information with other applications through HTTP requests, and can be used to build integrations with extendable applications (such as Azure Services and Slack).
It also allows you to call a REST API endpoint using application/json
or application/x-www-form-urlencoded
payloads. RESTAPICLIENT will then receive and process the response from the external API by mapping the response content with defined OUT parameters.
How it works
The RESTAPICLIENT application requires the
APP_URL
parameter, which corresponds to the REST API endpoint.The default request payload content type (
APP_REQUEST_CONTENT_TYPE
) isapplication/json
.application/x-www-form-urlencoded
is also supported.The default HTTP request method (
APP_METHOD
) isGET
. Other request methods (POST
,PUT
,DELETE
, etc.) are also supported.In case of error, when the
APP_RESPONSE_IGNORE_ERROR
IN parameter is defined and hasY
as its value, the error will be ignored and defined OUT parameters (APP_RESPONSE_STATUS
orAPP_RESPONSE_CONTENT
) will be mapped. Otherwise, an exception will be thrown.Since the application parameters are case sensitive, parameters must use the API’s accepted notation.
The default request timeout is 30,000 milliseconds (30 seconds); this default value can be modified by setting the
RestApiClientRequestTimeout
parameter value in theweb.config
file. The request timeout can also be defined in theAPP_TIMEOUT
IN parameter; the maximum timeout is 3,600,000 milliseconds (1 hour).✏️ Note: This timeout value must be less than the IIS request timeout value.
The HTTP request headers can be defined with the
APP_HEADER_xxx
parameters, wherexxx
is the header field name. For more information, see the Header parameters section.The request payload can be defined in the
APP_REQUEST_CONTENT_FILE
orAPP_REQUEST_CONTENT
IN parameters. When both parameters are defined, theAPP_REQUEST_CONTENT_FILE
parameter has priority. For more information on these parameters, see the Request payload section.The response from the REST API can be mapped to the
APP_RESPONSE_CONTENT_FILE
orAPP_RESPONSE_CONTENT
OUT parameters. Both parameters can be defined at the same time. For more information on these parameters, see the Response payload section.Besides the optional parameters listed below, you can also add additional custom IN and OUT parameters to send and receive custom user-defined data to and from the external API. For more information on and examples of these custom IN and OUT parameters, see the Request payload and Response payload sections.
The application supports the JSONPath query language (see https://github.com/json-path/JsonPath), which allows extraction of specific data from a JSON response (similar to XPath expressions in XML). For information on how to use this with the application along with examples, see the Response payload section.
Application logs are available and can be specified by setting the
RestApiClientLogLevel
parameter value in theweb.config
file to0
to disable logging (default),2
for simple logs, or3
for debug logs.The default maximum response length is 4194304 characters (4 MB); this default value can be modified by setting the
RestApiClientMaxResponseLength
parameter value in theweb.config
file.Automatic deletion of temporary files can be disabled by setting the
RestApiClientEnableFilesCleanUp
parameter value toN
in theweb.config
file; the default value isY
.
Required parameter
Parameter | Type | Direction | Description |
| Text | IN | External API URL |
Optional parameters
General
Parameter | Type | Direction | Description |
| Numeric | IN | Maximum time interval between sending the request and receiving the response The default is 30,000 milliseconds (30 seconds) and the maximum is 3,600,000 milliseconds (1 hour); the default can be modified by setting the ✏️ Note: This timeout value must be less than the IIS request timeout value. |
| Text | IN | API method The default is |
| Text | IN | Request content type supported by the external API The application supports |
| Text | IN | When set to |
APP_URL
optional parameters
APP_URL
optional parametersParameter | Type | Direction | Description |
| Text | IN | API URL optional parameter where It must be defined in the |
📌 Example
Parameter | Type | Direction | Value |
| Text | IN |
|
| Text | IN |
|
| Text | IN |
|
| Text | IN |
|
The parameters defined above will generate the following URL in APP_URL
:
Header parameters
Parameter | Type | Direction | Description |
| Text | IN | External API header parameters where |
📌 Example
Parameter | Type | Direction | Value |
| Text | IN |
|
| Text | IN |
|
The parameters defined above will generate two headers in the request payload:
Authorization parameters
The application also supports some predefined authorization header parameters in order to avoid adding these HTTP header parameters with the APP_HEADER_xxx
parameter name.
Parameter | Type | Direction | Description |
| Text | IN | API authorization Basic username |
| Text | IN | API authorization Basic password; must be used with |
| Text | IN | API authorization Bearer token |
| Text | IN | API authorization Azure SAS token |
Only one authorization header can be defined, otherwise an exception is thrown.
APP_AUTH_BEARER_TOKEN
is equivalent to defining the header parameterAPP_HEADER_Authorization
.
Request payload
There are two different ways to prepare the request payload. The first way is when you have access to the whole request payload (see Set the whole request payload via a parameter below); the second way is by building the JSON or URL encoded payload via IN parameters (see URL encoded request payload and JSON request payload below).
Set the whole request payload via a parameter
The following parameters can be used when you have access to the whole request payload, or the request content type is neither application/json
nor application/x-www-form-urlencoded
. You can set this request payload in a file/text data or directly in the text value.
Parameter | Type | Direction | Description |
| File | IN | Request payload in a file |
| Text | IN | Request payload |
APP_REQUEST_CONTENT_FILE
has priority overAPP_REQUEST_CONTENT
.APP_REQUEST_CONTENT
has priority over IN parameters used to build a JSON or an URL encoded payload.
URL encoded request payload
The following examples show how to build a request payload with application/x-www-form-urlencoded
as content type.
Standard URL encoded request payload
The following parameters are used to build a standard URL encoded request payload:
Parameter | Type | Direction | Description |
| Text | IN |
|
| Text | IN |
|
The parameters defined above will generate the following request payload:
JSON request payload encoded into a key name
The following parameters are used to build a JSON payload encoded into a key name:
Parameter | Type | Direction | Description |
| Text | IN |
|
| Text | IN |
|
| Text | IN |
|
The parameters defined above will generate the following request payload:
The APP_REQUEST_CONTENT_PAYLOAD_NAME
parameter is only supported with the application/x-www-form-urlencoded
request content type.
JSON request payload
The following examples show how to build a request payload with application/json
as content type.
Standard JSON request payload
The following parameters are used to build a simple JSON request payload:
Parameter | Type | Direction | Value |
| Text | IN |
|
| Text | IN |
|
| Text | IN |
|
| Text | IN |
|
The parameters defined above will generate the following request payload:
If you want to convert this JSON into an array, you have to set the APP_REQUEST_CONTENT_IS_ARRAY
parameter value to Y
.
Parameter | Type | Direction | Description |
| Text | IN | When set to Only supported when building JSON request payload with IN parameters. |
Setting the APP_REQUEST_CONTENT_IS_ARRAY
parameter to Y
will generate the following request payload:
To see how to build more complex JSON, see Setting a JSON array into a JSON property and Setting a JSON object/array into a JSON property using the __JSON
suffix parameter sections below.
Setting a JSON array into a JSON property
To set an array into a JSON property, you have to define the property path (e.g. person.spokenlanguages
) followed by the __X
suffix, where X
is the array index number.
The following parameters are used to set a JSON array into a JSON property:
Parameter | Type | Direction | Value |
| Text | IN |
|
| Text | IN |
|
| Text | IN |
|
The parameters defined above will generate the following request payload:
If you want to set a JSON array of JSON objects (e.g. "spokenlanguages": [{"spokenlanguage":"french"}, {"spokenlanguage":"english"}]
) into a JSON property, see the next section.
The array parameters will be ordered depending on their index number.
Index numbers have no limit (e.g.
person.spokenlanguages__9999
).A correct index sequence is not mandatory (e.g.
person.spokenlanguages__90
,person.spokenlanguages__30
). The__30
parameter value will be the first array parameter, and__90
the second one.An exception will be thrown if there is more than one JSON property specified in the IN parameters (e.g.
person.spokenlanguages
andperson.spokenlanguages__0
).The
__X
suffix uses two underscore characters.The parameter value can only be a text value.
Setting a JSON object/array into a JSON property using the __JSON
suffix parameter
__JSON
suffix parameterTo set a JSON object/array into a JSON property, you have to define the property path (e.g. person.children
) followed by the __JSON
suffix with the JSON object/array as the parameter value.
The following parameters are used to set a JSON object/array into a JSON property:
Parameter | Type | Direction | Value |
| Text | IN |
|
The parameters defined above will generate the following request payload:
An exception will be thrown if there is more than one JSON property specified in the IN parameters. (e.g.
person.children
andperson.children__JSON
).The
__JSON
suffix uses two underscore characters.
Response payload
The application supports OUT parameters to be mapped with the HTTP response:
Parameter | Type | Direction | Description |
| Text/Numeric | OUT | Response status code |
| Text | OUT | Response content type |
| File | OUT | Response payload or error message in a file |
| Text | OUT | Response payload or error message |
| Text | OUT | Returns Only supported for |
Mapping a JSON response payload with OUT parameters
The application also supports additional custom OUT parameters to map simple JSON response payloads.
📌 Example
JSON response payload:
The following parameters allow you to map the response payload into different process data:
Parameter | Type | Direction | Retrieve the value into a data |
| Text | OUT |
|
| Text | OUT |
|
| Text | OUT |
|
| Text | OUT |
|
For mapping complex JSON, see the next section.
Mapping a JSON response payload with OUT parameters using JSONPath query language
The application supports the JSONPath query language (similar to XPath expressions in XML). This language allows you to retrieve specific data from a JSON. For more details regarding the JSONPath syntax, see https://github.com/json-path/JsonPath.
📌 Example
JSON response payload:
For example, here we want to get the names of Charles's grandchildren who are older than seven years old, and we also want these names separated by a |
(using the APP_JSONPATH_DELIMITER
IN parameter). At the same time, we are also getting Elizabeth's age and date of birth. To get the information, the following parameters must be defined:
Parameter | Type | Direction | IN Value | OUT Value |
| Text | IN |
| |
| Text | INOUT |
| data |
| Text | IN |
| |
| Numeric | OUT | data | |
| Text | IN |
| |
| DateTime | OUT | data |
In the
PARAM1__JSONPATH
parameter name, thePARAM1
name is not relevant, but it must be followed by the__JSONPATH
suffix (two underscores are used in the suffix).To retrieve a value into a Text process data, you can use a single INOUT Text parameter (e.g.
PARAM1__JSONPATH
parameter as in the example above).To retrieve a value into a Numeric or DateTime process data, you must use separate parameters: an IN Text parameter for the JSONPath query and an OUT parameter that maps to the Numeric or DateTime process data. Both parameters must share the same name prefix (e.g.
AGE__JSONPATH
andAGE
parameters as in the example above).The default value of
APP_JSONPATH_DELIMITER
is a comma (,
) when this parameter is not defined.
Usage example with Azure REST API to obtain an OAuth 2.0 access token and then create an Event Grid topic
This example shows how to obtain an access token and use it to create an Event Grid topic. This can be done by creating a process with two actions having RESTAPICLIENT as application. The workflow below illustrates this example:
![](https://docs.advantys.com/~gitbook/image?url=https%3A%2F%2Fuser-images.githubusercontent.com%2F22150605%2F56391674-54de8480-61fd-11e9-8b6b-5645563e0d6d.png&width=768&dpr=4&quality=100&sign=6e56a8ce&sv=1)
The next sections describe the parameters that must be declared for each action.
GET_TOKEN
action: Obtaining an OAuth 2.0 access token
GET_TOKEN
action: Obtaining an OAuth 2.0 access tokenThe following parameters are needed to get an access token to use the Azure Resource management API. This token will be stored in the access_token
OUT parameter and will be used when creating an Event Grid topic in the next section.
Parameter | Type | Direction | Value |
| Text | IN |
|
| Text | IN |
|
| Text | IN |
|
| Text | IN |
|
| Text | IN |
|
| Text | IN |
|
| Text | IN |
|
| Text | IN |
|
| Text | OUT |
|
The parameters defined above will generate the following request payload:
Here's the response from the Azure API:
The access_token
OUT parameter is mapped with the access_token
JSON property.
For more details about how to get an access token to use the Azure Resource API, see https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-oauth2-client-creds-grant-flow#request-an-access-token.
CREATE_TOPIC
action: Creating an Event Grid topic
CREATE_TOPIC
action: Creating an Event Grid topicThe following parameters are needed to create an Event Grid topic using the Azure Resource management API.
Parameter | Type | Direction | Value |
| Text | IN |
|
| Text | IN |
|
| Text | IN |
|
| Text | IN |
|
| Text | IN |
|
| Text | IN |
|
| Text | IN |
|
| Text | IN |
|
| Text | IN |
|
The parameters defined above will generate the following request payload:
Here's the response from the Azure API:
For more information about how to create an Event Grid topic and the Azure REST API, see https://docs.microsoft.com/en-us/rest/api/eventgrid/topics/createorupdate.
Enabling SSL/TLS
In case of a Could not create SSL/TLS secure channel
error, strong encryption must be enabled by executing the following code in PowerShell:
Restart your IIS server after executing the commands.
Last updated