Panel

Table of Contents

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

1

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.

Software Requirements for Universal Agent

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.

Software Requirements for Universal Controller

Universal Controller Version 7.1.0.0 and later.

Key Features

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

...

access token.
Support for HTTP Methods GET, POST, PUT, DELETE, PATCH.
Support for SSL Protocol.
Ability to use proxy between Universal Agent and target web service.
Ability for configuration of 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.

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

OAuth2

Token
The request authenticates using an access

key

token.

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

OAuth2

Token

Optional

-

Large Text

The

token for "OAuth2 Token" Authorization Type

authentication access token.

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 Prefixin 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 Options

Required

False

Boolean

Specifies if SSL protocol should be used for the communication with the foreign API

Displays the available SSL options.

SSL

Hostname Check

Certificate Verification

Optional

True

Boolean

Determines if the host name of the certificate should be verified against the hostname in the URL

Enables certificate verification. Certificate verification is auto-enabled in case field "CA Bundle Path" field is populated.

Required when

Use

SSL Options is checked.

Trusted Certificates File

CA Bundle Path

Optional

-

Text

Path and file name of the

trusted certificate or CA

Certificate Authority bundle to use in certificate verification. The file

must

should be in PEM format.

Client Private Key

Certificate

Path

Optional

-

Text

Path and file name of the private key file for SSL client side authentication. The file must be in PEM format.

Public Key

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 Introduced in version 1.1.0	Optional	STDOUT	Choice	Specifies where to print the web service output payload. The following options are applicable. --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 regular expression patterns to exit codes. Provided exit codes should be in the range [100-255].

SSL Certificate Authority File Discovery

If Python 3.7 Distribution for Universal Agent is installed, the path location of the Certificate Authority file must be provided though Trusted Certificates File input field.
If Python is installed on the local system but not with the Universal Agent Distribution:
- If the SSL certificate is signed by a publicly trusted certificate authority (CA), it is not required to provide the certificate.
- If the SSL certificate is self-signed, either the path location of the certificate file must be provided, or the certificate must be stored at the machine's default location for installed certificates (in this case it will be trusted for all applications).
As an alternative to the population of Trusted Certificates File input field, environment variable "REQUESTS_CA_BUNDLE" can be used, which points to the Trusted Certificates File path.

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 web service response body.

This might be useful in the following cases:

...

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, certificates bundled with_certifi_ library shall not be enough. In such cases, the custom certificate 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

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, however it can be used to any SSL Client verification.
Related Universal Task fields:

SSL Options: enabled
SSL Certificate Verification: enabled
CA Bundle Path: populated
Client Certificate Path: populated
Client Private Key Path: populated

For HTTPS provided URL and disabled SSL Options, the established connection will still be secured over SSL protocol, however no certificates will be taken into consideration.

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 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 exit code.

For example, a user can configure the Universal Controller task to retry execution when Exit code is X. Exit code X can be configured by the user when 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 pattern provided as python regular expression is matched, then the configured Exit Code will be applied.

The extension will parse the webservice web service output JSON body and get the value returned by the Path Expression This value will be compared 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 match pattern is foundmatched, the extension will return the corresponding respective Exit Code related to the matched pattern.

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.
- Wrong Path Expression is provided.
- The result body is not of type JSON.
The custom exit codes that

...

intent to be considered successful, they have to be configured during 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 result success task (Ranges can be provided. For example:

...

- 0,100-255).

Task Examples

No Authorization Task Configuration

Example of Universal Task for "None" Authorization Type.

Image RemovedImage Added

Basic Authorization Task Configuration

Example of Universal Task for "Basic" Authorization Type.

Image RemovedImage Added

...

Token Authorization Task Configuration

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

Image Removed

...

An access token can be

...

saved also as a

...

Credential Token field and retrieved with the respective built-in UAC Function.

Image Added

Task Configuration for SSL Protocol

Example of Universal Task for Use SSL Options checked.

Image RemovedImage Added

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

Example of Universal Task for Use SSL Options checked.

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 web service printed to STDOUT.

Image RemovedImage Added

Response Code Output Field

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

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 "101150" if the first contract (contracts[0]) of the "contracts" list has a firstName = "Tom".Task inputs employee is "Tiger Nixon".

Task inputs for Web Service Integration Details.

