Overview

Universal Controller supports the following RESTful-based web services for Task Instance operations, which are listed alphabetically on this page.

Cancel a Task Instance
Clear All Dependencies
Clear Exclusive Dependencies
Clear Predecessor Dependencies
Clear Time Dependency
Clear Virtual Resource Dependencies
Delete a Task Instance
Force/Finish a Task Instance
Force/Finish Cancel a Task Instance
Hold a Task Instance
Issue Set Completed Command for a Manual Task Instance
Issue Set Started Command for a Manual Task Instance
List Task Instances
List Task Instances - Advanced
List Task Instance Variables (Show Variables)
Release a Task Instance from Hold
Rerun a Task Instance
Retrieve Task Instance Output
Set or Modify Wait Time/Duration for Task Instance
Set Priority for a Task Instance
Skip a Task Instance
Skip a Task Instance Path
Unskip a Task Instance
Update a Task Instance Operational Memo

Formatting specifications for each web service, including details about parameter requirements, are provided.

For RESTful-based web services for Workflow Task Instance operations, see Workflow Task Instance Web Services.

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 Web Service 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	Agent-based	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	Agent-based	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	Agent-based	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."
Queued	40	Agent-based	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: Cancelled Confirmation Required Failure In Doubt Running/Problems (for sub-workflows) Start Failure Undeliverable
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	Agent-based	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.

Cancel a Task Instance

Note

A Web Service Task instance cannot be cancelled if the specified Protocol is SOAP.

	Description
URI	http://host_name/uc/resources/taskinstance/cancel
HTTP Method	POST
Description	Cancel a task instance.
Example URI	http://localhost:8080/uc/resources/taskinstance/cancel
Authentication	HTTP Basic
Consumes Content-Type	application/xml, application/json
Produces Content-Type	application/xml, application/json
Example Request	See Cancel a Task Instance: XML and JSON Examples.
Request Properties	See Cancel a Task Instance: Request Properties.
Example Response	See Cancel a Task Instance: XML and JSON Examples.

Cancel a Task Instance: XML and JSON Examples

Examples

XML

JSON

Example Request

XML

<task-instance>
      <id>1464817327170011848D633V6106ENQ7</id>
</task-instance>

or

<task-instance>
      <name>Timer 60</name>
      <criteria>Newest Instance</criteria>
      <workflowInstanceName>test</workflowInstanceName>
</task-instance>

JSON

{
"name": "Timer 60",
"criteria": "Newest Instance",
"workflowInstanceName": "test"
}

Example Response

XML

<command-response>
      <type>cancel</type>
      <success>true</success>
      <info>Command Cancel executed successfully against task instance "test".</info>
      <errors />
</command-response>

JSON

{
  "type": "cancel",
  "success": true,
  "info": "Command Cancel executed successfully against task instance \"Timer 60\".",
  "errors": ""
}

Cancel a Task Instance: Request Properties

Property	UI Field Name	Description	Specifications	Required	Mutually Exclusive With
`criteria`	n/a	Specific task instance with this task instance `name` that you want to cancel.	Valid values: As String = Oldest Active Instance, As Value = 1 As String = Newest Active Instance, As Value = 2 As String = Oldest Instance, As Value = 3 As String = Newest Instance, As Value = 4 Default is Oldest Active Instance (1). Note Values with an underscore characters ( _ ) instead of spaces also are supported (for example, oldest_active_instance).	N
`id`	n/a	sys_id used within the Controller to identify this task instance.		Y (unless `name` is specified)	`name`
`name`	Instance Name	Name of the task instance.		Y (unless `id` is specified)	`id`
`workflowInstanceName`	Workflow	Name of the parent Workflow of the task instance.	You can select to display the Workflow field on the Activity Monitor and/or Task Instances List; it is not displayed in the Task Instance Details.	N

Clear All Dependencies

	Description
URI	http://host_name/uc/resources/taskinstance/cleardependencies
HTTP Method	POST
Description	Clears all dependencies of a task instance.
Example URI	http://localhost:8080/uc/resources/taskinstance/cleardependencies
Authentication	HTTP Basic
Consumes Content-Type	application/xml, application/json
Produces Content-Type	application/xml, application/json
Example Request	See Clear All Dependencies: XML and JSON Examples.
Request Properties	See Clear All Dependencies: Request Properties.
Example Response	See Clear All Dependencies: XML and JSON Examples.

Clear All Dependencies: XML and JSON Examples

Examples

XML

JSON

Example Request

XML

