CMS Notifications Documentation

Overview

The CMS Notifications interface is how backend code puts a message in a user's notification list. It has two halves: a taxonomy you declare once, and a builder you use every time you send.

The taxonomy is two levels deep. A category groups related notifications, a subject sits under a category and names one kind of message, and every notification is filed under a subject. Users manage what they receive per subject from their notification settings, so the subject you pick decides how the message is grouped for the user and whether it is delivered at all.

Both levels are declared at import time: NotificationCategory() first, then the NotificationSubject() calls that sit under it. Sending is a fluent chain: Notification() opens a builder, the setters fill in the icon, title, description and subject, and .build() returns an immutable SendableNotification you dispatch to one user, a list of users, the holders of a set of roles, or everyone.

Key Features

• Two-level taxonomy — Categories group subjects, and subjects classify notifications; the categoryId:subjectId pair is the key a user's preferences are stored under.
• Declarative registration — NotificationCategory() and NotificationSubject() register at import time and return plain info objects you keep as constants and pass around.
• Built-in system subjects — GeneralSubject, SecuritySubject, AccountSubject, CollaborationSubject and AutomationSubject cover the common platform messages without declaring anything.
• Type-checked builder — The builder tracks which fields have been supplied in its type parameter, so .build() does not compile until icon, title, description and subject are all set.
• Four dispatch targets — Send to one user, a list of users, every user holding at least one of a set of roles, or every user.
• Shared or individual read state — A multi-recipient send can give each recipient their own read state, or group the copies so one recipient reading it clears it for all of them.
• Preference-aware delivery — Sends are silently skipped for users who turned the subject off, and togglePermission marks the subjects users may not turn off.

Dependencies

This interface relies on the following AntelopeJS packages:

• @antelopejs/interface-core - Interface function and registration proxies used to reach the CMS implementation.

The implementation lives in the CMS module, so the interface only works in a project that loads @antelopejs-private/cms. Sending to users and roles uses the CMS user and role identifiers described in the DMS auth and tenancy guide.

Quick Start

The following example declares a category with one subject and sends a notification against it.

import {
  Notification,
  NotificationCategory,
  NotificationSubject,
} from "@antelopejs-private/cms/interfaces/cms-notifications";

// Declared at import time — the category first, then its subjects
export const shopCategory = NotificationCategory("shop", {
  labelKey: "shop.notifications.categories.shop",
  descriptionKey: "shop.notifications.categories.shop_desc",
  icon: "i-ph-shopping-cart",
});

export const orderSubject = NotificationSubject("orders", {
  category: shopCategory,
  labelKey: "shop.notifications.subjects.orders",
  togglePermission: "default",
});

export async function notifyOrderShipped(
  userId: string,
  orderRef: string,
): Promise<void> {
  await Notification()
    .icon("i-ph-truck")
    .title("$shop.notifications.order_shipped.title")
    .description("$shop.notifications.order_shipped.description")
    .params({ orderRef })
    .subject(orderSubject)
    .linkTo("/shop/orders")
    .build()
    .toUser(userId);
}

The user sees the notification in the dashboard, and finds an orders toggle under a shop group in their notification settings.

Documentation Sections

• Categories and Subjects - Declare categories and subjects, control what users may toggle, and use the built-in system subjects
• Sending Notifications - Build a notification, dispatch it to users, roles or everyone, and understand what gates delivery