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. OAuth2 Token The request authenticates using an access key.
Credentials	Optional	-	Credentials	Credentials for "Basic" Authorization Type. They are comprised of: username password 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: 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 "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: 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 manually insert the required payload. 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	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 Introduced in version 1.1.0	Optional	STDOUT	Choice	Specifies where to print the web service output payload. Currently available options are: --None-- STDOUT
Process Exit Code Mapping Introduced in version 1.1.0	Required	False	Boolean	Flag that determines whether exit code mapping is enabled or not.
Path Expression Introduced in version 1.1.0	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 Introduced in version 1.1.0	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].

SSL Certificate Authority File Discovery

...

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).

Task Examples

No Authorization Task Configuration

Example of Universal Task for "None" Authorization Type.

Image Added

Basic Authorization Task Configuration

Example of Universal Task for "Basic" Authorization Type.

Image Added

OAuth2 Token Authorization Task Configuration

Example of Universal Task for "OAuth2 Token" Authorization Type.

Image Added

A token can be fetched with the OAuth2 Token Universal Extension, saved as a variable and used from this Universal Extension.

Task Configuration for SSL Protocol

Example of Universal Task for Use SSL checked.

Image Added

Task Configuration for POST request with JSON payload and use of proxy server

Example of Universal Task for Use SSL checked.

Image Added

JSON payload used:

Code Block

language	text
linenumbers	true

{
  "first name": "John",
  "last name": "Smith"
}

Printing Result Body to STDOUT

Example showing the result body of the webservice printed to STDOUT.

Image Added

Response Code Output Field

Example showing the value of the output field "Response Code" filled with the actual response code from webservice result.

Image Added

Task Configuration for Exit Code Mapping Scenario

The following example scenario describes the configuration of a task where the user expects an exit code equal to "101" if the first contract (contracts[0]) of the "contracts" list has a firstName = "Tom".

Task inputs for Web Service Integration Details.

Image Added

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.

Image Added

Task Results

Image Added

Task Output

Output Fields

Field	Type	Preserved on re-run	Description
Response Code	Text	False	The webservice 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

The extension output result has the following fields:

code
Response's exit code.
headers
List of the response's HTTP headers.
body
Body of the response.

Extension Output Example

Code Block

language	text
linenumbers	true

{
    "exit_code": 101,
    "status_description": "SUCCESS: Task executed successfully with mapped exit code.",
    "invocation": {
        "extension": "ue-webservice",
        "version": "1.0.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\": \"123\"\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/UC71x/Universal+Templates	User documentation for creating Universal Templates in the Universal Controller user interface.
Credentials	https://docs.stonebranch.com/confluence/display/UC71x/Credentials#Credentials-CredentialDetailsFieldDescriptions	User Documentation for Credentials Details Field Description
Universal Tasks	https://docs.stonebranch.com/confluence/display/UC71x/Universal+Tasks	User documentation for creating Universal Tasks in the Universal Controller user interface.

Versions Compared

Old Version 2

New Version 3

Key

SSL Certificate Authority File Discovery

Task Examples

No Authorization Task Configuration

Basic Authorization Task Configuration

OAuth2 Token Authorization Task Configuration

Task Configuration for SSL Protocol

Task Configuration for POST request with JSON payload and use of proxy server

Printing Result Body to STDOUT

Response Code Output Field

Task Configuration for Exit Code Mapping Scenario

Task Inputs for Result Processing Details

Task Results

Task Output

Output Fields

Exit Codes

Extension Output

Extension Output Example

Document References

Page Comparison

Versions Compared

Old Version 2

New Version 3

Key

SSL Certificate Authority File Discovery

Task Examples

No Authorization Task Configuration

Basic Authorization Task Configuration

OAuth2 Token Authorization Task Configuration

Task Configuration for SSL Protocol

Task Configuration for POST request with JSON payload and use of proxy server

Printing Result Body to STDOUT

Response Code Output Field

Task Configuration for Exit Code Mapping Scenario

Task Inputs for Result Processing Details

Task Results

Task Output

Output Fields

Exit Codes

Extension Output

Extension Output Example

Document References