Creating a Universal Task
Before You Begin
Universal Task allows you to run a platform-specific application on a Linux/Unix or Windows machine. To run a Universal task, you must first complete the following tasks:
- Install Universal Agent for Linux/Unix on a Linux/Unix machine and/or install Universal Agent for Windows on a Windows machine.
- Launch the Agent(s). When an Agent connects with the Controller, it automatically creates an Agent resource definition in the database.
- Optionally, customize the Agent heartbeat and log levels, as described in:
Built-In Variables
In addition to the system-assigned variables in the Universal Template script that a Universal task executes, the following built-in variables can be used in a Universal task to pass data where appropriate:
Creating a Universal Task
Step 1 | From the Universal Tasks section of the Automation Center navigation pane, select a Universal Task type. The Universal Tasks list for that Universal Task type displays. |
---|---|
Step 2 | Enter / select Details for a new Universal 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 a Save button. The task is added to the database, and all buttons and tabs in the Universal 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 Task Details
The following Universal Task Details is for an existing Universal task.
Depending on the values that you enter / select for these fields, and whether or not the Universal 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 Task Details.
Universal Task Details Field Descriptions
The following table describes the fields, buttons, and tabs that display in the Universal 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. |
Agent Details | This section contains assorted detailed information about the Agent. |
Agent | Name of the Agent resource that identifies the machine where the operation will run. If you do not specify an Agent, you must specify an Agent Cluster. |
Agent Cluster | If Cluster is selected and Broadcast is not selected; Group of Agents, one of which the Controller will choose to run this task (compare with Cluster Broadcast). You can specify an agent cluster in addition to or in place of a specific Agent. If you specify an Agent and an agent cluster, the Controller first tries to run the task on the specific agent. If the Agent is not available, the Controller reverts to the agent cluster. See Agent Clusters for more information. |
Agent Variable | Indication of whether the Agent field is a reference field for selecting a specific Agent (unchecked) or a text field for specifying the Agent 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 an Agent reference to using an Agent variable, you must change the Agent Variable field to Yes and specify the Agent variable in the Agent Unresolved field. Conversely, to change from using an Agent variable to using an Agent reference, you must change the Agent Variable field to No and specify the Agent reference in the Agent field. |
Agent Cluster Variable | Indication of whether the Agent Cluster field is a reference field for selecting a specific Agent Cluster (unchecked) or a text field for specifying the Agent Cluster 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 an Agent Cluster reference to using an Agent Cluster variable, you must change the Agent Cluster Variable field to Yes and specify the Agent Cluster variable in the Agent Cluster Unresolved field. Conversely, to change from using an Agent Cluster variable to using an Agent Cluster reference, you must change the Agent Cluster Variable field to No and specify the Agent Cluster reference in the Agent Cluster field. |
Credentials | Credentials under which an Agent runs this task. These Credentials override any Credentials provided in the Agent Details for any Agent running this task. If the user does not have a login shell, add a - character in front of the runtime credentials name. The Controller will provide a shell for that user and strip the - character from the name. Required if the Agent Credentials Required Universal Controller system property is true. When required, if the Credential is specified as a variable, and the variable resolves to blank, a Start Failure will occur. |
Credentials Variable | Indication of whether the Credentials field is a reference field for selecting a specific Credential (unchecked) or a text field for specifying the 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. |
Cluster Broadcast | Group of Agents, all of which will run this task (compare with Agent Cluster). If Broadcast is selected for a task, you must select a Cluster Broadcast instead of a specific Agent and/or agent cluster. Each instance of the task running on its own Agent becomes a separate task instance record in the database and displays separately on the Activity Monitor. |
Cluster Broadcast Variable | Indication of whether the Cluster Broadcast field is a reference field for selecting a specific Cluster Broadcast (unchecked) or a text field for specifying the Cluster Broadcast 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 Cluster Broadcast reference to using a Cluster Broadcast variable, you must change the Cluster Broadcast Variable field to Yes and specify the Cluster Broadcast variable in the Cluster Broadcast Unresolved field. Conversely, to change from using a Cluster Broadcast variable to using a Cluster Broadcast reference, you must change the Cluster Broadcast Variable field to No and specify the Cluster Broadcast reference in the Cluster Broadcast field. |
Run with Highest Privileges | For Windows Agents; Execute the task using an elevated privileges token, rather than one subject to User Account Control (UAC) restrictions. An elevated token allows a process to execute with all the privileges available to its specified credentials. For example, a task executed with an administrative account will behave as though it received permission via a UAC dialog to perform a privileged operation. Note This option only will affect tasks executed on Windows systems that support User Account Control (UAC). It will have no affect on tasks run on Windows releases prior to Vista (for example, Windows XP, Server 2003). |
Universal Task Details | This section contains assorted detailed information about the Agent. Note The fields in this section may have Read Only or Hidden restrictions applied to them, as specified in the Universal Template on which the Universal Task is based. |
(user-defined fields) | The Details for each Universal Task contains any editable fields that were created in the Universal Template on which the Universal Task type for that Universal Task is based. System-assigned variables that match these fields are provided for inclusion in the template script. When the task is run, it executes the script, and the variables are resolved to the values of their matching values in the task. There are eight types of user-defined fields that can appear in the Details of a Universal Task:
For each type of field, default values, format, and/or limitations are specified in the Universal Template. In any Universal Task based on that Universal Template, you can override and/or define values - within the specified format and limitations - for those fields.
|
Runtime Directory |
|
Environment Variables |
Allows you to enter environment variables needed by the program to run. To add a variable, click the + icon and enter a Name and Value. To delete a variable, select in the list of variables and click the - icon. You can add a maximum of 4,000 characters for the combined Names and Values of all variables. The variable is listed in the space underneath. |
Result Processing Details | This 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:
|
Output Type | Required if Exit Code Processing = Success Output Contains or Failure Output Contains; type of output. Options:
|
Content Type | If Output Type is Extension; Output type that the Result Processing mechanism should assume when evaluating the output. If the expected output is XML or JSON, it is valid to specify Text. However, when specifying XML or JSON, the output must be XML or JSON respectively; otherwise, the parsing will fail and the path expression evaluation will return no matches. |
Path Expression | XPath Expression if Content Type is XML, or the JsonPath Expression if Content Type is JSON, to be used when evaluating the Extension output. |
Operator | If Output Type is Extension; Condition Operator to evaluate in combination with the specified condition Value. |
Value | If Output Type is Extension; Condition Value to evaluate in combination with the specified condition Operator. |
Strategy | If Content Type is XML or JSON; Strategy to take when applying the condition Operator and Value against the Path Expression matches when Content Type is XML or JSON. |
Auto Cleanup | Enables the auto cleanup of Extension output upon task instance completion or, if the task instance is within a workflow, when the top level workflow instance completes. |
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:
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); Indication for whether output should be retrieved on task failure only. |
Start Line | If Automatic Output Retrieval = Standard Output, Standard Error, File, or Standard Output/Error; Instructs the Controller to retrieve data beginning at the line indicated.
|
Number of Lines | If Automatic Output Retrieval = Standard Output, Standard Error, File, or Standard Output/Error; Allows you to limit the retrieved data to the number of lines specified. If a Number of Lines value is not specified, the default is the value of the Retrieve Output Default Number Of Lines Universal Controller system property. |
Scan Text | If Automatic Output Retrieval = Standard Output, Standard Error, File, or Standard Output/Error; Regex pattern that the Controller will search for a match for in STDOUT/STDERR or a specified file. The Controller will include the Number of Lines above and below the first line matched. |
Output File (for Automatic Output Retrieval) | Required if Automatic Output Retrieval = File; path and file name containing the output that you want automatically retrieved and attached to the task instance. |
Retry Options | This section contains specifications for retrying the task. |
Retry Exit Codes |
Exit code range for which an auto-retry of tasks in FAILED status will occur. Exit code ranges must be in the same format as ranges specified in the Exit Codes field. Maximum Retries must be greater than 0. If this field is empty, any exit code potentially will cause a retry. Variables are supported. |
Maximum Retries |
User-defined; maximum number of times that the Controller should retry this task after it has started and gone to a failed state. |
Retry Indefinitely | User-defined; indicates whether the Controller should continue trying indefinitely to run this task. If you enable this field, it overrides any value placed in the Maximum Retries field. |
Retry Interval (Seconds) |
User-defined; number of seconds between each retry. |
Suppress Intermediate Failures | User-defined; If the task instance is in the Failed status, indicates whether or not the following will be suppressed until all scheduled retry attempts (a Maximum Retries value has been entered or Retry Indefinitely has been enabled) have been made:
|
Wait / Delay Options | This section contains specifications for waiting to start and/or delaying on start the task. |
Wait To Start |
Amount of time to wait before starting a task from the time that it was launched.
|
Wait Time | If Wait To Start = Time or Relative Time; Time of day (in 24-hour time) to wait until before starting the task. |
Wait Day Constraint | If Wait To Start = Time or Relative Time; Specification for whether or not to advance the wait time to another day. Valid values:
Default is – None --. |