Skip to main content

Trigger Web Services

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

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

Common Web Services​

The following web services are common to multiple Trigger types:

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

Trigger-Specific Web Services​

The following web services are specific to each Trigger type:

  • Create a Trigger
  • List Trigger Qualifying Times (Cron and Time Triggers only)
  • Modify a Trigger
  • Modify Time of Time Trigger (Time Trigger only)
  • Read a Trigger

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

Assign an Execution User to a Trigger​

Description

URI

http://host_name/uc/resources/trigger/assignexecutionuser

HTTP Method

POST

Description

Assigns an Execution User to the specified trigger.

URI Parameters

See Assign an Execution User to a Trigger: URI Parameters.

Authentication

HTTP Basic

Example URI

Consumes Content-Type

application/xml, application/json

Produces Content-Type

n/a

Example Request

See Assign an Execution User to a Trigger: XML and JSON Request Examples.

Request Properties

See Assign an Execution User to a Trigger: Request Properties.

Example Response

  • Status 200 /OK
    Successfully assigned execution user "test" to trigger "testTrigger".
  • Status 404 /Not Found
    Assign Execution User failed. You must provide an execution user.

Assign an Execution User to a Trigger: URI Parameters​

Name

Description

Specifications

Required

Mutually Exclusive With

triggerid

Unique ID for this trigger.

Y
(unless triggername
is specified)

triggername

triggername

Name used within the Controller to identify this trigger.

Maximum 40 alphanumerics.

Y
(unless triggerid
is specified)

triggerid

Assign an Execution to a Trigger: XML and JSON Request Examples​

JSON
JSON
{
 "username": "test",
 "password": "pass1" 
}

Assign an Execution User to a Trigger: Request Properties​

Property

UI Field Name

Description

Specifications

Required

password

n/a

If the user executing this web service does not have the ops_admin role; Password of the Execution User.

Y

username

n/a

Name of the Execution User.

Wildcards are supported.

Y

Delete a Trigger​

Description

URI

http://host_name/uc/resources/trigger

HTTP Method

DELETE

Description

Deletes the specified Trigger.

URI Parameters

See Delete a Trigger: URI Parameters.

Authentication

HTTP Basic

Example URI

Example Response

  • Status 200 /OK
    Trigger deleted successfully.
  • Status 404 /Not Found
    A trigger with id "f87848b00a0001037f43e7c81c8ec969" does not exist.

Delete a Trigger: URI Parameters​

Name

Description

Specifications

Required

Mutually Exclusive With

triggerid

Unique ID for this trigger.

Y
(unless triggername
is specified)

triggername

triggername

Name used within the Controller to identify this trigger.

Maximum 40 alphanumerics.

Y
(unless triggerid
is specified)

triggerid

Enable/Disable a Trigger​

Description

URI

http://host_name/uc/resources/trigger/enabledisable

HTTP Method

POST

Description

Enables/Disables a list of triggers.

Example URI

http://localhost:8080/uc/resources/trigger/enabledisable

Authentication

HTTP Basic

Consumes Content-Type

application/xml, application/json

Produces Content-Type

application/xml, application/json

Example Request

See Enable/Disable a Trigger: XML and JSON Examples.

Request Properties

See Enable/Disable a Trigger: Request Trigger Properties.

Example Response

See Enable/Disable a Trigger: XML and JSON Examples.

Enable/Disable a Trigger: XML and JSON Examples​

Request Example​

JSON
JSON
[  
    {
      "enable": true,
      "name": "uc - 1st and 15th"
    },
  {
      "enable": false,
      "name": "uc - 1st Sunday of Month"
  }  
]

Response Example​

JSON
JSON
{
    "type": Enable/Disable Triggers",
    "success": true,
    "info": "Successfully enabled trigger "uc - 1st and 15th"., Successfully disabled trigger "uc - 1st Sunday of Month".",
    "errors": ""
}

Enable/Disable a Trigger: Request Trigger Properties​

Property

UI Field Name

Description

Specifications

Required

trigger

n/a

There are two attributes for this property:

  • enable: Indication of whether to enable or disable the trigger. Only enabled triggers are processed by the Controller. Boolean; Valid values: true/false.
  • name: Name used within the Controller to identify this trigger. Maximum of 255 alphanumerics.

For example: <trigger enable="false" name="uc - 1st Sunday of Month"></trigger>

Y

List Triggers​

Description

URI

http://host_name/uc/resources/trigger/list

HTTP Method

POST

Description

Lists triggers matching specific search criteria.

Example URI

http://localhost:8080/uc/resources/trigger/list

Authentication

HTTP Basic

Consumes Content-Type

