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 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:
|
Connectivity and Authentication Options | A variety of authentication options are supported:
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 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:
| |
STDOUT | If the field “Print Result Body To” is set to STDOUT, the body of the response will be printed here. |
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.
| |
Credentials | Credentials | - | Optional | Credentials for "Basic" Authorization Type. The Credentials definition should be as follows.
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.
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.
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.
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.
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.
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.
| |
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.
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.
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.
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 |