Skip to content

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.

See Notification templates.