Panel

Table of Contents

Template Name	Extension Name	Extension Version
Web Service Integration	ue-webservice	1.3.01

Note
Version 1.3.01, does not support Universal Agent/Controller 7.1.0.0. Detailed Software Requirements are below.

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.

...

This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.
To import the Universal Template into your Controller,follow the these instructions here.
When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.

...

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. 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	Optional	-	Credentials	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 Introduced in version 1.3.0	Optional	-	Credentials	Credentials for “API Key” Authorization Type. API Key should either be stored as the “Password” or “Token” Credential attribute, during Credential definition. Required when Authorization Type is “API Key”.
Grant Type Introduced in version 1.3.0	Optional	Client Credentials	Choice	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".
Access Token URL Introduced in version 1.3.0	Optional		Text	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".
Scope Introduced in version 1.3.0	Optional	-	Text	A space-separated list of scopes used during retrieval of an OAuth 2.0 access token. Required when Authorization Type is "OAuth 2.0".
Client Credentials Introduced in version 1.3.0	Optional	-	Credentials	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".
Resource Owner Credentials Introduced in version 1.3.0	Optional	-	Credentials	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".
Client Authentication Introduced in version 1.3.0	Optional	Send Client Credentials in Body	Choice	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".
Token	Optional	-	Large Text	The authentication access token. Required when Authorization Type is "Token".
Add Authorization Data To	Optional	Request Header	Choice	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	Optional	Bearer	Text	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 Introduced in version 1.3.0	Optional	-	Credentials	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 "24870913 Passing Credentials as Query Parameters or as Headers".
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
SSL Options	Required	False	Boolean	Displays the available SSL options.
SSL Certificate Verification	Optional	True	Boolean	Enables certificate verification. Certificate verification is auto-enabled in case field "CA Bundle Path" field is populated. Required when SSL Options is checked.
CA Bundle Path	Optional	-	Text	Path and file name of the Certificate Authority bundle to use in certificate verification. The file should be in PEM format.
Client Private Key Path	Optional	-	Text	Path and file name of the private key file for SSL client-side authentication. The file must be in PEM format.
Client Certificate Path	Optional	-	Text	Path and file name of the public key certificate for SSL 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. The following options are applicable. --None-- STDOUT
Process Exit Code Mapping Introduced in version 1.1.0	Required	False	Boolean	The 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. An array that maps regular expression patterns to exit codes. Provided exit codes should be in the range [100-255].

...

Panel

{
  "exit_code": 150,
  "status_description": "SUCCESS: Task executed successfully with mapped exit code.",
  "invocation": {
    "extension": "ue-webservice",
    "version": "1.3.01",
    "fields": {
      "protocol": "HTTP_REST",
      "http_version": "1.1",
      "authorization_type": "None",
      "credentials_user": null,
      "credentials_password": null,
      "api_key": null,
      "access_token_url": null,
      "grant_type": null,
      "scope": null,
      "client_credentials_user": null,
      "client_credentials_password": null,
      "resource_owner_credentials_user": null,
      "resource_owner_credentials_password": null,
      "additional_credentials_user": null,
      "additional_credentials_password": null,
      "client_authentication": null,
      "oauth2_token": "",
      "add_authorization_data_to": null,
      "url": "https://dummy.restapiexample.com/api/v1/employees",
      "http_method": "GET",
      "timeout": null,
      "url_query_parameters": {},
      "payload_type": null,
      "payload_source": null,
      "mime_type": null,
      "other_value_for_mime_type": "",
      "form_data": {},
      "payload": "",
      "payload_script": null,
      "http_headers": {},
      "proxies": "",
      "use_ssl": false,
      "trusted_certificates_file": "",
      "ssl_hostname_check": false,
      "private_key_certificate": "",
      "public_key_certificate": "",
      "result_body_medium": "None",
      "path_expression": "data.[*].employee_name",
      "exit_code_mapping": {
        "Tiger Nixon": "150"
      },
      "process_exit_code_mapping": true
    }
  },
  "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\":\"\"}, {\"id\":3,\"employee_name\":\"Ashton Cox\",\"employee_salary\":86000,\"employee_age\":66,\"profile_image\":\"\"},{\"id\":4,\"employee_name\":\"Cedric Kelly\",\"employee_salary\":433060,\"employee_age\":22,\"profile_image\":\"\"},{\"id\":5,\"employee_name\":\"Airi Satou\",\"employee_salary\":162700,\"employee_age\":33,\"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": ""
          },
          {
              "id": 3,
              "employee_name": "Ashton Cox",
              "employee_salary": 86000,
              "employee_age": 66,
              "profile_image": ""
          },
          {
              "id": 4,
              "employee_name": "Cedric Kelly",
              "employee_salary": 433060,
              "employee_age": 22,
              "profile_image": ""
          },
          {
              "id": 5,
              "employee_name": "Airi Satou",
              "employee_salary": 162700,
              "employee_age": 33,
              "profile_image": ""
          }
      ]
  }
}

...

This document references the following documents.

Document Link	Description
Universal Templates	User documentation for creating, working with and understanding Universal Templates and Integrations.
Universal Tasks	User documentation for creating Universal Tasks in the Universal Controller user interface.
Credentials	User documentation for creating and working with credentials.
Resolvable Credentials Permitted Property	User documentation for Resolvable Credentials Permitted Property.

...

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

...

Anchor

	changelog
	changelog

Changelog

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)

...

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 ue-webservice-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 literal string (#31224)
Fixed : Parse properly the JSON response when this is a list of objects (#30966)

...

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)

...

Versions Compared

Old Version 10

New Version 11

Key

Requirements

Software Requirements for Universal Template and Universal Task

Changelog

ue-webservice 1.3.1 (2023-04-28)

Fixes

ue-webservice 1.3.0 (2023-03-23)

Fixes

Fixes

Page Comparison

Versions Compared

Old Version 10

New Version 11

Key

Requirements

Software Requirements for Universal Template and Universal Task

Changelog

ue-webservice 1.3.1 (2023-04-28)

Fixes

ue-webservice 1.3.0 (2023-03-23)

Fixes

Fixes