<task-instance>
	<id>1464817327170011848D633V6106ENQ7</id>
</task-instance>

or

<task-instance>
      <name>Timer 60</name>
      <criteria>Newest Instance</criteria>
      <workflowInstanceName>test</workflowInstanceName> 
</task-instance>

JSON

{
"name": "Timer 60",
"criteria": "Newest Instance",
"workflowInstanceName": "Test"
}

Example Response

XML

<command-response>
      <type>clear_all_dependencies</type>
      <success>true</success>
      <info>Command Clear All Dependencies executed successfully against task instance "Timer 60".</info>
      <errors />
</command-response>

JSON

{
  "type": "clear_all_dependencies",
  "success": true,
  "info": "Command Clear All Dependencies executed successfully against task instance \"Timer 60\".",
  "errors": ""
}

Clear All Dependencies: Request Properties

Property	UI Field Name	Description	Specifications	Required	Mutually Exclusive With
`criteria`	n/a	Specific task instance with this task instance `name` for which you want to clear all dependencies.	Valid values: As String = Oldest Active Instance, As Value = 1 As String = Newest Active Instance, As Value = 2 As String = Oldest Instance, As Value = 3 As String = Newest Instance, As Value = 4 Default is Oldest Active Instance (1). Note Values with an underscore characters ( _ ) instead of spaces also are supported (for example, oldest_active_instance).	N
`id`	n/a	sys_id used within the Controller to identify this task instance.		Y (unless `name` is specified)	`name`
`name`	Instance Name	Name of the task instance.		Y (unless `id` is specified)	`id`
`workflowInstanceName`	Workflow	Name of the parent Workflow of the task instance.	You can select to display the Workflow field on the Activity Monitor and/or Task Instances List; it is not displayed in the Task Instance Details.	N

Clear Exclusive Dependencies

	Description
URI	http://host_name/uc/resources/taskinstance/clearexclusive
HTTP Method	POST
Description	Clears all exclusive dependencies of a task instance.
Authentication	HTTP Basic
Example URI	http://localhost:8080/uc/resources/taskinstance/clearexclusive
Consumes Content-Type	application/xml, application/json
Produces Content-Type	application/xml, application/json
Example Request	See Clear Exclusive Dependencies: XML and JSON Examples.
Request Properties	See Clear Exclusive Dependencies: Request Properties.
Example Response	See Clear Exclusive Dependencies: XML and JSON Examples.

Clear Exclusive Dependencies: XML and JSON Examples

Examples

XML

JSON

Example Request

XML

<task-instance>
	<id>1464817327170011848D633V6106ENQ7</id>
</task-instance>

or

<task-instance>
      <name>Timer 60</name>
      <criteria>Newest Instance</criteria>
      <workflowInstanceName>test</workflowInstanceName> 
</task-instance>

JSON

{
"name": "Timer 60",
"criteria": "Newest Instance",
"workflowInstanceName": "Test"
}

Example Response

XML

<command-response>
      <type>clear_exclusive</type>
      <success>true</success>
      <info>Command Clear Exclusive executed successfully against task instance "Timer 60".</info>
      <errors />
</command-response>

JSON

{
  "type": "clear_exclusive",
  "success": true,
  "info": "Command Clear Exclusive executed successfully against task instance \"Timer 60\".",
  "errors": ""
}

Clear Exclusive Dependencies: Request Properties

Property	UI Field Name	Description	Specifications	Required	Mutually Exclusive With
`criteria`	n/a	Specific task instance with this task instance `name` for which you want to clear exclusive dependencies.	Valid values: As String = Oldest Active Instance, As Value = 1 As String = Newest Active Instance, As Value = 2 As String = Oldest Instance, As Value = 3 As String = Newest Instance, As Value = 4 Default is Oldest Active Instance (1). Note Values with an underscore characters ( _ ) instead of spaces also are supported (for example, oldest_active_instance).	N
`id`	n/a	sys_id used within the Controller to identify this task instance.		Y (unless `name` is specified)	`name`
`name`	Instance Name	Name of the task instance.		Y (unless `id` is specified)	`id`
`workflowInstanceName`	Workflow	Name of the parent Workflow of the task instance.	You can select to display the Workflow field on the Activity Monitor and/or Task Instances List; it is not displayed in the Task Instance Details.	N

Clear Predecessor Dependencies

	Description
