Manage notifications
This feature is still being finalized by Development.
- Synopsis
- Full Details
In briefA notification group watches agents, relays, workflows or jobs and tells people when one of them changes state. You switch on triggers for the group's type, and each trigger sends its actions when it fires: an Email, an In-App notification in each recipient's feed, or an OpCon Event submitted back into the platform. Groups live on Design › Notifications.
- A group needs a name and at least one member before it saves; a group with every trigger off is valid, and is how you quieten it for maintenance.
- Name patterns match case-sensitively.
- A property token that can't be resolved arrives as its own name and the message still goes out; an OpCon Event action is the exception and fails the send.
- In a Job or Workflow group, an email recipient can name a property set on the job, its workflow
or its agent. A property's value may separate addresses with
;or,. - Only agent and relay Online/Offline repeats in the same 5-minute block of clock time collapse into one notification; every other trigger notifies each time.
- In-App roles are matched by name.
- An encrypted property shows as
********in an Email or In-App message, and naming a property you cannot view stops the action saving.
- Test sends real notifications. An OpCon Event action in a test really runs, and a timed-out test may still arrive, so testing again can send twice.
- A trigger switched on with no enabled action records its notification as sent, and nobody is told.
- An OpCon Event action keeps running after its author loses the permission it needs.
Notifications tell the right people when something happens to your automation: an agent goes offline, a job fails, a schedule finishes. You create a notification group that watches a set of objects, turn on the triggers you care about, and attach actions that deliver over email or the in-app feed, or submit an OpCon event.
When a critical job fails at 2 a.m., silence is the enemy: the run stalls and no one knows until a business process is already late. Without a way to say "tell this team when these jobs fail," alerting is ad-hoc and easily missed.
- How It Fits
- Email Recipients
- Property Tokens
- Testing a Trigger
- Planned Maintenance
- In-App Feed
How It Fits
How it fits together
The Notifications page (Design › Notifications) is a list of groups.
New Notification Group creates one, and a group is created and edited in a single
dialog that holds its name, what it watches, and its triggers and actions together. The name, the
type and the description sit in a fixed header along with any alert the dialog raises; below them
are two tabs — Select {type}(s) and Triggers & Actions — and only those scroll. Switching
between them keeps unsaved edits, and a tab holding something that blocks Save carries an error
dot on its label.
Nothing is written until you save, and Save comes alive once the group has a name and at least one member — a group that watches nothing can never fire. A group with every trigger switched off is a valid configuration and saves happily; that is the ordinary way to quieten a group for a maintenance window.
Creating a group takes Notifications Create. Saving a change to a saved group's members, or to its triggers and actions, takes Notifications Edit, Notifications Create and Notifications Delete together, because that save can add and remove rows; a change to only the name or description takes Notifications Edit. See Permissions.
- A group has a type (Agent, Relay, Workflow, or Job) chosen when you create it and fixed thereafter. The type decides what it can watch and which triggers it offers.
- Members say which objects the group watches: a specific agent, relay, workflow or job, a
name pattern (
nightly-*), or (for jobs) a tag. Name patterns work for all four types, so*is how you watch every agent without editing the group each time one is added. Patterns are case-sensitive:nightly-*does not matchNightly-Close. Naming a specific job picks it asworkflow / joband binds to the job's own identity, so renaming the job doesn't break the notification — where a name pattern deliberately stops matching a job renamed out of it. A job from a workflow version that predates job identities isn't offered; save a new version of the workflow to make it selectable. A Workflow or Job member can be limited to one environment. An Agent or Relay member can't — those events don't belong to an environment, so a scoped member would never fire, and it's rejected rather than saved. A member you have already saved is editable in place — fix a typo in a pattern, change the object, or move the environment, and reset puts back the value it was loaded with. Blanking a saved pattern leaves that row unfinished and out of the save; the rest of your changes still go through. - Triggers are a built-in list for that type. You switch on the ones you want (Job Failed, Job Late to Finish, agent Offline, and so on) — Job triggers are labelled with a Job prefix and Workflow triggers with a Schedule prefix. A Workflow group also offers every Job trigger, which fires for each job in its member workflows. They're off until you enable them. You can have several triggers open at once, and opening a saved group opens the ones that already have actions. Each row shows its count as "N Action(s)", and a trigger with no action shows a warning in its body, because switched on it would fire and tell nobody. An Agent group also offers Marked Offline, Marked Draining, and Mark Cleared — for when someone takes an agent out of service rather than the agent losing contact. They're kept separate from the connectivity triggers, so clearing a mark won't page anyone with an Online alert about an agent that never went down. While an agent is Marked Offline, its Offline and Online triggers don't fire, although the mark stops communication with it; once you clear the mark, an agent that reconnects raises Online as usual. There is no Agent Disabled trigger. It listened for a status nothing ever set, so it could never fire; a group that had it configured, switched on or off, had that trigger and its actions removed on upgrade. Use Marked Offline for an agent taken out of service.
- Actions on a trigger deliver the notification. Three channels are offered when you add one:
Email, OpCon Event, and In-App. Messages carry
property tokens —
{{objectName}}and{{status}}, and any property, threshold or resource your tenant defines, written as[[Scope.Name]]. They're filled in when the notification is sent. A token that can't be resolved comes through as its own name and the notification still goes out — with one deliberate exception, the OpCon Event channel below; see Template tokens for the details, including why a template should use one delimiter style throughout. An Email action needs a subject; the body is optional, since plenty of alerts say everything they need to in the subject line. An In-App action targets people by role name. If a role-targeted notification says it sent but nobody sees it, re-open the action and re-select the roles — an older configuration may have stored a role id, which matches nobody. An OpCon Event action is the one that acts rather than telling somebody — it submits an event back into the platform, so a failure can restart the job, tag it, or set a property. Three things are specific to it, and none of them applies to the other channels: its Event Type must be one of the types the platform routes and can apply (a type that is not built yet is listed but cannot be picked, and a name that isn't on that list is rejected when you save); you then fill in that type's own fields, and the command line is generated from them and shown as Generated Event rather than typed; and that line is rendered strictly — a token that can't be resolved fails the send instead of coming through as its own name, because a half-resolved instruction to the platform is a different instruction, not a lesser message. Every save re-checks the whole action against the event type's rules, so an action saved before those rules can block a save by naming a field you did not touch. Saving or testing one also needs the permission the event itself requires —$JOB:KILLneeds Job Instances Execute, for example — in the workspace of the object it names. Once saved, the action runs whenever the trigger fires, even after its author loses that permission. See OpCon Event actions, and what changed for an action you configured before this build — until now the channel reported delivery without submitting anything, and the stricter rules arrived with the fix.
Email Recipients
Address an email action to whoever is on call
To, Cc and Bcc each take a comma-separated list, and an entry can be a literal address or a property token. That is what lets one action page whoever your on-call property names today instead of naming a person in the configuration.
Because the address isn't known until the notification is sent, the check happens then:
- Each entry is resolved and split on semicolons and commas, so a property holding two addresses stays a distribution list, whichever separator it uses.
- An entry that doesn't resolve to a real address is dropped and the rest still goes out, so an unset token can't silence the alert for the one real address sitting beside it.
- The send only fails if To has nothing deliverable left. A surviving Cc deliberately doesn't rescue it — a courtesy copy shouldn't quietly become the only recipient.
In a Job or Workflow group, an entry can also name a property set on the job
([[JI.<name>]]), its workflow ([[SI.<name>]]) or the agent the job ran on ([[MI.<name>]]), so a
job can carry the address of whoever owns it. The value is the one captured when the event fired. A
few properties are not carried, encrypted job properties among them; see
The object's own properties.
Keep one literal address in To alongside any token. That way a property nobody has set yet costs you a missing recipient, not the whole alert.
Property Tokens
Pick a property instead of typing a token
You don't have to remember a property's name. Every action field the platform resolves carries an
insert button in the narrow column beside it — select it, search your properties by name or by value, and the token
is placed at the cursor as [[Scope.Name]].
Those are an email's To, Cc, Bcc, Subject and Body; an OpCon Event action's own text, multiline and date fields; and an In-App Title and Body. The fields that are delivered verbatim — Event Type, Environment, Roles, Users — deliberately don't offer it, because a token typed there arrives as literal text.
Practical notes:
- The list always offers all four scopes — Global, Job, Schedule, Agent — even on a group type that can't resolve three of them. An Agent or Relay group has no job or schedule behind it, so a Job or Schedule token there has nothing to fill in. In a message that costs you a token showing as its own name; in a recipient field it costs you a recipient. In an Agent or Relay group, prefer a Global property in To, Cc and Bcc.
- An Agent group can name the agent.
[[$MACHINE NAME]]resolves in every agent notification, and the three operator-mark triggers also resolve[[$MACHINE OPER STATUS]]as Active, Marked Offline or Marked Draining — so a message can say which agent, and what was done to it. A Relay group resolves neither. See What an agent notification can resolve. - Encrypted properties can only be found by name, not by value — there is no value to search. The list also loads up to 1000 global properties and says so when your tenant has more.
- An encrypted property shows as
********in an Email or In-App message, and cannot be used in To, Cc or Bcc: a save that adds one is refused. Only an OpCon Event action carries the real value. - You need Properties View for the properties you name. Saving or testing an Email or In-App action that names a property you cannot view is refused, naming the property. See Encrypted properties and properties you cannot view.
There's no way to create a property from the list. Define it first — see Properties — then pick it here. Full details in Inserting a property token.
Testing a Trigger
Test a trigger before you rely on it
You don't have to wait for a 2 a.m. failure to find out whether anyone gets told. An open trigger carries a Test button beside + Action that sends its enabled actions now, as real notifications — including edits you haven't saved, on a group that doesn't have to be saved yet.
What to know before you use it:
- A confirmation lists exactly what will go, one line per action, with anything that won't be sent marked as such. A disabled action shows its channel followed by — Not sent (disabled).
- An OpCon Event action really runs. Each one gets its own warning naming the event type and the
environment — a
$JOB:RESTARTin a test restarts the job. Test the other channels freely; think before you test that one. - Your global properties resolve; job, schedule and agent tokens don't. There is no triggering
job behind a test, so those come through as their own name in a message, are dropped from a
recipient field, and fail an OpCon Event payload.
{{objectName}}reads as the group's name and{{status}}as the trigger's label. - Nothing marks the message as a test. Whoever is on the recipient list gets the alert you wrote. If that matters, address the test at yourself first.
- You get a per-action result — how many recipients an email reached, which actions failed and why. A result of Timed out — may still have been sent means what it says: don't test again without checking, or you'll send it twice.
- Nothing is retried, nothing lands in the group's delivery history, and an in-app test lands in the feed. There's a cap on how many tests one person can send in a window, and a tested email action reaches at most 50 recipients.
Testing needs edit or create permission on notifications — either one, so someone who can't save this group may still test it. Full behaviour in Testing a trigger.
Planned Maintenance
Quieten a group for planned maintenance
During planned maintenance the failures are expected and nobody needs paging about them. To quieten a group, switch every trigger off and save. A group that fires nothing is a valid configuration, and turning a trigger back on starts it matching again.
In-App Feed
The in-app feed
A bell in the header shows your unread count and opens a panel holding your feed, grouped into Today and Older and paging as you scroll. Each row can be marked read or unread — both ways — or deleted, and Delete All clears your feed after a confirmation.
All of that is per-user. One notification aimed at a role is a single record fanned out to its recipients, so deleting it or clearing your feed affects your feed only. Delete All does not hide anything that arrives afterwards.
With nothing in your feed the bell is disabled, with a No notifications tooltip.
- Config changes take a few seconds to take effect (the matcher refreshes on a short interval).
- Each occurrence notifies: a job that fails, is restarted and fails again sends two. Only the agent and relay Online and Offline triggers collapse repeats for the same object that fall in the same fixed 5-minute block of clock time (10:00–10:05, 10:05–10:10…), so a flapping connection won't spam. Two repeats either side of a block boundary both notify.
- A trigger switched on with no enabled action still records its notification as sent, with nothing sent.
- If email says it sent but nothing arrives, contact support with the notification's time and recipients: delivery depends on how email is set up for your environment.
Related topics
- Notifications (groups, triggers, channels) — full configuration reference and troubleshooting
- Set up failure notifications (Build Outcome)
- Manage permissions (Administrator)
- Respond to a failed job (Operator)