/
Web Service Task

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.
 
To the right of the list, Web Service Task Details for a new Web Service task displays.
 

Step 2

Enter/select Details for a new Web Service task, using the field descriptions below as a guide.

  • Required fields display an asterisk ( * ) after the field name.
  • Default values for fields, if available, display automatically.

To display more of the Details fields on the screen, you can either:

  • Use the scroll bar.
  • Temporarily hide the list above the Details.
  • Click the  button above the list to display a pop-up version of the Details.

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:

  • – System Default –
    Time zone is based on the value of the Task Time Zone Preference Universal Controller system property: Server or Inherited.
  • Server (xxx)
    Where (xxx) is the time zone ID of the server; time zone is evaluated in the time zone of the server.
  • Inherited
    Time zone is evaluated in the time zone of the Parent Workflow or Trigger / Launch specification in the case there is no Parent Workflow.

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: 

  • No

    Behavior determined by the parent workflow configuration.
  • Yes / -- None --

    Regardless of the parent workflow configuration, the task instance will never wait for a previous instance to complete.
  • Yes / Wait for Last

    Regardless of the parent workflow configuration, the task instance will remain in Instance Wait until the most recent prior instance of the same task has completed.
  • Yes / Wait for Last / Same Workflow

    Regardless of the parent workflow configuration, the task instance will remain in Instance Wait until the most recent prior instance of the same task, within an instance of the same workflow, have completed.
  • Yes / Wait for All

    Regardless of the parent workflow configuration, the task instance will remain in Instance Wait until all prior instances of the same task has completed.
  • Yes / Wait for All / Same Workflow

    Regardless of the parent workflow configuration, the task instance will remain in Instance Wait until all prior instances of the same task, within an instance of the same workflow, have completed.

Web Service Details

This section contains assorted detailed information about the task.

Protocol


Protocol to use for the operation.
 
Options:

  • HTTP(S)/REST
  • SOAP

Default is HTTP(S)/REST.

HTTP Authentication


HTTP authentication scheme to use.
 
Options:

  • - - None - -
  • Basic

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:

${variable name}.

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


Version of the HTTP protocol to use.
 
Options:

  • 1.0
  • 1.1

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.
 
Options:

  • GET
  • POST
  • PUT
  • PATCH
  • DELETE

Default is POST.

SOAP Version

If Protocol = SOAP; Version of the SOAP protocol to use.
 
Options:

  • 1.1
  • 1.2

Default is 1.2.

Timeout


Number of seconds to wait for the request to complete.
 
If no value is specified, the value defaults to the Web Service Task Timeout Universal Controller property value.

URL

URL of the target service, excluding query parameters.
 
Optionally, you can include query parameters directly on the URL; however, the query string must be properly URL-encoded. In other words, the URL must be valid. For specifying unencoded query parameters, use URL 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.
 
Options:

  • Raw
  • Form Data

Default is Raw.

MIME Type

If Protocol = HTTP(S)/REST; MIME type of the message body.
 
Options:

  • application/javascript
  • application/json
  • application/xml
  • text/html
  • text/plain
  • text/xml
  • Other...

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

If Protocol = SOAP; Type of SOAP payload.
 
Options:

  • Body
  • Envelope

Default is Body.

SOAP Action

If Protocol = SOAP; Value of:

  • SOAPAction HTTP Header field in SOAP 1.1
  • action parameter in SOAP 1.2

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.
 
Options:

Default is Form.

Payload

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