|
| 1 | +--- |
| 2 | +title: Notifications |
| 3 | +description: Configure how ObjectOS routes events into user inboxes — subscriptions, per-user preferences, and render templates. |
| 4 | +--- |
| 5 | + |
| 6 | +# Notifications |
| 7 | + |
| 8 | +This page covers the **administrator side** of notifications: how events become |
| 9 | +messages, and the three system-managed objects you use to route and render |
| 10 | +them. For the recipient's view of the inbox — reading and muting notifications — |
| 11 | +see [Notifications](/docs/use/notifications) under *Use*. |
| 12 | + |
| 13 | +## The notification pipeline |
| 14 | + |
| 15 | +A notification is not a single record. It flows through four stages: |
| 16 | + |
| 17 | +```text |
| 18 | +emit() → Notification Event → routed by Subscription + Preference + Template → Inbox Message |
| 19 | +``` |
| 20 | + |
| 21 | +1. **`emit()`** — Application code raises an event (an approval submitted, a |
| 22 | + record shared, an invitation sent). |
| 23 | +2. **Notification Event** (`sys_notification`) — Each `emit()` writes one |
| 24 | + ingress row. This is the diagnostic log of *what happened*, before any |
| 25 | + delivery decision. See [Audit Logs](/docs/operate/audit-logs) for how to |
| 26 | + read it. |
| 27 | +3. **Routing** — For each event, ObjectOS resolves who should be notified |
| 28 | + (**Subscriptions**), whether each recipient allows that topic on that channel |
| 29 | + (**Preferences**), and how the message should be rendered (**Templates**). |
| 30 | +4. **Inbox Message** (`sys_inbox_message`) — The materialized, per-user result |
| 31 | + the recipient actually sees in their inbox. |
| 32 | + |
| 33 | +Preferences, Subscriptions, and Templates are the admin/system-side |
| 34 | +configuration. Inbox Messages are the user-side output. |
| 35 | + |
| 36 | +### How routing resolves |
| 37 | + |
| 38 | +For a single event, the three objects each answer one question: |
| 39 | + |
| 40 | +| Object | Question it answers | |
| 41 | +|---|---| |
| 42 | +| Notification Subscription | *Who is interested?* — which principals stand subscribed to the topic | |
| 43 | +| Notification Preference | *Does this recipient allow it here?* — the per-user mute/allow for the topic and channel | |
| 44 | +| Notification Template | *How is it written?* — the subject and body to render for the recipient's channel and locale | |
| 45 | + |
| 46 | +Only when a recipient is subscribed **and** their preference for the |
| 47 | +topic/channel is enabled does a template render and an inbox message |
| 48 | +materialize. All three objects are seeded and maintained by the platform, so |
| 49 | +the list views mostly show system-generated rows. |
| 50 | + |
| 51 | +## Notification Preferences |
| 52 | + |
| 53 | +At **Setup → Configuration → Notification Preferences** (`sys_notification_preference`). |
| 54 | + |
| 55 | +Per-user × topic × channel toggle (mute/allow), with admin-global defaults. A |
| 56 | +preference decides whether a given recipient receives a given topic on a given |
| 57 | +channel. |
| 58 | + |
| 59 | +| Field | Purpose | |
| 60 | +|---|---| |
| 61 | +| `user_id` | The principal the preference belongs to | |
| 62 | +| `topic` | Notification topic (e.g. `project.digest`) | |
| 63 | +| `channel` | Delivery channel (in-app, email, …) | |
| 64 | +| `enabled` | Boolean — allow or mute this topic/channel for the user | |
| 65 | +| `digest` | Batching cadence for the topic | |
| 66 | +| `quiet_hours` | JSON window during which delivery is suppressed | |
| 67 | +| `created_at` / `updated_at` | Audit timestamps | |
| 68 | + |
| 69 | +> Entries appear automatically when their source action first runs (for |
| 70 | +> example *Submit for Approval*, *Share*, or *Invite*) — you rarely create |
| 71 | +> preference rows by hand. Use the list to adjust admin defaults or mute a |
| 72 | +> noisy topic. |
| 73 | +
|
| 74 | +## Notification Subscriptions |
| 75 | + |
| 76 | +At **Setup → Configuration → Notification Subscriptions** (`sys_notification_subscription`). |
| 77 | + |
| 78 | +A **standing subscription** of a principal (role, team, or user) to a |
| 79 | +notification topic. Subscriptions answer *who is interested* in a topic before |
| 80 | +per-user preferences filter delivery. |
| 81 | + |
| 82 | +| Field | Purpose | |
| 83 | +|---|---| |
| 84 | +| `topic` | The topic being subscribed to | |
| 85 | +| `principal` | Role, team, or user that receives the topic | |
| 86 | +| `enabled` | Boolean — activate or pause the subscription | |
| 87 | + |
| 88 | +## Notification Templates |
| 89 | + |
| 90 | +At **Setup → Configuration → Notification Templates** (`sys_notification_template`). |
| 91 | + |
| 92 | +A per **(topic × channel × locale)** render template. Templates turn an event |
| 93 | +payload into the subject and body a recipient reads, in their locale and for |
| 94 | +their channel. |
| 95 | + |
| 96 | +| Field | Purpose | |
| 97 | +|---|---| |
| 98 | +| `topic` | Topic this template renders | |
| 99 | +| `channel` | Channel the rendered output targets | |
| 100 | +| `locale` | Locale of this rendering (matched to the recipient) | |
| 101 | +| `version` | Template version number | |
| 102 | +| `subject` | Rendered title | |
| 103 | +| `body` | Message body (markdown) | |
| 104 | +| `format` | Output format for the body | |
| 105 | +| `is_active` | Boolean — whether this template is used for rendering | |
| 106 | + |
| 107 | +These objects are **system-managed**: rows are seeded by the platform and the |
| 108 | +capabilities you run, so most of your work is editing template content or |
| 109 | +toggling `is_active`, `enabled`, and preference defaults rather than creating |
| 110 | +records from scratch. |
| 111 | + |
| 112 | +## Where to go next |
| 113 | + |
| 114 | +| Task | Page | |
| 115 | +|---|---| |
| 116 | +| Configure the email channel used for delivery | [Email](/docs/configure/email) | |
| 117 | +| Diagnose events with the ingress log and audit trail | [Audit Logs](/docs/operate/audit-logs) | |
| 118 | +| See the recipient's inbox experience | [Notifications](/docs/use/notifications) | |
| 119 | +| Set locale defaults that templates match against | [Localization](/docs/configure/localization) | |
| 120 | +| Return to the administration overview | [Configure](/docs/configure) | |
0 commit comments