Import users and cohorts
Import users and cohorts
Use the Import page to create or update users and group memberships in bulk. The import is a guided wizard that validates everything before anything is queued, so problems are caught while you can still fix them. This is the fastest way to onboard a large number of users at the start of term or to set up cohorts from an MIS export.
This page — the sidebar calls it Advanced user import — sits alongside two other, simpler imports under the same Import group: Password import (set passwords for existing users from a CSV) and Cohort import (add existing users to groups from a CSV). If all you need is one of those, use the simpler page — it's less to fill in.
Before you start
- You must be an admin for the school you are importing into.
- Select the school first. The import always runs against the school you are currently in — switch to it using the school switcher before you start. (You can't import while viewing all schools in MAT mode.)
- Prepare your data with the correct column headers — see the format below. You can either upload a CSV or paste rows copied from a spreadsheet.
CSV format
The import understands the following columns. Only type, username, forename and surname are required; everything else is optional. Column names are matched flexibly (for example first_name, email and role are recognised as forename, upn and type), and any columns it doesn't recognise can be mapped by hand in the wizard.
| Column | Required | Description |
|---|---|---|
type |
Yes | Role: admin, mentor, learner, observer, governor, or ofsted |
username |
Yes | Unique login username for this school (letters, numbers and . _ - @) |
forename |
Yes | User's first name |
surname |
Yes | User's surname |
status |
No | ACTIVE, PROTECTED, SUSPENDED, or DELETED (defaults to active) |
password |
No | Initial password (leave blank to auto-generate) |
misId |
No | Internal identifier from your MIS (numeric) |
upn |
No | Email / unique pupil number, as a valid email address |
title |
No | Title (e.g. Mr, Mrs) |
legal_forename / legal_surname |
No | Legal names where they differ from preferred |
year |
No | Year group (numeric) |
house |
No | House name |
admission_number |
No | Admission number (numeric) |
registration |
No | Registration group name |
groups |
No | Groups to add the user to, separated by ; or , |
Groups that don't exist yet are flagged as a warning and created during the import. Download a template CSV from the Import page to get started.
Steps
Step 1 — Provide your data {#step-1}
Open Import in the sidebar. You have two options:
- Upload a CSV — select Download example CSV, fill it in, then upload your file.
- Paste data — copy rows (including the header row) from a spreadsheet and paste them into the box, then select Use pasted data.
Step 2 — Map your columns {#step-2}
The wizard auto-matches your columns to the provisioning fields. Check the mapping, correct anything that's wrong, and make sure each required field (marked with *) is mapped. Select Validate & continue.
Step 3 — Validate {#step-3}
The wizard checks every row and cell — required values, valid roles and statuses, email/UPN format, numbers, and duplicate usernames, UPNs or MIS IDs within your data.
- Rows to fix lists each problem by row, field and reason. Fix them in your source data (or remap), then select Re-validate.
- Warnings (such as groups that will be created) must be acknowledged with the checkbox before you can continue.
- When everything is valid you'll see a preview and the import becomes submittable.
Choose whether to sync members and/or groups to connected platforms after the import.
Step 4 — Queue the import {#step-4}
Select Queue import (prioritised) and confirm. The import is placed at the front of the provisioning queue, ahead of scheduled syncs, and runs shortly.
Result
Your import is queued onto the priority lane and processed by the provisioning service. You'll get a reference (e.g. IMP-XXXXXXXX) — note it down. Live progress ends once it's queued, so track the outcome in the Logs area for the school. Members and groups are synced to connected platforms according to the options you chose.
Troubleshooting
- "Map a column to the required field…" — one of the required fields (
type,username,forename,surname) isn't mapped. Pick the matching column on the mapping step. - "Duplicate username/UPN/MIS ID in this import" — two rows share the same value. Each must be unique within a single import.
- "Must be one of…" — the
typeorstatusvalue isn't recognised. Use one of the allowed values listed in the format table. - Groups will be created — this is a warning, not an error. Acknowledge it to continue, or create the groups first via Groups if you'd rather control their settings.