application/xml, application/json

Produces Content-Type

application/xml, application/json

Example Request

See List Triggers: XML and JSON Examples.

Request Properties

See List Triggers: Request Properties.

Example Response

See List Triggers: XML and JSON Examples.

List Triggers: XML and JSON Examples​

Request Example​

JSON
JSON
{
  "name": "*time*",
  "enabled": true,
  "type": "Time",  
  "tasks": ["CMD_WF", "PING"],
  "taskIds": ["ffda846987be43c69c4dd62ac452eabf", "ca960a653a704fec893eb17adc6f5f3d"],
  "description": "manual1"
}

Response Example​

JSON
JSON
[  
  {
    "enabled": true,
    "name": "Example time trigger 1",
    "sysId": "68aca9ea398f4d17a7ca23eeaa1d4fa1",
    "type": "Time",
    "version": 5
  },  
  {
    "enabled": true,
    "name": "Example time trigger 2",
    "sysId": "54c562ceb5e44aeca99f836b65fd86fb",
    "type": "Time",
    "version": 11
  }  
]

List Triggers: Request Properties​

Property

UI Field Name

Description

Specifications

Required

businessServices

Member of Business Services

Business Services that this trigger belongs to.

N

description

Description

Filter the trigger list using the description.

Wildcards are supported.

N

enabled

Status

Indication of whether to list enabled (true) or disabled (false) triggers.

Boolean; Valid values: true/false.

N

name

Name

Name or partial name of one or more triggers.

Wildcards are supported.

N

tasks

Task(s)

List Triggers that reference any one of the specified links.

Comma-separated Task names.

N

type

n/a

Type of triggers to list.

Valid values:

  • As String = Cron, As Value = 1
  • As String = Time, As Value = 2
  • As String = File Trigger, As Value = 3
  • As String = Temporary, As Value = 4
  • As String = Task Monitor, As Value = 5
  • As String = Manual, As Value = 6
  • As String = Application Monitor, As Value = 8
  • As String = Composite, As Value = 9
  • As String = Variable Monitor, As Value = 10
  • As String = Email Monitor, As Value = 11
  • As String = Universal Monitor, As Value = 12
  • As String = z/OS Monitor, As Value = 13

N

List Triggers - Advanced​

Description

URI

http://host_name/uc/resources/trigger/listadv

HTTP Method

GET

Description

Retrieves trigger details using specific query parameters.

Example URI

Authentication

HTTP Basic

Consumes Content-Type

n/a

Produces Content-Type

application/xml, application/json

URI Properties

See List Triggers - Advanced: URI Properties.

Example Response

See List Triggers - Advanced: XML and JSON Examples.

List Triggers - Advanced: URI Parameters​

Property

UI Field Name

Description

Specifications

Required

businessServices

Member of Business Services

Business Services that this trigger belongs to.

N

description

Description

Filter the trigger list using the description.

Wildcards are supported.

N

enabled

Status

Indication of whether to list enabled (true) or disabled (false) triggers.

Boolean; Valid values: true/false.

N

triggername

Name

Name or partial name of one or more triggers.

Wildcards are supported.

N

tasks

Task(s)

List Triggers that reference any one of the specified links.

Comma-separated Task names.

N

type

n/a

Type of triggers to list.

Valid values:

  • As String = Cron, As Value = 1
  • As String = Time, As Value = 2
  • As String = File Trigger, As Value = 3
  • As String = Temporary, As Value = 4
  • As String = Task Monitor, As Value = 5
  • As String = Manual, As Value = 6
  • As String = Application Monitor, As Value = 8
  • As String = Composite, As Value = 9
  • As String = Variable Monitor, As Value = 10
  • As String = Email Monitor, As Value = 11
  • As String = Universal Monitor, As Value = 12
  • As String = z/OS Monitor, As Value = 13

List Triggers - Advanced: XML and JSON Examples​

