What are centralised notifications?

Development of centralised notifications

In Totara 14 we introduced a new system for generating notifications. We changed the way in which developers write notification functionality into features, and how users configure and interact with notifications. In our documentation we refer to this feature as 'centralised notifications'. Historically, developers were required to make many decisions about how notifications would operate, which resulted in an inconsistent experience for users when it came to configuring and interacting with notifications. The centralised notifications system provides a consistent way for developers to implement notifications, and for users to use them.

The initial release of centralised notifications included the migration of program and certification notifications to the new system. In subsequent releases, more features' notifications have been added to centralised notifications, while others are still managed outside of the centralised notifications system and are now referred to as 'legacy notifications'. As Totara advances, we will continue to migrate existing notifications and add new notifications to the centralised notification system. For example, Totara 16 saw the introduction of course notifications, which are managed via centralised notifications.

Centralised notifications explained

'Centralised notifications' is the term used for the new notification system. Developers add functionality to features, allowing users to configure notifications to be sent in relation to events that occur. There are two different types of events for which you can configure notifications:

• Events can be actions that a user performs, such as when a user completes a course
• Events can be represented by dates recorded in the database, such as a program due date

Developers must implement a notification trigger for each type of event that needs to result in a notification. For example, a developer can implement a notification trigger based on the course due date. Users can then configure any number of notifications for each notification trigger. For example, a course administrator could create a 'Due in seven days' notification as well as a 'Two days overdue' notification, both based on the same notification trigger.

When an event occurs, the centralised notification system checks to see if any notifications are configured to be sent. There are several steps involved in deciding which notifications will be sent, who will receive them, what the content will be, and how they will be delivered.

Benefits of centralised notifications

The centralised notifications system provides a standard way for developers and end users to interact with notifications. Here we have outlined a number of the key benefits of using centralised notifications:

• Notifications for a range of different features share a common interface. In the past, different features provided different interfaces for configuring notifications, with different functionality and configurability.
• Notifications can be reused across more than one instance (e.g. the same notification in more than one course). In the past, different features implemented different ways of sharing between instances, such as using templates.
• Users have a single way to configure all of their notification preferences in the centralised notifications system. In the past, some notifications could be configured in user preferences, while others were hard-coded to be delivered by email, or had some other means of configuration.
• The behaviour for how notifications are sent is consistent. In the past, different systems were used to determine which notifications were sent, and when. There were various ways of dealing with notifications that should have been sent in the past, such as when a new notification was created to be sent when an event occurred, when that event had already occurred for some users.
• When setting up notifications, users have a consistent way to select who each notification will be sent to. In the past, if a notification needed to be sent to a user's manager, a developer needed to implement the code to make that happen, and custom interface elements to allow users to control when it would be used.
• A shared scheduling system, which allows almost any notification to be scheduled, with minimal work required by the developer. In the past, developers had to implement custom solutions to add scheduling, including the interface allowing users to configure the schedules.
• A unified placeholder system, which allows the reuse of placeholders between different notification triggers, and a common syntax for users to use placeholders in their notification content. In the past, developers had to implement a custom solution in each feature where placeholders were required, and users had to learn the correct placeholder syntax for that specific feature.
• Consistent implementation of multi-language functionality. In the past, developers had to implement the use of multi-language functionality in each feature using notifications.
• A new, single source for auditing all notifications, and all output types. In the past, users had to rely on logs made specifically for a feature, where available, or try to use the internal alerts and tasks notification data as a source for reporting.
• A core system for developers to implement notification triggers in a consistent, easy way. Much of the work of developing notification triggers has been done for the developer. In the past, developers often had to implement their own solutions to problems such as scheduling and placeholders, but these are all taken care of in centralised notifications.

How centralised notifications are processed

Notification events based on actions and those based on recorded dates are processed in slightly different ways:

• If the event was an action that a user performed, then the event is recorded in a notification events queue. The Process event-triggered notifications task (\totara_notification\task\process_event_queue_task) is configured by default to run in the background every minute, and looks at all events recorded in the queue and checks to see if any corresponding notifications exist which are configured to be sent On event. Decreasing the frequency of this scheduled task results in users waiting longer before they receive these notifications and has no performance benefit, so it should therefore be left to run every minute.
• Notifications that are scheduled to be sent Before or After recorded dates, or are scheduled to be sent On event and are based on recorded dates, are processed by the Process date-triggered notifications task (\totara_notification\task\process_scheduled_event_task), which is configured by default to run in the background once per day. This process finds all notifications which were scheduled to be sent since the last time the task ran. While it is possible to run this task more frequently, consider the performance impact of this decision, as this task must evaluate a lot of data to determine if any recorded dates match the schedules configured in the notifications.

