/
Task Web Services

Task Web Services

Sept 03, 2025

Overview

Universal Controller supports the following RESTful-based web services for Task operations.

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

Common Web Services

The following web services are common to all Task types:

Detailed information for each of these web services is provided on this page.
 

Task-Specific Web Services

The following web services are specific for each Task type:

  • Create a Task

  • Modify a Task

  • Read a Task

For detail information about these task-specific web services, see:

Delete a Task

 

Description

 

Description

URI

http://host_name/uc/resources/task

HTTP Method

DELETE

Description

Deletes the specified task.

URI Parameters

See Delete a Task: URI Parameters, below.

Example URI

Authentication

HTTP Basic

Example Response

  • Status 200 /OK
    Task deleted successfully.

  • Status 400 /Bad Request
    Mutual exclusion violation. Cannot specify taskname and taskid at the same time.

  • Status 404 /Not Found
    A task with id "f87848b00a0001037f43e7c81c8ec969" does not exist.

Delete a Task: URI Parameters

Parameter

Description

Specifications

Required

Mutually Exclusive With

Parameter

Description

Specifications

Required

Mutually Exclusive With

taskid

ID used within the Controller to identify this task.

String; URI parameter.

Y
(unless taskname
is specified)

taskname

taskname

Name used within the Controller to identify this task.

String; URI parameter.

Y
(unless taskid
is specified)

taskid

Launch a Task

 

Description

 

Description

URI

http://host_name/uc/resources/task/launch

HTTP Method

POST

Description

Launches the specified task.

Example URI

http://localhost:8080/uc/resources/task/launch

Authentication

HTTP Basic

Consumes Content-Type

application/xml, application/json

Produces Content-Type

application/xml, application/json

Example Request

See Launch a Task: XML and JSON Examples.

Example Request for Task-Related Records

See Launch a Task: XML and JSON Examples.

Request Properties

See Launch a Task: Request Properties.

Request Task-Related Records Properties

Example Response

See Launch a Task: XML and JSON Examples.

Launch a Task: XML and JSON Examples

Examples

XML

JSON

Examples

XML

JSON

Example Request for Task

<task-launch> <variables /> <virtual-resources /> <name>Timer 0</name> <timeZone>America/Halifax</timeZone> <virtualResourcePriority>10</virtualResourcePriority> <hold>yes</hold> <holdReason>Waiting for input</holdReason> <launchReason>Testing</launchReason> </task-launch>
{ "variables": null, "virtual-resources": null, "name": "Timer 0", "timeZone": "America/Halifax", "virtualResourcePriority": 10, "hold": "yes", "holdReason": "Waiting for input", "launchReason": "test" }

Example Request for Task-Related Records

Variables

<variables> <variable> <name>testVar</name> <value>value</value> </variable> </variables>

Virtual Resources

<virtual-resources> <virtual-resource> <name>uc - Solo</name> <limit>2</limit> </virtual-resource> </virtual-resources>

{ "variables": [{ "name": "testvar", "value": "abc" }], "virtualResources": [ { "name": "aaaaa", "limit": 2 } ], "name": "Timer 0", "virtualResourcePriority": 10, "hold": "yes" }

Example Response

<command-response> <type>launch</type> <success>true</success> <info>Successfully launched the Timer task Timer 0.</info> <sysId>1484021712811013671DQNWR5P2F9846</sysId> <errors /> </command-response>

{ "type": "launch", "success": true, "info": "Successfully launched the Timer task "Timer 0" with task instance sys_id 15136440261151733518FCQUD1BNHITA with hold on start.", "errors": "", "sysId": "15136440261151733518FCQUD1BNHITA" }

Launch a Task: Request Properties

Property

UI Field Name

Description

Specifications

Required

Property

UI Field Name

Description

Specifications

Required

hold

Hold on Start

Indicates that when the task is launched, it appears in the Activity Monitor with a status of Held. The task runs when the user releases it.

Valid values = Yes,Y,true

N

holdReason

Hold Reason

Information about why the task will be put on hold when it starts.

 

N

launchReason

Launch Reason

Reason for the task launch

 

N 

(Y if Task Launch Reason Required system property is True.)

name

Task Name

Name of the task.

 

Y

simulate

Simulate

Specifies if the workflow should execute under simulation mode.

Boolean; Valid values: true/false. Default is false.

N

timeZone

Time Zone

Time Zone in the which the task is launched.

 

N

vertices

Vertex Selection

Specifies Root Vertices and/or Specific Vertices to be included in the triggered workflow.

A vertex can be specified by taskName, vertexName, or vertexId.

If you specify a vertexId, then only a single vertex will match, whereas, if you leave vertexId unspecified, any vertex matching by taskName or vertexName, will be selected.

To indicate a vertex selection is a Root Vertex, set the vertex root attribute to true. If vertex root attribute is unspecified or false, it indicates a vertex selection is a Specific Vertex.

Duplicate vertex specifications are ignored and do not prevent the operation from completing.

XML

<vertices> <vertex root="true"> <taskName>JOB_A</taskName> </vertex> <vertex> <vertexName>JOB_B</vertexName> </vertex> <vertex root="false"> <vertexId>10</vertexId> </vertex> </vertices>

JSON

"vertices": [ { "taskName": "JOB_A", "root": true }, { "vertexName": "JOB_B" }, { "vertexId": "10", "root": false } ]

N

virtualResourcePriority

Virtual Resource Priority

Priority for acquiring a resource when two or more tasks are waiting for the resource; applies to all resources required by the task.

Integer; Valid values: 1 (high) to 100 (low). Default is 10.

N

Task-Related Records Properties: Variables

Property

UI Field Name

Description

Specifications

Required

Property

UI Field Name

Description

Specifications

Required

name

Name

Name of the variable.

 

Y

value

Value

Value of the variable.

 

Y

Task-Related Records Properties: Virtual Resources

The virtual resource dependencies specified in virtual-resources are merged with the default virtual resource dependencies:

  • If a default virtual resource dependency already exists for a specified virtual resource amount, the virtual resource dependency is updated.

  • Any virtual resource specified with an amount of 0 is dropped from the default virtual resource dependencies; if the virtual resource did not exist as a default dependency, the command will fail.

  • If a default virtual resource dependency does not already exist for a specified virtual resource amount, the virtual resource dependency is added. |
     

Property

UI Field Name

Description

Specifications

Required

Property

UI Field Name

Description

Specifications

Required

description

Resource Description

Description of the virtual resource.

 

N

name

Resource Name

Name of the virtual resource.

 

Y

limit

Resource Limit

Maximum number of units for this resource.

 

Y

List All Workflows That a Task Belongs To

 

Description

 

Description

URI

http://host_name/uc/resources/task/parent/list

HTTP Method

GET

Description

Retrieves a list of parent workflows that a task belongs to.

URI Parameters

See List All Workflows That a Task Belongs To: URI Parameters, below.

Example URI

Authentication

HTTP Basic

Consumes Content-Type

n/a

Produces Content-Type

application/xml, application/json

Example Response

See List All Workflows That a Task Belongs To: XML and JSON Examples.

Response Properties

See List All Workflows That a Task Belongs To: Response Properties.

List All Workflows That a Task Belongs To: URI Parameters

Parameter

Description

Specifications

Required

Mutually Exclusive With

Parameter

Description

Specifications

Required

Mutually Exclusive With

taskid

ID used within the Controller to identify this task.

String; URI parameter.

Y
(unless taskname
is specified)

taskname

taskname

Name used within the Controller to identify this task.

String; URI parameter.

Y
(unless taskid
is specified)

taskid

List All Workflows That a Task Belongs To: XML and JSON Examples