Skip to main content

Workflow Task and Dependency Web Services

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

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

Add a Dependency to a Workflow​

Description

URI

http://host_name/uc/resources/workflow/edges

HTTP Method

POST

Description

Adds a dependency to a workflow, with the dependency represented by a workflowEdge. (See Example Request, below.)

URI Parameters

See Add a Dependency to a Workflow: URI Parameters, below.

Example URI

http://localhost:8080/uc/resources/workflow/edges?workflowname=workflow1

Consumes Content-Type

application/xml, application/json

Produces Content-Type

n/a

Example Request

See Add a Dependency to a Workflow: Example Request, below.

Add a Dependency to a Workflow Properties

See Add a Dependency to a Workflow: Properties, below.

Example Response

  • Status 200 /OK
    Successfully added a dependency between <sourceId> and <targetId>.
  • Status 400 /Bad Request
    Workflow <workflowName> doesn`t exist.

Add a Dependency to a Workflow: URI Parameters​

Name

Description

Specifications

Required

Mutually Exclusive With

workflowid

ID used within the Controller to identify the workflow.

String; URI parameter.

Y
(unless workflowname
is specified)

workflowname

workflowname

Name used within the Controller to identify the workflow.

String; URI parameter.

Y
(unless workflowid
is specified)

workflowid

Add a Dependency to a Workflow: Example Request​

JSON
JSON
{
  "condition": {
    "value": "Success"
  },
  "points": [ {
     "x": "280",
     "y": "300"
  } ],
  "sourceId": {
    "value": "2"
  },
  "straightEdge": false,
  "targetId": {
    "value": "3"
  }
}

Add a Dependency to a Workflow: Request Properties​

Property

UI Field Name

Description

Specifications

Required

condition

n/a

Dependency condition between the source and target tasks of this dependency (connector).

Valid values:

  • Success
  • Failure
  • Success/Failure
  • Approved
  • Approval Required
  • Exit Code; Format: Numeric. Use commas to list a series of exit codes; use hyphens to specify a range. Example: 1,5, 22-30
  • Step Condition; Format: step:procedure:program:condition codes. Example: *:*:*:JCLERR
  • Variable

Default is Success.

For example:

XML
<condition>Success</condition>
<condition>Failure</condition>
<condition>Success/Failure</condition>
<condition>Approved</condition>
<condition>Approval Required</condition>
<condition>1,5,22-30</condition>
<condition>*:*:*:JCLERR</condition>
<condition>S1:PROC1:PGM1:U016</condition>
<condition type="Exit Code">1,5,22-30</condition>
<condition type="Step Condition">*:*:*:JCLERR</condition>
<condition type="Step Condition">*:*:*:S0C4</condition>
<condition type="Step Condition">S1:PROC1:PGM1:U016</condition>
<variableCondition>
  <firstValue>${_varToLowerCase('variableName')}</firstValue>
  <operator>=</operator>
  <secondValue>${var2}</secondValue>
</variableCondition>

Step Condition is valid for z/OS tasks only.

Approved and Approval Required are valid for Approval tasks only. See Specifying Conditions on Connections for more information.

Success/Failure and Failure are not valid for Workflow, Timer, and Manual tasks.

info

The type attribute (type=) is optional for Exit Code and Step Condition. Based on the format of the condition, in most cases it is easily determined if the condition is Exit Code and Step Condition. If the condition cannot be determined, the type attribute can be checked.

N

points

n/a

If straightEdge is false; x and y coordinates of the Edge angles.

For example:

<points>
  <point x="280" y="300" />
</points>

N

sourceId

n/a

Vertex ID of the source task.

Y

straightEdge

n/a

Specification for whether the edge is straight or bent.

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

N

targetId

n/a

Vertex ID of the target task.

Y

Add a Task to a Workflow​

Description

URI

http://host_name/uc/resources/workflow/vertices

HTTP Method

POST

Description

Adds a task to a workflow, with the task represented by a workflowVertex. (See Example Request, below.)

URI Parameters

See Add a Task to a Workflow: URI Parameters, below.

Example URI

http://localhost:8080/uc/resources/workflow/vertices?workflowname=workflow1

Consumes Content-Type

application/xml, application/json

Produces Content-Type

application/xml, application/json

Example Request

See Add a Task to a Workflow: Example Request, below.

Example Response

See Add a Task to a Workflow: Example Response (Status 200), below.

Add a Task to a Workflow Properties

See Add a Task to a Workflow: Request/Response Properties, below.

Example Response

  • Status 200 /OK
    Successfully added vertex with vertexId <vertextId>.
  • Status 400 /Bad Request
    Workflow <workflowName> doesn`t exist.

