/
Task Web Services

Task Web Services

Owned by Stonebranch (Deactivated)
Last updated: Dec 17, 2024 by Alec Berger

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