URI	http://host_name/uc/resources/taskinstance/clearpredecessors
HTTP Method	POST
Description	Clears all predecessor dependencies of a task instance in a Workflow.
Authentication	HTTP Basic
Example URI	http://localhost:8080/uc/resources/taskinstance/clearpredecessors
Consumes Content-Type	application/xml, application/json
Produces Content-Type	application/xml, application/json
Example Request	See Clear Predecessor Dependencies: XML and JSON Examples.
Request Properties	See Clear Predecessor Dependencies: Request Properties.
Example Response	See Clear Predecessor Dependencies: XML and JSON Examples.

Clear Predecessor Dependencies: XML and JSON Examples

Examples

XML

JSON

Example Request

XML

<task-instance>
      <id>1464817327170011848D633V6106ENQ7</id>
      <predecessorName>*</predecessorName>
</task-instance>

or

<task-instance>
      <name>Timer 60</name>
      <criteria>Newest Instance</criteria>
      <workflowInstanceName>test</workflowInstanceName> 
      <predecessorName>*</predecessorName>
</task-instance>

JSON

{
"name": "Timer 60",
"criteria": "Newest Instance",
"workflowInstanceName": "Test",
"predecessorName": "Task 1"
}

Example Response

XML

<command-response>
      <type>set_edges_satisfied</type>
      <success>true</success>
      <info>Command Clear Predecessors executed successfully against task instance "Timer 60".</info>
      <errors />
</command-response>

JSON

{
  "type": "set_edge_satisfied",
  "success": true,
  "info": "Successfully marked the dependency as satisfied.",
  "errors": ""
}

Clear Predecessor Dependencies: Request Properties

Property	UI Field Name	Description	Specifications	Required	Mutually Exclusive With
`criteria`	n/a	Specific task instance with this task instance `name` for which you want to clear predecessor dependencies.	Valid values: As String = Oldest Active Instance, As Value = 1 As String = Newest Active Instance, As Value = 2 As String = Oldest Instance, As Value = 3 As String = Newest Instance, As Value = 4 Default is Oldest Active Instance (1). Note Values with an underscore characters ( _ ) instead of spaces also are supported (for example, oldest_active_instance).	N
`id`	n/a	sys_id used within the Controller to identify this task instance.		Y (unless `name` is specified)	`name`
`name`	Instance Name	Name of the task instance.		Y (unless `id` is specified)	`id`
`predecessorName`	n/a	Name of the predecessor task instance for which you want to clear dependency.	* = Clears dependencies from all predecessor task instances.	Y
`workflowInstanceName`	Workflow	Name of the parent Workflow of the task instance.	You can select to display the Workflow field on the Activity Monitor and/or Task Instances List; it is not displayed in the Task Instance Details.	N

Clear Time Dependency

	Description
URI	http://host_name/uc/resources/taskinstance/cleartimewait
HTTP Method	POST
Description	Clears the time dependency of a task instance.
Authentication	HTTP Basic
Example URI	http://localhost:8080/uc/resources/taskinstance/cleartimewait
Consumes Content-Type	application/xml, application/json
Produces Content-Type	application/xml, application/json
Example Request	See Clear Time Dependency: XML and JSON Examples.
Request Properties	See Clear Time Dependency : Request Properties.
Example Response	See Clear Time Dependency: XML and JSON Examples.

Clear Time Dependency: XML and JSON Examples

Examples

XML

JSON

Example Request

XML

<task-instance>
      <id>1464817327170011848D633V6106ENQ7</id>
</task-instance>

or

<task-instance>
      <name>Test task</name>
      <criteria>Newest Instance</criteria>
      <workflowInstanceName>test</workflowInstanceName> 
</task-instance>

JSON

{
"name": "Task 1",
"criteria": "Newest Instance",
"workflowInstanceName": "Test"
}

Example Response

XML

<command-response>
      <type>clear_timewait</type>
      <success>true</success>
      <info>Command Clear Time Wait/Delay executed successfully against task instance "Test task".</info>
      <errors />
</command-response>

JSON

{
  "type": "clear_timewait",
  "success": true,
  "info": "Command Clear Time Wait/Delay executed successfully against task instance \"Task 1\".",
  "errors": ""
}

Clear Time Dependency: Request Properties

Property	UI Field Name	Description	Specifications	Required	Mutually Exclusive With
`criteria`	n/a	Specific task instance with this task instance `name` for which you want to clear time dependency.	Valid values: As String = Oldest Active Instance, As Value = 1 As String = Newest Active Instance, As Value = 2 As String = Oldest Instance, As Value = 3 As String = Newest Instance, As Value = 4 Default is Oldest Active Instance (1). Note Values with an underscore characters ( _ ) instead of spaces also are supported (for example, oldest_active_instance).	N
`id`	n/a	sys_id used within the Controller to identify this task instance.		Y (unless `name` is specified)	`name`
`name`	Instance Name	Name of the task instance.		Y (unless `id` is specified)	`id`
`workflowInstanceName`	Workflow	Name of the parent Workflow of the task instance.	You can select to display the Workflow field on the Activity Monitor and/or Task Instances List; it is not displayed in the Task Instance Details.	N

