Understanding and testing scheduled notifications

How scheduled notifications work

When configuring a notification, you must configure the schedule, meaning when the notification will be sent. You will always be able to select the option On event, and depending on the type of trigger event you might also be able to select Before and/or After. Most On event notifications are processed in the notification system as soon as the event occurs, and will actually be sent out on the next cron run by the \totara_notification\task\process_event_queue_task scheduled task. Users should receive these within a minute or so of the event occurring, assuming cron runs every minute and the task is running on the default schedule (every minute). Some On event notifications, and all Before and After scheduled notifications are processed in a different way.

Scheduled notifications are processed by the \totara_notification\task\process_scheduled_event_task scheduled task. This task calculates the period since the last time it was run, applies the offsets of the scheduled notifications, and asks each notification to calculate all events that occurred during these offset periods.

The last date/time that the scheduled notifications were processed is recorded in the totara_notification/last_scheduled_event_task_run_time config_plugins variable. It is not calculated based on the scheduled task last run time that you see when configuring scheduled tasks, although it is likely that it is similar, as long as the task and setting are left to operate normally. Note that manually changing this time in the database would result in either duplicate notifications being sent (if it was moved backwards), or notifications never being sent (if moving forwards), so this should not be changed on a production site.

For example, let's take a notification that is scheduled to be sent three days before an event occurs, such as a due date. The scheduled task is configured to run once a day by default, at 11pm. When it runs at 11pm, for the given notification, the period it calculates will be 'last cron run + 3 days' to 'now + 3 days'. The notification resolver (the piece of code which defines how an individual notification works, what data is involved, etc.) will be asked to find all events that occur during this period. For a notification to be sent, the event date must lie within this period.

If the task is run more frequently, then the period it searches will be smaller, but over a whole day it will process a whole day's worth of events, and it won't ever process the same event twice. For example, if it was set to run every hour, then each hour it would find all the notifications scheduled to be sent within the previous one-hour period. Thus is it possible to modify the task schedule, but it comes at the cost of having to repeat the search for notifications to be sent occurring more frequently. Depending on the site, this could take a lot of processing, hence the default being set to run only once per day.

In the same scenario as above, say if it was set to run every minute, then at 3:45pm it would search for (and send notifications for) all events that occur between 3:44pm and 3:45pm in three days' time. To observe the notification going out, the due date would have to be exactly within that minute on that day. When testing, if you run the scheduled task manually, you need to be aware that only notifications that are scheduled to be sent precisely in the period since the task was last run will be sent. When setting up the event which should trigger a notification, the user often doesn't have control over the exact minute of the event, so it's unlikely that the event is due to be sent exactly within the calculated period. This is frequently the cause of confusion when trying to force scheduled notifications to be sent on a test server.

In Totara 16 and below, when the task runs, it takes all events that occur in the given period and adds them to the notification queue. When the \totara_notification\task\process_notification_queue_task next runs, which by default is every cron run, then it will pick up the queued notifications and send them immediately. In Totara 17 and above, when the task runs, it takes all events that occur in the given period and immediately processes them, sending the notifications immediately. The intermediate queuing that occurred in Totara 16 and below has been skipped.

Testing scheduled notifications

Testing scheduled notifications can be difficult, primarily due to the way that the scheduled task chooses the period of notification events to search for.

In the following instructions, when manipulating dates, you sometimes need to use Unix timestamps. Use Epoch Converter to convert between Unix timestamps and human-readable dates. Any time a 'date' or 'time' is mentioned, this means 'date and time' - we always work with a full date and time, and if you ignore the hours, minutes and seconds from any calculation then things won't work as expected. 'Current date' means 'now, with hours, minutes and seconds'.

We have used program due date as an example here, however the process described can be used for testing most scheduled notifications. Just adapt the steps where appropriate.

To test sending a scheduled notification, follow these steps:

1. Set up your notification with a Before schedule, for example '3 days before'. Note that the most reliable means of receiving notifications for testing is to send to the Site notification delivery channel, so that the notification should appear within the user's notifications popup on the site. You should also ensure the notification has some text in the subject which clearly identifies the test notification, e.g. 'Test notification for program due date triggered 3 days before'.
2. Set up the event data that should result in a notification being sent. In this case, we would set up a user in the program with an assignment due date set to three days after today.
3. Find the exact time of the event. Depending on the feature you're using, there might be a place where you can see exactly what this time is. For programs, you can use the program completion editor to find the user's exact due date. Otherwise, you might need to look up this date in the database.
4. Given the event date, apply the notification offset to the date. If your schedule is Before then you subtract the offset. For example, 3 days before means you subtract 3 * 24 * 60 * 60 seconds. If it is On event then don't change it. If it is After then add it. We will call this calculated date the 'notification send date'.
5. Check the totara_notification/last_scheduled_event_task_run_time value in the config_plugins table in the database. Do not change this value on a live site! We will call this date the 'last run time'.
6. Compare the last run time to the notification send date you calculated:
   1. If the notification send date is less than the last run time then the notification will not be sent, because the event date is too early.
   2. If the notification send date is more than the current date (right at this moment) then you'll need to wait until the send date is reached.
   3. If the notification send date is more than the last run time and before the current date then it is ready to be sent. Skip the next step.
7. If the notification send date is not between the last run time and the current date then the notification will not be sent until this situation changes. There are a few possible options here:
   1. If the send date is in the future then you could simply wait until that time is reached.
   2. If the send date is in the future then you could change the date of the event. In our example, you could set the program due date to be an earlier date using the program completion editor, or you might be able to change the event date in the database.
   3. If the send date is in the future then you could adjust the notification schedule. In our example, you could reduce it to '2 days before'.
   4. If the send date is before the last run time then you could change the date of the event. In our example, you could set the program due date to be later using the program completion editor, or you might be able to change the event date in the database.
   5. If the send date is before the last run time then you could adjust the notification schedule. In our example, you could increase it to '4 days before'.
   6. If the send date is before the last run time then you could adjust the totara_notification/last_scheduled_event_task_run_time value in the config_plugins table in the database so that it is before the notification send date.
      
      Do not do this on a production site.
8. Either wait for or run the \totara_notification\task\process_scheduled_event_task scheduled task. By default this is run once a day, but it can be safely run at any time, as long as it doesn't cause server overload if run on a production site. It is not advised to change the task's schedule to run every minute, because it might take more than one minute to process all the records, but it should be fine to run it one-off for testing.
9. If you're on Totara 16 or below then you also need to wait for or run the \totara_notification\task\process_notification_queue_task scheduled task. As with the previous task, you should not change the schedule to run every minute for general use.
10. The notification should have been sent. Either check outgoing logs or log in as the recipient to check that the notification was sent and received.

If you're still having trouble, make sure that you can successfully trigger and receive a different non-On event notification.