Run events on job outcomes
- Synopsis
- Full Details
In briefAn event runs a command in response to what a job does — a status it reaches, the termination description it ends with, an expression that is true when it finishes, or, on a legacy LSAM job, a value its agent reports while it runs. You add events per job, on the job editor's Events tab, and build the command from the event type's own fields.
- Job Status events are checked on every status change, so they can fire mid-run; Exit Description and Completion Expression events only when the job ends. Exit Description compares against the termination description rather than the exit code.
- An LSAM Feedback event fires each time a matching value appears or changes, while the job is
still running, and
[[$TRIGGER MESSAGE]]carries that value. - Property tokens in the command are filled in as the event fires; one that cannot be resolved stays
as written, and the event still fires. The exception is the property name of a
$PROPERTY:ADD: if a token in it does not resolve, the event is refused and nothing is added.
- A Completion Expression event fires only on
True. An expression that cannot be evaluated skips the event, and it is not retried. - Removing a frequency the job's events are scoped to refuses the save until you fix the scope.
An event runs a command in response to what a job does: for example, send an alert when a job fails, or trigger a follow-up action when a job finishes late. Events are set per job.
When a job fails, finishes late, or ends with an unexpected result, nothing happens unless someone is watching, so problems sit silently and any follow-up waits for a person to notice.
Event triggers
| Trigger | Fires when |
|---|---|
| Job Status | The job reaches one of these statuses: Finished OK, Failed, Fixed, Skipped, Under Review, Start Attempted, Still Attempting Start, Late to Start, Late to Finish, or Missed Latest Start Time. The same list also offers Exceeded Max Runtime, which is not a status — see below. |
| Exit Description | The job's termination description matches a comparison you set (Equal To, Greater Than, Range, and so on). That is the text the job finishes with, not its exit code — see below. |
| Completion Expression | A custom expression evaluates to True when the job finishes. Checked once, at the job's final status; a result of False, or an expression that cannot be evaluated, skips the event — see Completion expression events. |
| LSAM Feedback | A legacy LSAM job's agent reports a value — a Job Status Description, an SAP job's Child Process, or a z/OS job's Step Completion, User Message or Trigger Messages — that matches your String to match, such as %:Terminated or S-0C7%. Use % and _ as wildcards: * and ? match only themselves, and the editor's hint says so when you type them. Checked as the agent reports, so it fires while the job is still running; [[$TRIGGER MESSAGE]] carries the value. Offered only for a legacy LSAM job other than an SMAFT file transfer — see LSAM Feedback events. |
Exit description is text, not the exit code
The Exit Description trigger reads the job's termination description — the text it finishes with. The exit code is a separate field, and this trigger never looks at it.
That changes what a numeric comparison means. The comparison is numeric only if the description
and both of your bounds are whole numbers; if any of them isn't, every operator falls back to
comparing text, where "10" sorts below "9". A job that finished OK usually has an empty
description and a failed one an error message — neither is a number — so Greater Than 4 on such a
job is not asking what it looks like it's asking.
What each Operator matches, with an example, and how Value and End Range work together (a Range includes both ends), is in Exit-description events.
A Windows, UNIX/Linux or SQL legacy LSAM job that reports an exit code now carries that code as its termination description, so a numeric comparison is meaningful on those and this is the trigger to use to key off a particular code.
It is also why such an event might start firing for you. Until recently a legacy job's description
was blank on success and Job failed on failure, so no exit-description trigger fired on one —
not even an Equal To 0. A job whose outcome exit criteria
decided keeps its exit code too, so a trigger written for a particular code now works on exactly
the jobs most likely to have one; the exit-criteria text used to replace the code and stop it firing.
One case still carries text rather than a number: a failure that produced no exit code at all.
An IBM i job's termination description is the message ID its agent reported — for example
SMA0036 when it finished OK, or SMA0037 when it failed. The trigger's Value takes text, so
enter the message ID itself: Equal To SMA0037 fires on that message ID and no other, in any
letter case. Contains finds part of one, and matches every message ID that holds it. See
The message ID is the job's Exit Description.
A z/OS job, of any z/OS job type, carries its agent's text
as its termination description too, and so does an
MCP job, such as 12345COMPLETED, and an
OS 2200 Job, and the same applies.
See Exit-description events for the full comparison rules.
Exceeded Max Runtime fires while the job is still running
Exceeded Max Runtime sits in the status list but is not a status: a job that passes its Max Run Time is labelled, and it keeps running and then finishes with whatever status it earns. The event fires once, on the overrun, while the job is still in progress.
That makes it the way to stop a job that runs too long, which the platform never does on its own:
- Set a Max Run Time on the job's frequency.
- Add an event with the Exceeded Max Runtime trigger.
- Choose
$JOB:KILLas the event to fire, and fill in the fields naming the job to kill.
This trigger did nothing in earlier builds — it could be selected and saved, and no command ever ran. If you configured one in the past and concluded it was inert, it is live now. Check what its command does before the next long run.
One thing to expect: because the job is still running when the event fires, a [[$JOB STATUS]]
token in the command renders Job Running, not the overrun.
Late to Start and Late to Finish fire now, and one of them fires on a badge
No job ever reached Late to Start or Late to Finish in earlier builds, so an event on either status could be selected, saved — and never ran. Both are raised now, each measured from the run's scheduled start plus the matching offset on the job's frequency. If you configured one in the past and concluded it was inert, it is live: check what its command does before the next run.
One thing about Late to Start is worth planning around. A job still waiting on a dependency,
threshold, resource, expression or machine keeps that wait status and takes a Late to Start
badge — the status cannot move, or the job would start ahead of what it is waiting for. The event
still fires, which is the point, but a command that reads [[$JOB STATUS]] renders the wait
status, not Late to Start. The event fires once per run either way.
To alert on a job running too long you now have two working choices: Exceeded Max Runtime, which needs only a Max Run Time, or Late to Finish, which needs a Late to Finish Offset on the frequency. The first measures from when the job actually started; the second from the run's scheduled start. See Late deadlines.
Add an event
To add an event to a job, complete the following steps:
- In the job editor, open the Events tab.
- Select Add New Event and choose the Trigger Type (Job Status, Exit Description, Completion Expression, or, on a legacy LSAM job other than an SMAFT file transfer, LSAM Feedback).
- Set the condition: the status, the comparison and value, the expression, or the Field and String to match.
- Choose the event to fire and fill in that event type's own fields. You do not write a command line — it is built from what you enter. Values accept property tokens. An event with no type chosen cannot be saved, and anything else the form objects to is reported against the field it belongs to. See How a job event is authored.
- Optionally set Fire Only For Frequency (Optional) to limit the event to one of the job's own frequencies — leave it empty and the event applies to every instance. See Scoping an event to one frequency.
- Select Save.
If you drop a frequency from the job's Frequencies tab, any event still scoped to it is flagged on its card and the save is refused — an event scoped to a frequency the job no longer runs on would never fire. Pick a frequency the job has, or clear the scope.
Put job details in the command
A command can carry property tokens, filled in as the event fires. Write the token in the command and the platform substitutes the value:
[[$JOB NAME]] finished with status [[$JOB STATUS]] on [[$MACHINE NAME]]
The values come from the job's own record at the moment the event fires, so [[$JOB STATUS]] is the
status the job is in — the one that triggered the event, for a status trigger — and
[[$MACHINE NAME]] is the agent that actually ran the job. The schedule name and date are available
too, as are properties you created yourself.
If you misspell a token or name a property that doesn't exist, the event still fires — that field
just arrives with that token's [[…]] text still in it, which is your signal to fix the name. Only
that token is affected: the other tokens in the same field, and every other field, are still filled
in. An encrypted property is replaced
with a mask, so a notification can't be used to move a credential.
One event is the exception: a $PROPERTY:ADD whose property name holds a token that does not
resolve is refused rather than creating a property named with the token's text. It shows as
FAILED in the Event log, and nothing is added.
See When tokens are resolved for the full list of names available.
- An event firing is the system working as designed (for example, a Failed-status event that sends an alert). It isn't itself a failure.
- Events decide when something fires; the command decides what happens.
Related topics
- Workflow events — full configuration reference and troubleshooting
- Add jobs to a workflow (Builder)
- Respond to a failed job (Operator)