/
Universal Command Task

Universal Command Task

Before You Begin

The Universal Command task allows you to run a platform-specific application on a machine where Universal Agent is running. Universal Command is functionality provided by the Agent that serves as an agent process. Universal Command runs on any supported platform: z/OS, Linux/Unix, and Windows.

To run a Universal Command task, you must first complete the following:

Note

If you are running multiple ubroker started tasks and want to run a Universal Command task on a specific ubroker, you must specify the service port number associated with that ubroker in the Universal Command Options field on the Universal Command Task Details. The syntax is -port nnnn.

Built-In Variables

The following built-in variables can be used in a Universal Command task to pass data where appropriate:

Creating a Universal Command Task

Step 1

From the Automation Center navigation pane, select Tasks > Universal Command Tasks. The Universal Command Tasks list displays a list of all currently defined Universal Command tasks.
 
To the right of the list, Universal Command Task Details for a new Universal Command task displays.
 

Step 2

Enter/select Details for a new Universal Command 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 a  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).

Universal Command Task Details

The following Universal Command Task Details is for an existing Universal Command task.

Depending on the values that you enter / select for these fields, and whether or not the Universal Command 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 Universal Command Task Details.
 

Universal Command Task Details Field Descriptions

The following table describes the fields, buttons, and tabs that display in the Universal Command 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.

Agent Details

This section contains assorted detailed information about the Agent / Agent Cluster selected for this task.

Cluster

Indication that selecting a Utility Agent Cluster is required.  If Cluster is selected, selecting a Utility Agent is not required unless Utility Agent Variable is selected.

Utility Agent

Name of the Agent resource that identifies the machine where the operation will run. If you do not specify a Utility Agent, you must specify a Utility Agent Cluster or Utility Cluster Broadcast.

Utility Agent Variable

If enabled, the Utility Agent field converts from a reference field (where you browse and select a record) into a text field that allows you to enter a variable. 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 Utility Agent reference to using a Utility Agent variable, you must change the Utility Agent Variable field to Yes and specify the Utility Agent variable in the Utility Agent Unresolved field. Conversely, to change from using a Utility Agent variable to using a Utility Agent reference, you must change the Utility Agent Variable field to No and specify the Utility Agent reference in the Utility Agent field.

Utility Agent Cluster

If Cluster is selected; Group of Agents, one of which the Controller will choose to run this task. You can specify a Utility Agent Cluster in addition to or in place of a specific Utility Agent. If you specify a Utility Agent and a Utility Agent Cluster, the Controller first tries to run the task on the specific Utility Agent. If the Utility Agent is not available, the Controller reverts to the Utility Agent Cluster. See Agent Clusters for more information.

Utility Agent Cluster Variable

Indication of whether the Utility Agent Cluster field is a reference field for selecting a specific Agent Cluster (unchecked) or a text field for specifying the Utility Agent Cluster 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 Utility Agent Cluster reference to using a Utility Agent Cluster variable, you must change the Utility Agent Cluster Variable field to Yes and specify the Utility Agent Cluster variable in the Utility Agent Cluster Unresolved field. Conversely, to change from using a Utility Agent Cluster variable to using a Utility Agent Cluster reference, you must change the Utility Agent Cluster Variable field to No and specify the Utility Agent Cluster reference in the Utility Agent Cluster field.

Utility Credentials


Login credentials that the Agent will use to access the Universal Command server machine.

Required if the Agent Credentials Required Universal Controller system property is true.

Utility Credentials Variable

Indication of whether the Utility Credentials field is a reference field for selecting a specific Credential (unchecked) or a text field for specifying the Utility Credentials 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 Utility Credentials reference to using a Utility Credentials variable, you must change the Utility Credentials Variable field to Yes and specify the Utility Credentials variable in the Utility Credentials Unresolved field. Conversely, to change from using a Utility Credentials variable to using a Utility Credentials reference, you must change the Utility Credentials Variable field to No and specify the Utility Credentials reference in the Utility Credentials field.

Universal Command Details

This section contains assorted detailed information about the task.

UCMD Agent