Image RemovedImage 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 ("

...

150") falls in.

Image RemovedImage Added

Task Results:

Image RemovedImage Added

Task Output

Output Only Fields

Field	Type	Description
Response Code	Text	The

webservice

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.

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

language	text
linenumbers	true

Panel

{
   "exit_code": 101150,
 
  "status_description": "SUCCESS: Task executed successfully with mapped exit code.",
    "invocation": {
  
     "extension": "ue-webservice",
        "version": "1.2.01",
  
     "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": "httphttps://ue-wiremock-dev-noauth.stonebranch.org:8080dummy.restapiexample.com/api/v1/contactsemployees",
            "http_method": "GET",
   
        "timeout": null,
            "url_query_parameters": {},
            "payload_"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": "contactsdata.[0*].firstNameemployee_name",
    
       "exit_code_mapping": {
                "Tom""Tiger Nixon": "101150"
    
       },
   
        "process_exit_code_mapping": true
        }
    },
 
  "result": {
        "code": 200,
        "headers": [
            {
                "header": "Content-TypeEncoding",
                "value": "gzip"application/json"
            },
            {
                "header": "MatchedContent-Stub-IdType",
                "value": "cf796328-38b8-4200-b0e1-c3ac5a83532bapplication/json"
            },
            {
                "header": "Matched-Stub-NameDisplay",
                "value": "GET all contactsstaticcontent_sol, orig_site_sol"
            },
            {
                "header": "VaryResponse",
                "value": "Accept-Encoding, User-Agent200"
            },
            {
                "header": "Content-EncodingVary",
                "value": "gzipAccept-Encoding,User-Agent,Origin"
            },
            {
                "header": "Transfer-Encoding",
                "value": "chunked"
            }

       ],
        "body": "{\n  \"contactsstatus\": [\n    {\n      \"id\"success\",\"data\": [{\"11111id\",\n      \"firstName:1,\"employee_name\": \"TomTiger Nixon\",\n      \"lastNameemployee_salary\": 320800,\"Smithemployee_age\":61,\n      \"email"profile_image\": \"tom.smith@example.com\"},\n      \"dateAdded{\"id\":2,\"employee_name\":\"Garrett Winters\",\"2021-01-03employee_salary\":170750,\n      \"companyId\"employee_age\":63,\"profile_image\": \"123\"\n    },\n    {\n      \"id{\"id\":3,\"employee_name\": \"22222Ashton Cox\",\n      \"firstNameemployee_salary\": 86000,\"Sukiemployee_age\":66,\n      \"lastName"profile_image\": \"Patel\"},\n      \"email{\"id\": 4,\"spatel@example.comemployee_name\",:\n      \"dateAdded"Cedric Kelly\",\"employee_salary\": 433060,\"2020-11-12employee_age\",\n      \"companyId:22,\"profile_image\": \"124\"\n    },\n    {\n      \"id\": 5,\"33333employee_name\",:\n      \"firstName"Airi Satou\",\"employee_salary\": 162700,\"Lexineemployee_age\",\n      \"lastName:33,\"profile_image\": \"Barnfield\"}",\n 
    \"email\body_json": \"barnfield8@example.com\",\n{
      \"dateAdded\status": \"2021-01-03\"success",\n
      \"companyId\data": \"234\"\n[
     }\n  ]\n}",   {
     "body_json": {        "id": 1,
   "contacts": [          "employee_name": "Tiger Nixon",
    {          "employee_salary": 320800,
         "id": 11111,    "employee_age": 61,
               "firstNameprofile_image": "Tom",
          },
         "lastName": "Smith", {
              "id": 2,
    "email": "tom.smith@example.com",         "employee_name": "Garrett Winters",
         "dateAdded": "2021-01-03",      "employee_salary": 170750,
              "companyIdemployee_age": "123"63,
              "profile_image": ""
},          },
      {    {
                ""id": 22222,
     3,
              "firstNameemployee_name": "SukiAshton Cox",
     
              "lastNameemployee_salary": "Patel",
  86000,
                 "email"employee_age": "suki.patel@example.com",
    66,
               "dateAddedprofile_image": "2020-11-12",
          },
         "companyId": "124" {
                },"id": 4,
              "employee_name": "Cedric Kelly",
{              "employee_salary": 433060,
     "id": 33333,        "employee_age": 22,
           "firstName   "profile_image": "Lexine",
          },
         "lastName": "Barnfield", {
                    "email"id": "barnfield@example.com"5,
                    "dateAdded"employee_name": "2021-01-03Airi Satou",
              "employee_salary": 162700,
      "companyId": "234"       "employee_age": 33,
        }      "profile_image": ""
      ]    }
    }  ]
  }
}

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.

...

. Backward compatibility is not guaranteed.

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.

Integration Modifications

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.
- Fields Restriction Section
  The setup of the template does not impose any restrictions, However with respect to "Exit Code Processing Fields" section.
  1. Success/Failure exit codes need to be respected.
  2. 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 for determining success or failure of a task.

Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.

Changelog

ue-webservice 1.2.1 (2022-12-22)

Enhancements

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 ue-webservice-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 literal string (#31224)
Fixed : Parse properly the JSON response when this is a list of objects (#30966)

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

...

Response status on output only field (#26782)
Added: Print Response Body in STDOUT (#26766)

Page Comparison

Versions Compared

Old Version 6

New Version 7

Key

Disclaimer

Overview

Version Information

Software Requirements

Software Requirements for Universal Template and Universal Task

Software Requirements for Universal Agent

Software Requirements for Universal Controller

Key Features

Import the Universal Template

Configure Universal Task

Input Fields

SSL Certificate Authority File Discovery

Exit Code Mapping

Server SSL verification by default CA

Server SSL verification by custom CA

Server and Client SSL verification

Exit Code Mapping

Task Examples

No Authorization Task Configuration

Basic Authorization Task Configuration

Token Authorization Task Configuration

Task Configuration for SSL Protocol

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

Response Code Output Field

Task Configuration for Exit Code Mapping Scenario

Task Output

Output Only Fields

Exit Codes

Extension Output

STDOUT and STDERR

Document References

Document References

Integration Modifications

Changelog

ue-webservice 1.2.1 (2022-12-22)

Enhancements

Fixes

ue-webservice 1.2.0 (2022-06-23)

Deprecations and Breaking Changes

Enhancements

Fixes

ue-webservice 1.1.0 (2022-03-10)

Enhancements