Clear Virtual Resource Dependencies

	Description
URI	http://host_name/uc/resources/taskinstance/clearresources
HTTP Method	POST
Description	Clears virtual resource dependencies of a task instance.
Authentication	HTTP Basic
Example URI	http://localhost:8080/uc/resources/taskinstance/clearresources
Consumes Content-Type	application/xml, application/json
Produces Content-Type	application/xml, application/json
Example Request	See Clear Virtual Resource Dependencies: XML and JSON Examples.
Request Properties	See Clear Virtual Resource Dependencies: Request Properties.
Example Response	See Clear Virtual Resource Dependencies: XML and JSON Examples.

Clear Virtual Resource Dependencies: XML and JSON Examples

Examples

XML

JSON

Example Request

XML

<task-instance>
      <id>1464817327170011848D633V6106ENQ7</id>
      <resourceName>V1</resourceName>
</task-instance>

or

<task-instance>
      <name>Timer 60</name>
      <criteria>Newest Instance</criteria>
      <workflowInstanceName>test</workflowInstanceName> 
      <resourceName>V1</resourceName>
</task-instance>

JSON

{
"name": "Task 1",
"criteria": "Newest Instance",
"workflowInstanceName": "Test",
"resourceName": "V1"
}

Example Response

XML

<command-response>
      <type>clear_resources</type>
      <success>true</success>
      <info>Command Clear Resources executed successfully against task instance "Timer 60".</info>
      <errors />
</command-response>

JSON

{
  "type": "clear_resources",
  "success": true,
  "info": "Command Clear Resources executed successfully against task instance \"Task 1\".",
  "errors": ""
}

Clear Virtual Resource Dependencies: Request Properties

Property	UI Field Name	Description	Specifications	Required	Mutually Exclusive With
`criteria`	n/a	Specific task instance with this task instance `name` for which you want to clear virtual resource dependencies.	Valid values: As String = Oldest Active Instance, As Value = 1 As String = Newest Active Instance, As Value = 2 As String = Oldest Instance, As Value = 3 As String = Newest Instance, As Value = 4 Default is Oldest Active Instance (1). Note Values with an underscore characters ( _ ) instead of spaces also are supported (for example, oldest_active_instance).	N
`id`	n/a	sys_id used within the Controller to identify this task instance.		Y (unless `name` is specified)	`name`
`name`	Instance Name	Name of the task instance.		Y (unless `id` is specified)	`id`
`resourceName`	n/a	Name of the virtual resource for which you want to clear dependency.	* = Clears dependencies from all virtual resources.	Y
`workflowInstanceName`	Workflow	Name of the parent Workflow of the task instance.	You can select to display the Workflow field on the Activity Monitor and/or Task Instances List; it is not displayed in the Task Instance Details.	N

Delete a Task Instance

	Description
URI	http://host_name/uc/resources/taskinstance
HTTP Method	DELETE
Description	Deletes the specified task instance. For Workflow task instances, if the `recursive` property is set to true, all children task instances will be removed.
Authentication	HTTP Basic
Consumes Content-Type	application/xml, application/json
Example URI	http://localhost:8080/uc/resources/taskinstance
Example Request	See Delete a Task Instance: XML and JSON Examples.
Request Properties	See Delete a Task Instance: Request Properties.
Example Response	Status 200 /OK Task instance(s) deleted successfully.

Delete a Task Instance: XML and JSON Examples

XML

JSON

XML

Delete Task instance by task instance id.

<task-instance>
      <id>1464817327170011848D633V6106ENQ7</id>
</task-instance>

Delete Task instance and all of its children by task instance id.

<task-instance>
      <id>14483224900880190549PGHP23IR12MO</id>
      <recursive>true</recursive>
</task-instance>

Delete Task instance by task instance name.

<task-instance>
      <name>Timer 60</name>
      <criteria>Newest Instance</criteria>
</task-instance>

JSON

{
"name": "Task 1",
"criteria": "Newest Instance"
}

Delete a Task Instance: Request Properties