Add a Task to a Workflow: URI Parameters​

Name

Description

Specifications

Required

Mutually Exclusive With

workflowid

ID used within the Controller to identify the workflow.

String; URI parameter.

Y
(unless workflowname
is specified)

workflowname

workflowname

Name used within the Controller to identify the workflow.

String; URI parameter.

Y
(unless workflowid
is specified)

workflowid

Add a Task to a Workflow: Example Request​

JSON
JSON
{
  "alias": "S30",
  "task": {  
    "value": "Sleep 30"
  }, 
  "vertexX": "360",
  "vertexY": "60"
}

Add a Task to a Workflow: Example Response (Status 200)​

JSON
JSON
{
  "alias": "S30",  
  "conditionExpression": null,
  "task": {
    "value": "Sleep 30"
  }, 
  "vertexId": "9,  
  "vertexX": "360",
  "vertexY": "60"
}

Add a Task to a Workflow: Request/Response Properties​

Property

UI Field Name

Description

Specification

Required

alias

n/a

Alias used for the task added to the workflow; specifically, the value of ops_task_workflow_vertex.name.

N

conditionExpression

n/a

Boolean condition expression to specify the dependency criteria.

XML
XML
<conditionExpression>
    <condition>
        <vertexId>7</vertexId>
    </condition>
    <condition>
        <vertexId>10</vertexId>
    </condition>
    <compoundCondition>
        <condition>
            <vertexId>9</vertexId>
        </condition>
        <condition>
            <vertexId>7</vertexId>
        </condition>
        <logicalOperator>And</logicalOperator>
    </compoundCondition>
    <logicalOperator>Or</logicalOperator>
</conditionExpression>
JSON
JSON
"conditionExpression": {
    "conditions": [
        {
            "type": "condition",
            "vertexId": "7"
        },
        {
            "type": "condition",
            "vertexId": "10"
        },
        {
            "type": "compoundCondition",
            "conditions": [
                {
                    "type": "condition",
                    "vertexId": "9"
                },
                {
                    "type": "condition",
                    "vertexId": "7"
                }
            ],
      "logicalOperator": "And"
        }
    ],
    "logicalOperator": "Or"
}

N

task

Task Name

Name of the task added to the workflow.

Y

vertexId

n/a

Vertex ID of the task added to the workflow.

Each task within a Workflow has a unique Vertex ID to distinguish it from other tasks of the same name, if any.

Y

vertexX

n/a

x-coordinate of the task added to the workflow.

Default is 0.

N

vertexY

n/a

y-coordinate of the task added to the workflow.

Default is 0.

N

List Dependencies in a Workflow​

Description

URI

http://host_name/uc/resources/workflow/edges

HTTP Method

GET

Description

Returns the list of dependencies for all tasks in a workflow, with each dependency represented by a workflowEdge (see Example Response, below).

URI Parameters

See List Dependencies in a Workflow: URI Parameters, below.

Example URI

http://localhost:8080/uc/resources/workflow/edges?workflowname=workflow1

Authentication

HTTP Basic

Consumes Content-Type

n/a

Produces Content-Type

application/xml, application/json

Example Response

See List Dependencies in a Workflow: Example Response, below.

Response Properties

See List Dependencies in a Workflow: Properties, below.

List Dependencies in a Workflow: URI Parameters​

Name

Description

Specifications

Required

Mutually Exclusive With

sourceid

Vertex ID of the source task.

String; URI parameter.

N

targetid

Vertex ID of the target task.

String; URI parameter.

N

workflowid

ID used within the Controller to identify the workflow.

String; URI parameter.

Y
(unless workflowname
is specified)

workflowname

workflowname

Name used within the Controller to identify the workflow.

String; URI parameter.

Y
(unless workflowid
is specified)

workflowid

List Dependencies in a Workflow: Example Response​

