Lesson reminders and other scheduled notifications¶
Applies to: Owner, Administrator, Manager (anyone with Notifications.View / Notifications.Manage, and Settings.Manage for payment rules); developers and server administrators. Last reviewed: 2026-11-18.
This page explains exactly when scheduled messages are sent, what runs them, and how duplicates, cancellations and reschedules are handled. It covers lesson reminders, driving test reminders, payment reminders, document expiry reminders and the reminders the mobile app sets on the phone.
1. What runs the schedule¶
All scheduled work is done by Hangfire recurring jobs. The Hangfire server runs inside the API process (AddHangfireServer() in DriveFlow.Api/Program.cs) and stores its state in the main SQL Server database. Jobs are registered at API start-up in DriveFlow.Infrastructure/Hangfire/HangfireJobRegistration.cs. There are no hosted services or timers for notifications.
| Job id | Schedule (cron) | Class | Sends messages? |
|---|---|---|---|
lesson-reminders |
Every 15 minutes (*/15 * * * *) |
LessonReminderJob |
Yes - lesson reminders |
driving-test-reminders |
Every 15 minutes | DrivingTestReminderJob |
Yes - driving test reminders |
invoice-reminders |
Daily at 08:00 | InvoiceReminderJob |
Yes - payment reminders; also marks invoices overdue |
document-expiry-reminders |
Daily at 07:00 | DocumentExpiryJob |
Intended to; see section 5 |
subscription-expiry |
Hourly | SubscriptionExpiryJob |
No. Only sets ended trials and subscriptions to Expired. |
meta-lead-requeue |
Every 15 minutes | MetaLeadImportJob |
No (lead import) |
report-generation |
Daily at 23:00 | ReportGenerationJob |
No |
Time zone of the daily jobs
The registration does not pass a time zone, and Hangfire's default for recurring jobs is UTC. The 08:00 and 07:00 runs are therefore 08:00 and 07:00 UTC (10:00 and 09:00 South African time) unless the deployment changes this. The Payment Settings page says "Reminders are sent daily at 08:00".
If registering the jobs fails at start-up the API logs "Failed to register Hangfire recurring jobs at startup. The API will continue to run." and carries on; the schedule then stays as it was last stored.
2. Lesson reminders¶
When a reminder is sent¶
One reminder per lesson, sent once the lesson is within the school's send before time.
- Default: 1,440 minutes (24 hours) before the lesson start.
- Configurable per school (not per branch, not per student): Settings > Notifications > Reminders > "Lesson Reminder: send before", in minutes, from 15 minutes up to 31 days in steps of 15.
- The job runs every 15 minutes, so a reminder goes out up to 15 minutes after the exact moment.
- There is only one reminder per lesson from the server. There is no second "1 hour before" reminder (the mobile app adds its own; see section 6).
What the job does on each run¶
flowchart TD
A["Every 15 minutes: LessonReminderJob"] --> B["Find lessons where<br/>status is Scheduled, not deleted, student not deleted,<br/>start is in the future and within the next 31 days,<br/>and no reminder has been sent for the current start time"]
B --> C{"For each lesson, using its school's settings<br/>(ReminderSchedule.Decide)"}
C -- "notifications inactive or no settings" --> W["Wait"]
C -- "Lesson Reminder switched off" --> W
C -- "too early (now is before start - send before)" --> W
C -- "lesson was created inside the reminder window" --> K["Skip, mark as reminded"]
C -- "inside quiet hours" --> W
C -- "otherwise" --> S["Send"]
S --> D["Send through the notification engine as the lesson's school and branch,<br/>then store the start time in Lesson.ReminderSentFor"]
Rules in detail¶
| Question | Answer from the code |
|---|---|
| Which lessons qualify? | Status Scheduled only. Cancelled, completed, no-show and in-progress lessons are excluded because they are not Scheduled. A lesson with status Confirmed is also excluded. |
| How are cancelled lessons excluded? | The job reads the status at each run. A lesson cancelled before its reminder time is never picked up. A lesson cancelled after the reminder was sent gets the separate cancellation message. |
| How are duplicates prevented? | After a reminder the lesson's ReminderSentFor is set to its start time. The lesson is not selected again while ReminderSentFor equals the start time. |
| What happens on reschedule? | The start time changes, so ReminderSentFor no longer matches and the lesson qualifies for a new reminder for the new time. If the new time is already inside the reminder window, the reminder goes out at the next 15-minute run (the student also gets the reschedule message). |
| Lesson booked at short notice? | If the lesson was created after its reminder was due (for example booked 3 hours ahead with a 24-hour reminder), no reminder is sent; the booking confirmation covers it. |
| Double lessons? | Each lesson in a double lesson is a separate record, so each one gets its own reminder. |
| Quiet hours? | The reminder is held and sent at the first run after quiet hours end, as long as the lesson has not started. |
| Lesson Reminder switched off, then on again? | Reminders that became due while it was off are sent at the next run if the lesson is still in the future. |
| How far ahead does the job look? | 31 days. A "send before" longer than that is effectively capped. |
| "Send before" left empty or 0? | The default of 24 hours is used. |
| Who receives it? | The student only. Instructors do not get lesson reminders. |
| Which channels? | Email, plus SMS/WhatsApp if ticked for Lesson Reminder, plus push. |
Time zone¶
The job compares lesson start times with the server's local clock (DateTime.Now). The branch time zone (IBranchTimeProvider), which other parts of DriveFlow use, is not used here, nor for quiet hours.
Important
If the server's time zone differs from the branch's, reminders and quiet hours shift by the difference. Run the API server in the schools' time zone.
Failure behaviour¶
- The notification engine never throws, so the job marks the lesson as reminded whether or not delivery succeeded. A failed reminder is not tried again. The failure is in the Notification Log.
- The same applies when the engine skips the message (for example every channel is off): the lesson is still marked as reminded.
- If the whole job fails (for example the database is unreachable), Hangfire's own automatic retry applies to that job run, and the next 15-minute run starts fresh.
- At the end of a run with work done the log shows "Lesson Reminder Job completed. N reminders sent, M booked inside the reminder window."
Example¶
A school keeps the default 24 hours and has quiet hours 21:00 to 07:00. Thabo has a lesson on Thursday at 06:30.
- The reminder becomes due on Wednesday at 06:30, which is inside quiet hours.
- It is therefore sent at the first run after 07:00 on Wednesday.
- If Thabo's lesson is then moved to Friday 10:00, a second reminder goes out on Thursday around 10:00.
3. Driving test reminders¶
Same mechanism as lesson reminders (DrivingTestReminderJob, same ReminderSchedule), with these differences:
| Item | Driving test |
|---|---|
| Which tests | Status Booked, not deleted, student not deleted, test date within 31 days |
| Start time | Test date plus test time |
| Setting | Settings > Notifications > Reminders > "Driving Test Reminder: send before", default 24 hours |
| Duplicate guard | DrivingTest.ReminderSentFor |
| Message | "Driving Test Reminder" with test number, date, time, testing centre and vehicle |
| Recipient | Student only |
A test whose date or time is changed gets a new reminder, as for lessons.
4. Invoice (payment) reminders¶
Run by InvoiceReminderJob, once a day. The rules are per school and are set under Settings > Payments (title Payment Settings); see Notification settings section 4.
What one daily run does¶
For every invoice, in every school, that has a due date, an outstanding balance, and status Pending, Partially Paid or Overdue:
- Mark overdue. If today is past the due date plus the grace period, the status becomes Overdue. This happens even when reminders are switched off.
- Check whether email reminders are allowed for the school: notifications active, Email master switch on, Payment Reminder enabled with Email ticked. If not, or the invoice has no email address, stop here.
-
Decide which reminder is due today:
Situation Reminder Not yet past due, "due soon" days greater than 0, within that many days of the due date, and no due-soon reminder sent yet Due soon (once per invoice) Past due, status Overdue, overdue reminders on, fewer than the maximum sent, none sent yet, and at least "First reminder" days past due Overdue reminder 1 As above, some already sent, "Repeat every" greater than 0, and that many days since the last one Next overdue reminder Anything else Nothing today -
Send the email with the invoice PDF attached, record it in the Notification Log, then update the invoice (
DueSoonReminderSentOn, orReminderCountandLastReminderSentOn). - Then raise the Payment Reminder event for SMS, WhatsApp and push (student invoices only).
Defaults¶
| Rule | Default |
|---|---|
| Grace period | 0 days (overdue the day after the due date) |
| Due-soon email | 3 days before |
| Overdue reminders | On |
| First overdue reminder | 1 day after the due date |
| Repeat every | 7 days |
| Maximum reminders | 3 |
Duplicates, failures, stopping¶
- Duplicates are prevented by the counters on the invoice, not by the clock: running the job twice on the same day sends nothing the second time.
- If the email fails, the counters are not updated, so the next daily run tries again. This is the only automatic "retry" in the notification system.
- Reminders stop as soon as the invoice is paid or cancelled, because it no longer matches the selection.
- The manual Send Reminder action on an invoice sends the same email immediately, ignores the notification switches, and counts towards the maximum.
- If the school has online payments set up and the plan includes payments, the reminder includes a link to the student portal's invoices page.
- The SMS/WhatsApp part is skipped when the run falls in the school's quiet hours; the email is not affected by quiet hours.
5. Document expiry reminders (not working)¶
DocumentExpiryJob runs daily and looks for documents with an expiry date in the next 30 days that have not been reminded. For each one it calls ReminderService.SendDocumentExpiryReminderAsync, which sends an email titled "Document Expiry Reminder" through the older NotificationService.
Document expiry reminders do not reach anyone
In the current code:
- The email is addressed to
Document.UploadedBy. That field is filled with the uploader's user id when a document is uploaded (UploadDocumentCommandHandler), not an email address, so the send fails. NotificationServicecatches the failure, so the job still marks the document as reminded (ExpiryReminderSentOn) and never tries again.- The log row is written without a company, so it does not appear in any school's Notification Log.
Treat document expiry reminders as not implemented. Staff should check expiry dates themselves. (Whether the user id could ever be an email address depends on how sign-in tokens are issued and was not confirmed.)
6. Reminders scheduled on the phone by the mobile app¶
The student mobile app also schedules local reminders on the device, independent of the server (DriveFlow.Mobile/Services/Student/LessonReminderService.cs):
| Reminder | When | Text |
|---|---|---|
| "Driving lesson tomorrow" | 18:00 on the day before the lesson | "Tomorrow at HH:mm with <instructor>. Pick-up: <location>." |
| "Driving lesson in an hour" | One hour before | "At HH:mm with <instructor>. Pick-up: <location>." |
- Scheduled for the next 10 upcoming, non-cancelled lessons each time the app loads the student's lessons, replacing the previous set.
- A cancelled or moved lesson is only corrected on the phone the next time the app loads the lessons.
- Cleared at sign-out. The student can turn them off for that phone in the app's Settings.
- These use the phone's own clock and need notification permission. They are not in the Notification Log.
See the mobile application documentation.
7. Looking at the jobs¶
The status of the recurring jobs is monitored by the DriveFlow platform team; schools do not have access to it.
Server log lines to search for:
| Text | Meaning |
|---|---|
| "Lesson Reminder Job completed." | A run sent or skipped at least one reminder |
| "Failed to send reminder for Lesson ..." | An unexpected error for one lesson |
| "Driving Test Reminder Job completed." | As above for tests |
| "Running Invoice Reminder Job at ..." / "Invoice Reminder Job completed. N reminders sent." | Daily invoice run |
| "Failed to process payment reminder for invoice ..." | An error for one invoice |
| "Running Document Expiry Job at ..." | Daily document run |