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

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:

GET
POST
PUT
DELETE
PATCH

Connectivity and Authentication Options

A variety of authentication options are supported:

Basic Authentication
API Keys
OAuth 2.0
SSL Client Authentication

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 Agent for Windows x64 >= 7.3.0.0. Universal Agent for Linux Version >= 7.3.0.0.
Universal Controller	Universal Controller Version >= 7.3.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

Example of Universal Task for "API Key" Authorization Type.

To see how to pass the API Key as HTTP Header refer to 150084807.

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

Example of Universal Task for "OAuth2.0" Authorization Type with client credentials grant type

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

Action Output

Output Type

Description (Successful Execution)

Example (Successful Execution)

EXTENSION

The extension output provides the following information:

“exit_code“, “status“, “status_description“: General info regarding the task execution.
“invocation”
- “fields”: The task configuration used for this task execution.
result
- “code“: The HTTP response code
- “headers”: The response headers
- “body”: The response body in string format
- “body_json”: The response body in JSON format

Successful Execution

{
    "exit_code": 0,
    "status_description": "Task executed successfully.",
    "invocation": {
        "fields": { ...
        },
    },
    "result": {
        "code": 200,
        "headers": [
            {
                "header": "Content-Encoding",
                "value": "gzip"
            },
            {
                "header": "Content-Type",
                "value": "application/json"
            },
            {
                "header": "Display",
                "value": "staticcontent_sol, orig_site_sol"
            },
            {
                "header": "Response",
                "value": "200"
            },
            {
                "header": "Vary",
                "value": "Accept-Encoding,User-Agent,Origin"
            },
            {
                "header": "Transfer-Encoding",
                "value": "chunked"
            }
        ],
        "body": "{\"status\":\"success\",\"data\":[{\"id\":1,\"employee_name\":\"Tiger Nixon\",\"employee_salary\":320800,\"employee_age\":61,\"profile_image\":\"\"},
{\"id\":2,\"employee_name\":\"Garrett Winters\",\"employee_salary\":170750,\"employee_age\":63,\"profile_image\":\"\"}",
        "body_json": {
            "status": "success",
            "data": [
                {
                    "id": 1,
                    "employee_name": "Tiger Nixon",
                    "employee_salary": 320800,
                    "employee_age": 61,
                    "profile_image": ""
                },
                {
                    "id": 2,
                    "employee_name": "Garrett Winters",
                    "employee_salary": 170750,
                    "employee_age": 63,
                    "profile_image": ""
                }
            ]
        }
    }

STDOUT

If the field “Print Result Body To” is set to STDOUT, the body of the response will be printed here.

STDOUT Output

{
    "status": "success",
    "data": [
        {
            "id": 1,
            "employee_name": "Tiger Nixon",
            "employee_salary": 320800,
            "employee_age": 61,
            "profile_image": ""
        },
        {
            "id": 2,
            "employee_name": "Garrett Winters",
            "employee_salary": 170750,
            "employee_age": 63,
            "profile_image": ""
        }
}

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. 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	Credentials	-	Optional	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	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 150084807. 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. Password Credentials Client Credentials 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. 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".	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. User as "Runtime User". Password as "Runtime Password". 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. Send as Basic Auth Header. Send Client Credentials in Body. 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. 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	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 150084807.	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. GET POST PUT PATCH DELETE
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. 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	Choice	Form	Optional	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	Choice	application/json	Optional	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	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 150084807 and 150084807.
SSL Options	Boolean	False	Required

Integrations

UAC Utility: Web Service