Notification triggers¶
Applies to: Owner, Administrator, Manager, support staff, developers. Last reviewed: 2026-11-18.
This page lists every place in the code that sends a message, traced from the business event to the provider call. Each row was checked against the handler or service named in it.
The list was built by searching the Application, Infrastructure and Api projects for every call to the notification dispatcher (INotificationDispatcher.SendAsync), the email service (IEmailService.SendAsync), the legacy INotificationService, and the SMS, WhatsApp and push services.
Looking for the short version?
Notifications at a glance groups the same messages into immediate, scheduled, payment-triggered and configuration-dependent tables, without the code detail.
How to read the matrix¶
Each row has a number (A1, A2, ... for engine messages; B1, B2, ... for direct emails) so you can refer to it.
- Engine in the Channels column means the message goes through
NotificationDispatcher: Email if on, plus SMS and WhatsApp if the school switched them on and ticked them for that message, plus Push if the plan includes the Mobile App. - Email only means a service calls the email service directly. SMS, WhatsApp and push are never used, whatever the settings say.
- Standard gating means: the school has notification settings and they are active; the message's Enabled switch is on; the channel's master switch and per-message tick are on; SMS/WhatsApp need the plan feature (and credits or a paid add-on); push needs the Mobile App plan feature and Firebase configured.
- Standard failure means: the error is caught, a Failed row with the error text is written to the Notification Log, the business action still succeeds, nothing is retried.
- "Urgent" events are still sent during quiet hours; "non-urgent" ones are not.
Matrix A - messages sent through the notification engine¶
| # | Event | Recipient | Channel(s) | Triggering code | Timing | Template | Required configuration / gating | Failure and retry behaviour |
|---|---|---|---|---|---|---|---|---|
| A1 | Student registered | Student | Engine | RegisterStudentHandler raises StudentWelcome |
Immediate, after the student and first invoice are saved | "Welcome to <school>" |
Standard gating. Non-urgent: skipped (not delayed) during quiet hours. | Standard failure. Registration never fails because of it. |
| A2 | Lesson booked by staff | Student | Engine | BookLessonHandler raises LessonBooked |
Immediate. One message per date; a double lesson gives one message. | "Driving Lesson Confirmed" | Standard gating. Urgent. | Standard failure. |
| A3 | Lesson booked by staff | Instructor | Engine | BookLessonHandler raises InstructorLessonAssigned |
Immediate, one per date | "New Lesson Assigned" | Standard gating. Urgent. Web settings give this message an on/off switch only. | Standard failure. |
| A4 | Student's lesson request approved | Student | Engine | ApproveBookingCommandHandler raises LessonBooked |
Immediate | "Driving Lesson Confirmed", with "Note from your school" when a note was typed or the lesson is an extra lesson | Standard gating. Urgent. | Standard failure. |
| A5 | Student's lesson request approved | Instructor | Engine | ApproveBookingCommandHandler raises InstructorLessonAssigned |
Immediate | "New Lesson Assigned" | Standard gating. Urgent. | Standard failure. |
| A6 | Student's change request approved (lesson moved) | Student | Engine | ApproveBookingCommandHandler.ApproveChangeAsync raises LessonRescheduled |
Immediate | "Driving Lesson Rescheduled" | Standard gating. Urgent. | Standard failure. |
| A7 | Student's change request approved | Instructor | Engine | Same method raises InstructorLessonRescheduled |
Immediate | "Lesson Rescheduled" | Standard gating. Urgent. | Standard failure. |
| A8 | Student's lesson or change request declined | Student | Engine | RejectBookingCommandHandler raises LessonRequestDeclined |
Immediate | "Lesson Request Declined", with the reason typed by staff | Standard gating. Urgent. | Standard failure. |
| A9 | Lesson rescheduled by staff | Student | Engine | RescheduleLessonCommandHandler raises LessonRescheduled |
Immediate. Moving a whole double lesson gives one message. | "Driving Lesson Rescheduled" | Standard gating. Urgent. | Standard failure. |
| A10 | Lesson rescheduled by staff | Instructor | Engine | RescheduleLessonCommandHandler raises InstructorLessonRescheduled |
Immediate | "Lesson Rescheduled" | Standard gating. Urgent. Sent to the instructor the lesson belonged to before the move. | Standard failure. |
| A11 | Lesson cancelled | Student | Engine | CancelLessonHandler raises LessonCancelled |
Immediate. One message per day when a block or series is cancelled. | "Driving Lesson Cancelled", with the reason | Standard gating. Urgent. | Standard failure. |
| A12 | Lesson cancelled | Instructor | Engine | CancelLessonHandler raises InstructorLessonCancelled |
Immediate, one per day | "Lesson Cancelled" | Standard gating. Urgent. | Standard failure. |
| A13 | Lesson completed (student signs off after the instructor) | Student | Engine: Email and Push only | StudentSignOffLessonCommand handler raises LessonCompleted |
Immediate | "Driving Lesson Completed" with lessons completed and remaining | Not in the settings list. Sent whenever the Email master switch is on; never by SMS or WhatsApp; cannot be switched off separately. Urgent. | Standard failure. |
| A14 | Lesson reminder | Student | Engine | LessonReminderJob (Hangfire lesson-reminders) raises LessonReminder |
Scheduled: checked every 15 minutes, sent once the lesson is within "send before" (default 24 hours) | "Driving Lesson Reminder" | Standard gating. Held during quiet hours and sent at the first run afterwards. Lesson status must be Scheduled. | Marked as reminded even when delivery failed; not retried. See Lesson reminders. |
| A15 | Driving test reminder | Student | Engine | DrivingTestReminderJob (Hangfire driving-test-reminders) raises DrivingTestReminder |
Scheduled: every 15 minutes, default 24 hours before | "Driving Test Reminder" | Standard gating. Held during quiet hours. Test status must be Booked. | As lesson reminder. |
| A16 | Payment recorded by staff | Student | Engine | RecordPaymentCommand handler raises PaymentReceived |
Immediate | "Payment Received", receipt PDF attached to the email | Standard gating. Urgent. Nothing is sent for a walk-in payment (no student to address). | Standard failure. If the receipt PDF cannot be built the email goes without it. |
| A17 | Online payment confirmed by PayFast | Student | Engine | PaymentProcessingService.FinalizeSuccessfulTransactionAsync raises PaymentReceived |
Immediate, when the gateway confirms | "Payment Received" with receipt PDF | Standard gating. Urgent. | Standard failure. |
| A18 | Payment reminder (text part) | Student | Engine: SMS, WhatsApp and Push only | InvoiceReminderService.SendTextRemindersAsync raises PaymentReminder with Email skipped |
Directly after the reminder email below succeeded | "Payment Reminder" with amount, invoice number, due date and pay-online link | Standard gating for SMS/WhatsApp/Push. Only for invoices that belong to a student. Non-urgent: skipped during quiet hours. | Standard failure. |
Matrix B - emails sent directly (not through the engine)¶
| # | Event | Recipient | Channel(s) | Triggering code | Timing | Template | Required configuration / gating | Failure and retry behaviour |
|---|---|---|---|---|---|---|---|---|
| B1 | First invoice at student registration | Student | Email only | RegisterStudentHandler calls InvoiceEmailService.TrySendAsync |
Immediate | "Invoice <number>" with PDF |
Notifications active, Email master on, Invoice Issued enabled with Email ticked. Quiet hours do not apply. | Logged as Failed; warning in server log; registration succeeds. No retry. |
| B2 | Extra lesson (top-up) invoiced | Student | Email only | LessonTopUpService calls TrySendAsync |
Immediate | "Invoice <number>" with PDF |
As above | As above |
| B3 | Student assessment invoiced | Student | Email only | StudentAssessmentFeatures calls TrySendAsync |
Immediate | "Invoice <number>" with PDF |
As above | As above |
| B4 | Quote converted to an invoice | Student or customer on the invoice | Email only | QuoteService (convert) calls TrySendAsync |
Immediate | "Invoice <number>" with PDF |
As above | As above. The result tells the user whether the invoice was emailed. |
| B5 | Send Email on an invoice | Student or walk-in customer | Email only | InvoicesController POST {id}/send calls InvoiceEmailService.SendAsync |
Immediate | "Invoice <number>" with PDF |
Permission Invoices.View; plan feature Payments. Ignores notification settings. Not for cancelled invoices. |
User sees "The invoice email could not be sent: ...". Logged as Failed. |
| B6 | Automatic payment reminder (due soon / overdue) | Student or walk-in customer on the invoice | Email only (text part in Matrix A) | InvoiceReminderJob (Hangfire invoice-reminders) calls InvoiceReminderService.ProcessDueRemindersAsync |
Scheduled daily | "Payment due soon: invoice <n> from <school>" or "Payment reminder: invoice <n> is overdue", invoice PDF attached |
Notifications active, Email master on, Payment Reminder enabled with Email ticked, invoice has an email address, rules under Settings > Payments. | Logged as Failed; the counters are not advanced, so the job tries again on the next daily run. |
| B7 | Send Reminder on an invoice | Student or walk-in customer | Email only (plus text part) | InvoicesController POST {id}/remind calls InvoiceReminderService.SendNowAsync |
Immediate | Same as automatic | Permission Invoices.View. Invoice must be unpaid with a balance. Ignores notification settings for the email. Counts towards the reminder total. |
User sees "The reminder could not be sent: ...". |
| B8 | Email Receipt on a payment | Student, or the customer email on the invoice | Email only | PaymentsController POST {id}/send-receipt calls PaymentReceiptEmailService.SendAsync |
Immediate | "Payment receipt: <receipt number>" with PDF |
Permission Payments.View or Payments.Create. Payment must be Successful. Ignores notification settings. |
User sees "The receipt email could not be sent: ...". Logged as Failed. |
| B9 | Quote emailed | Student or customer on the quote | Email only | QuotesController POST {id}/send calls QuoteService.SendAsync |
Immediate | "Quote <number> from <school>" with PDF |
Permission Quotes.Edit; plan feature Quotes. Not for rejected quotes. Ignores notification settings. |
User sees "The quote email could not be sent: ...". Logged as Failed. A draft stays a draft. |
| B10 | Staff user created | The new user | Email only | UserService.SendAccountEmailAsync (welcome) |
Immediate | "Welcome to <school>" with username and temporary password |
None. Ignores notification settings. | Error written to the server log only ("Unable to send the account password e-mail to ..."). Not in the Notification Log. The user is still created. |
| B11 | Administrator resets a user's password | That user | Email only | UserService.SendAccountEmailAsync (reset) |
Immediate | "Your new <school> password" |
None | As above |
| B12 | Invite to portal / Resend invite | Student | Email only | StudentPortalAccessService.InviteAsync |
Immediate | "Your <school> student portal" with username, temporary password and a button |
Plan feature Student Portal. Student must have an email address. | User sees "The portal sign-in was created, but the invite email could not be sent. Try Resend invite." Not in the Notification Log. |
| B13 | Forgot password | The user | Email only | PasswordRecoveryService.RequestResetAsync (POST api/auth/forgot-password) |
Immediate | "Reset your <school> password" with a one-time link valid 60 minutes |
Platform:AppUrl must be set. At most 3 emails per address per 15 minutes. Inactive or unknown accounts get nothing. |
Server log only. The person is told the same thing whether or not an email went. Not in the Notification Log. |
| B14 | School registers | The school's email and the owner's sign-in email | Email only | RegistrationEmailService.SendAsync, called from AuthService and OrganisationRegistrationService |
Immediate | "Welcome to DriveFlow" | Sent from the platform mail server. No school setting applies. | Logged as Failed in the new school's log; registration succeeds. |
| B15 | School registers | Platform admin (Platform:AdminEmail) |
Email only | Same service | Immediate | "New DriveFlow registration: <school>" |
Skipped if Platform:AdminEmail is empty |
As above |
| B16 | Subscription, add-on or SMS bundle payment confirmed | The school's organisation email | Email only | SubscriptionPaymentProcessor calls SubscriptionInvoiceEmailService.TrySendAsync |
Immediate, when PayFast confirms | "Your DriveFlow invoice <n> (paid)" with PDF |
School must have an organisation email. No school setting applies. | Warning in server log; Failed row in the school's log; the payment stays applied. |
| B17 | SuperAdmin billing action that raises a subscription invoice | The school's organisation email | Email only | SchoolSubscriptionAdminService (five call sites) calls TrySendAsync |
Immediate | "Your DriveFlow invoice <n>" |
As above | As above |
| B18 | Subscription invoice sent from Settings > Billing | The school's organisation email | Email only | BillingController POST invoices/{id}/send |
Immediate | "Your DriveFlow invoice <n>" |
Permission Subscription.Manage |
User sees "The invoice email could not be sent: ..." or "Your organisation has no email address. Add one under Settings > Organisation and try again." |
| B19 | Send Test Email | Address typed by the user | Email only | EmailSettingsService.SendTestEmailAsync |
Immediate | "DriveFlow Test Email" | Permission Email.Manage |
User sees "The test email could not be sent: ...". Not in the Notification Log. |
| B20 | Document expiring within 30 days | Intended: the person who uploaded it | Email only | DocumentExpiryJob (Hangfire document-expiry-reminders) calls ReminderService then NotificationService.SendEmailAsync |
Scheduled daily | "Document Expiry Reminder" | None | Does not work as intended; see Lesson reminders section 5. |
Row B20 does not work
Document expiry reminders do not reach anyone in the current version. Staff should check document expiry dates themselves.
Events that do NOT send any message¶
These were looked for and no sending code exists.
Do not promise these to a school
None of the notifications in the table below exist. Where the table says "Header bell only", staff see the item in the web header bell but no message is sent.
| Expected notification | What actually happens |
|---|---|
| Student marked as no-show | Nothing is sent |
| Instructor signs off a lesson (waiting for the student) | Nothing is sent; the student sees it in the portal or app |
| A student submits a lesson request or change request | No message to staff; it appears in the header bell as "Lesson request" |
| Lesson deleted | Nothing is sent |
| Instructor changed without a time change | Covered only if done through the reschedule action; the new instructor is not told (the message goes to the previous one) |
| Daily schedule for instructors | The setting "Daily Instructor Schedule" exists, but no code sends it |
| Driving test booked, changed, cancelled, passed or failed | Nothing is sent; only the reminder exists |
| Learner's test events | Nothing is sent |
| Lead created, lead follow-up due | Header bell only |
| Trial ending, subscription about to expire, subscription expired, add-on about to lapse, SMS credits low | Nothing is sent. SubscriptionExpiryJob only changes the status. The web app shows banners. |
| Subscription payment failed | Nothing is sent |
| Vehicle licence disc, roadworthy, insurance, service due | Header bell only |
| Fleet alerts | Header bell only |
| Instructor earnings, sales commission, salesperson payout | Nothing is sent |
| Payment refunded or deleted, invoice voided | Nothing is sent |
| Message to a guardian or emergency contact | Never |
| Instructor review submitted | Nothing is sent |
Flow examples¶
Staff book a lesson¶
flowchart TD
A["Staff click Save on a new lesson"] --> B["BookLessonHandler saves the lesson(s)"]
B --> C["LessonBooked<br/>student: email (+ SMS / WhatsApp / push if enabled)"]
B --> D["InstructorLessonAssigned<br/>instructor: email (+ push if they use the app)"]
B --> E["Lesson scheduled successfully."]
E -. "later: default 24 hours before the start" .-> F["LessonReminderJob<br/>LessonReminder to the student"]
An invoice goes overdue¶
flowchart TD
A["Invoice created<br/>(email sent if Invoice Issued is on)"] --> B["3 days before due date, 08:00 run<br/>Payment due soon email (+ SMS / WhatsApp / push)"]
B --> C["Due date passes; after the grace period<br/>the invoice is marked Overdue"]
C --> D["1 day after due date<br/>overdue reminder 1"]
D --> E["every 7 days<br/>reminders 2 and 3 (maximum 3 by default)"]
A -. "paid or cancelled at any point" .-> X["Reminders stop"]
B -.-> X
C -.-> X
D -.-> X
Notes on message content¶
Some handlers pass less information than the template can show. As a result:
- Booking, reschedule and cancellation messages show the lesson number, date, time and pickup location, but not the instructor's name, vehicle or branch. Only the lesson reminder includes those.
- Instructor messages do not show the student's name.
- "Previous time" is never filled in on reschedule messages.
- The school's note on an approved change request is not shown in the "Driving Lesson Rescheduled" message.