| Panel | |
|---|---|
|
Disclaimer
Your use of this download is governed by Stonebranch’s Terms of Use, which are available at Stonebranch Integration Hub - Terms of Use.
Overview
A Web service is a method of communication between two electronic devices over a network. This Universal Extension provides the capability to call endpoints of foreign APIs. It is beneficial for Stonebranch SaaS customers that are accessing the Universal Controller in the Stonebranch AWS Cloud and having their Universal Agents deployed in their data center. As the integration is triggered from the Universal Agent, no additional firewall port for the Universal Agent needs to be opened.
Version Information
...
Requirements
This integration requires a Universal Agent and a Python runtime to execute the Universal Task.
Software Requirements for Universal Template and Universal Task
Requires Python 3.7. Tested with the Universal Agent bundled Python distribution (version 3.7.6)
Software Requirements for Universal Agent
Both Windows and Linux agents are supported.
Universal Agent for Windows x64 Version 7.2.0.0 and later.
Universal Agent for Linux Version 7.2.0.0 and later.
Software Requirements for Universal Controller
Universal Controller Version 7.2.0.0 and later.
Network and Connectivity Requirements
The Universal Agent needs to have connectivity to the Web Service endpoint, Access Token endpoint in case Authentication Type is “OAuth 2.0” and Proxy if the connection is through a Proxy.
Key Features
This Universal Extension provides the following key features.
Actions
Execute Web Service task using HTTP(S)/REST protocol.
Support for HTTP Methods GET, POST, PUT, DELETE, PATCH.
Authentication/Authorization
Support for Basic Authentication, API Keys, Token
Ability to obtain OAuth2 Access token using Resource Owner Password Credentials (aka "Password Credentials") or Client Credentials Grant Types.
Other
Ability to use a proxy between Universal Agent and target endpoint.
Ability to configure custom exit codes based on the web service response payload (Supported for JSON payloads).
Import the Universal Template
To use this downloadable Universal Template, you first must perform the following steps.
...
Configure Universal Task
For a new Universal Task, create a new task, and enter the required input fields.
Input Fields
The input fields for this Universal Extension are described in the following table.
...
Field
...
Input type
...
Default value
...
Type
...
Description
...
Protocol
...
Required
...
HTTP(S)/REST
...
Choice
...
The communication protocol to be used towards the foreign API.
...
HTTP Version
...
Required
...
1.1
...
Choice
...
The Hypertext Transfer Protocol version.
...
Authorization Type
...
Required
...
Basic
...
Choice
...
The authorization type to be used for communicating with the foreign API. The following options are available.
None
No authorization details are sent with the request.Basic
Basic authentication involves sending a username and password with the request.API Key
The request is authorized through the use of an API key.Token
The request is authorized through the use of a known access token. This option is used typically if the access token is retrieved by former task execution.OAuth 2.0
Authorization is completed by getting automatically an access token from an authorization server and then using it to call the web service.
...
Credentials
...
Optional
...
-
...
Credentials
...
Credentials for "Basic" Authorization Type.
The Credentials definition should be as follows.
User as "Runtime User".
Password as "Runtime Password".
Required when Authorization Type is "Basic".
API Key
Introduced in version 1.3.0
...
Credentials for “API Key” Authorization Type. API Key should either be stored as the “Password” or “Token” Credential attribute, during Credential definition.
Required when Authorization Type is “API Key”.
Grant Type
Introduced in version 1.3.0
...
The OAuth 2.0 Grant Type used to get the token. Supported Grant Types are the following.
Password Credentials
Client Credentials
Required when Authorization Type is "OAuth 2.0".
Access Token URL
Introduced in version 1.3.0
...
The endpoint of the Authentication Server for the retrieval of access token. It is used to exchange the Client Credentials (and the Resource Owner Credentials in the case of "Password Credentials" Grant Type) for an access token.
Required when Authorization Type is "OAuth 2.0".
Scope
Introduced in version 1.3.0
...
A space-separated list of scopes used during retrieval of an OAuth 2.0 access token.
Required when Authorization Type is "OAuth 2.0".
Client Credentials
Introduced in version 1.3.0
...
Used for retrieval of OAuth 2.0 access token. The Credential definition should be as follows.
Client ID as "Runtime User". Client ID is the client identifier issued to the client during the client registration process.
Client Secret as "Runtime Password". The Client Secret is issued to the client during the client registration process.
Required when Authorization Type is "OAuth 2.0".
Resource Owner Credentials
Introduced in version 1.3.0
...
Used for retrieval of OAuth 2.0 access token. The Credential definition should be as follows.
User as "Runtime User".
Password as "Runtime Password".
Required when Grant Type is "Password Credentials".
Client Authentication
Introduced in version 1.3.0
...
Controls whether the Client Credentials are sent in the request body or as a basic authentication header during retrieval of OAuth 2.0 access token. The following options are available.
Send as Basic Auth Header.
Send Client Credentials in Body.
Required when Authorization Type is "OAuth 2.0".
...
Token
...
Optional
...
-
...
Large Text
...
The authentication access token.
Required when Authorization Type is "Token".
...
Add Authorization Data To
...
Optional
...
Request Header
...
Choice
...
Specifies where to include the Token in the request. The following options are available.
Request Header
The token is included in the request header with key: "Authorization" and value: <Authorization Header Prefix>< token_value>.Request URL
The token is added as a query parameter in the request with key: "access_token" and value: <token_value>.
Required when Authorization Type is "Token" or "OAuth2.0".
...
Authorization Header Prefix
...
Optional
...
Bearer
...
Text
...
The prefix for the Token.
The token value is appended to the Authorization Header Prefix in the request Authorization header. For example: Bearer <token_value>.
Required when Add Authorization Data To is "Request Header".
Additional Credentials
Introduced in version 1.3.0
...
URL
...
Required
...
-
...
Text
...
The URL to be called.
...
HTTP Method
...
Required
...
GET
...
Choice
...
The HTTP method to be used in the request.
The following options are available.
GET
POST
PUT
PATCH
DELETE
...
Timeout
...
Optional
...
-
...
Integer
...
The time (in seconds) that the request will wait for the server to send data before closing the connection.
If Timeout is not filled, the request will wait (hang) until the connection is closed.
...
URL Query Parameters
...
Optional
...
-
...
Array
...
The list of parameters key/value pairs to be sent in the query string for the request.
...
Payload Type
...
Optional
...
Raw
...
Choice
...
The type of data to be sent in the request body.
The following options are available.
Raw
A "Content-Type" header is set based on the selected MIME Type.Form-Data
"x-www-form-urlencoded" is set as a "Content-Type" header.
Required when HTTP Method is "POST", "PUT" or "PATCH".
...
Payload Source
...
Optional
...
Form
...
Choice
...
For Payload Type of value "Raw", it specifies how the payload will be provided.
The following options are available.
Form
The Payload field will be available to insert the required payload manually.Script
The The Payload Script field will be available to insert the required payload as a script.
Required when Payload Type is "Raw".
...
MIME Type
...
Optional
...
application/json
...
Choice
...
The MIME type to be used in the request's header.
The following options are available.
application/javascript
application/json
application/xml
text/html
text/plain
text/xml
Other
Required when Payload Type is "Raw".
...
Other Value For MIME Type
...
Optional
...
-
...
Text
...
The MIME type to be included in request's header in case "Other" is selected as MIME Type value.
Required when MIME Type is "Other".
...
Form Data
...
Optional
...
-
...
Array
...
The list of parameters key/value pairs to be sent in the request body.
The request header will include ""x-www-form-urlencoded" as a "Content-Type" in this case.
...
Payload
...
Optional
...
-
...
Large Text
...
The payload to be sent in the request body.
Required when Payload Source is "Form".
...
Payload Script
...
Optional
...
-
...
Script
...
The script to be used as a payload source.
Required when Payload Source is "Script".
...
HTTP Headers
...
Optional
...
-
...
Array
...
The list of HTTP Headers key/value pairs to be sent with the request.
If "Content-Type" header is provided, it will be disregarded by the extension, as the MIME Type field is used for this purpose.
Proxies (Deprecated)
Deprecated in version 1.4.0
...
Optional
...
-
...
Text
...
SSL Options
...
Required
...
False
...
Boolean
...
Displays the available SSL options.
...
SSL Certificate Verification
...
Optional
...
True
...
Boolean
...
Enables certificate verification. Certificate verification is auto-enabled in case field "CA Bundle Path" field is populated.
Required when SSL Options is checked.
...
CA Bundle Path
...
Optional
...
-
...
Text
...
Path and file name of the Certificate Authority bundle to use in certificate verification. The file should be in PEM format.
...
Client Private Key Path
...
Optional
...
-
...
Text
...
Path and file name of the private key file for SSL client-side authentication. The file must be in PEM format.
...
Client Certificate Path
...
Optional
...
-
...
Text
...
Path and file name of the public key certificate for SSL client-side authentication. The file must be in PEM format.
Print Result Body To
...
Optional
...
STDOUT
...
Choice
...
Specifies where to print the web service output payload. The following options are applicable.
--None--
STDOUT
Process Exit Code Mapping
...
Required
...
False
...
Boolean
...
The flag that determines whether exit code mapping is enabled or not.
Path Expression
...
Optional
...
-
...
Choice
...
Field visible only when Process Exit Code Mapping is checked and it is required when visible.
The JSON path which is used to check the provided patterns that are set up on the Response Exit Code Mapping array.
Response Exit Code Mapping
...
Optional
...
-
...
Array
...
Field visible only when Process Exit Code Mapping is checked and it is required when visible.
An array that maps regular expression patterns to exit codes.
Provided exit codes should be in the range [100-255].
SSL Certificate Authority File Discovery
This Universal Extension is bundled with certifi library, utilized as the default certificate discovery mechanism. However, more complex SSL verification scenarios are supported, according to the configured fields as described below.
Server SSL verification by default CA
Certifi provides a wide range of certificates signed by well-known Certificate Authorities, used for SSL Server verification.
Related Universal Task fields:
- SSL Options: Enabled
- SSL Certificate Verification: Enabled
Server SSL verification by custom CA
For SSL Server verification against hosts that have certificates signed by a custom Certificate Authority, a Certificate Authority Bundle should be provided as input.
Related Universal Task fields:
- SSL Options: Enabled
- SSL Certificate Verification: Enabled
- CA Bundle Path: Populated
Server and Client SSL verification
An additional security layer can be achieved with two-way SSL verification, where both the Server is verified by the Client, and the Client is verified by the Server. This scenario is common for hosts with self-signed certificate.
Related Universal Task fields:
- SSL Options: Enabled
- SSL Certificate Verification: Enabled
- CA Bundle Path: Populated
- Client Certificate Path: Populated
- Client Private Key Path: Populated
| Info |
|---|
When the communication between the client and the server is based on HTTPS and SSL Certificate Verification is not enabled, communication is still encrypted. However, certificates are not verified. An appropriate warning is printed on the STDERR output |
Exit Code Mapping
As part of task configuration, it is possible for the user to define custom exit codes that depend on the contents of the web service response body.
This might be useful in the following cases:
When the task is used in a workflow and based on the contents of the web service response body the workflow needs to follow a different path. Exit codes can be used in workflows to follow different branches.
When retry needs to be configured, based on the content of the web service response body. Task retry can be configured based on the exit code.
For example, a user can configure the Universal Controller task to retry execution when the exit code is X. Exit code X can be configured by the user when the web service response payload field JSON "document.status" is equal to value "Under Processing".
The fields related to this functionality are the following.
Process Exit Code Mapping
Should be checked to enable this functionality.Path Expression
The JSONPath expression (JSONPath Syntax).Response Exit Code Mapping
A list of pairs (Pattern/Exit Code). If the pattern provided as python regular expression is matched, then the configured exit code will be applied.
The web service output JSON body is parsed with the Path Expression. The matched response body content is evaluated against the list of patterns provided on Response Exit code Mapping array. When a pattern is matched, the extension will return the respective exit code.
The following features and restrictions are applied.
It is possible to provide multiple pairs of Pattern/Exit Code. The extension will return the corresponding exit code, on the first match in the array.
Provide
.*as a pattern, to match any value returned by the JSONPath.Provided exit codes should be between 100 and 255.
An error will be raised in case:
No match found.
A Wrong Path Expression is provided.
The result body is not of type JSON.
The custom exit codes that intend to be considered successful, have to be configured appropriately in the Result Processing Details section.
Exit Code Processing
Option "Success Exit Code Range" to be selected in this field.Exit Codes
To be filled with the list of exit codes that the user expects to reflect successful execution (Ranges can be provided. For example 0,100-255).
Passing Credentials as Query Parameters, Headers, or as Form Data
There are cases where the endpoint might require credentials to be passed either as part of Query Parameters, as Headers or in a URL-encoded form. For example, Mulesoft APIs can include Client ID Enforcement Policy for which a Client ID and a Client Secret are mandatory to be passed on top of other authorization/authentication inputs.
Additional Query Parameters can be passed through the "URL Query Parameters" field, additional HTTP Headers can be passed through the "HTTP Headers" field and form data can be passed through the "Form Data" field. All of them are Array fields. Array "Name" represents the Query Parameter Name, the Header Name, or the Form Data Key, and "Value" represents the value to be used. “Value” could be a specific string, or be in the format of [credential_name].attribute where
credential_name:The name of a Credential which is selected by a Credential field used in the task. Only Credential names that are selected in the task's credential fields can be used.attribute:The attribute of the specific Credential with possible values being the following.user
password
passphrase
token
If the provided credential_name is a valid Credential name and attribute is in the above domain, then a match is found and the specific Credential attribute is used. Else the provided input is used as a literal string.
Example: Let's suppose that a credential with name = "valid_credential_name" and password = "example_pass" is passed to a task. The expression [valid_credential_name].password will be resolved to example_pass.
...
Set Proxies with Environment Variables
If a proxy is required to route the traffic between the Universal Task and the configured endpoint, then HTTP_PROXY and/or HTTPS_PROXY environment variables need to be set. HTTP_PROXY environment variable defines the proxy used in case of HTTP communication between the Universal Task and the endpoint, while the HTTPS_PROXY environment variable defines the proxy used in case of HTTPS communication between the Universal Task and the endpoint. In the majority of cases, only one proxy is used that routes both HTTP and HTTPS traffic (in such cases HTTP_PROXY/HTTPS_PROXY environment variables point to the same value).
The format is explained by the following examples.
Passing a single proxy for HTTP and HTTPS traffic
Passing different proxies with credentials for HTTP and HTTPS traffic
Task Examples
No Authorization With Exit Code Mapping Task Configuration
Example of Universal Task for "None" Authorization Type where the user expects an exit code equal to "101" if the employee's first name is "John".
Task Inputs for Result Processing Details:
Here the Exit Codes field is filled with two elements, "0" and the range [100-255] where the expected exit code "101" falls in.
Task Results:
Printing Result Body to STDOUT
Example showing the result body of the web service printed to STDOUT.
Basic Authorization Task Configuration for a POST request with JSON payload
Example of Universal Task for "Basic" Authorization Type.
...
Example of Universal Task for "Token" Authorization Type with URL Query parameters.
API Key Authorization Task Configuration
Example of Universal Task for "API Key" Authorization Type.
To see how to pass the API Key as HTTP Header refer to Passing Credentials as Query Parameters, Headers, or as Form Data.
OAuth2.0 Authorization Task Configuration
Example of Universal Task for "OAuth2.0" Authorization Type with client credentials grant type.
To see how to pass credential fields as HTTP Headers refer to Passing Credentials as Query Parameters, Headers, or as Form Data.
Example of Universal Task for "OAuth2.0" Authorization Type with password credentials grant type.
Task Configuration with SSL Client Authentication
Example of a Universal Task with SSL Client Authentication.
Mulesoft Example
The following example shows the configuration of a task for a call to a Mulesoft API that has OpenID Connect access token enforcement and Client ID Enforcement policies enabled and when Okta is used as a Client Provider. OAuth2 Client Credentials flow is used in the following example.
Task Configuration
As it's evident from the Client ID enforcement configuration, Client Credentials are also passed as HTTP Headers.
To see how to pass the client credentials as HTTP Headers refer to Passing Credentials as Query Parameters, Headers, or as Form Data.
Task Output
Output Only Fields
...
Field
...
Type
...
Description
...
Response Code
...
Text
...
The web service response code.
Exit Codes
The exit codes for this Universal Extension are described in the following table.
...
Exit Code
...
Status Classification Code
...
Status Classification Description
...
Status Description
...
0
...
SUCCESS
...
Successful Execution
...
SUCCESS: Task executed successfully <Additional information>.
...
1
...
FAIL
...
Failed Execution
...
FAIL: <Unexpected error description>
...
3
...
AUTHORIZATION_ERROR
...
Insufficient Permissions
...
AUTHORIZATION_ERROR: The authorization credentials provided for the request are invalid.
...
21
...
FOREIGN_API_REQUEST_ERROR
...
Bad request to third party API
...
FOREIGN_API_REQUEST_ERROR: Client side error when sending the request.
...
22
...
FOREIGN_API_RESPONSE_ERROR
...
Validation error response from third party API
...
FOREIGN_API_RESPONSE_ERROR: Server side error.
...
23
...
FOREIGN_SERVER_ERROR
...
Destination URL not found or redirected
...
FOREIGN_SERVER_ERROR: Not Found
...
24
...
EXIT_CODE_MAPPING_ERROR
...
Error occurred during Exit Code Mapping
...
EXIT_CODE_MAPPING_ERROR: Invalid Path Expression
EXIT_CODE_MAPPING_ERROR: No match found for the provided expression
EXIT_CODE_MAPPING_ERROR: Response body not in JSON format
EXIT_CODE_MAPPING_ERROR: Unable to parse the JSON body
Extension Output
In the context of a workflow, subsequent tasks can rely on the information provided by this integration as Extension Output.
result section includes the following attributes.
...
An example of the Extension Output for a successful REST API call is presented below.
| Panel |
|---|
|
STDOUT and STDERR
| Panel | |
|---|---|
|
Disclaimer
Your use of this download is governed by Stonebranch’s Terms of Use, which are available at Stonebranch Integration Hub - Terms of Use.
Version Information
| Template Name | Extension Name | Extension Version |
|---|---|---|
| Web Service Integration | ue-webservice | 1.4.1 |
Refer to the Changelog for version history information.
Overview
A Web service is a method of communication between two electronic devices over a network. This Universal Extension provides the capability to call endpoints of foreign APIs. It is beneficial for Stonebranch SaaS customers that are accessing the Universal Controller in the Stonebranch AWS Cloud and having their Universal Agents deployed in their data center. As the integration is triggered from the Universal Agent, no additional firewall port for the Universal Agent needs to be opened.
Key Features
Feature | Description |
|---|---|
Send HTTP(S)/REST requests | This integration supports sending requests over HTTP(S)/REST protocol, using the following methods:
|
Connectivity and Authentication Options | A variety of authentication options are supported:
Additionally, a Proxy server can be configured to be used between the Universal Agent and target endpoint. |
Custom exit code processing | This integration provides the capability to the user, to configure custom exit codes based on the web service response payload (Supported for JSON payloads). |
Requirements
This integration requires a Universal Agent and a Python runtime to execute the Universal Task.
Area | Details |
|---|---|
Python Version | Requires Python 3.7. Tested with the Universal Agent bundled Python distribution (version 3.7.16) |
Universal Agent | Both Windows and Linux agents are supported:
|
Universal Controller | Universal Controller Version >= 7.2.0.0. |
Network and Connectivity | The Universal Agent needs to have connectivity to the Web Service endpoint, and Access Token endpoint in case Authentication Type is “OAuth 2.0” and Proxy if the connection is through a Proxy. |
Supported Actions
This integration is responsible for sending HTTP(S)/REST requests.
Configuration examples
The following examples demonstrate the available authentication types, combined with some of the key features of this integration.
Example 1: No Authorization With Exit Code Mapping Task Configuration
Example of Universal Task for "None" Authorization Type where the user expects an exit code equal to "101" if the employee's first name is "John".
Example 2: Basic Authorization Task Configuration for a POST request with JSON payload
Example of Universal Task for "Basic" Authorization Type.
Example 3: Token Authorization Task Configuration with URL Query parameters
Example of Universal Task for "Token" Authorization Type with URL Query parameters.
Example 4: API Key Authorization Task Configuration
| Anchor | ||||
|---|---|---|---|---|
|
Example of Universal Task for "API Key" Authorization Type.
To see how to pass the API Key as HTTP Header refer to Passing Credentials as Query Parameters, Headers, or as Form Data.
Example 5: OAuth2.0 Authorization Task Configuration
Example of Universal Task for "OAuth2.0" Authorization Type with client credentials grant type.
To see how to pass credential fields as HTTP Headers refer to Passing Credentials as Query Parameters, Headers, or as Form Data.
|  |
|---|---|
| User Scenario: Example of Universal Task for "OAuth2.0" Authorization Type with client credentials grant type | User Scenario: Example of Universal Task for "OAuth2.0" Authorization Type with password credentials grant type. |
Example 6: Task Configuration with SSL Client Authentication
Example of a Universal Task with SSL Client Authentication.
Example 7: Mulesoft
The following example shows the configuration of a task for a call to a Mulesoft API that has OpenID Connect access token enforcement and Client ID Enforcement policies enabled and when Okta is used as a Client Provider. OAuth2 Client Credentials flow is used in the following example.
Task Configuration
As it's evident from the Client ID enforcement configuration, Client Credentials are also passed as HTTP Headers.
To see how to pass the client credentials as HTTP Headers refer to Passing Credentials as Query Parameters, Headers, or as Form Data.
Action Output
Output Type | Description (Successful Execution) | Example (Successful Execution) | |||||
|---|---|---|---|---|---|---|---|
EXTENSION | The extension output provides the following information:
|
| |||||
STDOUT | If the field “Print Result Body To” is set to STDOUT, the body of the response will be printed here. |
|
Input Fields
Field | Type | Default value | Required | Description | Introduced In Version |
|---|---|---|---|---|---|
Protocol | Choice | HTTP(S)/REST | Required | The communication protocol to be used towards the foreign API. | |
HTTP Version | Choice | 1.1 | Required | The Hypertext Transfer Protocol version. | |
Authorization Type | Choice | Basic | Required | The authorization type to be used for communicating with the foreign API. The following options are available.
| |
Credentials | Credentials | - | Optional | Credentials for "Basic" Authorization Type. The Credentials definition should be as follows.
Required when Authorization Type is "Basic". | |
API Key | Credentials | - | Optional | Credentials for “API Key” Authorization Type. API Key should either be stored as the “Password” or “Token” Credential attribute, during Credential definition. API Keys can either be provided as URL Query Parameters or as Request Headers. Example configuration is described in section API Key Authorization Task Configuration. Required when Authorization Type is “API Key”. | Introduced in version 1.3.0 |
Grant Type | Choice | Client Credentials | Optional | The OAuth 2.0 Grant Type used to get the token. Supported Grant Types are the following.
Required when Authorization Type is "OAuth 2.0". | Introduced in version 1.3.0 |
Access Token URL | Text | Optional | The endpoint of the Authentication Server for the retrieval of access token. It is used to exchange the Client Credentials (and the Resource Owner Credentials in the case of "Password Credentials" Grant Type) for an access token. Required when Authorization Type is "OAuth 2.0". | Introduced in version 1.3.0 | |
Scope | Text | - | Optional | A space-separated list of scopes used during retrieval of an OAuth 2.0 access token. Required when Authorization Type is "OAuth 2.0". | Introduced in version 1.3.0 |
Client Credentials | Credentials | - | Optional | Used for retrieval of OAuth 2.0 access token. The Credential definition should be as follows.
Required when Authorization Type is "OAuth 2.0". | Introduced in version 1.3.0 |
Resource Owner Credentials | Credentials | - | Optional | Used for retrieval of OAuth 2.0 access token. The Credential definition should be as follows.
Required when Grant Type is "Password Credentials". | Introduced in version 1.3.0 |
Client Authentication | Choice | Send Client Credentials in Body | Optional | Controls whether the Client Credentials are sent in the request body or as a basic authentication header during retrieval of OAuth 2.0 access token. The following options are available.
Required when Authorization Type is "OAuth 2.0". | Introduced in version 1.3.0 |
Token | Large Text | - | Optional | The authentication access token. Required when Authorization Type is "Token". | |
Add Authorization Data To | Choice | Request Header | Optional | Specifies where to include the Token in the request. The following options are available.
Required when Authorization Type is "Token" or "OAuth2.0". | |
Authorization Header Prefix | Text | Bearer | Optional | The prefix for the Token. The token value is appended to the Authorization Header Prefix in the request Authorization header. For example: Bearer <token_value>. Required when Add Authorization Data To is "Request Header". | |
Additional Credentials | Credentials | - | Optional | Additional credentials that might be required to be used either as Query Parameters or as HTTP Headers. For more information on how to pass credentials as part of URL Query Parameters refer to Passing Credentials as Query Parameters, Headers, or as Form Data. | Introduced in version 1.3.0 |
URL | Text | - | Required | The URL to be called. | |
HTTP Method | Choice | GET | Required | The HTTP method to be used in the request. The following options are available.
| |
Timeout | Integer | - | Optional | The time (in seconds) that the request will wait for the server to send data before closing the connection. If Timeout is not filled, the request will wait (hang) until the connection is closed. | |
URL Query Parameters | Array | - | Optional | The list of parameters key/value pairs to be sent in the query string for the request. | |
Payload Type | Choice | Raw | Optional | The type of data to be sent in the request body. The following options are available.
Required when HTTP Method is "POST", "PUT" or "PATCH". | |
Payload Source | Choice | Form | Optional | For Payload Type of value "Raw", it specifies how the payload will be provided. The following options are available.
Required when Payload Type is "Raw". | |
MIME Type | Choice | application/json | Optional | The MIME type to be used in the request's header. The following options are available.
Required when Payload Type is "Raw". | |
Other Value For MIME Type | Text | - | Optional | The MIME type to be included in request's header in case "Other" is selected as MIME Type value. Required when MIME Type is "Other". | |
Form Data | Array | - | Optional | The list of parameters key/value pairs to be sent in the request body. The request header will include ""x-www-form-urlencoded" as a "Content-Type" in this case. | |
Payload | Large Text | - | Optional | The payload to be sent in the request body. Required when Payload Source is "Form". | |
Payload Script | Script | - | Optional | The script to be used as a payload source. Required when Payload Source is "Script". | |
HTTP Headers | Array | - | Optional | The list of HTTP Headers key/value pairs to be sent with the request. If "Content-Type" header is provided, it will be disregarded by the extension, as the MIME Type field is used for this purpose. | |
Proxies (Deprecated) Deprecated in version 1.4.0 | Text | - | Optional | The field is deprecated. For backward compatibility reasons, the field is kept and functioning as of version 1.3.1. However, it is strongly advised to migrate the task definition to the new logic to avoid disruptions in the future. For more information refer to Set Proxies with Environment Variables and Known Issues. | |
SSL Options | Boolean | False | Required | Displays the available SSL options. | |
SSL Certificate Verification | Boolean | True | Optional | Enables certificate verification. Certificate verification is auto-enabled in case field "CA Bundle Path" field is populated. Required when SSL Options is checked. | |
CA Bundle Path | Text | - | Optional | Path and file name of the Certificate Authority bundle to use in certificate verification. The file should be in PEM format. | |
Client Private Key Path | Text | - | Optional | Path and file name of the private key file for SSL client-side authentication. The file must be in PEM format. | |
Client Certificate Path | Text | - | Optional | Path and file name of the public key certificate for SSL client-side authentication. The file must be in PEM format. | |
Print Result Body To | Choice | STDOUT | Optional | Specifies where to print the web service output payload. The following options are applicable.
| Introduced in version 1.1.0 |
Process Exit Code Mapping | Boolean | False | Required | The flag that determines whether exit code mapping is enabled or not. | Introduced in version 1.1.0 |
Path Expression | Choice | - | Optional | Field visible only when Process Exit Code Mapping is checked and it is required when visible. The JSON path which is used to check the provided patterns that are set up on the Response Exit Code Mapping array. | Introduced in version 1.1.0 |
Response Exit Code Mapping | Array | - | Optional | Field visible only when Process Exit Code Mapping is checked and it is required when visible. An array that maps regular expression patterns to exit codes. Provided exit codes should be in the range [100-255]. | Introduced in version 1.1.0 |
SSL Certificate Authority File Discovery
This Universal Extension is bundled with certifi library, utilized as the default certificate discovery mechanism. However, more complex SSL verification scenarios are supported, according to the configured fields as described below.
Server SSL verification by default CA
Certifi provides a wide range of certificates signed by well-known Certificate Authorities, used for SSL Server verification.
Related Universal Task fields:
- SSL Options: Enabled
- SSL Certificate Verification: Enabled
Server SSL verification by custom CA
For SSL Server verification against hosts that have certificates signed by a custom Certificate Authority, a Certificate Authority Bundle should be provided as input.
Related Universal Task fields:
- SSL Options: Enabled
- SSL Certificate Verification: Enabled
- CA Bundle Path: Populated
SSL Client Authentication
An additional security layer can be achieved with two-way SSL verification, where both the Server is verified by the Client, and the Client is verified by the Server. This scenario is common for hosts with self-signed certificate.
Related Universal Task fields:
- SSL Options: Enabled
- SSL Certificate Verification: Enabled
- CA Bundle Path: Populated
- Client Certificate Path: Populated
- Client Private Key Path: Populated
| Info |
|---|
When the communication between the client and the server is based on HTTPS and SSL Certificate Verification is not enabled, communication is still encrypted. However, certificates are not verified. An appropriate warning is printed on the STDERR output |
Exit Code Mapping
As part of task configuration, it is possible for the user to define custom exit codes that depend on the contents of the web service response body.
This might be useful in the following cases:
When the task is used in a workflow and based on the contents of the web service response body the workflow needs to follow a different path. Exit codes can be used in workflows to follow different branches.
When retry needs to be configured, based on the content of the web service response body. Task retry can be configured based on the exit code.
For example, a user can configure the Universal Controller task to retry execution when the exit code is X. Exit code X can be configured by the user when the web service response payload field JSON "document.status" is equal to value "Under Processing".
The fields related to this functionality are the following.
Process Exit Code Mapping
Should be checked to enable this functionality.Path Expression
The JSONPath expression (JSONPath Syntax).Response Exit Code Mapping
A list of pairs (Pattern/Exit Code). If the pattern provided as python regular expression is matched, then the configured exit code will be applied.
The web service output JSON body is parsed with the Path Expression. The matched response body content is evaluated against the list of patterns provided on Response Exit code Mapping array. When a pattern is matched, the extension will return the respective exit code.
The following features and restrictions are applied.
It is possible to provide multiple pairs of Pattern/Exit Code. The extension will return the corresponding exit code, on the first match in the array.
Provide
.*as a pattern, to match any value returned by the JSONPath.Provided exit codes should be between 100 and 255.
An error will be raised in case:
No match found.
A Wrong Path Expression is provided.
The result body is not of type JSON.
The custom exit codes that intend to be considered successful, have to be configured appropriately in the Result Processing Details section.
Exit Code Processing
Option "Success Exit Code Range" to be selected in this field.Exit Codes
To be filled with the list of exit codes that the user expects to reflect successful execution (Ranges can be provided. For example 0,100-255).
Passing Credentials as Query Parameters, Headers, or as Form Data
| Anchor | ||||
|---|---|---|---|---|
|
There are cases where the endpoint might require credentials to be passed either as part of Query Parameters, as Headers or in a URL-encoded form. For example, Mulesoft APIs can include Client ID Enforcement Policy for which a Client ID and a Client Secret are mandatory to be passed on top of other authorization/authentication inputs.
Additional Query Parameters can be passed through the "URL Query Parameters" field, additional HTTP Headers can be passed through the "HTTP Headers" field and form data can be passed through the "Form Data" field. All of them are Array fields. Array "Name" represents the Query Parameter Name, the Header Name, or the Form Data Key, and "Value" represents the value to be used. “Value” could be a specific string, or be in the format of [credential_name].attribute where
credential_name:The name of a Credential which is selected by a Credential field used in the task. Only Credential names that are selected in the task's credential fields can be used.attribute:The attribute of the specific Credential with possible values being the following.user
password
passphrase
token
If the provided credential_name is a valid Credential name and attribute is in the above domain, then a match is found and the specific Credential attribute is used. Else the provided input is used as a literal string.
Example: Let's suppose that a credential with name = "valid_credential_name" and password = "example_pass" is passed to a task. The expression [valid_credential_name].password will be resolved to example_pass.
Set Proxies with Environment Variables
| Anchor | ||||
|---|---|---|---|---|
|
If a proxy is required to route the traffic between the Universal Task and the configured endpoint, then HTTP_PROXY and/or HTTPS_PROXY environment variables need to be set. HTTP_PROXY environment variable defines the proxy used in case of HTTP communication between the Universal Task and the endpoint, while the HTTPS_PROXY environment variable defines the proxy used in case of HTTPS communication between the Universal Task and the endpoint. In the majority of cases, only one proxy is used that routes both HTTP and HTTPS traffic (in such cases HTTP_PROXY/HTTPS_PROXY environment variables point to the same value).
The format is explained by the following examples.
Configuration Examples
| | |
|---|---|
| User Scenario: Passing a single proxy for HTTP and HTTPS traffic | User Scenario: Passing different proxies with credentials for HTTP and HTTPS traffic |
Output Fields
Field | Type | Description | Introduced in Version |
|---|---|---|---|
Response Code | Text | The webservice response code. | Introduced in version 1.0.0 |
Exit Codes
The exit codes for this Universal Extension are described in the following table.
Exit Code | Status Classification Code | Status Classification Description | Status Description |
|---|---|---|---|
0 | SUCCESS | Successful Execution | SUCCESS: Task executed successfully <Additional information>. |
1 | FAIL | Failed Execution | FAIL: <Unexpected error description> |
3 | AUTHORIZATION_ERROR | Insufficient Permissions | AUTHORIZATION_ERROR: The authorization credentials provided for the request are invalid. |
21 | FOREIGN_API_REQUEST_ERROR | Bad request to third-party API | FOREIGN_API_REQUEST_ERROR: Client side error when sending the request. |
22 | FOREIGN_API_RESPONSE_ERROR | Validation error response from third-party API | FOREIGN_API_RESPONSE_ERROR: Server side error. |
23 | FOREIGN_SERVER_ERROR | Destination URL not found or redirected | FOREIGN_SERVER_ERROR: Not Found |
24 | EXIT_CODE_MAPPING_ERROR | An error occurred during Exit Code Mapping | EXIT_CODE_MAPPING_ERROR: Invalid Path Expression |
STDOUT and STDERR
| Note |
|---|
STDOUT and STDERR provide additional information to User. The populated content can be changed in future versions |
...
without notice. |
...
Backward compatibility is |
...
Document References
This document references the following documents.
...
Integration Modifications
not guaranteed. |
How To
Import Universal Template
To use the Universal Template, you first must perform the following steps.
This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.
To import the Universal Template into your Controller, follow these instructions.
When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.
Modifications of this integration, applied by users or customers, before or after import, might affect the supportability of this integration. For more information refer to Integration Modifications.
Configure Universal Task
For a new Universal Task, create a new task, and enter the required input fields.
Integration Modifications
| Anchor | ||||
|---|---|---|---|---|
|
Modifications applied by users or customers, before or after import, might affect the supportability of this integration. The following modifications are discouraged to retain the support level as applied for this integration.
Python code modifications should not be done.
Template Modifications
General Section
"Name", "Extension", "Variable Prefix", "Icon" should not be changed.
Universal Template Details Section
"Template Type", "Agent Type", "Send Extension Variables", "Always Cancel on Force Finish" should not be changed.
Result Processing Defaults Section
Success and Failure Exit codes can be changed according to users' needs.
Fields Restriction Section
The setup of the template does not impose any restrictions. However,
...
with respect to the "Exit Code Processing
...
" section.
Success/Failure exit codes need to be respected.
In principle, as STDERR and STDOUT outputs can change in follow-up releases of this integration, they should not be considered as a reliable source
...
Users and customers are encouraged to report defects or feature requests at Stonebranch Support Desk.
...
for determining the success or failure of a task.
Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.
Document References
This document references the following documents.
| Document Link | Description |
|---|---|
| Universal Templates | User documentation for creating, working with and understanding Universal Templates and Integrations. |
| Universal Tasks | User documentation for creating Universal Tasks in the Universal Controller user interface. |
| Anchor | ||||
|---|---|---|---|---|
|
Known Issues
- The "proxies" field does not work correctly in some cases. Task authors are advised to use HTTP_PROXY and HTTPS_PROXY environment variables on task definition, or alternatively set those variables on the runtime user environment, leaving this field empty. For more information refer to Set Proxies with Environment Variables.
| Anchor | ||||
|---|---|---|---|---|
|
...
Changelog
ue-webservice 1.4.1 (2023-10-18)
Fixes
Fixed:Fix URL validation introduced on 1.3.0 (#34401)
ue-webservice 1.4.0 (2023-07-26)
...
Deprecated: "Proxies" field is deprecated. For backward compatibility reasons, the field is kept and functioning as of version 1.3.1. However, it is strongly advised to migrate the task definition to the new logic to avoid disruptions in the future. For more information refer to Set Proxies with Environment Variables and Known Issues. (#33623)
Enhancements
Added: Support for passing additional credential information in URL-Encoded Form (#33612)
ue-webservice 1.3.1 (2023-04-28)
Fixes
Fixed: STDOUT should include only the body of the webservice response (#32520)Fixed: Misleading warning message "...not designated as Output Only" is removed from UC logs (#32394)Fixed: Security Enhancements (#32631)
...
Changed: The following Input Field Labels are improved to bring more context on the surrounding functionality (#31203):- Choice OAuth2Token in Authorization Type renamed to: Token
- Optional text field OAuthToken renamed to: Token
- Checkbox field Use SSL renamed to: SSL Options
- Checkbox field SSL Hostname Check renamed to: SSL Certificate Verification
- Optional text field Trusted Certificate File renamed to: CA Bundle Path
- Optional text field Public Key Certificate renamed to: Client Certificate Path
- Optional text field Private Key Certificate renamed to: Client Private Key Path
Changed: Payload input field is not mandatory anymore (#30639)
Up to ue-webservice-1.2.0, input field Payload was mandatory for HTTP Methods POST, PUT, PATCH. Starting from version 1.2.1 it is not necessary to provide data payload.
Fixes
Fixed: Field Pattern in Response Exit Code Mapping table is now evaluated as python regular expression, instead of a literal string (#31224)Fixed: Parse properly the JSON response when this is a list of objects (#30966)
...
Added: JSON body response formatted and printed in the Extension Output in new JSON attribute 'body_json' (#28541)
Fixes
Fixed: JSON body was not printed on STDOUT in certain cases of content-type combinations (#28080)
...