Skip to main content

Workflow events

In briefA workflow event fires a command in response to an outcome. A job event fires on a job's status, on a comparison against its termination description, on a completion expression that is true when the job finishes, or on what a legacy agent reports while the job runs; a workflow completion event fires once when the workflow completes. The command is built from the event type's own fields.

WhereA job's events are on the job editor's Events tab: Add New Event, then the Trigger Type: Job Status, Exit Description, Completion Expression or, for a legacy LSAM job, LSAM Feedback. A workflow's own completion events are on the Event Trigger tab of the workflow set-up panel, added with Add Event Trigger. What an event compares against is on the job's Summary tab after a run: the status, and the Termination row that an Exit Description event reads.

When

  • Something should happen automatically when a job reaches a status, ends with a particular termination description, or runs past its Max Run Time: an alert, a machine taken out of service, a $JOB:KILL on an overrun.
  • Something should happen once when the whole workflow completes, such as releasing a downstream workflow.
  • An event fired when you did not expect it, or stayed silent when you did.

To make one job wait for another, use a dependency instead; an event runs a command, it does not hold a job.

How

  1. Open the job and its Events tab, and select Add New Event.
  2. Choose the Trigger Type and set its status or comparison.
  3. Choose the event to fire and fill in its fields.
  4. Optionally scope it to one of the job's frequencies, then save.

The full steps are in Run events on job outcomes.

Notes
  • Status events are checked on every status change; Exit Description and Completion Expression events only when the job finishes. An Exit Description event compares against the termination description rather than the exit code. A legacy Windows, UNIX or SQL job carries its exit code there, an IBM i job its message ID, and an SAP R/3, SAP BW, z/OS, MCP or OS 2200 job the agent's text.
  • An Exit Description comparison is numeric only when the description and both bounds are whole numbers; otherwise every operator compares as text, case-insensitively.
  • Value takes text or a whole number, so Equal To SMA0037 matches an IBM i message ID exactly; Contains is always a text search.
  • An LSAM Feedback event is checked whenever the agent reports a new or changed value, so it can fire mid-run; [[$TRIGGER MESSAGE]] carries the value.
  • An event can be scoped to one of the job's frequencies, and a scope that no longer exists is flagged.
Watch out
  • A Completion Expression event fires only on a result of True. An expression that cannot be evaluated skips the event, and it is not retried.
  • A Range with no End Range is treated as ending at 0, which usually never matches. Set both bounds.
  • A job that finished OK usually has an empty description unless it is a Windows, UNIX, SQL, IBM i, SAP R/3, SAP BW, z/OS, MCP or OS 2200 legacy job, so a numeric comparison on any other job type's success never matches.