CSV Import
To manage a large number of users efficiently, the CSV import function can be used. It requires the permissions to create and to update users. The following steps are required:
- Access the Menu: The Users navigation point in Relution is opened.
- Start Import: In the 3-dot menu, Import users via CSV starts the import.

- Use Template: The provided CSV template is downloaded. It uses the separator selected in the CSV separator field (Comma or Semicolon) and contains the columns
name,email,givenName,surname,password,disablePasswordAuthentication,phone,position,country,managedAppleId,locale,permissions,memberOfGroups,teacherOfClassesandstudentOfClasses. - Edit Data: The file is opened in an editor of choice and the required values are entered.
- Upload File: The edited CSV file is uploaded back to Relution in the CSV file step. This step also contains the option Automatically create groups and classes (see below).
- Review: The Preview shows the first 5 rows for verification.

- Assignment (Optional): Users can be added directly to existing groups during this process. This step is only shown with the permission to read groups.

- Completion: The import progress shows the current status. The summary distinguishes successful, skipped and failed lines and lists the message for each line.

Important Configuration Notes
- Password Policies: If fixed passwords are defined, they must comply with the password policy of the respective organization. For example, if the policy requires at least 8 characters, the import will fail for any users whose passwords contain fewer characters.
- Class Assignment: Teachers and students are assigned to classes via the
teacherOfClassesandstudentOfClassescolumns. Multiple classes in one cell are separated by|. Membership in a group (e.g.UIT Teacher) does not assign anyone to a class. A class is only saved if it then has at least one teacher and at least one student; for existing classes, the previous members count as well. Otherwise, this class is listed as skipped in the import report, while the users themselves are still imported. A class that does not exist yet is only created if the option Automatically create groups and classes is enabled; otherwise, the line is reported as failed. - Group Assignment: Groups (e.g. the system groups
UIT TeacherandUIT Student) are assigned via thememberOfGroupscolumn, permissions fromUsers→Permissions(e.g.Self service portal - read access) via thepermissionscolumn. The exact name is decisive in each case. The organization’s system groups carry its unique name as a prefix, e.g.UIT Teacher; self-created groups are entered with their own name. If the name of a permission is entered inmemberOfGroups, the import fails for this line with a message that the group could not be found; if Automatically create groups and classes is enabled, a new, empty group with this name is created instead. - Updating Existing Users: The CSV import can also be used for already existing user accounts. Matching accounts are identified by the
namecolumn (username) within the same organization and updated with the values from the CSV file instead of being created again. The email address is not used for this matching. Users managed by an external provider (e.g. a directory service) are skipped. Imported users are always activated. - Empty Columns During an Update: If a column exists in the CSV file but its value is empty for a given row, the corresponding field of the existing user is cleared. The columns
permissions,memberOfGroups,teacherOfClassesandstudentOfClassesare an exception: an empty cell leaves the existing assignments unchanged. A filled-in value, however, replaces the previous assignments completely; permissions and groups not listed are removed, as are classes not listed in which the user is entered as teacher or student. The groups additionally selected in the import dialog are added in any case. For all other columns: columns whose existing values should remain unchanged must be removed from the CSV file entirely rather than just left empty. - Password During an Update: If the
passwordcolumn is empty or omitted for an already existing user, that user’s current password remains unchanged. For newly created users without a password value, no password is generated automatically; an initial password needs to be set for them in a separate step. - SSO-only Sign-in: The
disablePasswordAuthenticationcolumn only takes effect when a user is created; during an update, the previous value is kept.
Behavior in Practice
A few concrete examples for updating existing users via the CSV file:
- The
emailcolumn is present but left empty for a row: The user’s existing email address gets deleted. To keep it unchanged, theemailcolumn must be removed from the CSV file entirely. - The
memberOfGroupscolumn is present but left empty for a row: The user’s existing group memberships remain unchanged. If the cell containsUIT Teacherinstead, the user is afterwards only a member of this group and of the groups selected in the import dialog. - How an existing user is recognized during an update: Exclusively by the
namecolumn (username) within the same organization — the email address plays no role in this. - The
passwordcolumn is left empty: For an already existing user, the current password remains unchanged, regardless of whether the column is missing or just empty. For a newly created user, no password is generated automatically in this case.
Naming Example:
- Organization name:
User-Import-Test - Organization unique name:
UIT - User Groups:
UIT Student,UIT Teacher
A CSV file with one teacher and one student, each assigned a group via the memberOfGroups column and the class 10a via teacherOfClasses or studentOfClasses, could look as follows:
name;email;givenName;surname;permissions;memberOfGroups;teacherOfClasses;studentOfClasses
teacher1;teacher1@uit-school.com;Jane;Teacher;;UIT Teacher;10a;
student1;student1@uit-school.com;Sam;Student;;UIT Student;;10a
Multiple groups, permissions or classes within the same cell are separated by a pipe character (|), for example UIT Teacher|UIT Student. This applies to the columns memberOfGroups, permissions, teacherOfClasses and studentOfClasses. A semicolon can also be used as a separator within the cell; however, since it may already separate the columns themselves depending on the chosen CSV separator, using | is recommended for unambiguous results. A comma does not separate values within a cell.
Automatic Creation of Missing Groups and Classes
Relution can automatically create classes and user groups that do not yet exist during the CSV import. This requires the option Automatically create groups and classes to be enabled in the first step (CSV file). The option is disabled by default and can only be enabled with the permissions to create groups and classes. Without this option, lines with groups or classes that do not exist are reported as failed. Permissions from the permissions column are never created automatically; they must already exist. The following points apply:
- Precision: The exact spelling of the name is decisive; a different spelling results in a new group or class.
- Whitespace: Leading and trailing spaces around group, class and permission names are removed automatically during import.
- Managed Classes: Classes synchronized by an external provider are skipped during the import.
Common Reasons for a Failed Import
A common reason for a failed CSV import is an email address that is already assigned to another user account on the server. Email addresses must be unique across the entire server, regardless of which organization the respective user belongs to.