UAC Utility: Web Service

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 NameExtension NameExtension Version
Web Service Integrationue-webservice1.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