Web Service Task
Overview
The Web Service Task allows you to invoke a Web Service running on any application server.
SSL/TLS Secured HTTPS
Web Service Tasks support the use of https:// instead of the non-encrypted http:// for the Web Service Task URL.
This requires setting up a truststore (keystore) and setting the following properties in the Universal Controller Start-up Properties (uc.properties) file:
You must make sure that the HTTPS server's certificate (or root certificate) exists in the truststore that is referenced by these two properties. This is required to validate the remote web service providers identity. Universal Controller does not provide an option to bypass https certificate validation.
The hostname in your URL is verified against the certificate and must match the certificate's CN (Common Name) or SAN (Subject Alternative Name).
Preemptive Authentication
The default behavior of Apache HttpClient library used by the Web Service task is to not use pre-emptive authentication out of the box, because if misused or used incorrectly, the preemptive authentication can lead to significant security issues, such as sending user credentials in clear text to an unauthorized third party.
Therefore, users are expected to evaluate potential benefits of preemptive authentication versus security risks in the context of their specific application environment. Thus, Web Service Tasks using Basic Authentication will not pre-emptively send authentication credentials until prompted by the receiving API. Please see the following link for more information.
https://hc.apache.org/httpcomponents-client-4.5.x/current/tutorial/html/authentication.html#d5e717
Built-In Variables
The following built-in variables can be used in a Web Service task to pass data where appropriate:
Creating a Web Service Task
Step 1 |
From the Automation Center navigation pane, select Tasks > Web Service Tasks. The Web Service Tasks list displays a list of all currently defined Web Service tasks. |
---|---|
Step 2 |
Enter/select Details for a new Web Service task, using the field descriptions below as a guide.
To display more of the Details fields on the screen, you can either:
|
Step 3 |
Click the button. The task is added to the database, and all buttons and tabs in the Task Details are enabled. |
Note
To open an existing record on the list, either:
- Click a record in the list to display its record Details below the list. (To clear record Details below the list, click the New button that displays above and below the Details.)
- Clicking the Details icon next to a record name in the list, or right-click a record in the list and then click Open in the Action menu that displays, to display a pop-up version of the record Details.
- Right-click a record in the a list, or open a record and right-click in the record Details, and then click Open In Tab in the Action menu that displays, to display the record Details under a new tab on the record list page (see Record Details as Tabs).
Web Service Task Details
The following Web Service Task Details is for an existing Web Service task.
Depending on the values that you enter / select for these fields, and whether or not the Web Service task has ever been launched, more (or less) fields may display. See the field descriptions, below, for a description of all fields that may display in the Web Service Task Details.
Web Service Task Details Field Descriptions
The following table describes the fields, buttons, and tabs that display in the Web Service Task Details.
Field Name |
Description |
---|---|
General |
This section contains general information about the task. |
Name |
User-defined name of this task (Maximum = 255 alphanumeric characters); variables supported. It is the responsibility of the user to develop a workable naming scheme for tasks. |
Version |
System-supplied; version number of the current record, which is incremented by the Controller every time a user updates a record. Click the Versions tab to view previous versions. For details, see Record Versioning. |
Description |
Description of this record. Maximum length is 255 characters. |
Member of Business Services |
User-defined; Allows you to select one or more Business Services that this record belongs to. (You also can Check All or Uncheck All Business Services for this record.) You can select up to 62 Business Services for any record type, and enter a maximum of 2048 characters for each Business Service. If the Business Service Visibility Restricted Universal Controller system property is set to true, depending on your assigned (or inherited) Permissions or Roles, Business Services available for selection may be restricted. |
Resolve Name Immediately |
If enabled, the Instance Name of the task instance will be resolved immediately at trigger/launch time. |
Time Zone Preference |
User-defined; Allows you to specify the time zone that will be applied to the task. Options:
|
Hold on Start |
If enabled, when the task is launched it appears in the Activity Monitor with a status of Held. The task runs when the user releases it. |
Hold Reason |
Information about why the task will be put on hold when it starts. |
Virtual Resource Priority |
Priority for acquiring a resource when two or more tasks are waiting for the resource. This priority applies to all resources required by the task. Options: 1 (high) - 100 (low). Default is 10. |
Hold Resources on Failure |
If enabled, the task instance will continue to hold Renewable resources if the task instance fails. Renewable resources will be returned only if the task instance status is either Complete, Finished, or Skipped. |
Mutually Exclusive With Self |
If enabled, the task will not be allowed to run concurrently with itself. Task will not start until the instance that is running finishes. An instance will transition to Exclusive Wait status if it cannot start due to another instance already running. |
Simulate | Specifies if the instance should execute under simulation mode. |
Override Previous Instance Wait | Specifies whether or not to override the parent workflow's Previous Instance Wait configuration. This option only applies for an instance running within a workflow. Options:
|
Web Service Details |
This section contains assorted detailed information about the task. |
Protocol |
Default is HTTP(S)/REST. |
HTTP Authentication |
Default is - - None - -. |
Credentials |
If HTTP Authentication = Basic; Credentials used when invoking the Web Service. |
Credentials Variable |
If Credentials Variable - Web Service#HTTP Authentication = Basic; Indication of whether the Credentials Variable - Web Service#Credentials field is a reference field for selecting a specific Credential (unchecked) or a text field for specifying the Credentials Variable - Web Service#Credential as a variable (checked). Use the format:
The variable must be a supported type as described in Variables and Functions. Note When updating multiple Tasks, to change from using a Credentials reference to using a Credentials variable, you must change the Credentials Variable field to Yes and specify the Credentials variable in the Credentials Unresolved field. Conversely, to change from using a Credentials variable to using a Credentials reference, you must change the Credentials Variable field to No and specify the Credentials reference in the Credentials field. |
HTTP Version |
Default is 1.1. |
Insecure |
Allows the Web Service task to use a TLS/SSL connection that is considered to be insecure. Note The Insecure field displays only if:
|
HTTP Method |
If Protocol = HTTP(S)/REST; Type of HTTP request method to use.
Default is POST. |
SOAP Version |
|
Timeout |
|
URL |
URL of the target service, excluding query parameters. Note The Web Service Task URL Whitelist Regular Expression Universal Controller system property specifies which URLs are supported by the Web Service task. (The default allows all URLs to be supported.) If a task instance attempts to run, but this URL does not match a URL specified by Web Service Task URL Whitelist Regular Expression, the task instance transitions to a Start Failure with an appropriate Status Description. |
URL Query Parameters |
Any query parameters to be encoded as a query string and appended to the URL. Parameter values support Resolvable Credential functions if both Web Service Task Resolvable Credentials Functions Permitted and Resolvable Credentials Permitted system properties are true. |
HTTP Payload Type |
If Protocol = HTTP(S)/REST and HTTP Method = POST, PUT, or PATCH; Type of HTTP payload.
Default is Raw. |
MIME Type |
If Protocol = HTTP(S)/REST; MIME type of the message body.
No default. Note If HTTP Payload Type = Form Data, MIME Type is automatically assigned a value of application/x-www-form-urlencoded and becomes read only. |
Form Data |
If HTTP Payload Type = Form Data; Any parameters to be encoded and added to the message body. Parameter values support Resolvable Credential functions if both Web Service Task Resolvable Credentials Functions Permitted and Resolvable Credentials Permitted system properties are true. |
SOAP Payload Type |
|
SOAP Action |
|
Payload Source |
If HTTP Payload Type = Raw; Specification for whether the payload is defined directly in this form (task Details) or if it is a reference to a script that contains the content of the request payload. Default is Form. |
Payload |
If Payload Source = Form; Request payload. Supports Resolvable Credential functions if both Web Service Task Resolvable Credentials Functions Permitted and Resolvable Credentials Permitted system properties are true. |
Payload Script |
If Payload Source = Script; Script that contains the content of the request payload. Supports Resolvable Credential functions if both Web Service Task Resolvable Credentials Functions Permitted and Resolvable Credentials Permitted system properties are true. |
HTTP Headers |
|