Import users via Excel

Use this article to import users into Cirrus from an Excel (.xlsx) file. The bulk import is the practical way to create candidate cohorts or staff lists at the start of an exam cycle. For one-off additions, see Manually add or manage a user.

Before you start

You need Manage users under Admin > Roles > Site administration.
Define your site roles before importing.
Define your hierarchy before importing.

Roles and hierarchy are assigned to each user at import, so they need to exist first.

Build the Excel file

A template is available: USERIMPORT-TEMPLATE(2024).xlsx.

Rules

Up to 2,000 users per file.
Username and UserID must be unique across the file.
The Username is the unique identifier in Cirrus.
Mandatory columns: First name, Last name, Username, Email, UserID.
Optional columns: Password, Sub-hierarchy, Region, Timezone.
Optional columns to leave blank when not used: Extra time (yes/no), Percentage extra time (number), Synchronisation key.
Set in the import dialog, not in the file: Role, Start hierarchy.
No trailing spaces in any field except First name and Last name.

Email rules

Every user needs an email (used for notifications). The same email address can be reused across users when needed, for example noreply@your.org.

Header rows

Give every column a clear header. The import dialog asks you to map each column to a Cirrus field, and clear headers make the mapping unambiguous.

Run the import

Sign in as a System Administrator.
Open Admin > Users.
Select Import users.
Choose your .xlsx file and confirm.
The Import users dialog opens.
Map each Cirrus field to its column using the drop-downs.

Import users mapping dialog

Time zone for imported users

Imported users are assigned the time zone set under Admin > Regional settings > Time zone at the moment of import.

Select Try import. Cirrus runs a dry-run and shows a feedback screen.

Feedback before final import

The feedback shows how many rows will be imported and how many will be skipped or rejected, with reasons. Fix the file and re-run Try import until the result is clean.

When the dry-run is clean, run the real import.

After the import

Imported users appear under Admin > Users.
Roles and start hierarchy are applied from the import dialog.
Time zone and regional defaults follow the Admin > Regional settings values current at import time. To change a user's regional settings later, the user sets them through My profile (or, for candidates, picks the language on the login screen).

Notes on existing users

Re-running the import for the same username does not create duplicates. Cirrus matches on Username and updates the existing user. The Synchronisation key column is intended for integration-driven imports where a system ID rather than the username is used for matching.