Once a notification event is found, the following process occurs:

1. If the notification trigger is disabled then the notification is discarded (this may actually occur earlier, but isn't relevant from the user's point of view).
2. If the notification is disabled then it is discarded.
3. The notification trigger can implement additional conditions that must be met before the notification is sent. The event data is evaluated, and the notification will be discarded if it does not meet these criteria.
4. The list of recipients is calculated, based on the event data.
5. The notification content is generated for each user. Placeholders in the subject and body are replaced with values calculated using the event data.
6. Each recipient's enabled outputs are calculated.
7. The notification content is sent via each output for each user.

Special note about when notifications are sent

In the past, different notifications were implemented in different ways. One significant issue was how the system knew whether a notification had been sent, thus helping to determine whether a notification needed to be sent. In many cases, if a new notification was set up by an administrator, the system would determine that the notification had not been sent to a number of users who already met the criteria for receiving that notification, and would then send that notification to those users. In most cases, this was not the intended outcome. In the centralised notifications system, notifications are only sent when they are due to be sent. Notifications are not put in a queue waiting to be delivered at some later point in time. The system does not check for notifications that were missed or should have been sent previously. The system relies on timing to determine what needs to be sent at any given time. It asks 'What notifications should have been sent between now and the last time that notifications were sent?', and only these notifications are sent.

An example will help to explain this. Say you created a notification to welcome new users when they are enrolled on a course. If the notification is scheduled to send On event (i.e. as soon as the user is enrolled), then it will only be sent to users who enrol after you create the notification. The notification will not be sent retroactively for users who enrolled prior to you creating the notification. If you set the same notification to send 1 month after enrolment, then each day the system will check for users with an enrolment date of one month ago, and will send to those users, even if the notification did not exist at the time they enrolled. In this case, all user who enrolled within the last month, and those that enrol in the future, will eventually receive the notification, on the appropriate date. Those who enrolled more than one month ago will never receive it, because they were due to receive the notification before it was created.

Notification inheritance

Notifications in the centralised notification system are inherited from higher contexts to lower contexts. The functionality provided by inheritance is similar to the idea of templates, as notifications can be created and managed in one place, and are then reused in many other places.

Notifications can be created in various contexts, such as within courses, programs, seminars, or in the system context (also referred to as the 'site level'). Notifications can be configured in contexts higher than the context where the event occurs, and inherited to lower context levels. For example, course completion events occur in a course context, but Course completed notifications can be created in the system context, as well as within individual courses. The notifications in any context are determined by those created in that context as well as those inherited from higher contexts. Notifications in higher contexts are inherited in all descendent contexts where the event occurs.

Notifications inherited from higher contexts can have various properties overridden in a lower context. For example, a Learner assigned in program notification could be created in the system context, with generic subject and body content suitable for most programs. Then in a specific program the subject and body could be customised to be more suitable for that program, or the notification could be disabled in that program entirely.

For example, you might want all courses on your site to send a course welcome message when a user is first enrolled. This message should have the same content in all courses, except for the name of the course and the name of the user. In the site-level notifications interface, the Site Administrator can set up a notification and include the Course full name and User first name placeholders in the subject and/or body (1). This notification will be inherited in all courses, meaning all new and existing courses will have this new notification set up automatically (2). In one particular course, the course administrator might decide that the notification body needs to be changed to provide additional information for new users. They can change the notification at this specific context level by editing the inherited notification within the course's notifications interface, enabling the Override toggle for the body, and making the necessary changes (3). In another course, the course admin might decide to disable the inherited notification and create a new custom notification based on the same notification trigger (4). 

Legacy notifications

Currently a number of different features use legacy notifications, which work differently to the centralised notifications system. If the functionality you're using isn't covered by centralised notifications, check the documentation for that feature. We will continue to add new notifications and migrate existing notifications to the centralised notifications system.