Property	UI Field Name	Description	Specifications	Required	Mutually Exclusive With
`criteria`	n/a	Specific task instance with this task instance `name` which you want to delete.	Valid values: As String = Oldest Instance, As Value = 3 As String = Newest Instance, As Value = 4 Default is Oldest Instance (3). Note Values with an underscore characters ( _ ) instead of spaces also are supported (for example, oldest_instance).	N
`id`	n/a	sys_id used within the Controller to identify this task instance.		Y (unless `name` is specified)	`name`
`name`	Instance Name	Name of the task instance.		Y (unless `id` is specified)	`id`
`recursive`	n/a	For Workflow task instances only; Specification for whether or not to delete all children task instances of the task instance.	Boolean; Valid values: true/false. Default is false.	N

Force Finish a Task Instance

	Description
URI	http://host_name/uc/resources/taskinstance/forcefinish
HTTP Method	POST
Description	Force Finish a task instance. (To Force Finish (Halt) a task instance, set the halt property to true.)
Example URI	http://localhost:8080/uc/resources/taskinstance/forcefinish
Authentication	HTTP Basic
Consumes Content-Type	application/xml, application/json
Produces Content-Type	application/xml, application/json
Example Request	See Force Finish a Task Instance: XML and JSON Examples.
Request Properties	See Force Finish a Task Instance: Request Properties.
Example Response	See Force Finish a Task Instance: XML and JSON Examples.

Force Finish a Task Instance: XML and JSON Examples

Examples

XML

JSON

Example Request

XML

<task-instance>
      <id>1464817327170011848D633V6106ENQ7</id>
</task-instance>

or

<task-instance>
      <name>Timer 60</name>
      <halt>true</halt>
      <criteria>Newest Instance</criteria>
      <workflowInstanceName>test</workflowInstanceName> 
</task-instance>

JSON

{
"name": "Task 1",
"halt": "True",
"criteria": "Newest Instance",
"workflowInstanceName": "Test"
}

Example Response

XML

<command-response>
    <type>force_finish</type>
    <success>true</success>
    <info>Command Force Finish executed successfully against task instance "test".</info>
    <errors />
</command-response>

JSON

{
  "type": "force_finish",
  "success": true,
  "info": "Command Force Finish executed successfully against task instance \"Task 1\".",
  "errors": ""
}

Force Finish a Task Instance: Request Properties

Property	UI Field Name	Description	Specifications	Required	Mutually Exclusive With
`criteria`	n/a	Specific task instance with this task instance `name` that you want to force finish.	Valid values: As String = Oldest Active Instance, As Value = 1 As String = Newest Active Instance, As Value = 2 As String = Oldest Instance, As Value = 3 As String = Newest Instance, As Value = 4 Default is Oldest Active Instance (1). Note Values with an underscore characters ( _ ) instead of spaces also are supported (for example, oldest_active_instance).	N
`halt`	n/a	Prevents successor task instances of the specified task instance in a Workflow from being run.	Boolean. Valid values: true/false. Default is false.	N
`id`	n/a	sys_id used within the Controller to identify this task instance.		Y (unless `name` is specified)	`name`
`name`	Instance Name	Name of the task instance.		Y (unless `id` is specified)	`id`
`workflowInstanceName`	Workflow	Name of the parent Workflow of the task instance.	You can select to display the Workflow field on the Activity Monitor and/or Task Instances List; it is not displayed in the Task Instance Details.	N

Force Finish/Cancel a Task Instance

	Description
URI	http://host_name/uc/resources/taskinstance/forcefinishcancel
HTTP Method	POST
Description	Force Finish/Cancel a task instance. (To Force Finish/Cancel (Halt) a task instance, set the halt property to true.)
Example URI	http://localhost:8080/uc/resources/taskinstance/forcefinishcancel
Authentication	HTTP Basic
Consumes Content-Type	application/xml, application/json
Produces Content-Type	application/xml, application/json
Example Request	See Force Finish Cancel a Task Instance: XML and JSON Examples.
Request Properties	See Force Finish/Cancel a Task Instance: Request Properties.
Example Response	See Force Finish Cancel a Task Instance: XML and JSON Examples.

Force Finish/Cancel a Task Instance: XML and JSON Examples

Examples

XML

JSON

Example Request

XML

<task-instance>
      <id>1464817327170011848D633V6106ENQ7</id>
</task-instance>

or

<task-instance>
      <name>Timer 60</name>
      <halt>true</halt>
      <criteria>Newest Instance</criteria>
      <workflowInstanceName>test</workflowInstanceName> 
</task-instance>

JSON

{
"name": "Task 1",
"halt": "True",
"criteria": "Newest Instance",
"workflowInstanceName": "Test"
}

Example Response

XML

<command-response>
    <type>force_finish_cancel</type>
    <success>true</success>
    <info>Command Force Finish/Cancel executed successfully against task instance "test".</info>
    <errors />
</command-response>

JSON

{
  "type": "force_finish_cancel",
  "success": true,
  "info": "Command Force Finish/Cancel executed successfully against task instance \"Task 1\".",
  "errors": ""
}

Force Finish/Cancel a Task Instance: Request Properties

Property	UI Field Name	Description	Specifications	Required	Mutually Exclusive With
`criteria`	n/a	Specific task instance with this task instance `name` that you want to force finish/cancel.	Valid values: As String = Oldest Active Instance, As Value = 1 As String = Newest Active Instance, As Value = 2 As String = Oldest Instance, As Value = 3 As String = Newest Instance, As Value = 4 Default is Oldest Active Instance (1). Note Values with an underscore characters ( _ ) instead of spaces also are supported (for example, oldest_active_instance).	N
`halt`	n/a	Prevents successor task instances of the specified task instance in a Workflow from being run.	Boolean. Valid values: true/false. Default is false.	N
`id`	n/a	sys_id used within the Controller to identify this task instance.		Y (unless `name` is specified)	`name`
`name`	Instance Name	Name of the task instance.		Y (unless `id` is specified)	`id`
`workflowInstanceName`	Workflow	Name of the parent Workflow of the task instance.	You can select to display the Workflow field on the Activity Monitor and/or Task Instances List; it is not displayed in the Task Instance Details.	N

Hold a Task Instance

	Description
URI	http://host_name/uc/resources/taskinstance/hold
HTTP Method	POST
Description	Hold a task instance.
Example URI	http://localhost:8080/uc/resources/taskinstance/hold
Authentication	HTTP Basic
Consumes Content-Type	application/xml, application/json
Produces Content-Type	application/xml, application/json
Example Request	See Hold a Task Instance: XML and JSON Examples.
Request Properties	See Hold a Task Instance: Request Properties.
Example Response	See Hold a Task Instance: XML and JSON Examples.

Hold a Task Instance: XML and JSON Examples

Examples

XML

JSON

Example Request

XML

<task-instance>
      <id>410d6c0bc0a801c901838d8ac43b3279</id>
</task-instance>

or

<task-instance>
      <name>Timer 60</name>
      <criteria>Newest Instance</criteria>
      <workflowInstanceName>test</workflowInstanceName> 
</task-instance>

JSON

{
"name": "Task 1",
"criteria": "Newest Instance",
"workflowInstanceName": "Test"
}

Example Response

XML

<command-response>
    <type>hold</type>
    <success>true</success>
    <info>Command Hold executed successfully against task instance "test".</info>
    <errors />
</command-response>

JSON

{
  "type": "hold",
  "success": true,
  "info": "Command Hold executed successfully against task instance \"Task 1\".",
  "errors": ""
}

Hold a Task Instance: Request Properties

Property	UI Field Name	Description	Specifications	Required	Mutually Exclusive With
`criteria`	n/a	Specific task instance with this task instance `name` that you want to hold.	Valid values: As String = Oldest Active Instance, As Value = 1 As String = Newest Active Instance, As Value = 2 As String = Oldest Instance, As Value = 3 As String = Newest Instance, As Value = 4 Default is Oldest Active Instance (1). Note Values with an underscore characters ( _ ) instead of spaces also are supported (for example, oldest_active_instance).	N
`id`	n/a	sys_id used within the Controller to identify this task instance.		Y (unless `name` is specified)	`name`
`name`	Instance Name	Name of the task instance.		Y (unless `id` is specified)	`id`
`workflowInstanceName`	Workflow	Name of the parent Workflow of the task instance.	You can select to display the Workflow field on the Activity Monitor and/or Task Instances List; it is not displayed in the Task Instance Details.	N

Issue Set Completed Command for a Manual Task Instance

	Description
URI	http://host_name/uc/resources/taskinstance/setcompleted
HTTP Method	POST
Description	Issues a Set Completed command for a Manual Task instance.
Example URI	http://localhost:8080/uc/resources/taskinstance/setcompleted
Authentication	HTTP Basic
Consumes Content-Type	application/xml, application/json
Produces Content-Type	application/xml, application/json
Example Request	See Issue Set Completed Command for a Manual Task Instance: XML and JSON Examples.
Request Properties	See Issue Set Completed Command for a Manual Task Instance: Request Properties.
Example Response	See Issue Set Completed Command for a Manual Task Instance: XML and JSON Examples.