JSON
JSON
[
    {
        "type": "triggerCron",
        "action": "Do Not Trigger",
        "calendar": "System Default",
        "dayLogic": "And",
        "dayOfMonth": "*",
        "dayOfWeek": "*",
        "description": "cron test",
        "disabledBy": "",
        "disabledTime": "",
        "enabled": false,
        "enabledBy": "ops.admin",
        "enabledTime": "2021-06-01 11:29:48 -0400",  
        "exportReleaseLevel": "7.2.0.0"  
        "exportTable": "ops_trigger_cron",
        "forecast": false,
        "hours": "1",
        "minutes": "0",
        "month": "*",
        "name": "cron-1",
        "nextScheduledTime": "",  
        "notes": [],
        "opswiseGroups": [
            "B"
        ],
        "rdExcludeBackup": false,
        "restriction": false,
        "restrictionAdjective": "Every",
        "restrictionComplex": false,
        "restrictionMode": "Or",
        "restrictionNoun": {
            "value": "Day"
        },
        "restrictionNthAmount": 5,
        "restrictionQualifier": {
            "value": "Year"
        },
        "restrictionSimple": false,
        "retainSysIds": true,
        "retentionDuration": 1,
        "retentionDurationPurge": false,
        "retentionDurationUnit": "Days",
        "simulationOption": "-- System Default --",
        "situation": "Holiday",
        "skipActive": false,
        "skipAfterDate": null,
        "skipAfterTime": null,
        "skipBeforeDate": null,
        "skipBeforeTime": null,
        "skipCondition": "None",
        "skipCount": 0,
        "skipDateList": [],
        "skipRestriction": "None",
        "sysId": "e9b45bc055b24f1abacfcea057af711d",
        "tasks": ["CMD_WF", "PING"],
        "taskIds": ["ffda846987be43c69c4dd62ac452eabf", "ca960a653a704fec893eb17adc6f5f3d"],
        "timeZone": null,
        "variables": [],
        "version": 1
    },
    {
        "type": "triggerManual",
        "calendar": "System Default",
        "description": "Manual test",
        "disabledTime": "",
        "enabled": false,
        "enabledTime": "",  
        "exportReleaseLevel": "7.2.0.0"  
        "exportTable": "ops_trigger_manual",
        "name": "man-trig-1",
        "nextScheduledTime": "",  
        "notes": [],
        "opswiseGroups": [],
        "rdExcludeBackup": false,
        "restrictionNthAmount": 5,
        "retainSysIds": true,
        "retentionDuration": 1,
        "retentionDurationPurge": false,
        "retentionDurationUnit": "Days",
        "sysId": "728fc94ce80c4b97ae63ab741e902cc5",
        "tasks": ["CMD_WF", "PING"],
        "taskIds": ["ffda846987be43c69c4dd62ac452eabf", "ca960a653a704fec893eb17adc6f5f3d"],
        "timeZone": null,
        "variables": [],
        "version": 1
    },
    {
        "type": "triggerTm",
        "action": "Do Not Trigger",
        "calendar": "System Default",
        "description": "Task Monitor Trigger 1",
        "disabledTime": "",
        "enabled": false,
        "enabledEnd": "00:00",
        "enabledStart": "00:00",
        "enabledTime": "",  
        "exportReleaseLevel": "7.2.0.0"  
        "exportTable": "ops_trigger_tm",
        "name": "Taskmon-trig-1",
        "nextScheduledTime": "",  
        "notes": [],
        "opswiseGroups": [
            "A"
        ],
        "rdExcludeBackup": false,
        "restrictedTimes": false,
        "restriction": false,
        "restrictionAdjective": "Every",
        "restrictionComplex": false,
        "restrictionMode": "Or",
        "restrictionNoun": {
            "value": "Day"
        },
        "restrictionNthAmount": 5,
        "restrictionQualifier": {
            "value": "Year"
        },
        "restrictionSimple": false,
        "retainSysIds": true,
        "retentionDuration": 1,
        "retentionDurationPurge": false,
        "retentionDurationUnit": "Days",
        "situation": "Holiday",
        "skipActive": false,
        "skipAfterDate": null,
        "skipAfterTime": null,
        "skipBeforeDate": null,
        "skipBeforeTime": null,
        "skipCondition": "None",
        "skipCount": 0,
        "skipDateList": [],
        "skipRestriction": "None",
        "sysId": "808272bdf2aa49a9bb8edcb700c40cfd",
        "taskMonitor": "Task-mon-1",
        "tasks": ["CMD_WF", "PING"],
        "taskIds": ["ffda846987be43c69c4dd62ac452eabf", "ca960a653a704fec893eb17adc6f5f3d"],
        "timeZone": null,
        "variables": [],
        "version": 1
    },
    {
        "type": "triggerTime",
        "action": "Do Not Trigger",
        "adjustInterval": false,
        "adjustmentAmount": 1,
        "adjustmentType": "Day",
        "calendar": "System Default",
        "dateAdjective": "Every",
        "dateAdjustment": "None",
        "dateNoun": {
            "value": "Day"
        },
        "dateQualifier": {
            "value": "Year"
        },
        "dayInterval": 2,
        "dayStyle": "Simple",
        "description": "Time trigger test",
        "disabledTime": "",
        "enabled": false,
        "enabledEnd": "00:00",
        "enabledStart": "00:00",
        "enabledTime": "",  
        "exportReleaseLevel": "7.2.0.0"  
        "exportTable": "ops_trigger_time",
        "forecast": false,
        "fri": false,
        "intervalStartingDate": "2021-06-01",
        "mon": false,
        "name": "time-trig-1",
        "nextScheduledTime": "",  
        "notes": [],
        "nthAmount": 5,
        "opswiseGroups": [
            "A"
        ],
        "rdExcludeBackup": false,
        "restrictedTimes": false,
        "restriction": false,
        "restrictionAdjective": "Every",
        "restrictionComplex": false,
        "restrictionMode": "Or",
        "restrictionNoun": {
            "value": "Day"
        },
        "restrictionNthAmount": 5,
        "restrictionQualifier": {
            "value": "Year"
        },
        "restrictionSimple": false,
        "retainSysIds": true,
        "retentionDuration": 1,
        "retentionDurationPurge": false,
        "retentionDurationUnit": "Days",
        "sat": false,
        "simpleDateType": "Daily",
        "simulationOption": "-- System Default --",
        "situation": "Holiday",
        "skipActive": false,
        "skipAfterDate": null,
        "skipAfterTime": null,
        "skipBeforeDate": null,
        "skipBeforeTime": null,
        "skipCondition": "None",
        "skipCount": 0,
        "skipDateList": [],
        "skipRestriction": "None",
        "startTimeEnable": false,
        "startingAt": "*:00",
        "sun": false,
        "sysId": "16bde4cef2df4cc3b26dd04a6bcfce91",
        "tasks": ["CMD_WF", "PING"],
        "taskIds": ["ffda846987be43c69c4dd62ac452eabf", "ca960a653a704fec893eb17adc6f5f3d"],
        "thu": false,
        "time": "00:00",
        "timeInterval": null,
        "timeIntervalUnits": "Hours",
        "timeStyle": "Absolute",
        "timeZone": null,
        "tue": false,
        "variables": [],
        "version": 1,
        "wed": false
    }
]

