/
Task Web Services

Task Web Services

Owned by Former user (Deleted)
Last updated: Jun 28, 2023 by Stonebranch (Deactivated)

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

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

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

URI

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

HTTP Method

POST

Description

Launches the specified task.

Example URI

http://localhost:8080/uc/resources/task/ops-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

Example Request for Task

 XML
<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>
 JSON

{
    "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

 XML

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>
 JSON
{
    "variables": [{
      "name": "testvar",
      "value": "abc"
    }],
    "virtualResources": [ {
      "name": "aaaaa",
      "limit": 2
    } ], 
    "name": "Timer 0",
    "virtualResourcePriority": 10,
    "hold": "yes"
}

Example Response

 XML
<command-response>
    <type>launch</type>
    <success>true</success>
    <info>Successfully launched the Timer task Timer 0.</info>
    <sysId>1484021712811013671DQNWR5P2F9846</sysId>
    <errors />
</command-response>
 JSON
{
"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

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

launchReasonLaunch ReasonReason for the task launch

N 

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

name

Task Name

Name of the task.


Y

timeZone

Time Zone

Time Zone in the which the task is launched.


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 20 (low). Default is 10.

N

Task-Related Records Properties: Variables

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

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

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

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

Examples

XML

JSON

Example Response

 XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<workflows>
    <workflow>
        <name>WF_A</name>
        <sysId>2be1385324ab410995fda3f0292c07ee</sysId>
        <description />
        <version>2</version>
        <vertexName>SB_JOB</vertexName>
        <vertexId>2</vertexId>
    </workflow>
    <workflow>
        <name>WF_B</name>
        <sysId>c8d5ad7cee3f46288482872dbd63770c</sysId>
        <description />
        <version>43</version>
        <vertexName>SB_JOB</vertexName>
        <vertexId>2</vertexId>
    </workflow>
    <workflow>
        <name>WF_C</name>
        <sysId>830105616cc74d7d8d394bedc1c47a43</sysId>
        <description />
        <version>6</version>
        <vertexName>SB_JOB.1</vertexName>
        <vertexId>2</vertexId>
    </workflow>
    <workflow>
        <name>WF_C</name>
        <sysId>830105616cc74d7d8d394bedc1c47a43</sysId>
        <description />
        <version>6</version>
        <vertexName>SB_JOB.2</vertexName>
        <vertexId>3</vertexId>
    </workflow>
</workflows>
 JSON
[ {
  "name": "WF_A",
  "sysId": "2be1385324ab410995fda3f0292c07ee",
  "description": null,
  "version": 2,
  "vertexName": "SB_JOB",
  "vertexId": "2"
}, {
  "name": "WF_B",
  "sysId": "c8d5ad7cee3f46288482872dbd63770c",
  "description": null,
  "version": 43,
  "vertexName": "SB_JOB",
  "vertexId": "2"
}, {
  "name": "WF_C",
  "sysId": "830105616cc74d7d8d394bedc1c47a43",
  "description": null,
  "version": 6,
  "vertexName": "SB_JOB.1",
  "vertexId": "2"
}, {
  "name": "WF_C",
  "sysId": "830105616cc74d7d8d394bedc1c47a43",
  "description": null,
  "version": 6,
  "vertexName": "SB_JOB.2",
  "vertexId": "3"
} ]