Issue Set Completed Command for a Manual Task Instance: XML and JSON Examples

Examples

XML

JSON

Example Request

XML

<task-instance>
      <id>1464817327170011848D633V6106ENQ7</id>
</task-instance>

or

<task-instance>
      <name>test manual</name>
      <criteria>Newest Instance</criteria>
      <workflowInstanceName>test</workflowInstanceName> 
</task-instance>

JSON

{
"name": "Task 1",
"criteria": "Newest Instance",
"workflowInstanceName": "Test"
}

Example Response

XML

<command-response>
    <type>set_manual_completed</type>
    <success>true</success>
    <info>Command Set Completed executed successfully against task instance "test".</info>
    <errors />
</command-response>

JSON

{
  "type": "set_manual_completed",
  "success": true,
  "info": "Command Set Completed executed successfully against task instance \"Task 1\".",
  "errors": ""
}

Issue Set Completed Command for a Manual Task Instance: Request Properties

Property	UI Field Name	Description	Specifications	Required	Mutually Exclusive With
`criteria`	n/a	Specific task instance with this task instance `name` that you want to issue a Set Completed command for.	Valid values: As String = Oldest Active Instance, As Value = 1 As String = Newest Active Instance, As Value = 2 As String = Oldest Instance, As Value = 3 As String = Newest Instance, As Value = 4 Default is Oldest Active Instance (1). Note Values with an underscore characters ( _ ) instead of spaces also are supported (for example, oldest_active_instance).	N
`id`	n/a	sys_id used within the Controller to identify this task instance.		Y (unless `name` is specified)	`name`
`name`	Instance Name	Name of the task instance.		Y (unless `id` is specified)	`id`
`workflowInstanceName`	Workflow	Name of the parent Workflow of the task instance.	You can select to display the Workflow field on the Activity Monitor and/or Task Instances List; it is not displayed in the Task Instance Details.	N

Issue Set Started Command for a Manual Task Instance

	Description
URI	http://host_name/uc/resources/taskinstance/setstarted
HTTP Method	POST
Description	Issues a Set Started command for a Manual Task instance.
Example URI	http://localhost:8080/uc/resources/taskinstance/setstarted
Authentication	HTTP Basic
Consumes Content-Type	application/xml, application/json
Produces Content-Type	application/xml, application/json
Example Request	See Issue Set Started Command for a Manual Task Instance: XML and JSON Examples.
Request Properties	See Issue Set Started Command for a Manual Task Instance: Request Properties
Example Response	See Issue Set Started Command for a Manual Task Instance: XML and JSON Examples.

Issue Set Started Command for a Manual Task Instance: XML and JSON Examples

Examples

XML

JSON

Example Request

XML

<task-instance>
      <id>1464817327170011848D633V6106ENQ7</id>
</task-instance>

or

<task-instance>
      <name>test manual</name>
      <criteria>Newest Instance</criteria>
      <workflowInstanceName>test</workflowInstanceName> 
</task-instance>

JSON

{
"name": "Task 1",
"criteria": "Newest Instance",
"workflowInstanceName": "Test"
}

Example Response

XML

<command-response>
    <type>set_manual_started</type>
    <success>true</success>
    <info>Command Set Started executed successfully against task instance "test".</info>
    <errors />
</command-response>

JSON

{
  "type": "set_manual_started",
  "success": true,
  "info": "Command Set Started executed successfully against task instance \"Task 1\".",
  "errors": ""
}

Issue Set Started Command for a Manual Task Instance: Request Properties

Property	UI Field Name	Description	Specifications	Required	Mutually Exclusive With
`criteria`	n/a	Specific task instance with this task instance `name` that you want to issue a Set Started command for.	Valid values: As String = Oldest Active Instance, As Value = 1 As String = Newest Active Instance, As Value = 2 As String = Oldest Instance, As Value = 3 As String = Newest Instance, As Value = 4 Default is Oldest Active Instance (1). Note Values with an underscore characters ( _ ) instead of spaces also are supported (for example, oldest_active_instance).	N
`id`	n/a	sys_id used within the Controller to identify this task instance.		Y (unless `name` is specified)	`name`
`name`	Instance Name	Name of the task instance.		Y (unless `id` is specified)	`id`
`workflowInstanceName`	Workflow	Name of the parent Workflow of the task instance.	You can select to display the Workflow field on the Activity Monitor and/or Task Instances List; it is not displayed in the Task Instance Details.	N

