Run events on job outcomes

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.

What this solves

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.
Job exit description	The job's termination description matches a comparison you set (equal to, greater than, a range, and so on). That is the text the job finishes with, not its exit code — see below.
Job completion expression	A custom expression is true. This one does not run its command yet — you can select it and save it, and nothing happens.

Exit description is text, not the exit code

The Job 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 GreaterThan 4 on such a job is not asking what it looks like it's asking.

Legacy jobs are the case where a number does work

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 EqualTo 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.

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:

1. Set a Max Run Time on the job's frequency.
2. Add an event with the Exceeded Max Runtime trigger.
3. Enter $JOB:KILL as the command.

Good to know

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.

Add an event

To add an event to a job, complete the following steps:

1. In the job editor, open the Events tab.
2. Add an event and choose the trigger (job status, exit description, or completion expression).
3. Set the condition: the status, the comparison and value, or the expression.
4. Enter the command to run when the event fires.
5. Optionally set Frequency 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.
6. Select Save & Close.

Remove a frequency and check the events scoped to it

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.

A token that can't be resolved doesn't stop the event

If you misspell a token or name a property that doesn't exist, the event still fires — that field just arrives with the [[…]] text still in it, which is your signal to fix the name. Only that field is affected: a subject that resolved is still sent resolved. An encrypted property is replaced with a mask, so a notification can't be used to move a credential.

See When tokens are resolved for the full list of names available.

Good to know

• 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
• Create a workflow (Builder)
• Respond to a failed job (Operator)