Workflow events
- Synopsis
- Full Details
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:KILLon 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
- Open the job and its Events tab, and select Add New Event.
- Choose the Trigger Type and set its status or comparison.
- Choose the event to fire and fill in its fields.
- Optionally scope it to one of the job's frequencies, then save.
The full steps are in Run events on job outcomes.
- 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
SMA0037matches 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.
- 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.
See How workflows work.
Task walkthrough: Run events on job outcomes. This page is the full configuration and troubleshooting reference.
An event fires a command in response to a job outcome — for example, sending a notification when a job fails, or triggering another action when a job finishes late. Events are configured per job; workflows can also carry schedule-level events.
- Trigger Types
- When Events Fire
- Job Statuses
- Exit Descriptions
- LSAM Feedback
- Workflow Completion
Trigger Types
Event trigger types
| Trigger Type | Fires based on | Key settings |
|---|---|---|
| Job Status | The job reaching a specific status | Job Status (see the Job Statuses tab) |
| Exit Description | A comparison against the job's termination description — see the Exit Descriptions tab | Operator, Value, plus End Range when the operator is Range |
| Completion Expression | A custom expression evaluating to True when the job finishes — see Completion expression events | The expression |
| LSAM Feedback | A value a legacy agent reports about the job, appearing or changing to match a pattern — see the LSAM Feedback tab. Offered only for a legacy LSAM job other than an SMAFT file transfer | Field, String to match |
Every event carries a command to run and an optional Fire Only For Frequency (Optional) that scopes when it applies.
How a job event is authored
A job event has two halves, and they are edited separately on the event's card:
- When it fires — the trigger type above and its settings, plus the optional frequency scope.
- What it fires — built in the standard event form, the same editor the workflow's completion events (on the Workflow Completion tab), the Self Service portal and Vision use. Pick the event type and fill in that type's own fields; values accept the job's, the schedule's and the tenant's property tokens.
The command line is rebuilt from the fields when you save, so what fires always matches what you entered. An event carried over from the legacy product as a command line only is read into the form's fields when the job editor opens it, and is stored in that form the next time you save the job. A stored line the form cannot read keeps firing as stored until you choose its event again.
An event naming no type cannot be saved. The job editor refuses it rather than storing a blank, and the workflow's own validation names the job and the event (Job 'X': event 2 has no event to fire) so you can find it.
Everything else the event form checks is reported per field, both in the job editor and by the server when the workflow is saved — and on every event the job carries, not only the ones you changed, so an untouched event that could never fire is surfaced rather than failing silently at run time. Editing a job on a running instance is validated the same way. As with completion events, an event whose type the platform cannot fire is a warning rather than a refusal (except one of the three agent-only types, which is always refused); see Every completion event is checked when the workflow is saved (on the Workflow Completion tab).
An event scoped to a frequency the job no longer has is named, so a frequency renamed or removed on the Frequencies tab does not leave an event quietly scoped to nothing.
Scoping an event to one frequency
An event's optional Fire Only For Frequency (Optional) picker scopes it to one of the job's own frequencies: the event is kept only on instances built for that frequency, and every other instance of the job is built without it. Leave it empty and the event applies to every instance. The picker's own description says the same: Send this event only when this job runs under the chosen frequency. Blank sends it for every frequency.
This picker is not the frequency field of an Add Job event. That field, Added Job's Frequency, chooses which frequency the added job is built from; see Job events.
The picker offers the job's frequencies, live. The options come from the job's own Frequencies tab as you edit it, so adding or removing a frequency there is reflected immediately. A frequency the job doesn't run on is never offered, because an event scoped to one could never fire.
It is offered in definition scope only. Open a job instance and there is no picker: an instance is already one frequency, and its events were filtered to that frequency when it was built, so a choice there would change nothing. A stored value round-trips untouched.
If you remove a frequency on the Frequencies tab while an event is still scoped to it, the
event's Fire Only For Frequency (Optional) picker stays visible, keeps showing the stale name, and reports
"<the frequency>" is not one of this job's frequencies, so this event will never fire. Save
refuses it until you pick a frequency the job has, or clear the scope.
It is flagged rather than cleared for you, because clearing it would silently widen the event to every frequency — a different event from the one you authored. Earlier builds accepted the stale scope and the event was saved to fire on instances that are never built.
An event command separates its fields on commas and has no way to escape one, so a comma is refused in any field except a trailing list. Typing one now keeps the character, reports the message on the offending field, and leaves the generated command empty — which keeps Save disabled. The message names the field (Schedule Name: commas aren't allowed here, the event uses commas to separate its fields) rather than telling you to choose an event you have already chosen.
A comma inside a property token is fine, and it stays inside it. Every reader of the command
line — the save-time check, the event as it fires, and the authorization check that has to agree
with it — skips over [[…]] and {{…}} spans when it splits on commas, so a token's own argument
is never mistaken for the next field. An expression such as [[=Replace("a;b", ";", "-")]] is
therefore usable as a field value, and a stored event whose command was built elsewhere — Code view,
the API, or a token holding a comma — fires against the field it was written in.
A token has to begin and end in the same field. A value that opens [[ or {{ with nothing
closing it inside the same field, paired with a later value that supplies the closing brackets,
would read back as one field and shift everything after it. That is refused, with the offending
field named, rather than fired.
A command can carry property tokens. Write [[$JOB NAME]] or [[MyProperty]] anywhere in the
command and it is resolved as the event fires, from the job's own record — so [[$JOB STATUS]]
reports the status that fired the event, not the one assumed when the job started. If a token can't
be resolved the event still fires and that field keeps the text as you wrote it. The
exception is a property name the event would create: the property name of a $PROPERTY:ADD, or a
name in the Instance Properties or Schedule Properties list of $JOB:ADD or
$SCHEDULE:BUILD. There an unresolved token refuses the event, and nothing is added.
A job's events also read the
machine properties of the agent the job ran on, as
[[MI.Name]]; a workflow's events read only another agent's, named as [[MI.Name.AGENT01]]. See
When tokens are resolved for the names available
and how encrypted properties are handled.
Taking a machine out of service from an event
Set Machine Status ($MACHINE:STATUS) is offered in the event form. It names a machine and a
Status, and sets that agent's operator mark:
Up clears any mark, Down marks it offline, and Limited marks it draining, so running jobs
finish and no new work is sent. The machine is matched by its exact name, ignoring case; a name no
agent has, or one several agents share, fails the event and says which. Saving the event needs the
Agents Edit permission.
Set Machine Max Jobs ($MACHINE:MAXJOBS) is not applied: Continuum does not enforce a
per-machine job limit. The event form lists it but does not let you pick it, and a stored one fails
when it fires rather than reporting a limit nothing enforces.
A $PROPERTY event can write an agent's machine property. Name it MI.Name.AGENT01, or
leave the machine blank in a job's event, MI.Name, to write onto the agent the job ran on. A
workflow's event has no agent to default to, so it must name one. Saving the event needs
Agents Edit under All workspaces. See
Writing a machine property.
Events written with the older $TOKEN:ADD, $TOKEN:SET or $TOKEN:DELETE spelling fire as
$PROPERTY:ADD, $PROPERTY:SET and $PROPERTY:DELETE. They are checked, permission-checked and
fired exactly as the $PROPERTY event, and the saved configuration keeps the spelling it was
written with. The event form does not offer the older spelling for new events. In the same way,
the older $JOB:REVIEW spelling fires as $JOB:UNDERREVIEW.
When Events Fire
When each trigger is evaluated
The trigger types are checked at different points in a job's life, which is why a status event can fire mid-run but an exit-description event never does.
- Job status events are checked on every status change, so they can fire while the job is still running (for example on Late to Finish).
- Exit description events are checked only when the job finishes. Until then the job has no termination description to compare against.
- Completion expression events are checked only when the job finishes, the same as exit description events. A status change before that never evaluates the expression.
- LSAM Feedback events are checked each time the job's agent reports a new or changed value, so they fire while the job is running as well as when it ends. A status change never fires one.
Job Statuses
Job status values
The Job Status field lists:
Finished OK · Failed · Fixed · Skipped · Under Review · Start Attempted · Still Attempting Start · Late to Start · Late to Finish · Missed Latest Start Time · Exceeded Max Runtime
Start Attempted fires when the job is handed to its agent, and Still Attempting Start when its agent has not confirmed the start about five minutes later — see A job is Running only once its agent confirms it. Earlier builds moved a job straight past both, so neither fired.
Failed also covers a job an operator marked failed, and a job that failed during initialization. Finished OK likewise covers a job an operator marked finished OK.
Exceeded Max Runtime is the odd one out — it is not a job status at all. See below.
Exceeded Max Runtime is a derived condition, not a status
Exceeded Max Runtime sits in the Job Status list in the editor, but it is the one entry there that is not a status. A job that runs past its Max Run Time is labelled rather than transitioned, so this trigger is matched by name and fires on the overrun itself.
It now fires. In earlier builds you could configure it, save it, and get silence forever — nothing in the platform compared a running job's elapsed time against its limit. What to know when you use it:
- It fires while the job is still running, once per run, and the job is not stopped. A
$JOB STATUStoken in the command therefore renders the job's real status — Job Running — not the condition that fired the event. - It is the opt-in way to kill an overrunning job. Attach a
$JOB:KILLcommand to it. The platform never kills the job on its own. - It does not fire on the job's start, and it does not fire again when the job later finishes.
Completion expression events
A Completion Expression event runs its command when the job finishes and its expression
evaluates to True. It is evaluated once, when the job reaches a final status — never while the job
is running.
- Only
Truefires the event. A result ofFalseskips it. So does an expression that cannot be evaluated — a syntax error, a token that does not resolve, or a result that is notTrueorFalse— and the event is skipped rather than retried. - Each event's expression is evaluated on its own, so one event's expression never decides another's.
- An expression can read the job's own run facts, such as
[[JI.$JOB STATUS]], and the job's, its workflow's and global properties. The operators and functions are those of every expression. - An encrypted global property is refused as an operand, as it is in an expression dependency, and the event is skipped. See Encrypted global properties are refused as operands.
For example, 0 == 0 is always true, so an event with that expression fires every time the job
finishes.
To alert on a job that runs too long you have two working choices: an Exceeded Max Runtime event, which needs only a Max Run Time on the job's frequency; or a Late to Finish status event, which needs a Late to Finish Offset on the job's frequency — the job moves to Late to Finish once that long has passed since the run's scheduled start.
This page previously said a Late to Finish event fires once the job passes a planned end time plus a late-finish threshold. Those two fields were never populated on a running job, so the check they fed was unreachable and no job ever reached Late to Finish or Late to Start — a Late to Finish event set up that way never ran its command. Both statuses are raised now, and the deadline comes from the frequency's Late to Start Offset and Late to Finish Offset, measured from the run's scheduled start. The old threshold fields are gone.
A Late to Start event is worth a second look too: it fires for a job still waiting on a dependency, threshold, resource, expression or machine as well as for one queued to start, even though a waiting job keeps its wait status. See Late to Start and Late to Finish are raised.
Exit Descriptions
Exit-description events
An Exit Description event fires when the job's termination description passes the comparison you set. It is checked when the job reaches a final status. The event card has three fields for it:
| Field | What it is |
|---|---|
| Operator | How the termination description is compared with Value. A new event starts on Equal To. |
| Value | What to compare with: text, such as SMA0037, or a whole number, such as 0 — Enter text or a whole number. Up to 255 characters. A new event starts on 0. |
| End Range | The upper bound, text or a whole number, up to 255 characters. Shown only when Operator is Range. Changing the operator away from Range removes it. |
Neither can be left blank. Saving refuses an event with no Value — enter a Value for the Exit Description comparison — and a Range event with no End Range — enter an End Range for the Range comparison — and the field reads Enter a Value or Enter an End Range. A value of only spaces counts as blank. A longer value reads The Value must be 255 characters or fewer.
A value is kept exactly as you type it. A plain whole number such as 5 or -1 is stored as a
number; anything else — SMA0037, 007, +5, a value with a space — is stored as the text you
typed, with no spaces trimmed, so 007 stays 007. Either way, what it is compared with is text
the job wrote, and whether the comparison is made as numbers or as text decides what each operator
means — see
What is actually compared just below. In the table, "the
description" is the job's termination description.
| Operator | Fires when | Use it to | Example |
|---|---|---|---|
| Equal To | The description equals Value. | Act on one exact code or message. | Equal To 0 on a legacy job fires when it reported exit code 0; Equal To SMA0037 fires on an IBM i job that ended with that message ID. |
| Not Equal To | The description is anything other than Value. An empty description counts as different. | Act on every code but one. | Not Equal To 0 on a legacy job fires on any code other than 0. |
| Greater Than | The description is greater than Value. | Act on codes above a threshold. | Greater Than 4 fires on exit code 8, but not on 4. |
| Greater Than or Equal To | The description is greater than Value, or equal to it. | The same, including the threshold itself. | Greater Than or Equal To 4 fires on 4 and on 8. |
| Less Than | The description is less than Value. | Act on codes below a threshold. | Less Than 4 fires on 0 and on 3, but not on 4. |
| Less Than or Equal To | The description is less than Value, or equal to it. | The same, including the threshold itself. | Less Than or Equal To 4 fires on 0 and on 4. |
| Contains | The description holds Value anywhere in it, in any letter case. Contains is always a text search, even when the description is a number. | Find part of a longer text. | Contains CPF fires on SMA0023-CPF0006, and on any other description holding those letters. |
| Range | The description is from Value to End Range, both ends included. | Act on a band of codes. | Range 1 to 4 fires on 1, 2, 3 and 4, but not on 0 or 5. |
The examples assume a job whose description is a whole number, such as a legacy LSAM job that reported an exit code. For such a job, a Range whose End Range is lower than its Value holds no number, so the event never fires.
What is actually compared
The value on the left of the comparison is the job's termination description — the text a job finishes with — not its exit code. The two are separate fields, and this trigger only ever reads the description.
That matters more than it sounds, because of how the comparison then works:
- The comparison is numeric only if all three values are whole numbers — the termination description and both bounds you set. If any of them is not, every operator falls back to a text comparison, including Greater Than, Less Than and Range.
- A job that finished OK has an empty description, and a job that failed usually has an error message. Neither is a number.
So on a job whose description is text, Greater Than 4 does not mean "greater than four" — it
compares as text, where "10" sorts below "9". Set a numeric comparison only where you know
something writes a numeric termination description.
A legacy job is one place that does. A Windows, UNIX/Linux or SQL legacy LSAM job that reports an exit code carries that code as its termination description, whether it finished or failed — so a numeric comparison is meaningful on those, and this is the trigger to use to key off a particular code.
This is also why such an event may be firing for you now when it never did before. Until recently a
legacy job's description was blank on success and the text Job failed on failure, so no
exit-description trigger fired on one, including an Equal To 0. A job whose outcome
exit criteria decided now carries its exit code too —
the exit-criteria line used to overwrite it, which is why a trigger written for a particular code
stayed silent on exactly the jobs most likely to have one. One case still carries text rather than a
number: a failure that produced no exit code at all. SMAFT file-transfer jobs are not included.
An IBM i job carries the message ID its agent
reported — for example SMA0036 when it finished OK, SMA0037 when it failed — as its termination
description, on either outcome. That is text, so enter the message ID itself as the Value:
Equal To SMA0037 fires on that message ID and no other, in any letter case. Contains
0037 matches it too, and also any other description holding those characters. A
z/OS Batch Job carries the agent's text as its
description too, and so do an MCP job and an
OS 2200 Job, and the same applies.
Text comparison rules
When the comparison falls back to text:
- it is case-insensitive —
ABORTEDandabortedmatch; - accents are significant;
- trailing spaces are ignored, so
"ABORTED "equals"ABORTED".
Two operators have their own rules:
| Operator | Rule |
|---|---|
| Contains | Never numeric. Always a case-insensitive substring search, whatever the values look like. |
| Range | The job editor refuses a Range event whose End Range is blank. A stored Range with no End Range (one written through the Code tab, for example) is treated as ending at 0, which usually makes the range empty and the event never fire. Always set both bounds. |
A job with no termination description at all is compared as an empty string — the event is still evaluated, not skipped.
- An event firing is expected behavior, not an error — e.g. a Failed status event that sends an alert is the system working as designed.
- If an expected event didn't fire, check the trigger configuration first: the status/exit comparison may not have matched, or the event's Frequency scope may have excluded the run.
- Events run a command — what that command does is defined by the command itself; the event only decides when it fires.
LSAM Feedback
LSAM Feedback events
An LSAM Feedback event fires when a legacy LSAM job's agent feedback gains a value, or a value changes, and the new value matches a pattern you give. It is checked as the agent reports, so it can fire while the job is still running — when an SAP job's child job terminates, say, rather than once the whole job ends.
| Field | What to enter |
|---|---|
| Field | Which feedback to watch. Job Status Description is offered for every legacy LSAM job except an SMAFT file transfer; an SAP R/3 Job also offers Child Process, EXEC Target and Job Number, an SAP BW Process Chain Process and Process Chain Log, an MCP job its task statistics (Mix Number, Process Name, Task Processor Time, Accum Processor Time and the other task and accumulated time, print-line and wait-time counters), and every z/OS job type — z/OS Batch Job, z/OS Started Task, z/OS REXX Exec, z/OS Console Command, z/OS Tracked Job and z/OS Queued Job — User Message, Step Completion and Trigger Messages |
| String to match | The pattern the whole value must match, up to 4,000 characters. Use % for any characters and _ for one character. |
LSAM Feedback is in the Trigger Type list only when the job's type runs on a legacy LSAM agent and reports feedback, which an SMAFT file-transfer job does not. An existing LSAM Feedback event still shows and can be edited on any job; a Field the job's platform does not report reads Agent feedback, and never fires.
How the pattern matches. The pattern is compared with the whole value, ignoring case:
| In the pattern | Matches |
|---|---|
% | Any run of characters, including none |
_ | Exactly one character |
[abc], [a-z] | One character from the set or range |
[^abc] | One character not in the set |
| Anything else | Itself |
So %:Terminated matches a Child Process value such as CHILD1:11203800:Terminated,
%ABEND% matches any value containing ABEND, and on a z/OS job S-0C7% matches a Step
Completion value such as S-0C7 STEP2 — and fires while the job is still running, as the step
ends.
* and ? are not wildcards here, though a z/OS job's Step Control rows treat them as such:
S-0C7* matches only the text S-0C7* itself. When the pattern holds * or ? and neither %
nor _, the hint under String to match changes to * and ? match themselves here. Use % for
any characters and _ for one character. It is only a hint: the event still saves.
It fires once per change. The same value reported again does not fire it again. A value that
changes to another matching value fires it again, and so does a value that changes back. Each
value — each child job of an SAP job, for instance — fires on its own. A value already seen while
the job ran does not fire again when the job ends. In the event's fields,
[[$TRIGGER MESSAGE]] is the value that fired it, so the command can say which child terminated.
A feedback event that fails to send is not retried. It never settles the job: the job's outcome is still its agent's.
Workflow Completion
Workflow completion events
Every other tab on this page covers job events. A workflow can also carry events of its own, which fire when the workflow completes rather than on any one job's outcome. They live on the Event Trigger tab of the workflow set-up panel, and they are the place to put the one thing that should happen once the whole run is done — build tomorrow's schedule, release a downstream workflow, send a single all-clear.
Each event is a row you open in the standard event form — the same editor the job editor, the Self Service portal and Vision use, so an event is built on the chosen type's own fields rather than on a hand-typed command line. Rows can be dragged into order, and that order is the order they fire in. Only event types the platform can actually apply can be picked: a type that is not built yet is listed but disabled, and one the platform will never support is not listed. A row holding a type that is no longer offered still shows the type it was saved with rather than reading as blank, and a row the platform cannot read at all shows its stored line with the reason beside it.
Add Event Trigger opens the form, and the form will not save an event with no type, so a blank event cannot be added in the first place. Values accept property tokens — the schedule's own and the tenant's globals.
What you fire is rebuilt from what you entered. Saving regenerates each event's command line from its type and its field values, so the line that fires always matches the form you filled in. An event that was authored in the legacy product as a command line only is kept exactly as it is until you edit it, and converts to the form at that point.
A workflow event has no trigger condition. Unlike a job event there is no status or comparison to set — a completion event fires on completion, which is why the tab asks only what to fire and not when.
The events are frozen onto the run when the workflow is built, so editing them changes the next build rather than a run already in progress.
Every completion event is checked when the workflow is saved
The server validates every completion event in the config, not only the ones you changed, and refuses the save with the problem reported per field. An event you never touched that could not fire blocks the save, because it would have failed silently at completion time. The same rules run on an automation import, which used to write straight past them.
Two problems only a stored event can have are named for what they are:
- The event has no command line. Its field values cannot be stored on their own, so the row could never be persisted. This used to surface as a schema error naming a position in the request body rather than the event.
- The event's values live only in its line. The row shows them because the line is parsed for display, so reporting each one as "missing" contradicted what you were looking at. It now says that the values are not stored, and what to do about it.
An event whose type is unknown, not supported, or not built yet does not block the save. There is nothing you could edit to fix one — the type is the problem — and the event is inert either way, so refusing it would only force you to delete an event you did not write.
This matters on the two paths that carry a configuration rather than author it:
Copy Workflow and an automation import. Each of those presents events that
differ from what is already stored, so any workflow holding such an event — an imported legacy
configuration holding a $NOTIFY:LOG, for instance — still saves and copies, with a warning.
Authoring a new one is still refused, by the event form, which is the only place that can tell
authoring from carrying over. An event naming no type at all is still an error everywhere, and
so is one of the three agent-only types ($JOB:TRACK,
$JOB:QUEUED, $JOB:QUESTATE): only an agent raises those, so a stored one is refused, never
warned about.
The event parameter form is shared with the Self Service portal, where a
parameter can carry a ${…} placeholder filled in from the requester's form. A workflow has no
requester and no form, so nothing would ever fill one in. Those hints — the ${inputId} note, the
field hint and the input and system-variable chips — are therefore not shown on a workflow's
Event Trigger tab. Use a property token for a value the tenant already
knows.