User notifications

The user notification framework in CMS 13 sends targeted messages between users through a channel-based system. Use it to notify editors about content changes, approval workflows, or custom events.

A sender posts a message on a named channel to one or more recipients. The system stores posted messages and dispatches them through a formatter and a provider. The formatter transforms message text and retrieves related content or user data as needed. Formatters also group messages to reduce the total delivered to each recipient. The provider delivers the formatted message through a specific method, such as email. Each channel supports multiple providers, and recipients choose their preferred provider.

Post a message to INotifier for immediate delivery or for the scheduled job queue. The NotificationDispatcher retrieves queued messages, formats them with a NotificationFormatter, and delivers them through a NotificationProvider. Create custom formatters and providers to extend delivery behavior.

Every message belongs to a channel, a namespace that groups messages of a certain kind and keeps them separate. Create a custom channel by defining a name and providing a supporting formatter. To enable immediate processing for a channel, add a NotificationChannelOptions instance to INotificationChannelOptionsRegistry. The scheduler processes messages periodically by default.

The sender does not control how the recipient receives the message. The recipient's provider preferences for that channel determine the delivery method.

Three message types control when the system processes a notification:

Identify notification recipients and senders through their INotificationUser identity, which carries a name and a display name. Retrieve a QueryableNotificationUserService instance to search for users. Call FindAsync to search by partial name or GetAsync to retrieve a specific user by name.

Provider preferences determine how each user receives notifications per channel. Register a default preference resolver for a channel and provider through INotificationPreferenceRegister. The resolver accepts a username and returns a provider-specific address, such as an email address for the email provider.

The INotifier interface queues messages for delivery to one or more recipients. Call PostNotificationAsync to post a message. A message with multiple recipients creates one internal message per recipient. Subscribe to the NotificationPosted, NotificationSaved, and NotificationFiltered events to track posting results per message.

The NotificationDispatcher retrieves queued messages and groups them by recipient and channel. For each group, the dispatcher locates a matching formatter and provider, then formats and delivers the messages. Failed messages return to the queue for retry.

The scheduler triggers the dispatcher, or the system calls it directly for immediate messages.

Formatters transform messages before delivery and control how the system prepares content for each provider. Each formatter has a name and a list of supported channel names. The dispatcher selects the formatter whose supported names match the message channel.

For implementation details, see the following section.

Create a custom formatter by implementing the INotificationFormatter interface. Assign it a name and a list of supported channels. The FormatMessagesAsync method accepts and returns a list of messages. In the simplest case, return the incoming messages unchanged.

The formatter combines multiple messages into one by setting ContainedID to match the IDs of the combined messages. The system treats any input message ID absent from the output as completed and removes it from the queue. If formatting fails, the formatter throws an exception. The system returns those messages to the queue for the next scheduled job.

Providers deliver notifications through a specific communication method, giving each channel flexibility in how it reaches users. The built-in EmailNotificationProvider handles email delivery. For configuration details, see Configure your email server. Each provider has a name and a format property. The format property specifies constraints such as maximum length and HTML support.

Implement INotificationProvider to build a custom provider. Optionally implement INotificationProviderStatus to enable or disable the provider at runtime. The SendAsync method handles delivery. Call succeededAction or failedAction for each message.

The IUserNotificationRepository interface retrieves notification data for display in the Optimizely UI. Call GetUserNotificationAsync, GetUserNotificationsAsync, or GetUserNotificationsCountAsync to retrieve notifications.

Implement IUserNotificationFormatter for one or more channels to return formatted messages. The formattingMode parameter on GetUserNotification(s)Async controls formatting behavior.

Subscribe to the UserNotificationMissing event to receive a callback when the system cannot locate a notification.

The IUserNotificationRepository interface also marks notifications as read. Call one of the MarkUserNotification(s)AsReadAsync methods to update read status. Subscribe to the UserNotificationRead and UserNotificationReads events to track read-status changes.

Old notifications accumulate in the database over time. The Notification Message Truncate scheduled job runs every night by default and removes notifications older than three months.

The notification system limits retry attempts for failed messages and marks them as undeliverable when retries are exhausted. This prevents failed messages from blocking the queue indefinitely.

The tblNotificationMessage table stores retry state in the following fields:

The dispatcher applies the following logic when processing messages:

When RetriesLeft reaches zero, the system marks the notification as undeliverable and stops retrying.

The retry delay increases with each failed attempt:

Notification providers must throw an exception when a send operation fails. The retry mechanism relies on the exception to take the following actions: