CONTENT
Note: Some functions listed here may be disabled depending on country-specific or customer-specific requirements. In such cases, user management is carried out through a different method. Please contact your system administrator.
For schools with a large amount of users (+ 500) it is advisable to use an integration with the SIS/user management system to automate the creation of user accounts. Please contact your itslearning account manager for more information about integrations.
Preparations for Import
Preparation of Hierarchies
Before importing users to itslearning, you need to consider what heirarchy structure is intended and which users you want to import. More information about creating a hierarchy structure to your site can be found in the article on Hierarchies.
Preparation of the Import File
The CSV import feature enables the bulk creation or updating of multiple users within itslearning.
This guide provides an example of how to prepare the import file, demonstrating the functionality of using a CSV file. Typically, user information can be structured and exported from a school management system, then organized in Excel according to the following guidelines.
To prepare the data in Excel, create a separate worksheet or file for each user group:
Important: Save each table as a separate CSV file (UTF-8 comma-separated). If the file size exceeds 550 MB, it is necessary to split it into smaller files.
Below, we outline the procedure for importing teachers and students. Some customers may also want to add parents/guardians to itslearning. Please refer to the section “Importing Parents and Guardians” at the end of this article for more special considerations.
Import File for Teachers
To successfully import data, the following information is essential. The order of columns and their headings can vary, as they will be mapped to the corresponding fields in itslearning prior to the import process.
- Synchronization Key (ID): This key is crucial for matching records when reusing the import file to update user data, for example at the beginning of a new school year. Each ID must be unique, meaning it cannot be duplicated, and every user should have one distinct ID. If you have a user management system, we recommend sourcing this ID from there. If not, you can generate a unique synchronization key using the following format:
- L_20200611_001
- L = Teacher
- 20200611 = the current date in reverse (YYYYMMDD)
- 001 = A sequential number, which can restart at 001 each day.
- In Excel, you can mark the first cell and drag it down the column to automatically create all IDs.
- If you are using itslearning across multiple schools on a shared platform, such as one provided by the school authority, it’s advisable to include a school identifier in the ID. The format would then look like this: 7389201_L_20200611_001
- First Name: The teacher's first name (or an abbreviation if preferred).
- Last Name: The teacher's last name.
- Username: Username must be unique. Common formats include "FirstName.LastName" or the teacher's abbreviation. Umlauts are acceptable and will be recognized both with and without dots during login (e.g., Müller = Muller). Be sure to consider a method for handling double names.
To prevent duplicate usernames, you can also have itslearning generate them automatically. This is particularly beneficial if you are using itslearning across multiple schools on a shared platform or if you maintain user data in various tables. This approach helps avoid errors during import that would require manual corrections if a username already exists. This also applies if the username is used by another school on the same itslearning platform. You may leave this column blank, allowing for automatic username generation. Alternatively, you can specify that automated names should only be generated in cases of duplicates. More information on this can be found in the import section below.
Automatically generated usernames typically consist of the initial letters of the first and last names, for example, "MaSc" or "MarSch" for Maria Schneider.
You may also include additional columns, such as a (work) email address, if desired.
Import File for Students
- Synchronization Key: If you already have a student number, e.g., from a management software, you can and should use it here as well. Otherwise, you can generate an ID following the same pattern as above for teachers.
- S_20200611_001
- S = Student
- continue as for teacher
- First Name + Last Name: as for teacher
- Username: as for teacher, if students are familiar with a student number, it can also be used as a username.
- Year + Class: These designations can vary depending on the educational institution, e.g., in vocational schools, training course and graduation year. There can be more or fewer than 2 columns. The aim is to map the learners in the familiar structure so that, e.g., a teacher can retrieve them as a group. These columns will appear as sub-hierarchies of the student level after import.
The import process
Step 1: Upload the Import File
To begin the user import process, navigate to Admin > User and Access Management > Import Users from File. Follow the prompts to upload your pre-prepared CSV import file.
You have the option to either search for the file on your computer or drag and drop it into the designated file upload area. If you need to correct an error and replace the file, simply click on the file upload field and select a new file.
Once you are ready, click on Next to proceed with mapping your data to the itslearning fields.
Step 2: Map the Data Fields
Begin by selecting the user profile, and then connect the fields from itslearning to the corresponding column labels in your CSV file. For any fields that are not required and do not appear in your file (such as date of birth), simply leave them blank.
Please note that itslearning will automatically map the columns if the headings closely align with those used in itslearning. However, it is crucial to double-check that all mappings are accurate.
Note about Usernames
itslearning has the capability to automatically generate usernames if a username is missing from your file or if there are duplicates in it.
- If you wish to generate all usernames automatically, simply leave the default entry as "Generate (has not changed during synchronisation)" and check the box labeled "Allow username generation (if empty or used)".
- If you already have usernames in your import file and only want an automatically generated username in the event of duplicates, select the appropriate column in your table and check the box "Allow username generation (if empty or used)".
Further down, enter the ID as the synchronisation key and mark the field "Synchronisation field" on the right:
If you opt to generate usernames automatically, you can select the username as the synchronization field, as itslearning guarantees that all usernames will be unique. For usernames created manually, an additional ID serves as a safeguard to prevent the accidental overwriting of existing accounts with new data.
Next, assign the corresponding hierarchy role and hierarchy.
The initial hierarchy ("Start hierarchy:") must already be created. The sub-level hierarchies will be created with the import if they do not already exist. In this case, students will be assigned to the corresponding hierarchies when imported. Teachers are usually not assigned to further sub-hierarchies and when importing teachers, you can leave these fields blank.
When your mapping is ready, click on "Next".
Step 3: Start the Import
In the next step, you will see a preview of your hierarchies. Levels that are newly created during the import are marked as ‘new’.
Click on "Next" again and preliminary report of the expected import appears next. This will give you a simple overview after a quick scan of the file for errors. If the the number of errors in the initial scan are high, we recommend to double-check that it is correctly formatted. If only a few errors, you can proceed with the import. Once it is complete, you’ll will be presented a detailed summary with numbers of the lines that have errors. 
In the first line, "1" (=one error) is sometimes displayed. This is usually happens if the first empty line of the import file contains an invisible control character. You can ignore this error.
Start the import process by clicking on “Finish”.
Step 4: View import summary
Once the import process starts, you are taken to the CSV import summary page where you can see the status of the currently running import and import summaries from the past 14 days. If your import is large, you can safely leave the page and come back later to check if the process has completed and view the detailed import summary.
Once the import has completed, you can view a detailed summary it. If there were errors, the report will reference the type of error and the line number of the import file where they happened. This way you can easily make the necessary changes and run the import again.
Important: Please note that with such a CSV import, only users can be added, not deleted. Deletion, on the other hand, happens in user management under "Users and Access Rights".
Importing Parents and Guardians
Note that that students should to be imported before parents and guardians.
The import file for parents and guardians should the same logic as for teachers with the important exception that it also must include a unique identifier of the child that is connected with them. Without this it is not possible to connect a parent or guardian and a child automatically.
There are two fields at the bottom of the field mapping form that are used to connect a parent or guardian with a child.
Synchronisation field in import file
Here you tell itslearning what field to use when connecting parents or guardians to their children. The alternatives in the drop-down list are retrieved from the CSV file from which you are importing. In the above example, the synchronisation field would be studentSyncKey.
Matching synchronisation field for child
This field must match the selection you have made for Synchronisation field in import file, above, and tells itslearning what kind of field the Synchronisation field in the import file involve. You can select from three alternatives: Internal person ID, Synchronisation key, and Username. If the synchronisation field in the import file contains usernames, select Username as the matching synchronisation field. If you have a SyncID field in your CSV file, then select Synchronisation key.