Set Skip Count​

Description

URI

http://host_name:port/uc/resources/trigger/setskipcount

http://host_name:port/uc/resources/trigger/setSkipCount

HTTP Method

POST

Description

Sets the skip count for a specific trigger.

info

Temporary Triggers and Manual Triggers do not support Skip Count. Therefore, the Set Skip Count API is not applicable for Temporary Triggers and Manual Triggers.

Example URI

http://localhost:8080/uc/resources/trigger/setskipcount?triggerid=04257ad80d6e4a62a11b916ede093b37&skipCount=10

http://localhost:8080/uc/resources/trigger/setskipcount?triggerid=04257ad80d6e4a62a11b916ede093b37&skipCount=10

http://localhost:8080/uc/resources/trigger/setskipcount?triggername=time-1&skipCount=10

Authentication

HTTP Basic

Produces Content-Type

Application/XML, Application/JSON

Consumes Content-Type

Application/XML, Application/JSON

Example Responses

  • Status 200
  • Status 403
    • Operation prohibited due to security constraints.
  • Status 404
    • A trigger with id "triggerid" does not exist.
  • Status 400
    • Mutual exclusion violation. Cannot specify triggername and triggerid at the same time.
  • Status 500
    • Unexpected request failure. See log(s) for more details.

Set Skip Count: URI Parameters​

Name

Description

Specifications

Required

Mutually Exclusive With

triggername

Name used within the Controller to identify this trigger.

Maximum 40 alphanumerics.

Y
(unless triggerid
is specified)

triggerid

triggerid

Unique ID for this trigger.

Y
(unless triggername
is specified)

triggername

skipCount

Skip count to set.

Default is 0.

N

Set Skip Count: XML and JSON Examples​

JSON
JSON
{
    "type": "set_skip_count",
    "success": true,
    "info": "Successfully set skip count \"10\" to trigger \"time-1\".",
    "errors": ""
}

Trigger Task(s) (Trigger Now)​

Description

URI

http://host_name/uc/resources/trigger/triggernow

HTTP Method

POST

Description

Launches trigger-associated tasks.

Example URI

http://localhost:8080/uc/resources/trigger/triggernow?includeTaskInstanceIds=true

Authentication

HTTP Basic

Consumes Content-Type

application/xml, application/json

Produces Content-Type

application/xml, application/json

Example Request

See Trigger Now: XML and JSON Examples.

Example Request Properties

See Trigger Now: Request Properties.

Example Response

See Trigger Now: XML and JSON Examples.

Trigger Task(s) (Trigger Now): XML and JSON Examples​

Request Example​

