Task Functions
Overview
The command line syntax for each execution of the CLI command, uagcmd, must specify a single CLI function, required / optional Global parameters, and required / optional function-specific parameters. You must use the required Global parameters to connect to OMS Servers and to log on to a Controller (User ID and Password).
Universal Controller supports the following CLI functions for Tasks, which are listed alphabetically on this page.
- Cancel Task
- Clear All Dependencies
- Clear Virtual Resource Dependencies
- Clear Exclusive Dependencies
- Clear Time Dependency
- Display All Tasks
- Display Task Instance Status
- Force Finish a Task
- Launch a Task
- Put Task on Hold
- Release a Task from Hold
- Rerun a Task
- Set Manual Task to Started
- Set Manual Task to Success
- Set or Modify Wait Time for a Task Instance
- Set Task Priority
- Skip a Task
Syntax, parameters, and examples for each function are provided.
Cancel Task
Description |
Cancels the specified task instance. |
---|---|
Syntax |
Note For backward-compatibility, you can exclude |
Parameter |
Deprecated Replaced by
|
Example |
uagcmd ops-task-cancel -c config.cfg task-instance-name=Task A |
Clear All Dependencies
Description |
Clears all dependencies of a task instance. |
---|---|
Syntax |
|
Parameters |
|
Example |
uagcmd ops-task-clear-dependencies -c config.cfg task-instance-name=Task A |
Clear Virtual Resource Dependencies
Description |
Clears all virtual resource dependencies of a task instance. |
---|---|
Syntax |
|
Parameters |
|
Example |
uagcmd ops-task-clear-resources -c config.cfg task-instance-name=Task A resource-name=Resource A |
Clear Exclusive Dependencies
Description |
Clears all exclusive dependencies of a task instance. |
---|---|
Syntax |
|
Parameters |
|
Example |
uagcmd ops-task-clear-exclusive -c config.cfg task-instance-name=Task A |
Clear Time Dependency
Description |
Clears the time dependency of a task instance. |
---|---|
Syntax |
|
Parameters |
|
Example |
uagcmd ops-task-clear-timewait -c config.cfg task-instance-name=Task A |
Display All Tasks
Description |
Displays all specified tasks. |
---|---|
Syntax |
Note For backward-compatibility, you can exclude |
Parameters |
|
Example |
uagcmd ops-task-list -c config.cfg task-name=Task A task-type=timer |
Display Task Instance Status
Description |
Displays the status of all task instance(s) associated with the specified task. |
---|---|
Syntax |
Note For backward-compatibility, you can exclude |
Parameters |
Deprecated Replaced by
|
Example |
uagcmd ops-task-status -c config.cfg task-instance-name=mantask agent-name=managent task-type=manual |
Task Instance Status Types
The following table describes all possible task instance statuses for all task types.
Note
The format of multi-word task status names specified in the Task Instance Status CLI function differs from the format of task status names used in the Controller user interface. In Task Instance Status, the words are separated by an underscore character; in the user interface, they are separated by a space.
Status Name |
Status Code |
Task Type |
Description |
---|---|---|---|
Action_Required |
60 |
Manual |
When a manual task launches, it goes into Action Required status, meaning a user must perform some manual activity. For details, see Manual task. |
Cancel_Pending |
99 |
A process running on the Agent needs to be terminated. When the Cancel command is issued, the task instance will go into a Cancel Pending status until the Agent reports back that the process has been cancelled. At that point, the task instance will transition into the Cancelled status. |
|
Cancelled |
130 |
All |
The task was cancelled by a user. |
Confirmation_Required |
125 |
z/OS |
If you make JCL changes and restart a z/OS task, Universal Controller will put the task into Confirmation Required status and prompt you for a confirmation. For detailed processing steps, see Rerunning a z/OS Task. |
Defined |
0 |
All |
The new task instance has been created (the task has been launched). |
Exclusive_Requested |
22 |
All |
All tasks with a mutually exclusive task defined go immediately to a status of Exclusive Requested. If the task is available to run exclusively, the task then moves to the next appropriate processing status. |
Exclusive_Wait |
23 |
All |
The task is mutually exclusive with one or more other tasks, and it is waiting for those tasks to finish before it will run. |
Execution_Wait |
33 |
The task must wait to be completed; either the Agent/Agent Cluster running the task has reached its Task Execution Limit, or the ability of the Agent/Agent Cluster to run tasks has been suspended. |
|
Failed |
140 |
All* |
The task ran to a failure status. |
Finished |
190 |
All |
The task was forced by the user to finish. The user may do this in cases where the task had a Cancelled or Failed status, and the user needed to release other task instances depending on the successful completion of this task instance in a workflow. For more information, see Force Finishing a Task. |
Held |
20 |
All |
The task has been put on hold by a user. |
In_Doubt |
110 |
The Agent is "in doubt" about the current status of the task instance. This may occur if an Agent or Agent connection goes down. In this case, the Agent restarts and reviews its data about tasks in progress. If the Agent finds a task still running, it resumes normal monitoring. If the Agent cannot find the task, this usually indicates that the task completed, but the Agent considers the task status to be "in doubt." |
|
Instance_Wait | 17 | All | The task instance has been loaded by a workflow and is waiting on a previous instance(s) of the same task based on the Instance Wait Resolved specification. |
Queued |
40 |
The task has been queued on a resource. |
|
Resource_Requested |
25 |
All |
All tasks with a virtual resource defined go immediately to a status of Resource Requested. If the resource is available, the task then moves to the next appropriate processing status. |
Resource_Wait |
30 |
All |
All tasks with a virtual resource defined go immediately to a status of Resource Requested. If the resource is not available, the task goes to a status of Resource Wait. When the resource becomes available, the task moves to the next appropriate processing status |
Running |
80 |
All |
The task is running. For Agent-based tasks, the Agent has started running the program. |
Running/Problems |
81 |
Workflow |
One or more tasks within the workflow has one of the following statuses:
|
Skipped |
180 |
All |
The task was skipped by a user. |
Start Failure |
120 |
All |
The task was unable to start. |
Started |
70 |
Agent-based, Manual |
The task has started. For Agent-based tasks, this means the Agent has received the task. |
Submitted |
43 |
z/OS |
The task has been submitted to the z/OS Job Entry subsystem and scheduled by the z/OS Job Scheduler. |
Success |
200 |
All |
The task has completed successfully. Workflows will transition to Success status when all of its tasks have transitioned to Success, Finished, or Skipped status. |
Time_Wait |
15 |
All (except Timer) |
The task is waiting to start based on a Wait To Start and/or Delay On Start specification. |
Undeliverable |
35 |
The Agent is unavailable. |
|
Waiting |
10 |
All |
The task has been loaded by a workflow and is waiting on a predecessor. |
* Workflows cannot go to Failed status.
Force Finish a Task
Description |
Force finishes the specified task instance. |
---|---|
Syntax |
Note For backward-compatibility, you can exclude |
Parameter |
Deprecated Replaced by
|
Example |
uagcmd ops-task-forcefinish -c config.cfg task-instance-id=90079020d861e5e40128cbb3cdbe1cf3 |
Launch a Task
Description |
Launches the specified task(s). |
---|---|
Syntax |
Note For backward-compatibility, you can exclude |
Parameters |
|
Example |
(All variable=value pairs must be specified within one set of braces.) uagcmd ops-task-launch -c config.cfg task-name=Windows Task A task-variables={variable1=first value variable2=second value} |
Put Task on Hold
Description |
Puts the specified task instance on hold. |
---|---|
Syntax |
Note For backward-compatibility, you can exclude |
Parameter |
Deprecated Replaced by
|
Example |
uagcmd ops-task-hold -c config.cfg task-instance=90079020d861e5e40128cbb3cdbe1cf3 |
Release a Task from Hold
Description |
Releases the specified task instance from hold. |
---|---|
Syntax |
Note For backward-compatibility, you can exclude |
Parameter |
Deprecated Replaced by
|
Example |
uagcmd ops-task-release -c config.cfg task-instance-id=90079020d861e5e40128cbb3cdbe1cf3 |
Rerun a Task
Description |
Reruns the specified Task instance. |
---|---|
Syntax |
Note For backward-compatibility, you can exclude |
Parameter |
Deprecated Replaced by
|
Example |
uagcmd ops-task-rerun -c config.cfg task-instance=8fda93dcd861e5e4005bf48e2cad6206 task-status=140 |
Set Manual Task to Started
Description |
For a Manual task, changes its status from Action Required to Started. This allows you to acknowledge the Manual task and indicate that the manual procedures have been started. |
---|---|
Syntax |
Note For backward-compatibility, you can exclude |
Parameter |
Deprecated Replaced by
|
Example |
uagcmd ops-manual-setstarted -c config.cfg task-instance=8fda93dcd861e5e4005bf48e2cad6206 |
Set Manual Task to Success
Description |
For a Manual task, sets its status to Success. |
---|---|
Syntax |
Note For backward-compatibility, you can exclude |
Parameter |
Deprecated Replaced by
|
Example |
uagcmd ops-manual-setcompleted -c config.cfg task-instance=8fda93dcd861e5e4005bf48e2cad6206 |
Set or Modify Wait Time for a Task Instance
Description |
Sets or modifies the Wait time for a task instance that specifies how long it will wait to run after it has become eligible to run. |
---|---|
Syntax |
|
Parameters |
|
Example |
uagcmd ops-task-set-timewait -c config.cfg task-instance-name=Task 5A workflow-instance-name=Workflow A wait-type=time wait-time=18:00 |
Set Task Priority
Description |
For Agent-based tasks (Linux/Unix, Universal, Windows, and z/OS), changes the priority on the specified task instance. |
---|---|
Syntax |
|
Parameters |
Deprecated Replaced by
|
Example |
uagcmd ops-task-setpriority -c config.cfg task-instance=90079026d861e5e400bba81913a4fdd0 priority=high |
Skip a Task
Description |
Skips the specified task instance. |
---|---|
Syntax |
|
Parameter |
Deprecated Replaced by
|
Example |
uagcmd ops-task-skip -c config.cfg task-instance=90079026d861e5e400bba81913a4fdd0 |