Depending on the value in the UCMD Agent Option field, this field contains either:

  • Record name from the UCMD Agent table.
  • Variable that will be resolved when the task is launched.
  • Host name of a machine where the UCMD Agent is running.

UCMD Agent Option

Specifies how the name of the UCMD Agent is being supplied in the UCMD Agent field.

Options:

  • UCMD Agent - UCMD Agent record is selected from the UCMD Agent table.
  • UCMD Agent Variable - UCMD Agent field contains a variable that will be resolved when the task is launched.
  • UCMD Agent Hostname - UCMD Agent field contains the host name where the UCMD Agent is running. The host name must be accessible by the Controller.

UCMD Credentials


Login credentials that Controller will use to access the remote machine where the UCMD Agent is running.

UCMD Credentials Variable

Indication of whether the UCMD Credentials field is a reference field for selecting a specific Credential (unchecked) or a text field for specifying the UCMD Credentials 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 UCMD Credentials reference to using a UCMD Credentials variable, you must change the UCMD Credentials Variable field to Yes and specify the UCMD Credentials variable in the UCMD Credentials Unresolved field. Conversely, to change from using a UCMD Credentials variable to using a UCMD Credentials reference, you must change the UCMD Credentials Variable field to No and specify the UCMD Credentials reference in the UCMD Credentials field.

Command or Script

Specifies whether a single command or a script is being executed.

Options:

  • Command (default)
  • Script

Command

Required if Command or Script = Command; Command being executed on the remote machine. Variables supported.

Script File

Required if Command or Script = Script; Path and filename of the script file that will be executed on the remote machine.

Script Options

If Command or Script = Script; Optional. One or more command line options to pass to the script file.

UCMD Options


Any UCMD options needed by the program to execute properly. Variables supported.

Runtime Directory


Directory from which the application should be executed. Variables supported.

Result Processing DetailsThis section contains assorted detailed information about result processing for this task.

Exit Code Processing

Specifies how the Controller should determine whether the executed command failed or completed successfully.

Options:

  • Success Exitcode Range
    Command is considered completed successfully if its exit code falls within the range specified in the Exit Codes field.
  • Failure Exitcode Range
    Command is considered failed if its exit code falls within the range specified in the Exit Codes field.
  • Success Output Contains
    Command is considered completed successfully if its output contains the text specified in the Scan Output For field.
  • Failure Output Contains
    Command is considered failed if its output contains the text specified in the Scan Output For field.
  • Step Conditions (z/OS only)
    Command is considered completed successfully/failed if any of its specified condition codes falls within the range specified under the Step Conditions tab (see Creating Step Conditions).

Output Type

Required if Exit Code Processing = Success Output Contains or Failure Output Contains; type of output.

Options:

  • Standard Output (STDOUT)
  • Standard Error (STDERR)
  • File
  • Extension

Scan Output For

Required if Exit Code Processing = Success Output Contains or Failure Output Contains; text for which the Controller should scan the output file. The Controller will process this field as a regular expression.

Output File (for Exit Code Processing)

Required if Output Type = File; path and file name of the output file that should be scanned for the text in the Scan Output For field.

Exit Codes

Required if Exit Code Processing = Success Exitcode Range or Failure Exitcode Range; range of exit codes. Format: Numeric. Use commas to list a series of exit codes; use hyphens to specify a range. Example: 1,5, 22-30.

Variables are supported.

Automatic Output Retrieval

Specifies whether you want the Controller to automatically retrieve any output from the job and attach it to the task instance record.

Options:

  • None
    Do not attach any output to the task instance record.
  • Standard Output
    Attach all standard output.
  • Standard Error
    Attach standard error output.
  • File
    Attach the file specified in the Output File field.
  • Standard Output/Error
    Attach all standard output and standard error output.
     

Note

Tasks specifying Automatic Output Retrieval will fail with Start Failure if the Agent Output Prohibited field is true in the Details of the specified Agent.

Wait For Output

If Automatic Output Retrieval = Standard Output, Standard Error, File, or Standard Output/Error, and Failure Only is not enabled (checked); Specification that the task should wait for the requested output before completing.

Failure Only

If Automatic Output Retrieval = Standard Output, Standard Error, File, or Standard Output/Error, and Wait For Output is not enabled (checked); I