JSON
JSON
{
  "name": "man-trig1",
  "hold": "yes",
  "holdReason": "Waitng for input",
  "launchReason": "test1",
  "timeZone": "America/Chicago",
  "virtualResourcePriority": 10,
  "virtualResources": [
    {
      "name": "VR-1",
      "limit": 2
    }
  ],
  "variables": [
    {
      "name": "testVariable",
      "value": "Hello"
    }
  ],
  "overrideTriggerDateTime": "true",
  "overrideDate": "2022-09-20",
  "overrideTime": "11:15",
  "overrideTimeZone": "America/Chicago"
}

Response Example​

JSON
JSON
{  
    "type": "trigger_now",  
    "success": true,  
    "info": "Successfully triggered \"MT4 - Multiple Tasks\" with id 60fe6cfa8089463d987bf84fc6a98631.",  
    "errors": "",  
    "sysId": "60fe6cfa8089463d987bf84fc6a98631",  
    "taskInstanceIds": [  
        "1748439639994114960X5QU9R2MEOQQJ",  
        "1748439639994118960RNR1UKGH3R07S",  
        "1748439639994121960O5XLT5H47VP0T"  
    ]  
}

Trigger Task(s) (Trigger Now): Request Properties​

Property

UI Field Name

Description

Specifications

Required

hold

Hold on Start

Indication of whether or not to launch the task in Held status. The task runs when the user releases it.

Boolean; Valid values: Yes, Y, true.

N

holdReason

Hold Reason

Information about why the task instances will be put on hold when the tasks start.

N

includeTaskInstanceIds

n/a

Specifies whether or not to include the task instance id(s) for task(s) launched by the trigger in the response.

Task instance id(s) are specified in the taskInstanceIds response payload property.

Example response:

<taskInstanceIds>
    <taskInstanceId>17484396399941439602L6HF5OHP3CP3</taskInstanceId>
</taskInstanceIds>

Boolean; URI parameter

N (defaults to false)

launchReason

Launch Reason

Reason for the task launch

N

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

name

Name

Name of the trigger to trigger the task.

Y

overrideDate

Date

Date of the override execution.

YYY-MM-DD

N
(Y if overrrideTriggerDateTime
is true.)

overrideTime

Time

Time of the override execution.

HH:MM

N
(Y if overrrideTriggerDateTime
is true.)

overrideTimeZone

Time Zone

Time zone of the override execution.

N
(Y if overrrideTriggerDateTime
is true.)

overrideTriggerDateTime

Override Trigger Date/Time

Specification for whether to enable or disable override functionality.

Boolean; Valid values: true/false.

Default is false.

N

simulate

Simulate

Specifies if the workflow should execute under simulation mode.

You can only enable simulation mode with the Trigger Now command, you cannot disable it if it is already enabled on the Trigger Record.

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

N

timeZone

Time Zone

Time zone in which task is triggered.

N

variables

n/a

<variables>
  <variable>
    <name>testVariable</name>
    <value>Hello</value>
  </variable>
</variables>

See Trigger Task(s) (Trigger Now): Request Variable Properties.

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
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
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. This priority applies to all resources required by the task.

Integer; Valid values: 1-20 (1 is high priority, 20 is low priority). Default is 10.

N

virtual-resources

n/a

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

See Triger Task(s) (Trigger Now): Request Virtual Resource Properties.

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.

N

Trigger Task(s) (Trigger Now): Request Variable Properties​

Property

UI Field Name

Description

Specifications

Required

name

Name

Name used within the Controller to identify this variable.

Maximum 40 alphanumerics.

Y

value

Value

Value of the variable.

Y

Trigger Task(s) (Trigger Now): Request Virtual Resource Properties​

Property

UI Field Name

Description

Specifications

Required

limit

Resource Limit

Maximum number of units available for this resource.

Integer; Valid values: 1-20.

N

name

Resource Name

Name used within the Controller to identify this virtual resource.

Maximum 40 alphanumerics.

Y

Unassign an Execution User from a Trigger​

Description

URI

http://host_name/uc/resources/trigger/unassignexecutionuser

HTTP Method

POST

Description

Unassigns an Execution User from the specified trigger.

URI Parameters

See Unassign an Execution User to a Trigger: URI Parameters.

Authentication

HTTP Basic

Example URI

Example Response

  • Status 200 /OK
    Successfully unassigned execution user "test" from trigger "testTrigger".

Unassign an Execution User from a Trigger: URI Parameters​

Name

Description

Specifications

Required

Mutually Exclusive With

triggerid

Unique ID for this trigger.

Y
(unless triggername
is specified)

triggername

triggername

Name used within the Controller to identify this trigger.

Maximum 40 alphanumerics.

Y
(unless triggerid
is specified)

triggerid