Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

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.

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

  • Support for HTTP Methods GET, POST, PUT, DELETE, PATCH.

  • Support for SSL Protocol.

  • Ability to use proxy between Universal Controller 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:

  1. This Universal Task requires the /wiki/spaces/UC71x/pages/5178443 feature. Check that the/wiki/spaces/UC71x/pages/5177877 system property has been set to true.

  2. Download the provided ZIP file.

  3. In the Universal Controller UI, select Administration >Configuration > Universal Templates to display the current list of /wiki/spaces/UC71x/pages/5178050.

  4. Click Import Template.

  5. Select the template ZIP file and Import.

When the template has been imported successfully, the Universal Template will appear on the list. Refresh your Navigation Tree to see these tasks in the Automation Center Menu.

Configure Universal Task

For this new Universal Task type, create a new task, and enter the task-specific details that were created in the Universal Template.

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.

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

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

  • 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 JSON Path (JSONPath Syntax).

  • Response Exit Code Mapping
    A list of pairs (Pattern/Exit Code). If pattern is matched, then the configured Exit Code will be applied.

The extension will parse the webservice output JSON body and get the value returned by the Path Expression This value will be compared against the list of patterns provided on Response Exit code Mapping array. When a match is found, the extension will return the corresponding 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 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).











  • No labels