Import User Data via the Data Loader

In this topic, we focus on managing user data in bulk.  For information about creating and managing users in the User Manager, please see one of the following topics:

To import user data via the User Data Loader, your user role must have unrestricted access to the User Data Loader feature in System Roles (Manage Features > User Manager Features).

Create the CSV File

You have two options for creating a CSV file for import:

  • Download a CSV template - The CSV file template includes any user attributes and user attribute extensions (prefixed with UA-).
  1. Go to Manage Center >  Users > User Manager > User Data Loader.
  2. Download the CSV file template. 
  • Run report R109 - Generate User Data Dump in CSV Data Uploader Format - to export users to a CSV file and update the field values. 

Prepare the File for Import

Once you have created the CSV import file, you prepare it for import by entering the necessary values in the fields.  Please see User Data Loader Field Reference for detailed information about the fields.

When adding a new user, the mandatory fields are:

  • Action
  • UserID
  • FamilyName
  • GivenName

When updating users, the mandatory fields are:

  • Action
  • UserID

Assign a value of NONE to clear the value from a field.

Note that CSV files are likely to be opened by Microsoft Excel if it is installed on your system. If you encounter any problems with importing a CSV file into the LMS, it could be caused by Microsoft Excel applying extra formatting to the file. Alternatively, you can edit CSV files in a text editor instead of Microsoft Excel. The data should conform to the formatting required by the template as specified in the corresponding CSV Formatting Help.

If the values for text area fields include punctuation, these fields must be enclosed in double quotation marks (" "). Do not include commas or semicolons in other fields as they could be interpreted as a field delimiter (depending on your choice of delimiter at import).

Import User Data

To add, update or delete users via the User Data Loader

  1. Go to Manage Center >  Users > User Manager > User Data Loader. 
  2. Click + Import CSV file.
  3. Click Choose File to select the CSV file to upload.
  4. If one or more user profiles have been configured in the LMS, and you want new users in the CSV file to inherit the settings from a profile user, select the profile from the drop-down list. Otherwise, select Use Domain Configured DEFAULT PROFILE.
  5. If your CSV file was saved with a specific file encoding the LMS can automatically detect it, otherwise you can select it from the list.
  6. Select the delimiter used to separate fields in your CSV file. This can be a comma or a semicolon.
  7. Click Preview. The contents of the CSV file are shown in the Data Loader page so that you can review the data before importing the file.
  8. Click Upload to import the CSV file. The Summary Report shows how many records in the file were imported successfully and how many failed.
  9. If any records failed to import, you can go back to the User Data Loader page and click the CSV Error Report link for the failed import. The error report downloads to your desktop as a copy of the imported file that includes the error message.

User Data Loader Validation

Use the information below to help you resolved errors when importing user data.

Adding New Users

When adding new users:

  • Ensure that the data contained in the CSV file conforms to the formatting required by the template. Do not insert commas as these will cause subsequent data to be treated as a separate column.
  • If a new user is to be assigned to a particular organization structure, ensure that the entire organization hierarchy is included in the CSV file. This could be a new or existing structure. For example, in an organization with four levels, you must include specifications for levels 1, 2, 3, and 4. You may not omit definitions for intermediate levels (that is, levels 2 or 3).
  • If an organization structure is not specified (that is, levels and descriptions are left blank), the user profile organization structure will be used if the option to use a profile has been selected. If a profile is not used, the user will be created with an organization structure of Unassigned.
  • If an organization description for a particular level is entered but the corresponding description code is not, the organization level will not be added. A warning message will appear in the log file.
  • When adding a new user, the mandatory fields are: Action, UserID, FamilyName, GivenName, Password.
  • The length of the password field is specified in the system configuration settings.
  • If the password field is left blank when adding system defaults, the system default password will be used.
  • If you use a profile during a data upload, the password defined in the profile will be used.
  • Personal Title: the LMS will check the format of this field to ensure that it complies with one of the valid, predefined titles (for example, Mr., Mrs., Dr.). If the personal title specified in the uploaded file does not match one of the predefined titles, it will default to NONE.

Updating Users

When updating users:

  • Ensure that the data contained in the CSV file conforms to the formatting required by the template. Do not insert commas as these will cause subsequent data to be treated as a separate column.
  • Profiles are not used when updating existing users even if the option is selected.
  • Incorrectly formatted records will be rejected as invalid data.
  • When updating the only mandatory fields are: Action and User ID.
Error Corrective Action
Invalid User ID format Ensure that all User IDs do not exceed the maximum length of 85 characters, that there are no spaces, and that only valid alphanumeric characters are used.
Adding users to other organizations is not allowed Log in as System Administrator to import the data or disable the Enforce Partitioning by Level 1 Organizations system configuration setting.
Assigning users to an inaccessible organization is not allowed Log in and import with a system role that has Role with Highest Organization Level Visible higher than or equal to the organization level that users are being moved to in the file.
Updating users from an inaccessible organization is not allowed Log in and import with a system role that has Role with Highest Organization Level Visible higher than or equal to the organization level of the users being updated.
Creating organizations in an inaccessible area is not allowed Log in and import with a system role that has Role with Highest Organization Level Visible higher than or equal to the organization level that is being created via the upload.
Deleting users from an inaccessible organization is not allowed Log in and import with a system role that has Role with Highest Organization Level Visible higher than or equal to the organization level of the users being deleted.
Multiple assignments found for User ID: 'X', please specify an Assignment ID Identify X's assignment ID that should be used and insert it in the appropriate column with the required format.
More than one special character Remove this value to allow the rest of the row to be processed. Configure the property manually in the LMS.
Additional Role Column Format Incorrect Check the values in the AdditionalRoles, AssignRoles, and UnassignRoles columns are in the required format.
FAILED. The importer (User ID "{user ID}") does not have permissions to add the User Role ID "{role ID}"

Ensure the user account importing the new Role ID has a system role with unrestricted access to the Role Permissions feature.