Student Registration¶
Applies to: Owner, Administrator, Manager, Receptionist (any role with the Students.Create permission). Last reviewed: 2026-11-18.
This page explains how to register a new student on the DriveFlow web application, what every field means, and exactly what the system creates when you click Register Student.
1. Before you start¶
You need the following in place before a student can be registered:
| Requirement | Why | Where to set it up |
|---|---|---|
| The Students.Create permission | The New Student button is only shown to users with this permission, and the API refuses the request without it. | Settings > Roles (see Roles and permissions) |
| At least one active branch | Every student belongs to one branch. Their student number and first invoice number use the branch code. | Settings > Organisation |
| At least one licence code switched on | The Licence Code list only shows codes your school offers. | Licence codes |
| At least one training package | A training package is compulsory. The package becomes the student's first course and first invoice. | Training packages |
| Room on your subscription plan | The API checks the plan's student limit before registering. If the limit is reached the registration is refused. | Subscription plans |
Default roles that can register students (as seeded; a school can change role permissions): Owner (who always has every permission), Administrator, Manager and Receptionist. Instructor, Finance and Viewer cannot.
2. Where to find it¶
- In the left menu, under OPERATIONS, click Students. The Student Directory page opens.
- In the table card, click New Student (top right of the "Students" heading).
- The Register Student page opens (
/students/new).
Screenshot to be added
Screen: Student Directory. Should show: the table toolbar with the "New Student" button highlighted.
A student can also be registered from a lead. When you register a lead, the same page opens with the lead's first name, last name, email, mobile number, alternative number and branch already filled in. See Leads for the lead side of this.
3. How the page is laid out¶
One page, not a wizard
The owner's notes describe this as a "wizard". In the current code it is one page, not a step-by-step wizard. All sections are on the same page as collapsible panels and there is a single save button at the bottom.
At the top there is a three-item progress strip (1 Student Details, 2 Training, 3 Guardian). It is decorative only: it does not change as you type and you cannot click it to move between steps.
The panels are:
| Panel | Marked as | Open by default |
|---|---|---|
| Personal Information - "Student's basic identification details" | Required | Yes |
| Contact Information - "Phone, email and address details" | Required | Yes |
| Training Information - "Select the student's course or package" | Required | Yes |
| Guardian Information - "Add a parent or guardian if applicable" | Optional | No (click the panel heading to open it) |
At the bottom of the page: the note "Fields marked as required must be completed before saving.", a Cancel button and the Register Student button. Back to Students at the top of the page does the same as Cancel.
Screenshot to be added
Screen: Register Student. Should show: the full page with all four panels and the "Register Student" button.
There is no review step. A component called StudentReviewStep exists in the code but is not used by any page (see Limitations and notes).
4. Step by step¶
Step 1 - Personal Information¶
| Field | Required | What it means | Rules |
|---|---|---|---|
| First Name | Yes | The student's first name. | Maximum 100 characters. |
| Middle Name | No | Middle name(s). | Maximum 100 characters. |
| Last Name | Yes | Surname. | Maximum 100 characters. |
| Identity Number | Yes | The student's ID number. | Must be exactly 13 characters. Must not already belong to another student of your school. |
| Gender | - | Male or Female. Starts on Male. | Must be one of the two options. |
| Date of Birth | Yes (in practice) | The student's date of birth. Starts on today's date, so you must change it. | Must be before today, and the student must be older than 16 (see below). |
| Physical Address | No | The student's address, as free text (three lines). | Saved as the first address line. |
| Has Learners Licence | No | Tick if the student already holds a learner's licence. | Unlocks the next two fields. |
| Learners Licence Number | No | The learner's licence number. | Disabled unless Has Learners Licence is ticked. |
| Learners Licence Expiry | No | Expiry date of the learner's licence. | Disabled unless Has Learners Licence is ticked. Affects the starting status (section 6). |
| Has PDP | No | Tick if the student holds a Professional Driving Permit. | Unlocks the next two fields. |
| PDP Number | No | The PDP number. | Disabled unless Has PDP is ticked. |
| PDP Expiry | No | The PDP expiry date. | Disabled unless Has PDP is ticked. |
Automatic date of birth (South African schools only). If your school's country is South Africa, typing a 13-digit identity number fills in Date of Birth from the first six digits (YYMMDD). A two-digit year that is not later than the current year is read as 20xx, otherwise 19xx. You can still change the date by hand. For other countries nothing is filled in.
Age and identity number rules
Age rule. The validation message is "Student must be older than 16 years." The check requires the student's age in completed years to be greater than 16, so in practice the student must already have turned 17. A student who is exactly 16 is refused.
Identity number length. The 13-character rule applies to every school, including schools outside South Africa. A passport number or an ID of another length cannot be saved.
Step 2 - Contact Information¶
| Field | Required | What it means | Rules |
|---|---|---|---|
| Mobile Number | Yes | The student's main phone number. | Maximum 20 characters. |
| Alternative Number | No | A second number. | Maximum 20 characters. |
| Yes | The student's email address. Used for the welcome message, invoices and the student portal invite. | Must be a valid email address, maximum 150 characters, and not already used by another student of your school. |
Step 3 - Training Information¶
A blue information box at the top of this panel reads "Training selection will be connected to Branches, Licence Codes, Training Packages and Instructors." It is leftover text; the lists below are already connected.
| Field | Required | What it means | Rules |
|---|---|---|---|
| Branch | Yes | The branch the student trains at. | Must be an active branch of your school. Staff who are tied to one branch can only choose their own branch. |
| Licence Code | Yes, unless the package is an Assessment package | The licence the student is training for. Only codes your school offers are listed. | Changing the licence code clears the selected package and reloads the package list. |
| Training Package | Yes | The package the student is buying. The list shows packages for the chosen licence code, plus all Assessment packages (these are not tied to a licence code). | See the note about inactive packages below. |
| Instructor (Optional) | No | The student's assigned instructor. Leave on "-- Not Assigned --" if not known. | Must be an active instructor who works at the same branch as the student. |
Once a package is chosen, an information box shows:
- Lessons: the number of lessons in the package
- Price: the package price
- Valid for N days - the package validity
Screenshot to be added
Screen: Register Student, Training Information panel. Should show: a licence code and package selected, with the Lessons / Price / Valid for box showing.
Notes:
- Choose the licence code first. Before a licence code is chosen the package list only contains Assessment packages.
- The package list is not filtered by the Active switch. A package that has been switched off still appears here and can be chosen. To stop a package being sold, see Training packages.
Inactive packages are still offered
A package that has been switched off still appears in the Training Package list and can be chosen. Check that you pick a current package.
Step 4 - Guardian Information (optional)¶
Click the Guardian Information panel heading to open it. The box at the top reads "Complete this section if the student is under 18 or if an emergency contact is required."
| Field | Required | What it means |
|---|---|---|
| Guardian Full Name | No | Name of the parent or guardian. |
| Relationship | No | For example Mother, Father, Brother. |
| Mobile Number | No | The guardian's phone number. |
| Alternative Number | No | A second number for the guardian. |
| No | The guardian's email. | |
| Occupation | No | The guardian's occupation. |
| Physical Address | No | The guardian's address. |
| Use as Emergency Contact | No | Tick to also save the guardian's name, relationship and mobile number as the student's emergency contact. |
None of these fields is validated, and the system does not force you to add a guardian for a student under 18. Full details, including what is and is not editable later, are in Guardians and emergency contacts.
Step 5 - Save¶
- Click Register Student.
- If a required field is empty, the fields are highlighted and you see "Please complete all required fields." Nothing is saved.
- Otherwise the registration is sent. On success you see "Student registered successfully." and the new student's profile opens.
5. What happens when you save¶
flowchart TD
A["Click 'Register Student'"] --> B["Plan student limit checked (API)"]
B --> C["Field validation (lengths, email, 13-character ID, age)"]
C --> D["Branch allowed? Instructor active and at the same branch?"]
D --> E["Training package exists? Licence code given (unless Assessment package)?"]
E --> F[Identity number and email not already used by another student]
F --> G["Created in one save:<br/>- Student (with a new student number)<br/>- Guardian record (and emergency contact, if ticked)<br/>- Course (status Active, started today)<br/>- Invoice (status Pending, due in 15 days) with one line for the package"]
G --> H["'Student welcome' notification sent<br/>First invoice emailed to the student (if Email and Invoice Issued are on)"]
H --> I[Student profile opens]
In detail, one successful registration creates:
| Created | Details |
|---|---|
| Student | With a generated student number in the form <branch code>-STU-<running number>, for example JHB01-STU-00042. The number of digits is set by the school's number sequence. |
| Guardian | A guardian record holding whatever was typed in the Guardian panel. If Use as Emergency Contact was ticked, an emergency contact is also created with the guardian's name, relationship and mobile number. |
| Course | The student's first course: the chosen package and licence code, at the chosen branch, status Active, start date today. |
| Invoice | One invoice for the full package price: status Pending, invoice date today, due date 15 days later, amount paid 0. It has one line (quantity 1, unit price = package price) linked to the new course. The line description is the package name; if the package is built from items, the items and their prices are listed after the name. See Invoicing. |
| Notification | The "student welcome" notification is sent with the student's name, student number and branch name. Which channels are used depends on the school's notification settings (see Notification settings). |
| Invoice email | The first invoice is emailed to the student, but only when the school's notification settings are active with Email on and the Invoice Issued notification enabled with Email ticked. Otherwise no invoice email is sent; staff can send it later with Send Email on the invoice. |
What registration does not create:
- No user account. The student cannot sign in to the student portal until a staff member invites them. See Student portal.
- No lessons. Lessons are booked afterwards; see Scheduling lessons.
A failed welcome notification or a failed invoice email never cancels the registration: the student is already saved.
6. The student's starting status¶
| Situation at registration | Starting status |
|---|---|
| Has Learners Licence is ticked and an expiry date is entered and that date is today or later | Learners Passed |
| Anything else (no learner's licence, no expiry date entered, or an expiry date in the past) | Registered |
Enter the learner's licence expiry date
Note the middle case: a student who has a learner's licence but whose expiry date is left empty starts as Registered, not Learners Passed. Enter the expiry date if you want the correct status. (For booking lessons, a learner's licence with no expiry date is still treated as valid.)
All statuses are explained in Student status management.
7. Messages you may see¶
Validation messages appear as red notifications. Each problem is shown as its own notification.
| Message | Cause | What to do |
|---|---|---|
| Please complete all required fields. | A required field on the page is empty. | Fill in the highlighted fields. |
| Student must be older than 16 years. | The date of birth makes the student 16 or younger (it also appears if the date of birth was left on today's date). | Correct the date of birth. |
| A message that the Identity Number must be 13 characters in length | The identity number is not exactly 13 characters. | Enter the 13-character ID number. |
| A message that the Email is not a valid email address | The email is not in a valid format. | Correct the email. |
| A message that a field must be a certain number of characters or fewer | A name is longer than 100 characters, the email longer than 150, or a phone number longer than 20. | Shorten the value. |
| Branch not found. | The branch does not exist or belongs to another school. | Choose a branch from the list. |
| Branch is not active. | The branch has been deactivated. | Choose an active branch. |
| You can only place students at your own branch. | You are tied to one branch and chose a different one. | Choose your own branch. |
| Assigned instructor not found. | The instructor no longer exists. | Choose another instructor or leave unassigned. |
| The assigned instructor works at a different branch from the student. Choose an instructor from the student's branch. | The instructor's branch is not the student's branch. | Choose an instructor from the same branch. |
| The assigned instructor is not active. | The instructor has been deactivated. | Choose an active instructor. |
| Training Package not found. | The package no longer exists. | Choose another package. |
| Licence Code is required for this training package. | No licence code was chosen and the package is a Training (not Assessment) package. | Choose a licence code. |
| Licence Code not found. | The licence code no longer exists. | Choose another licence code. |
| Identity Number already exists. | Another student of your school has this identity number. | Search the Student Directory for the existing student. |
| Email address already exists. | Another student of your school has this email address. | Use a different email, or find the existing student. |
| The server took too long to respond. Please try again. | The request timed out. | Check the Student Directory before retrying, in case the student was saved. |
| Unable to reach the server. Please try again. | No connection to the server. | Retry when the connection is back. |
| Unable to register student. | A failure with no specific message. | Retry; contact support if it continues. |
| The lead couldn't be marked as converted: (reason) | Only when registering from a lead. The student was created; only the lead update failed. | Update the lead by hand. |
If your plan's student limit has been reached, the registration is refused with the plan-limit message described in Subscription plans.
8. Example¶
Thandi Mokoena walks into the Johannesburg Main branch wanting a Code B licence. She already has a learner's licence that expires on 14 March 2027.
- Reception clicks Students > New Student.
- Personal Information: First Name "Thandi", Last Name "Mokoena", Identity Number (13 digits) - the Date of Birth fills in automatically. Gender Female. Tick Has Learners Licence, enter the number and the expiry 14 Mar 2027.
- Contact Information: Mobile Number and Email.
- Training Information: Branch Johannesburg Main, Licence Code Code B, Training Package Code B - 10 Driving Lessons. The box shows Lessons: 10 and the price. Instructor left as "-- Not Assigned --".
- Guardian panel left closed (Thandi is an adult).
- Click Register Student.
Result: Thandi gets student number JHB01-STU-..., status Learners Passed, an Active course for the 10-lesson package, and a Pending invoice for the package price due in 15 days, which is emailed to her along with the welcome message (the school has Email and Invoice Issued switched on). Her profile opens, ready for the first lesson to be scheduled.
9. Limitations and notes¶
- Not a wizard. Registration is a single page. The numbered strip at the top is not interactive and its third item ("Guardian") never becomes highlighted.
StudentReviewStepis unused.DriveFlow.Web/Features/Students/Components/StudentReviewStep.razor(a "Review Student" summary of name, email and phone) is not referenced by any page.- A guardian record is always created. The web form always sends a guardian object, even when the Guardian panel is left empty, and the handler creates a guardian row whenever one is sent. A student registered without guardian details therefore still gets a blank guardian record (
RegisterStudentHandler.cs,CreateStudentRequest.cs). - Guardian is never compulsory. There is no rule that a minor must have a guardian.
- Notes are not captured. The registration request has a Notes field (filled from a lead's notes when registering a lead) but there is no Notes box on the form and the handler does not save it. Add notes afterwards on the profile's Notes tab.
- Only the first address line is used. The student record has fields for address line 2, city, province, postal code and country, but the form only fills the first line.
- Inactive packages can still be chosen in the Training Package list (the lookup does not filter on Active).
- 13-character identity number for all countries. The length rule is not country-specific.
- Uniqueness is per school. Identity number and email are checked against the students your sign-in can see. A deleted student's identity number and email still count as "already exists"; see Student status management.
- Date of Birth and Gender are not marked with a required star, but Date of Birth must be changed from today's date or the age rule fails.
- Registration through the mobile app is not covered here; see the mobile app documentation.
Related articles¶
- Student profiles - the profile that opens after registering.
- Student training information - branch, licence code, package and learner's licence.
- Guardians and emergency contacts - the optional Guardian panel.
- Student status management - the starting status and what changes it.
- Student enrolment - registration as one of the enrolment routes.
- Student portal - inviting the student to sign in.