List Task Instances

	Description
URI	http://host_name/uc/resources/taskinstance/list
HTTP Method	POST
Description	Retrieves information on task instances matching specific search criteria.
Authentication	HTTP Basic
Example URI	http://localhost:8080/uc/resources/taskinstance/list
Consumes Content-Type	application/xml, application/json
Produces Content-Type	application/xml, application/json
Example Request	See List Task Instances: XML and JSON Request Examples.
Request Properties	See List Task Instances: Request Properties.
Example Response	See List Task Instances: XML and JSON Response Examples.

List Task Instances: XML and JSON Examples

Examples

XML

JSON

Example Request

XML

Task instance with multiple query criteria.

<task-instance-query-filter>
      <name>B-06884*</name>
      <status>!45</status>
      <customField1>My*</customField1>
      <customField2>*Custom*</customField2>
      <workflowDefinitionId>36551ed5663042c2b79975ad6a23915e</workflowDefinitionId>
      <taskName>B-06884 - Timer - END - ${B_08477_WKFLW_ID}</taskName>
</task-instance-query-filter>

All task instances in the last three minutes.

<task-instance-query-filter>
      <name>*</name>
      <updatedTimeType>Offset</updatedTimeType>
      <updatedTime>-3mn</updatedTime>
</task-instance-query-filter>

Task instance with the specified id.

<task-instance-query-filter>
      <sysId>1448396297341015141TB2QF51JBYM8V</sysId>
</task-instance-query-filter>

Task instance with multiple query criteria.

<task-instance-query-filter>
      <name>*</name>
      <status>110</status>
      <type>windows</type>
      <agentName>test agent</agentName>
      <lateStart>true</lateStart>
      <lateFinish>true</lateFinish>
      <earlyFinish>false</earlyFinish>
</task-instance-query-filter>

All task instances that either started late or finished late.

<task-instance-query-filter>
      <name>*</name>
      <late>true</late>
</task-instance-query-filter>

All task instances that either started late, finished late, or finished early.

<task-instance-query-filter>
      <name>*</name>
      <lateEarly>true</lateEarly>
</task-instance-query-filter>

All task instances that neither started late nor finished late.

<task-instance-query-filter>
      <name>*</name>
      <late>false</late>
</task-instance-query-filter>

All task instances that neither started late, finished late, nor finished early.

<task-instance-query-filter>
      <name>*</name>
      <lateEarly>false</lateEarly>
</task-instance-query-filter>

Task instance with the specified template name.

  
  <task-instance-query-filter>
        <name>*</name>
        <templateName>Demo_Ext_1</templateName>
  </task-instance-query-filter>

Task instance with updated time type: between.

<task-instance-query-filter>
<name>*</name>
<updatedTimeType>between</updatedTimeType>
<updatedTime>2022-08-08 10:56:00 -0400,2022-08-10 10:56:00 -0400</updatedTime>
</task-instance-query-filter>

JSON

Task instance with multiple query criteria.

{
      "name": "*",
      "status": "!45",
      "instanceNumber": 2,
      "businessServices": "Rgr A",
      "customField2": "*Custom*"
}

All task instances in the last three minutes.

{
      "name": "*",
      "type": "Timer",
      "updatedTimeType": "offset",
      "updatedTime": "-3mn"
 }

Task instance with the specified id.

{
      "sysId": "1513644026115413351LS9ACLESSKLXZ"
       
 }

Task instance with multiple query criteria.

{
      "name": "*",
      "status": "200",
      "type": "windows",
      "agentName": "Mark-4 - AGNT0002",
      "lateStart": true,
      "lateFinish": false,
      "earlyFinish": false
 }

All task instances that either started late or finished late.

{
      "name": "*",
      "late": true
 }

All task instances that either started late, finished late, or finished early.

{
      "name": "*",
      "lateEarly": true
 }

All task instances that neither started late nor finished late.

 {
      "name": "*",
      "late": false
 }

All task instances that neither started late, finished late, nor finished early.

{
      "name": "*",
      "lateEarly": false
 }

Task instance with the specified template name.

  
{
        "name": "*"
        "templateName": Demo_Ext_1
 }

Task instance with updated time type: between.

{

"name": "*",

"type": "Timer",

"updatedTimeType": "between",

"updatedTime": "2022-08-08 10:56:00 -0400,2022-08-10 10:56:00 -0400"

}

Example Response

XML

JSON