Workspace notifications
Hear on Slack and by email when work arrives or changes and when a run waits, fails, or completes, and choose which events send a notice.
Overview
A workspace tells its people about five events. Each event is about one work item or one run. Oxagen shows every event in the app, posts it to the workspace's Slack channel, and emails the people it names.
The Slack connection belongs to the organization, and an organization Owner makes it once. The channel belongs to the workspace, and each workspace picks its own on that connection. See Connect Slack.
Until someone sets it up, a new workspace posts nothing to Slack and emails only the people an event names. Every event starts on. The in-app notices work from the start.
The five events
| Event | When it happens | What the notice says |
|---|---|---|
| Work received | A collector brings an item into the workspace, or a person enters one. | New work item and the item's number and subject. The line under it reads "Collected by" and the collector's name, "Collected from a tracker", or "Entered in Oxagen". |
| Work state changed | An item moves to another state. | The item's number, its new state, and its subject. The line under it reads "Moved from" the old state "by" a person, the runtime, triage, Oxagen, or the tracker. |
| Run waiting | A live run stops until a person acts. | The item, or "A run", and what it waits for. |
| Run failed | A run ends in anything but a clean finish, or a work order fails before a run starts. | "Run failed", with the item. |
| Run completed | A run ends and the agent reported it complete. | "Run completed", with the item. |
A notice carries a link to the item or the run. It never carries an item's description, a question's text, a transcript, or a tool call's input.
Work state changed
Any move out of the New state, including a triage failure that holds a new item, writes only the in-app notice and sends nothing to Slack or email. Triage moves each new item out of New, so a large first read stays quiet. Every later move, such as Ready or Sent, sends as usual.
When triage cannot finish an item, the notice says the item is Held and waits for a person. When triage asks a question first, the notice says so.
Run waiting
The notice names the cause.
| Cause | The run waits for |
|---|---|
| Approval | A person to approve a call. |
| Consent | A person to consent to a call. |
| Question | An answer to a question the agent asked. |
| Budget hold | A budget decision, because a run or workspace budget is spent. |
| Idle pause | Someone to resume it. |
| No progress | Someone to resume it, after the run repeated one call with no new result. |
An approval or consent wait keeps its approver notices. It does not add a second in-app notice for the same wait.
Run failed and run completed
Oxagen reports Run completed only when the agent said the run finished. Every other end is Run failed, so a run that someone stopped and a run that went silent both read as failed. The notice says which:
- Run stopped by the person's name. That person gets no email about their own stop.
- Run went silent. The run sent nothing for twelve hours, so Oxagen closed it.
- Run failed with the way it ended, when the run ended in error.
- Run failed or Run stopped, when the run's sandbox ended before the run reported its end. The notice says why: the sandbox crashed, lost its host, sat idle, reached the runtime's longest run time, or someone stopped it. A harness that exits on its own reports its end, so its sandbox's end sends nothing more. When a person stopped it, the notice names them and they get no email about it. A later report that the same run failed sends nothing more. A later report that the run finished sends Run completed.
A work order can also fail before any run exists. The notice says the runtime refused the work order, or that the sandbox could not start. The reason the runtime gave stays on the work item and out of the notice.
A run that was reopened and ends again sends a second notice only when its outcome changed, or when a person stops it after Oxagen closed it.
Which runs send notices
A run sent from a work order sends all three run events. Any other run sends Run waiting only, and only to the person who started it, in the app and by email. It never goes to Slack. An in-app assistant turn sends nothing.
Who receives each notice
In the app
The people an event names get a notice in the app, and so does every Admin of the workspace. The switches below do not turn off the in-app notice. Two cases differ: an approval or consent wait notifies its approvers, and a run sent from no work order notifies only the person who started it.
By email
Email reaches only current members of the workspace, at their verified address. An event reaches:
- The person who started the run and the person who sent its work order.
- The people the item names: the person who entered it, the person it is assigned to, and the member whose verified email matches the owner the tracker lists. A tracker owner who is not a member gets nothing.
- Every member whose workspace role the workspace checks under Email. The roles are Admin and Member. None is checked at first.
One person gets one email per event, however many of these apply. The workspace's switch for the event and the person's own switch must both be on. A requester outside the workspace never gets email.
On Slack
A post reaches everyone in the channel. The settings page lists public channels only.
Flood rule
More than ten work received events in ten minutes become one notice. A large first read from a collector then sends one message, not hundreds.
The window opens at the oldest work received event that has not been sent and lasts ten minutes. When the window closes with ten or fewer events, each goes out on its own. With more than ten, one notice says how many items arrived and links the work list. It names the collector when every item came from one.
Each item in the summary still gets its own in-app notice. The summary goes once to Slack and once to each email recipient, including the people the items name.
A single item can wait up to ten minutes for its notice, because Oxagen waits for the window to close.
Threading
On Slack, a work item's notices share one thread. The first notice for the item is a channel message, and later notices reply under it. A run sent from a work order for one item posts into that item's thread, so the whole story stays together.
A run with no item, such as a batch run, threads under itself. A run failed notice also shows in the channel, so a failure is visible without opening the thread.
When the workspace picks another channel, the next notice starts a new thread. Email is not threaded.
Turn an event off
There are two switches, and both stop only Slack and email. The in-app notice always arrives.
For the workspace
An Admin of the workspace or an organization Owner turns events off for everyone.
- Open the workspace's Settings at
/{org}/{workspace}/settings?tab=notifications. - Under Slack, select Pick a channel, choose one, and select Save channel.
- Under Events, turn off the events that should not send a notice.
- Under Email, check the workspace roles whose members get email.
Each switch saves as you change it. Every change is recorded in the organization's audit trail as workspace.notifications_changed.
For you
Any member turns off an event's email for themselves.
- Open the user menu and select Notification settings.
- Under Email, turn off the events you do not want.
This applies in every workspace you belong to. Each email also ends with an unsubscribe link. Select it, or use your mail client's unsubscribe button, and Oxagen turns off that event's email for you with no sign-in. A link in an old email keeps working.
Slack posts
Item numbers and subjects often come from a tracker, so Oxagen treats them as outside text. It escapes them so a subject cannot mention a channel or a person, and it sets a subject from a tracker in a code span so Slack's formatting does not apply. Email escapes the same text.
Slack and email deliveries try up to five times. A failure that repeats until someone acts, such as a bot that was removed from a private channel, stops the retries. Connect Slack lists each code and its fix. The in-app notice and email still go out.
Capabilities
The settings page calls these capabilities. They are available to the app only, and an API key or an agent run is refused.
| Capability | What it does |
|---|---|
get_workspace_notifications | Reads the workspace's channel, email roles, and event switches. |
set_workspace_notifications | Changes them. |
list_workspace_slack_channels | Lists the public channels a workspace Admin can pick. |
get_user_preferences and set_preferences | Read and change your own email switches. |
list_notifications | Lists your in-app notices. |