...
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 datacenter. As the integration is triggered from the Universal Agent, no additional firewall port for the Universal Agent needs to be opened.
Version Information
Template Name | Extension Name | Extension Version |
---|---|---|
Web Service Integration | ue-webservice | 1.2.0 |
Software 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.0 or higher. Tested with the Universal Agent bundled Python distribution.
...
Both Windows and Linux agents are supported:.
Universal Agent for Windows x64 Version 7.1.0.0 and later.
Universal Agent for Linux Version 7.1.0.0 and later.
...
This Universal Extension provides the following key features:.
Support for communicating with APIs using the HTTP(S)/REST protocol.
Support for Authorization towards the foreign API using Basic Authentication or OAuth2 token.
Support for HTTP Methods GET, POST, PUT, DELETE, PATCH.
Support for SSL Protocol.
Ability to use proxy between Universal Controller Agent and target web service.
Ability for configuration of custom exit codes based on the web service response payload (Supported for JSON payloads).
...
To use this downloadable 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.
- Download the provided ZIP file.
- In the Universal Controller UI, select Configuration > Universal Templates to display the current list of Universal Templates.
- Click Import Template.
Select the template ZIP file and Import.
...
- To import the Universal Template into your Controller, follow the instructions here.
- When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.
...
Configure Universal Task
For this a new Universal Task type, create a new task, and enter the task-specific details that were created in the Universal Templaterequired 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:.
|
Credentials | Optional | - | Credentials | Credentials for "Basic" Authorization Type. They are comprised of: username The Credentials definition should be as follows.
Required when Authorization Type is "Basic". |
OAuth2 Token | Optional | - | Large Text | The token for "OAuth2 Token" Authorization Type. Required when Authorization Type is "OAuth2 Token". |
Add Authorization Data To | Optional | Request Header | Choice | Specifies where to include the OAuth2 Token in the request. The following options are available:.
Required when Authorization Type is "OAuth2 Token". |
Authorization Header Prefix | Optional | Bearer | Text | The prefix for the OAuth2 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". |
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:.
|
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:.
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:.
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:.
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 | Optional | - | Text | The proxy servers to be used, in the format of values separated by comma. For example: http://ip1:port1,ftp://ip2:port2 |
Use SSL | Required | False | Boolean | Specifies if SSL protocol should be used for the communication with the foreign API. |
SSL Hostname Check | Optional | True | Boolean | Determines if the host name of the certificate should be verified against the hostname in the URL. Required when Use SSL is checked. |
Trusted Certificates File | Optional | - | Text | Path and file name of the trusted certificate or CA bundle to use in certificate verification. The file must be in PEM format. |
Private Key Certificate | Optional | - | Text | Path and file name of the private key file for client side authentication. The file must be in PEM format. |
Public Key Certificate | Optional | - | Text | Path and file name of the public key certificate for 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. Currently available The following options are :applicable.
|
Process Exit Code Mapping
| Required | False | Boolean | 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 that 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. Array that maps patterns to exit codes. Provided exit codes should be in the range [100-255]. |
...
The fields related to this functionality are the following:.
Process Exit Code Mapping
Should be checked to enable this functionality.Path Expression
The JSON Path (JSONPath Syntax).Response Exit Code Mapping
A list of pairs (Pattern/Exit Code). If pattern is matched, then the configured Exit Code will be applied.
...
The following features and restrictions are applied:.
It is possible to provide multiple pairs of Pattern/Exit Code. The first match will be considered.
It is possible to provide an asterisk (*) as a pattern. This will tell the extension to match any value found (catch all).
Provided exit codes should be between 100 and 255.
An error will be raised in case:
No match found.
Wrong Path Expression is provided.
The result body is not of type JSON.
The custom exit codes that from a business perspective are resulting in the success of the task, need to be configured during task configuration or the task will be marked as failed. Configuration can be found under the field group Result Processing Details:
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 result success task (Ranges can be provided. For example: 2,100-255).
...
Example of Universal Task for "None" Authorization Type.
Basic Authorization Task Configuration
Example of Universal Task for "Basic" Authorization Type.
OAuth2 Token Authorization Task Configuration
Example of Universal Task for "OAuth2 Token" Authorization Type.
A token can be fetched with the OAuth2 Token Universal Extension, saved as a variable and used from this Universal Extension.
...
Example of Universal Task for Use SSL checked.
Task Configuration for POST request with JSON payload and use of proxy server
Example of Universal Task for Use SSL checked.
JSON payload used:
...
Example showing the result body of the webservice printed to STDOUT.
Response Code Output Field
Example showing the value of the output field "Response Code" filled with the actual response code from webservice result.
Task Configuration for Exit Code Mapping Scenario
...
Task inputs for Web Service Integration Details.
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
Task Output
Output Only Fields
Field | TypePreserved on re-run | Description | |
---|---|---|---|
Response Code | Text | False | The webservice response code. |
...
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 |
Extension Output
The extension output result has the following fields:
...
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.
Attribute | Type | Description |
---|---|---|
code | number | Response's exit code. |
headers |
...
array | Array of the response's HTTP headers |
...
in header/value format | ||
body | string | Body of the response. |
Extension Output Example
...
language | text |
---|---|
linenumbers | true |
body_json | object | Response Body in JSON format |
An example of the Extension Output for a successful REST API call is presented below.
An example of Extension Output for this Universal Extension is below.
Code Block | ||||
---|---|---|---|---|
| ||||
{ "exit_code": 101, "status_description": "SUCCESS: Task executed successfully with mapped exit code.", "invocation": { "extension": "ue-webservice", "version": "1.02.0", "fields": { "protocol": "HTTP_REST", "http_version": "1.1", "authorization_type": "None", "credentials_user": null, "credentials_password": null, "oauth2_token": "", "add_authorization_data_to": null, "url": "http://ue-wiremock-dev-noauth.stonebranch.org:8080/v1/contacts", "http_method": "GET", "timeout": null, "url_query_parameters": {}, "payload_type": null, "payload_source": null, "mime_type": null, "other_value_for_mime_type": "", "form_data": {}, "payload": "", "payload_script": null, "http_headers": {}, "proxies": "", "use_ssl": false, "trusted_certificates_file": "", "ssl_hostname_check": false, "private_key_certificate": "", "public_key_certificate": "", "result_body_medium": "None", "path_expression": "contacts.[0].firstName", "exit_code_mapping": { "Tom": "101" }, "process_exit_code_mapping": true } }, "result": { "code": 200, "headers": [ { "header": "Content-Type", "value": "application/json" }, { "header": "Matched-Stub-Id", "value": "cf796328-38b8-4200-b0e1-c3ac5a83532b" }, { "header": "Matched-Stub-Name", "value": "GET all contacts" }, { "header": "Vary", "value": "Accept-Encoding, User-Agent" }, { "header": "Content-Encoding", "value": "gzip" }, { "header": "Transfer-Encoding", "value": "chunked" } ], "body": "{\n \"contacts\": [\n {\n \"id\": \"11111\",\n \"firstName\": \"Tom\",\n \"lastName\": \"Smith\",\n \"email\": \"tom.smith@example.com\",\n \"dateAdded\": \"2021-01-03\",\n \"companyId\": \"123\"\n },\n {\n \"id\": \"22222\",\n \"firstName\": \"Suki\",\n \"lastName\": \"Patel\",\n \"email\": \"spatel@example.com\",\n \"dateAdded\": \"2020-11-12\",\n \"companyId\": \"123124\"\n },\n {\n \"id\": \"33333\",\n \"firstName\": \"Lexine\",\n \"lastName\": \"Barnfield\",\n \"email\": \"barnfield8@example.com\",\n \"dateAdded\": \"2021-01-03\",\n \"companyId\": \"234\"\n }\n ]\n}", } } |
Document References
This document references the following documents:
...
Name
...
Location
...
Description
...
Universal Templates
...
https://docs.stonebranch.com/confluence/display/UC72x/Universal+Templates
...
User documentation for creating Universal Templates in the Universal Controller user interface.
...
Universal Tasks
...
https://docs.stonebranch.com/confluence/display/UC72x/Universal+Tasks
...
User documentation for creating Universal Tasks in the Universal Controller user interface.
...
Credentials
...
...
"body_json": {
"contacts": [
{
"id": 11111,
"firstName": "Tom",
"lastName": "Smith",
"email": "tom.smith@example.com",
"dateAdded": "2021-01-03",
"companyId": "123"
},
{
"id": 22222,
"firstName": "Suki",
"lastName": "Patel",
"email": "suki.patel@example.com",
"dateAdded": "2020-11-12",
"companyId": "124"
},
{
"id": 33333,
"firstName": "Lexine",
"lastName": "Barnfield",
"email": "barnfield@example.com",
"dateAdded": "2021-01-03",
"companyId": "234"
}
]
}
}
} |
STDOUT and STDERR
STDOUT and STDERR provide additional information to User. The populated content can be changed in future versions of this extension without notice.
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. |
Credentials | User documentation for creating and working with credentials. |
Resolvable Credentials Permitted Property | User documentation for Resolvable Credentials Permitted Property. |
Changelog
ue-webservice 1.2.0 (2022-06-23)
Deprecations and Breaking Changes
Deprecated
: "Print Result Body to" STDOUT functionality is intended to be used only for informational purposes. Users authoring workflows which read STDOUT from tasks originating from this Universal Template, are encouraged to read this information from EXTENSION_OUTPUT instead of STDOUT. In future releases the Response Body will be part only of EXTENSION_OUTPUT. (#28541)
Enhancements
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)
ue-webservice 1.1.0 (2022-03-10)
Enhancements
Added
: Exit Code Mapping (#27233)Added
: Print Reponse status on output only field (#26782)Added
: Print Response Body in STDOUT (#26766)