JSON
JSON
[
  {
  "condition": {
    "value": "Success"
  },
  "sourceId": {
    "taskAlias": "test",
    "taskName": "Sleep 30",
    "value": "2"
  },
  "straightEdge": true,
  "targetId": {
    "taskName": "Sleep 60",
    "value": "3"
  }
},
  {
  "condition": {
    "value": "Success"
  },
  "sourceId": {
    "taskName": "Sleep 60",
    "value": "3"
  },
  "straightEdge": true,
  "targetId": {
    "taskName": "Sleep 60",
    "value": "6"
  }
} 
]

List Dependencies in a Workflow: Properties​

Property

UI Field Name

Description

condition

n/a

Dependency condition between the source and target tasks of this edge (connector).

sourceId

n/a

Vertex ID of the source task.

straightEdge

n/a

Specification for whether the edge is straight or bent.

targetId

n/a

Vertex ID of the target task.

List Tasks in a Workflow​

Attribute sysId identifies the sysid of the specified task.

Description

URI

http://host_name/uc/resources/workflow/vertices

HTTP Method

GET

Description

Returns the list of tasks in a workflow, with each task represented by a workflowVertex (see Example Response, below).

URI Parameters

See List Tasks in a Workflow: URI Parameters, below.

Example URI

Authentication

HTTP Basic

Consumes Content-Type

n/a

Produces Content-Type

application/xml, application/json

Example Response

See List Tasks in a Workflow: Example Response, below.

Response Properties

See List Tasks in a Workflow: Properties, below.

List Tasks in a Workflow: URI Parameters​

Parameter

Description

Specifications

Required

Mutually Exclusive With

taskalias

Alias used for the task within the Workflow; specifically, the value of ops_task_workflow_vertex.name.

String; URI parameter.

