SETUP¶

The main user is an "admin". The "setup" consists in a series of steps in which the admin configures the school on the system. The setup ends when all the steps are completed, but not all the steps in the setup are required. There will be other stories for non-required steps of the setup.

The required-setup is split in 2 main parts:

School configuration (required) - all stories already implemented
People importing (required) - all user stories below are refined and complete for this

As long as the required-setup isn't complete, the admin can't navigate the rest of the application. The admin should be able to start were it left returning to the setup.

HIGH LEVEL OVERVIEW¶

The admin needs to import/add peoples in the school: students, teachers, and staff

USER STORIES¶

US6: Import Students File¶

As a Admin, I want to import my existing student data into the platform, so that I can quickly onboard students without having to enter them one by one.

Acceptance Criteria¶

Scenario 1: User is guided to use the required SIS import schema Given the Admin opens the “Import Students” flow When the user requests a file upload Then the system presents the required SIS Student import schema as the reference for the file structure, clearly stating that the uploaded file must match the schema entirely Note: the import schema is not the full Student record schema, it contains all the Student required field + a subset of its optionals.

Scenario 2: Reject file that does not match the required schema Given the Admin uploads a CSV/Excel file
When the uploaded file’s header structure does not exactly match the SIS Student import schema entirely Then the system blocks progression to the next step
And informs the Admin that the file must contain exactly the expected column headers. Note: we ask for optional column to match too since a user may have them with other names and fail to realize to change their names.

Scenario 3: Data Validation overview shows status for all columns
Given the Admin has uploaded a Student import file that matches the required schema
When the system runs data validation
Then the system displays a validation overview including all failed columns, and for each column shows: - Row range(s) containing invalid values (e.g., 12–46)
- Reason (“invalid format...”, “value not in list”, “duplicate”, “missing required”)
- Allowed values where applicable (ad es: invalid format, the departments should match one of these: departments_available) The system validates the entire file before returning the results and blocks progression to all records creation if some column fails.

Scenario 4: Import is blocked if validation errors exist
Given the validation overview is displayed
When one or more cells contain invalid values Then the system blocks progression to the record creation step
And the Admin must re-upload a corrected file
Until all validation errors are resolved and all columns are marked as Valid.

Scenario 5: Domain validation rules (blocking) Given the Admin has uploaded a Student import file that matches the required schema The system validates the following domain constraints and reports violations: - Referenced school structure entities must exist in the platform (Department, Grade) - Department–Grade compatibility: if a Grade is provided and exists in the platform, it must belong to the selected Department - Student must have at least one referent in email fields and phone fields - Student identification number, when not present, is assigned by the system following the format: S-XXXXX where X is a progressive number - gender (R): enum, string must match MALE, FEMALE, OTHER, PREFER_NOT_TO_SAY in whatever form, so try to parse it and match it with one of the enum - all emails must be valid emails

Scenario 6: Behavior of Optional Fields If a column is defined as optional in the SIS import schema When the column has empty values the system allows progress without errors and the corresponding field values will be stored as empty or default (if defined).

Scenario 7: Create new Student records from validated import Given the Admin has completed schema validation and data validation of the imported file Then the system creates the Student records and displays a confirmation message with the number of students created

Scenario 8: Create Referent records from import data Given the validated import file contains referent information When the system processes the import file Then the system creates Referent records for the provided referent data, linked to each students. Note: it only creates Referents, not Users yet, since referents will be provided an invitation link via mail later on.

Notes¶

If a column is included in the file (whether Required or Optional), all its values must comply with the validation rules.

Fields associated with the student entity¶

firstName (R) surnlastNameame (R) nickName (O) dateOfBirth (R) gender (R): enum, string must match MALE, FEMALE, OTHER, PREFER_NOT_TO_SAY place_of_birth: string (O) nationality: ISO 3166-1 alpha-2 (R) status (R) identificationCode (matricola) (0) department (R) grade (O) enrollment_date (R) school_email (O) referent_cell_phone_1 (R) referent_cell_phone_2 (O) home_phone (O) home_address (O) home_city (O) home_state (O) home_postcode (O) home_country (O) tax_code (R) passport_number (O) passport_expiry_date (O) identity_card_number (O) identity_card_expiry_date (O) medical_problems: string (O) medications: string (O) medication_allergies: string (O) food_allergies: string (O) diet_type: string (O) learning_support: string (O) referent_email_1 (R) referent_email_2 (O)

Field of the Referent¶

email phone