| Panel | |
|---|---|
|
Disclaimer
Your use of this download is governed by Stonebranch’s Terms of Use, which are available at https://www.stonebranch.com/integration-hub/Terms-and-Privacy/Terms-of-Use/
Overview
The Webservice Universal Task allows you to call a web service triggered from Universal Agent.
This Universal Task is especially useful for Stonebranch SaaS customers, which access Universal Controller in the Stonebranch AWS Cloud and deploy their Universal Agents in their own datacenter. As the Universal Task is triggered from the Universal Agent, no additional firewall port for the Universal Agent needs to be opened.
Software Requirements
Software Requirements for Universal Agent
Universal Agent for Linux or Windows Version 7.0.0.0 or later is required.
Universal Agent needs to be installed with python option (--python yes).
Software Requirements for Universal Controller
Universal Controller 7.0.0.0 or later is required.
Key Features
Call a Webservice triggered from Universal Agent.
Support all common HTTP Methods for RESTful Services:
Get, Post, Put, Patch and Delete.Support for Basic Authentication.
Support for Form based query Parameters.
Support for Form and Script based HTTP Payload Parameters.
Provide HTTP Headers as Form Data: for example, key:
Accept, Value:application/json.Support Response Processing using either Output Type JSON or Text.
Current Limitations
For the HTTP payload type FORM, only the MIME Type application/json is supported.
For Output processing, the Output Type XML is currently not supported.
The SOAP messaging protocol is not support in this Version.
Import the Webservice Universal Template
To use this downloadable Universal Template, you first must perform the following steps:
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.
Download the provided ZIP file.
In the Universal Controller UI, select Administration >Configuration > Universal Templates to display the current list of Universal Templates.
Click Import Template.
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 Webservice Universal Tasks
For this new Universal Task type, create a new task, and enter the task-specific details that were created in the Universal Template.
Field Descriptions for Webservice Universal Task - HTTP Method
Webservice Universal Task provides five different HTTP Methods.
Get
Post
Put
Patch
Delete
...
Get - HTTP Method
The GET HTTP method is used to retrieve data from the server. This is a read-only method.
...
Field
...
Description
...
protocol
...
[ HTTP(S)/REST | SOAP ]
| Note | ||
|---|---|---|
| ||
The SOAP messaging protocol is not supported in this version. |
...
HTTP Authentication
...
[ --None-- | Basic ]
If Basic HTTP Authentication is selected, the field credentials will be visible to enter Basic Authentication Credentials.
...
Credentials
...
Credentials for Basic Authentication
The field is only visible if HTTP Authentication Method “Basic” has been selected.
...
HTTP Method
...
[Get | Post | Put | Patch | Delete]
GET - retrieve data
POST - add new data
PUT - replace existing data
PATCH - update some existing data fields
DELETE - delete existing data
...
Timeout
...
REST request timeout in seconds.
If a value is entered, it will overwrite the default
timeout default for consuming the REST API.
...
URL
...
REST Service Endpoint
For example,
https://jsonplaceholder.typicode.com/posts
...
URL Query Parameters
...
Name & Value Array Field
Enter the URL Query Parameters in the Array Field.
For example, Name=ID, Value=10
Query parameters are a defined set of parameters attached to the end of a URL.
...
HTTP Payload Type
...
[ Raw | Form Data ]
If Raw is selected, the Payload needs to provided in the format set in the field MIME Type.
For example, MIME Type = application/json requires a JSON-formatted Payload.
The Payload can be provided as Payload Source Form or Script. The Script can be uploaded or created in the Universal Controller script library.
| Note | ||
|---|---|---|
| ||
When Form is selected, only the MIME Type |
...
MIME Type
...
[application/javascript | Application/json | application/xml | application/x-www-form-urlencoded | test/html | test/plain | test/xml | Other]
Mime Type is the same as the Content-Type header and describes the format the body of your request is being sent as.
...
Form Data
...
Payload Form Data
...
Payload Source
...
[ Form | Script ]
The Payload can be provided as Payload Source Form or Script. The Script can be uploaded or created in the Universal Controller script library.
If Payload Script is selected, the field Payload appears to enter the payload in the format selected in the Field MIME Type.
...
Payload
...
Payload
The field is only visible if Payload Source is selected as Form.
The Payload: Enter the payload in the format selected in the Field MIME Type.
For example, MIME Type application/json.
Payload JSON format:
| Code Block |
|---|
{
"userId": 6,
"title": "Stonebranch",
"body": "Certified SAP Workload Scheduler"
} |
...
Payload Script
...
Payload Script
The field is only visible if Payload Source is selected as Script.
Select or create a new Script saved in the Universal Controller script library.
Enter the Payload in the script in the format selected in the Field MIME Type.
...
HTTP Headers
HTTP Header array field.
Enter the HTTP Header as Name & Value Pairs.
For example,
HTTP Header Name= Accept , Value = application/json
...
Response Processing
...
[Print HTTP Response Code to STDOUT | Print HTTP Response Header to STDOUT | Print HTTP Response Body to STDOUT | Print HTTP Response Header to File | Print HTTP Response Body to File]
...
Output Type
...
[ Text | XML | JSON ]
| Note | ||
|---|---|---|
| ||
XML currently is not supported |
...
Path Expression
JSON Path Expression
The field is only visible if Output Type JSON is selected.
For example,
- Output Type = JSON
- Path Expression: 0.title
These match the Variable “title” in the following JSON:
| Code Block |
|---|
[
{
"userId":1,
"id":2,
"title":"qui est esse",
"body":"Hello world"
}
] |
...
Response Output File
...
Full Path and file name of the Output File
The field is only visible if in the Response Processing field one of the following entries has been selected: [Print HTTP Response Header to File | Print HTTP Response Body to File]
The Response is written to an Output File on the File System.
For example, Output File = /home/stonebranch/demo/out/name.json
...
Response Exit Code Mapping
...
The Value that pattern match the Path Expression of the JSON output, will used in the Response Exit Code Mapping table to set the exit code of the Task.
See Response Exit Code Mapping Example.
...
Proxies
...
Proxy Server
https=https://proxyip:port
For example,
https=https://192.155.10.130:8080
...
Log level (default is Inherited)
...
Universal Task logging settings: [Inherited | Trace | Debug | Info | Warn | Error | Severe]
...
The Value that pattern matched the Path Expression of the JSON output will be used in the Response Exit Code Mapping table to set the exit code of the Task.
For example,
Output Type = JSON
Path Expression: 0.title
These match the Variable “title” in the following JSON:
| Code Block |
|---|
[
{
"userId":1,
"id":2,
"title":"qui est esse",
"body":"Hello world"
}
] |
The Exit code of the Task is “0” because the Path Expression: 0.title matched the entry "qui est esse" in the Response Exit Code Mapping table.
...
The following example calls the Rest endpoint https://jsonplaceholder.typicode.com/users to retrieve the user record for Leanne Graham (URL Query Parameter).
Post HTTP Method
The POST HTTP method is used to send data to a server to create/update a resource.
The data sent to the server with POST is stored in the request body of the HTTP request.
...
Field
...
Description
...
protocol
...
[ HTTP(S)/REST | SOAP ]
| Note | ||
|---|---|---|
| ||
The SOAP messaging protocol is not supported in this version. |
...
HTTP Authentication
...
[ --None-- | Basic ]
If Basic HTTP Authentication is selected, the field credentials will be visible to enter Basic Authentication Credentials.
...
Credentials
...
Credentials for Basic Authentication
The field is only visible if HTTP Authentication Method “Basic” has been selected.
...
HTTP Method
...
[Get | Post | Put | Patch | Delete]
GET - retrieve data
POST - add new data
PUT - replace existing data
PATCH - update some existing data fields
DELETE - delete existing data
...
Timeout
...
REST request timeout in seconds.
If a value is entered, it will overwrite the default
timeout default for consuming the REST API.
...
URL
...
REST Service Endpoint
For example,
https://jsonplaceholder.typicode.com/posts
...
URL Query Parameters
...
Name & Value Array Field
Enter the URL Query Parameters in the Array Field.
For example, Name=ID, Value=10
Query parameters are a defined set of parameters attached to the end of a URL.
...
HTTP Payload Type
...
[ Raw | Form Data ]
If Raw is selected, the Payload needs to provided in the format set in the field MIME Type.
For example, MIME Type = application/json requires a JSON-formatted Payload.
The Payload can be provided as Payload Source Form or Script. The Script can be uploaded or created in the Universal Controller script library.
| Note | ||
|---|---|---|
| ||
When Form is selected, only the MIME Type |
...
MIME Type
...
[application/javascript | Application/json | application/xml | application/x-www-form-urlencoded | test/html | test/plain | test/xml | Other]
Mime Type is the same as the Content-Type header and describes the format the body of your request is being sent as.
...
Form Data
...
Payload Form Data
...
Payload Source
...
[ Form | Script ]
The Payload can be provided as Payload Source Form or Script. The Script can be uploaded or created in the Universal Controller script library.
If Payload Script is selected, the field Payload appears to enter the payload in the format selected in the Field MIME Type.
...
Payload
...
Payload
The field is only visible if Payload Source is selected as Form.
The Payload: Enter the payload in the format selected in the Field MIME Type.
For example, MIME Type application/json.
Payload JSON format:
| Code Block |
|---|
{
"userId": 6,
"title": "Stonebranch",
"body": "Certified SAP Workload Scheduler"
} |
...
Payload Script
...
Payload Script
The field is only visible if Payload Source is selected as Script.
Select or create a new Script saved in the Universal Controller script library.
Enter the Payload in the script in the format selected in the Field MIME Type.
...
HTTP Headers
...
HTTP Header array field.
Enter the HTTP Header as Name & Value Pairs.
For example,
HTTP Header Name= Accept , Value = application/json
...
Response Processing
...
[Print HTTP Response Code to STDOUT | Print HTTP Response Header to STDOUT | Print HTTP Response Body to STDOUT | Print HTTP Response Header to File | Print HTTP Response Body to File]
...
Output Type
...
[ Text | XML | JSON ]
| Note | ||
|---|---|---|
| ||
XML currently is not supported |
...
Path Expression
JSON Path Expression
The field is only visible if Output Type JSON is selected.
For example,
- Output Type = JSON
- Path Expression: 0.title
These match the Variable “title” in the following JSON:
| Code Block |
|---|
[
{
"userId":1,
"id":2,
"title":"qui est esse",
"body":"Hello world"
}
] |
...
Response Output File
...
Full Path and file name of the Output File
The field is only visible if in the Response Processing field one of the following entries has been selected: [Print HTTP Response Header to File | Print HTTP Response Body to File]
The Response is written to an Output File on the File System.
For example, Output File = /home/stonebranch/demo/out/name.json
...
Response Exit Code Mapping
...
The Value that pattern match the Path Expression of the JSON output, will used in the Response Exit Code Mapping table to set the exit code of the Task.
See Response Exit Code Mapping Example.
...
Proxies
...
Proxy Server
https=https://proxyip:port
For example,
https=https://192.155.10.130:8080
...
Log level (default is Inherited)
...
Universal Task logging settings: [Inherited | Trace | Debug | Info | Warn | Error | Severe]
...
The following example calls the Rest endpoint https://jsonplaceholder.typicode.com/posts to add a new user record with userId = 8, tittle = Stonebranch and body “Hello world form”.
Put HTTP Method
The HTTP Method Put is used to send data to a server to create/update a resource.
The difference between POST and PUT is that PUT requests are idempotent. That is, calling the same PUT request multiple times will always produce the same result. In contrast, calling a POST request repeatedly have side effects of creating the same resource multiple times.
A PUT request requires the entire body to be sent through.
...
Field
...
Description
...
protocol
...
[ HTTP(S)/REST | SOAP ]
| Note | ||
|---|---|---|
| ||
The SOAP messaging protocol is not supported in this version. |
...
HTTP Authentication
...
[ --None-- | Basic ]
If Basic HTTP Authentication is selected, the field credentials will be visible to enter Basic Authentication Credentials.
...
Credentials
...
Credentials for Basic Authentication
The field is only visible if HTTP Authentication Method “Basic” has been selected.
...
HTTP Method
...
[Get | Post | Put | Patch | Delete]
GET - retrieve data
POST - add new data
PUT - replace existing data
PATCH - update some existing data fields
DELETE - delete existing data
...
Timeout
...
REST request timeout in seconds.
If a value is entered, it will overwrite the default
timeout default for consuming the REST API.
...
URL
...
REST Service Endpoint
For example,
https://jsonplaceholder.typicode.com/posts
...
URL Query Parameters
...
Name & Value Array Field
Enter the URL Query Parameters in the Array Field.
For example, Name=ID, Value=10
Query parameters are a defined set of parameters attached to the end of a URL.
...
HTTP Payload Type
...
[ Raw | Form Data ]
If Raw is selected, the Payload needs to provided in the format set in the field MIME Type.
For example, MIME Type = application/json requires a JSON-formatted Payload.
The Payload can be provided as Payload Source Form or Script. The Script can be uploaded or created in the Universal Controller script library.
| Note | ||
|---|---|---|
| ||
When Form is selected, only the MIME Type |
...
MIME Type
...
[application/javascript | Application/json | application/xml | application/x-www-form-urlencoded | test/html | test/plain | test/xml | Other]
Mime Type is the same as the Content-Type header and describes the format the body of your request is being sent as.
...
Form Data
...
Payload Form Data
...
Payload Source
...
[ Form | Script ]
The Payload can be provided as Payload Source Form or Script. The Script can be uploaded or created in the Universal Controller script library.
If Payload Script is selected, the field Payload appears to enter the payload in the format selected in the Field MIME Type.
...
Payload
...
Payload
The field is only visible if Payload Source is selected as Form.
The Payload: Enter the payload in the format selected in the Field MIME Type.
For example, MIME Type application/json.
Payload JSON format:
| Code Block |
|---|
{
"userId": 6,
"title": "Stonebranch",
"body": "Certified SAP Workload Scheduler"
} |
...
Payload Script
...
Payload Script
The field is only visible if Payload Source is selected as Script.
Select or create a new Script saved in the Universal Controller script library.
Enter the Payload in the script in the format selected in the Field MIME Type.
...
HTTP Headers
...
HTTP Header array field.
Enter the HTTP Header as Name & Value Pairs.
For example,
HTTP Header Name= Accept , Value = application/json
...
Response Processing
...
[Print HTTP Response Code to STDOUT | Print HTTP Response Header to STDOUT | Print HTTP Response Body to STDOUT | Print HTTP Response Header to File | Print HTTP Response Body to File]
...
Output Type
...
[ Text | XML | JSON ]
| Note | ||
|---|---|---|
| ||
XML currently is not supported |
...
Path Expression
JSON Path Expression
The field is only visible if Output Type JSON is selected.
For example,
- Output Type = JSON
- Path Expression: 0.title
These match the Variable “title” in the following JSON:
| Code Block |
|---|
[
{
"userId":1,
"id":2,
"title":"qui est esse",
"body":"Hello world"
}
] |
...
Response Output File
...
Full Path and file name of the Output File
The field is only visible if in the Response Processing field one of the following entries has been selected: [Print HTTP Response Header to File | Print HTTP Response Body to File]
The Response is written to an Output File on the File System.
For example, Output File = /home/stonebranch/demo/out/name.json
...
Response Exit Code Mapping
...
The Value that pattern match the Path Expression of the JSON output, will used in the Response Exit Code Mapping table to set the exit code of the Task.
See Response Exit Code Mapping Example.
...
Proxies
...
Proxy Server
https=https://proxyip:port
For example,
https=https://192.155.10.130:8080
...
Log level (default is Inherited)
...
Universal Task logging settings: [Inherited | Trace | Debug | Info | Warn | Error | Severe]
...
The following two example call the Rest endpoint https://jsonplaceholder.typicode.com/posts/1 to update a user record. The first example uses a Forma Data payload. The second example uses a RAW Data payload.
Example HTTP Method: Put Using Form Data
The following example calls the Rest endpoint https://jsonplaceholder.typicode.com/posts/1 to update a user record using Form Data.
Example HTTP Method: Put Using Raw Data
The following example calls the Rest endpoint https://jsonplaceholder.typicode.com/posts/1 to update a user record using Raw Data.
Patch HTTP Method
The HTTP Method Patch updates an existing resource, and does not require sending the entire body with the request.
...
Field
...
Description
...
protocol
...
[ HTTP(S)/REST | SOAP ]
| Note | ||
|---|---|---|
| ||
The SOAP messaging protocol is not supported in this version. |
...
HTTP Authentication
...
[ --None-- | Basic ]
If Basic HTTP Authentication is selected, the field credentials will be visible to enter Basic Authentication Credentials.
...
Credentials
...
Credentials for Basic Authentication
The field is only visible if HTTP Authentication Method “Basic” has been selected.
...
HTTP Method
...
[Get | Post | Put | Patch | Delete]
GET - retrieve data
POST - add new data
PUT - replace existing data
PATCH - update some existing data fields
DELETE - delete existing data
...
Timeout
...
REST request timeout in seconds.
If a value is entered, it will overwrite the default
timeout default for consuming the REST API.
...
URL
...
REST Service Endpoint
For example,
https://jsonplaceholder.typicode.com/posts
...
URL Query Parameters
...
Name & Value Array Field
Enter the URL Query Parameters in the Array Field.
For example, Name=ID, Value=10
Query parameters are a defined set of parameters attached to the end of a URL.
...
HTTP Payload Type
...
[ Raw | Form Data ]
If Raw is selected, the Payload needs to provided in the format set in the field MIME Type.
For example, MIME Type = application/json requires a JSON-formatted Payload.
The Payload can be provided as Payload Source Form or Script. The Script can be uploaded or created in the Universal Controller script library.
| Note | ||
|---|---|---|
| ||
When Form is selected, only the MIME Type |
...
MIME Type
...
[application/javascript | Application/json | application/xml | application/x-www-form-urlencoded | test/html | test/plain | test/xml | Other]
Mime Type is the same as the Content-Type header and describes the format the body of your request is being sent as.
...
Form Data
...
Payload Form Data
...
Payload Source
...
[ Form | Script ]
The Payload can be provided as Payload Source Form or Script. The Script can be uploaded or created in the Universal Controller script library.
If Payload Script is selected, the field Payload appears to enter the payload in the format selected in the Field MIME Type.
...
Payload
...
Payload
The field is only visible if Payload Source is selected as Form.
The Payload: Enter the payload in the format selected in the Field MIME Type.
For example, MIME Type application/json.
Payload JSON format:
| Code Block |
|---|
{
"userId": 6,
"title": "Stonebranch",
"body": "Certified SAP Workload Scheduler"
} |
...
Payload Script
...
Payload Script
The field is only visible if Payload Source is selected as Script.
Select or create a new Script saved in the Universal Controller script library.
Enter the Payload in the script in the format selected in the Field MIME Type.
...
HTTP Headers
...
HTTP Header array field.
Enter the HTTP Header as Name & Value Pairs.
For example,
HTTP Header Name= Accept , Value = application/json
...
Response Processing
...
[Print HTTP Response Code to STDOUT | Print HTTP Response Header to STDOUT | Print HTTP Response Body to STDOUT | Print HTTP Response Header to File | Print HTTP Response Body to File]
...
Output Type
...
[ Text | XML | JSON ]
| Note | ||
|---|---|---|
| ||
XML currently is not supported |
...
Path Expression
JSON Path Expression
The field is only visible if Output Type JSON is selected.
For example,
- Output Type = JSON
- Path Expression: 0.title
These match the Variable “title” in the following JSON:
| Code Block |
|---|
[
{
"userId":1,
"id":2,
"title":"qui est esse",
"body":"Hello world"
}
] |
...
Response Output File
...
Full Path and file name of the Output File
The field is only visible if in the Response Processing field one of the following entries has been selected: [Print HTTP Response Header to File | Print HTTP Response Body to File]
The Response is written to an Output File on the File System.
For example, Output File = /home/stonebranch/demo/out/name.json
...
Response Exit Code Mapping
...
The Value that pattern match the Path Expression of the JSON output, will used in the Response Exit Code Mapping table to set the exit code of the Task.
See Response Exit Code Mapping Example.
...
Proxies
...
Proxy Server
https=https://proxyip:port
For example,
https=https://192.155.10.130:8080
...
Log level (default is Inherited)
...
Universal Task logging settings: [Inherited | Trace | Debug | Info | Warn | Error | Severe]
...
The following example calls the Rest endpoint https://jsonplaceholder.typicode.com/posts/1 to update title field with the value “Title update using patch”.
Delete HTTP Method
The HTTP Method DELETE removes a resource.
...
Field
...
Description
...
protocol
...
[ HTTP(S)/REST | SOAP ]
| Note | ||
|---|---|---|
| ||
The SOAP messaging protocol is not supported in this version. |
...
HTTP Authentication
...
[ --None-- | Basic ]
If Basic HTTP Authentication is selected, the field credentials will be visible to enter Basic Authentication Credentials.
...
Credentials
...
Credentials for Basic Authentication
The field is only visible if HTTP Authentication Method “Basic” has been selected.
...
HTTP Method
...
[Get | Post | Put | Patch | Delete]
GET - retrieve data
POST - add new data
PUT - replace existing data
PATCH - update some existing data fields
DELETE - delete existing data
...
Timeout
...
REST request timeout in seconds.
If a value is entered, it will overwrite the default
timeout default for consuming the REST API.
...
URL
...
REST Service Endpoint
For example,
https://jsonplaceholder.typicode.com/posts
...
URL Query Parameters
...
Name & Value Array Field
Enter the URL Query Parameters in the Array Field.
For example, Name=ID, Value=10
Query parameters are a defined set of parameters attached to the end of a URL.
...
HTTP Payload Type
...
[ Raw | Form Data ]
If Raw is selected, the Payload needs to provided in the format set in the field MIME Type.
For example, MIME Type = application/json requires a JSON-formatted Payload.
The Payload can be provided as Payload Source Form or Script. The Script can be uploaded or created in the Universal Controller script library.
| Note | ||
|---|---|---|
| ||
When Form is selected, only the MIME Type |
...
MIME Type
...
[application/javascript | Application/json | application/xml | application/x-www-form-urlencoded | test/html | test/plain | test/xml | Other]
Mime Type is the same as the Content-Type header and describes the format the body of your request is being sent as.
...
Form Data
...
Payload Form Data
...
Payload Source
...
[ Form | Script ]
The Payload can be provided as Payload Source Form or Script. The Script can be uploaded or created in the Universal Controller script library.
If Payload Script is selected, the field Payload appears to enter the payload in the format selected in the Field MIME Type.
...
Payload
...
Payload
The field is only visible if Payload Source is selected as Form.
The Payload: Enter the payload in the format selected in the Field MIME Type.
For example, MIME Type application/json.
Payload JSON format:
| Code Block |
|---|
{
"userId": 6,
"title": "Stonebranch",
"body": "Certified SAP Workload Scheduler"
} |
...
Payload Script
...
Payload Script
The field is only visible if Payload Source is selected as Script.
Select or create a new Script saved in the Universal Controller script library.
Enter the Payload in the script in the format selected in the Field MIME Type.
...
HTTP Headers
...
HTTP Header array field.
Enter the HTTP Header as Name & Value Pairs.
For example,
HTTP Header Name= Accept , Value = application/json
...
Response Processing
...
[Print HTTP Response Code to STDOUT | Print HTTP Response Header to STDOUT | Print HTTP Response Body to STDOUT | Print HTTP Response Header to File | Print HTTP Response Body to File]
...
Output Type
...
[ Text | XML | JSON ]
| Note | ||
|---|---|---|
| ||
XML currently is not supported |
...
Path Expression
JSON Path Expression
The field is only visible if Output Type JSON is selected.
For example,
- Output Type = JSON
- Path Expression: 0.title
These match the Variable “title” in the following JSON:
| Code Block |
|---|
[
{
"userId":1,
"id":2,
"title":"qui est esse",
"body":"Hello world"
}
] |
...
Response Output File
...
Full Path and file name of the Output File
The field is only visible if in the Response Processing field one of the following entries has been selected: [Print HTTP Response Header to File | Print HTTP Response Body to File]
The Response is written to an Output File on the File System.
For example, Output File = /home/stonebranch/demo/out/name.json
...
Response Exit Code Mapping
...
The Value that pattern match the Path Expression of the JSON output, will used in the Response Exit Code Mapping table to set the exit code of the Task.
See Response Exit Code Mapping Example.
...
Proxies
...
Proxy Server
https=https://proxyip:port
For example,
https=https://192.155.10.130:8080
...
Log level (default is Inherited)
...
Universal Task logging settings: [Inherited | Trace | Debug | Info | Warn | Error | Severe]
...
The following example calls the Rest endpoint https://jsonplaceholder.typicode.com/posts/1 to delete the resource specified in the endpoint URL.
...
| Panel | |
|---|---|
|
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:
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.
Download the provided ZIP file.
In the Universal Controller UI, select Administration >Configuration > Universal Templates to display the current list of /wiki/spaces/UC71x/pages/5178050.
Click Import Template.
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:
|
Credentials | Optional | - | Credentials | Credentials for "Basic" Authorization Type. They are comprised of:
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:
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:
|
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:
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:
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:
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 | Optional | STDOUT | Choice | Specifies where to print the web service output payload. Currently available options are:
|
Process Exit Code Mapping | Required | False | Boolean | Flag that determines whether exit code mapping is enabled or not. |
Path Expression | 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 | 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).