Y
(unless taskid,
taskname or vertexid,
is specified

taskid,
taskname,
vertexid

taskid

ID used within the Controller to identify this task.

String; URI parameter.

Y
(unless taskalias,
taskname or vertexid,
is specified

taskalias,
taskname,
vertexid

taskname

Name used within the Controller to identify this task.

String; URI parameter.

Y
(unless taskalias,
taskid or vertexid,
is specified

taskalias,
taskid,
vertexid

vertexid

Vertex ID of the task in the workflow to be listed.

Each task within a Workflow has a unique Vertex ID to distinguish it from other tasks, if any, of the same name.

String; URI parameter.

Y
(unless taskalias,
taskid or taskname,
is specified

taskalias,
taskid,
taskname

workflowid

ID used within the Controller to identify a workflow.

Y
(unless workflowname
is specified

workflowname

workflowname

Name of a workflow.

Y
(unless workflowid
is specified

workflowid

List Tasks in a Workflow: Example Response​

JSON
JSON
[
  {
    "alias": "Task 1",  
    "conditionExpression": null,
    "task": {
      "sysId": "1010f538c0a801c900e0fe0af94d9be5",
      "value": "task1"
    },
    "vertexId": "5",
    "vertexX": "253",
    "vertexY": "296"
    },
    {
    "alias": "Task 2",  
    "conditionExpression": null,
    "task": {
      "sysId": "f81d30ccc0a801c9008ea20e4f5f61d6",
      "value": "task2"
    },
    "vertexId": "6",
    "vertexX": "252.5",
    "vertexY": "429"
  }
]

List Tasks in a Workflow: Response Properties​

Property

UI Field Name

Description

alias

n/a

Alias used for the task; specifically, the value of ops_task_workflow_vertex.name.

conditionExpression

n/a

Boolean condition expression to specify the dependency criteria.

task

Task Name

Name of the task added.

vertexId

n/a

Vertex ID of the task.

Each task within a Workflow has a unique Vertex ID to distinguish it from other tasks of the same name, if any.

vertexX

n/a

x-coordinate of the task.

vertexY

n/a

y-coordinate of the task.

Modify a Dependency in a Workflow​

Description

URI

http://host_name/uc/resources/workflow/edges

HTTP Method

PUT

Description

Modifies a dependency in a workflow, with the dependency represented by a workflowEdge.

URI Parameters

See Modify a Dependency in a Workflow: URI Parameters.

Example URI

http://localhost:8080/uc/resources/workflow/edges?workflowname=workflow1

Consumes Content-Type

application/xml, application/json

Produces Content-Type

n/a

Example Request

See Modify a Dependency in a Workflow: Example Request, below.

Modify a Dependency in a Workflow Properties

See Add a Dependency to a Workflow: Properties.

Example Response

  • Status 200 /OK
    Successfully updated dependency between <sourceId> and <targetId>.
  • Status 400 /Bad Request
    Workflow <workflowName> doesn`t exist.

Modify a Dependency in a Workflow: URI Parameters​

Name

Description

Specifications

Required

Mutually Exclusive With

workflowid

ID used within the Controller to identify the workflow.

String; URI parameter.

Y
(unless workflowname
is specified)

workflowname

workflowname

Name used within the Controller to identify the workflow.

String; URI parameter.

Y
(unless workflowid
is specified)

workflowid

Modify a Dependency in a Workflow: Example Request​

JSON
JSON
{
  "condition": {
     "value": "Success"
  },
  "points": [ {
     "x": "280",
     "y": "300"
  } ],
  "sourceId": {
    "value": "2"
  },
  "straightEdge": false,
  "targetId": {
    "value": "3"
  }
}

Modify a Task in a Workflow​

Description

URI

http://host_name/uc/resources/workflow/vertices

HTTP Method

PUT

Description

Modifies a task in a workflow, with the task represented by a workflowVertex.

URI Parameters

See Modify a Task in a Workflow: URI Parameters, below.

Example URI

http://localhost:8080/uc/resources/workflow/vertices?workflowname=workflow1

Consumes Content-Type

application/xml, application/json

Produces Content-Type

n/a

Example Request

See Modify a Task in a Workflow: Example Request, below.

Modify a Task in a Workflow Properties

See Add a Task to a Workflow: Properties.

Modify a Task in a Workflow: URI Parameters​

Name

Description

Specifications

Required

Mutually Exclusive With

workflowid

ID used within the Controller to identify the workflow.

String; URI parameter.

Y
(unless workflowname
is specified)

workflowname

workflowname

Name used within the Controller to identify the workflow.

String; URI parameter.

Y
(unless workflowid
is specified)

workflowid

Modify a Task in a Workflow: Example Request​

JSON
JSON
{
  "alias": "S30",  
  "conditionExpression": null,
  "task": {
    "value": "sleep 30"
  },
  "vertexX": "360",
  "vertexY": "60"
}

Modify a Task in a Workflow: Properties​

Property

UI Field Name

Description

Specifications

Required

alias

n/a

Alias used for the task to be modified in the workflow; specifically, the value of ops_task_workflow_vertex.name.

N

conditionExpression

n/a

Boolean condition expression to specify the dependency criteria.

XML
XML
<conditionExpression>
    <condition>
        <vertexId>7</vertexId>
    </condition>
    <condition>
        <vertexId>10</vertexId>
    </condition>
    <compoundCondition>
        <condition>
            <vertexId>9</vertexId>
        </condition>
        <condition>
            <vertexId>7</vertexId>
        </condition>
        <logicalOperator>And</logicalOperator>
    </compoundCondition>
    <logicalOperator>Or</logicalOperator>
</conditionExpression>
JSON
JSON
"conditionExpression": {
    "conditions": [
        {
            "type": "condition",
            "vertexId": "7"
        },
        {
            "type": "condition",
            "vertexId": "10"
        },
        {
            "type": "compoundCondition",
            "conditions": [
                {
                    "type": "condition",
                    "vertexId": "9"
                },
                {
                    "type": "condition",
                    "vertexId": "7"
                }
            ],
        "logicalOperator": "And"
        }
    ],
    "logicalOperator": "Or"
}

N

task

Task Name

Name of the task to be modified in the workflow.

Cannot be modified; used only to search for the task. To modify by task, the task must be unique in the workflow.

If both task and vertextId are specified, vertextId is used to search for the task to be modified.

Y
(unless vertextid
is specified.)

vertexId

n/a

Vertex ID of the task within the workflow.

Each task within a Workflow has a unique Vertex ID to distinguish it from other tasks of the same name, if any.

Cannot be modified; used only to search for the task.

If both task and vertextId are specified, vertextId is used to search for the task to be modified.

Y
(unless task
is specified.)

vertexX

n/a

x-coordinate of the task to be modified in the workflow.

Default is 0.

N

vertexY

n/a

y-coordinate of the task to be modified in the workflow.

Default is 0.

N

Remove a Dependency from a Workflow​

Description

URI

http://host_name/uc/resources/workflow/edges

HTTP Method

DELETE

Description

Removes a dependency from a workflow, with the dependency represented by sourceid and targetid (see Example Response, below).

URI Parameters

See Remove a Dependency from a Workflow: URI Parameters, below.

Example URI

http://localhost:8080/uc/resources/workflow/edges?workflowname=workflow1&sourceid=2&targetid=4

Authentication

HTTP Basic

Example Response

  • Status 200 /OK
    Successfully updated vertex with vertex id <vertexId>.
  • Status 400 /Bad Request
    Workflow <workflowName> doesn`t exist.

Remove a Dependency from a Workflow: URI Parameters​

Name

Description

Specifications

Required

Mutually Exclusive With

sourceid

Vertex ID of the source task.

Integer; URI parameter.

Y

targetid

Vertex ID of the target task.

Integer; URI parameter.

Y

workflowid

ID used within the Controller to identify a workflow.

String; URI parameter.

Y
(unless workflowname
is specified.

workflowname

workflowname

Name used within the Controller to identify a workflow.

String; URI parameter.

Y
(unless workflowid
is specified.

workflowid

Remove Task(s) from a Workflow​

Description

URI

http://host_name/uc/resources/workflow/vertices

HTTP Method

DELETE

Description

Removes one or more tasks from a workflow, with each removed task represented by a workflowVertex (see Example Response, below).

URI Parameters

See Remove Task(s) from a Workflow: URI Parameters, below.

Example URI

Consumes Content-Type

n/a

Produces Content-Type

application/xml, application/json

Authentication

HTTP Basic

Example Response

See Remove Task(s) from a Workflow: Example Response, below.

Remove Task(s) from a Workflow Properties

See Remove Task(s) from a Workflow: Properties, below.

Remove Task(s) from a Workflow: URI Parameters​

If taskid, taskname, or taskalias is specified, all tasks matching the taskid, taskname, or taskalias - and their dependencies - are removed.

If vertexid is specified, only the task with that specific Vertex ID - and its dependencies - is removed.

Parameter

Description

Specifications

Required

Mutually Exclusive With

taskalias

Alias of the task(s) to be removed from the Workflow; specifically, the value of ops_task_workflow_vertex.name.

String; URI parameter.

Y
(unless taskid,
taskname or vertexid,
is specified

taskid,
taskname,
vertexid

taskid

SysId of the task(s) to be removed from the Workflow.

String; URI parameter.

Y
(unless taskalias,
taskname or vertexid,
is specified

taskalias,
taskname,
vertexid

taskname

Name of the task(s) to be removed from the Workflow.

String; URI parameter.

Y
(unless taskalias,
taskid or vertexid,
is specified

taskalias,
taskid,
vertexid

vertexid

Vertex ID of the task to be removed from the workflow.

Each task within a Workflow has a unique Vertex ID to distinguish it from other tasks, if any, of the same name.

String; URI parameter.

Y
(unless taskalias,
taskid or taskname,
is specified

taskalias,
taskid,
taskname

workflowid

ID used within the Controller to identify a workflow.

String; URI parameter.

Y
(unless workflowname
is specified.

workflowname

workflowname

Name used within the Controller to identify a workflow.

String; URI parameter.

Y
(unless workflowid
is specified.

workflowid

Remove Task(s) from a Workflow: Example Response​

JSON
JSON
[  
  {
    "alias": "task 1",  
    "conditionExpression": null,
    "task": {
      "sysId": "1010f538c0a801c900e0fe0af94d9be5",
      "value": "task1"  
    },
    "vertexId": "5",
    "vertexX": "253",
    "vertexY": "296"
  }  
]
info

If there are no matching tasks to remove, an empty list is returned.

Remove Task(s) from a Workflow: Response Properties​

This response contains a list of tasks removed from a workflow

Property

UI Field Name

Description

alias

n/a

Alias of the task removed from the Workflow; specifically, the value of ops_task_workflow_vertex.name.

conditionExpression

n/a

Boolean condition expression to specify the dependency criteria.

task

Task Name

Name of the task removed from the Workflow.

vertexId

n/a

Vertex ID of the task removed from the Workflow.

Each task within a Workflow has a unique Vertex ID to distinguish it from other tasks of the same name, if any.

vertexX

n/a

x-coordinate of the task removed from the Workflow.

vertexY

n/a

y-coordinate of the task removed from the Workflow.