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

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

Requirements

This integration requires a Universal Agent and a Python runtime to execute the Universal Task.

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 Passing Credentials as Query Parameters, Headers, or as Form Data.

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 Passing Credentials as Query Parameters, Headers, or as Form Data.

User Scenario: Example of Universal Task for "OAuth2.0" Authorization Type with client credentials grant type	User Scenario: 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 Passing Credentials as Query Parameters, Headers, or as Form Data.

Action Output

{
    "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": ""
                }
            ]
        }
    }

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

SSL Certificate Authority File Discovery

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, a Certificate Authority Bundle should be provided as input.
Related Universal Task fields:

• SSL Options: Enabled
• SSL Certificate Verification: Enabled
• CA Bundle Path: Populated

SSL Client Authentication

An 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.
Related Universal Task fields:

• SSL Options: Enabled
• SSL Certificate Verification: Enabled
• CA Bundle Path: Populated
• Client Certificate Path: Populated
• Client Private Key Path: Populated

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

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

The web service output JSON body 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 pattern is matched, the extension will return the respective exit code.

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.

  • A Wrong Path Expression is provided.

  • The result body is not of type JSON.

• The custom exit codes that intend to be considered successful, have to be configured 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 reflect successful execution (Ranges can be provided. For example 0,100-255).

Passing Credentials as Query Parameters, Headers, or as Form Data  

There are cases where the endpoint might require credentials to be passed either as part of Query Parameters, as Headers or in a URL-encoded form. For example, Mulesoft APIs can include Client ID Enforcement Policy for which a Client ID and a Client Secret are mandatory to be passed on top of other authorization/authentication inputs.

Additional Query Parameters can be passed through the "URL Query Parameters" field, additional HTTP Headers can be passed through the "HTTP Headers" field and form data can be passed through the "Form Data" field. All of them are Array fields. Array "Name" represents the Query Parameter Name, the Header Name, or the Form Data Key, and "Value" represents the value to be used. “Value” could be a specific string, or be in the format of [credential_name].attribute where

• credential_name: The name of a Credential which is selected by a Credential field used in the task. Only Credential names that are selected in the task's credential fields can be used.

• attribute: The attribute of the specific Credential with possible values being the following.

  • user

  • password

  • passphrase

  • token

If the provided credential_name is a valid Credential name and attribute is in the above domain, then a match is found and the specific Credential attribute is used. Else the provided input is used as a literal string.

Example: Let's suppose that a credential with name = "valid_credential_name" and password = "example_pass" is passed to a task. The expression [valid_credential_name].password will be resolved to example_pass.

Set Proxies with Environment Variables  

If a proxy is required to route the traffic between the Universal Task and the configured endpoint, then HTTP_PROXY and/or HTTPS_PROXY environment variables need to be set. HTTP_PROXY environment variable defines the proxy used in case of HTTP communication between the Universal Task and the endpoint, while the HTTPS_PROXY environment variable defines the proxy used in case of HTTPS communication between the Universal Task and the endpoint. In the majority of cases, only one proxy is used that routes both HTTP and HTTPS traffic (in such cases HTTP_PROXY/HTTPS_PROXY environment variables point to the same value).

The format is explained by the following examples.

Configuration Examples

User Scenario: Passing a single proxy for HTTP and HTTPS traffic	User Scenario: Passing different proxies with credentials for HTTP and HTTPS traffic

Output Fields

Exit Codes

The exit codes for this Universal Extension are described in the following table.

STDOUT and STDERR

How To

Import Universal Template

To use the Universal Template, you first must perform the following steps.

1. This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.

2. To import the Universal Template into your Controller, follow these instructions.

3. When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.

Modifications of this integration, applied by users or customers, before or after import, might affect the supportability of this integration. For more information refer to Integration Modifications.

Configure Universal Task

For a new Universal Task, create a new task, and enter the required input fields.

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.

  • Result Processing Defaults Section

    • Success and Failure Exit codes can be changed according to users' needs.

  • Fields Restriction Section
    The setup of the template does not impose any restrictions. However, with respect to the "Exit Code Processing" 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 the success or failure of a task.

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

Document References

This document references the following documents.

Known Issues 

• The "proxies" field does not work correctly in some cases. Task authors are advised to use HTTP_PROXY and HTTPS_PROXY environment variables on task definition, or alternatively set those variables on the runtime user environment, leaving this field empty. For more information refer to Set Proxies with Environment Variables.

Changelog 

ue-webservice 1.4.1 (2023-10-18)

Fixes

• Fixed: Fix URL validation introduced on 1.3.0 (#34401)

ue-webservice 1.4.0 (2023-07-26)

Deprecations and Breaking Changes

• Deprecated: "Proxies" 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 Set Proxies with Environment Variables and  Known Issues. (#33623)

Enhancements

• Added: Support for passing additional credential information in URL-Encoded Form (#33612)

ue-webservice 1.3.1 (2023-04-28)

Fixes

• Fixed: STDOUT should include only the body of the webservice response (#32520)

• Fixed: Misleading warning message "...not designated as Output Only" is removed from UC logs (#32394)

• Fixed: Security Enhancements (#32631)

ue-webservice 1.3.0 (2023-03-23)

Enhancements

• Added: Support for API Keys (#31456)

• Added: Support for retrieving OAuth 2.0 token using "Password Credentials" or "Client Credentials" grant and calling a Web Service within the same task (#31479)

• Added: Support for passing additional credential information as Query Parameters or as Headers (#31478)

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 version 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 a 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 that read STDOUT from tasks originating from this Universal Template are encouraged to retrieve information from EXTENSION_OUTPUT instead of STDOUT to avoid disruptions. 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)