Overview

You can use batch user CSV files to import, update, export and delete user accounts on mass. Template CSV files are available from both the Import users and Delete users dialog boxes, accessed from the Users page within the Civica Learning Administration portal.

CSV file format

You can use any spread sheet editing application to create the CSV file containing your user account data. A better approach is to download a template version of the CSV file available from the Import users dialog box. The advantage of using the template file is that it contains the exact set of columns for all the specific user profile fields defined on your system.

The first row in the CSV file must contain the names of each of the profile data items to be imported. Each subsequent row should specify profile data for a specified username.

Mandatory fields

You only need to populate the columns for mandatory profile fields in the CSV file, however, you can choose to provide values for optional fields as well. The following fields are mandatory for import and update operations:

• Username
• First name (this may be labelled differently on your system)
• Surname (this may be labelled differently on your system)

For delete operations, only the Username is mandatory.

Usernames

The Username field is mandatory and must be unique. This is the unique identifier for each user account. It is often the user's email address but it could be another identifier such as a personnel number or an employee number. A user name that's based on a combination of the user's first and last name is also a commonly used approach.

The New username field is optional, but where used must also be unique, across all of the values within both the Username and New username columns, as well across existing users on your system. You only use the New username column when you need to change an existing user's username for example where a user's username is based on their name, and their name changes when they get married, or when the username is an email address which changes following company merger, acquisition or re-brand. 

The bulk username update feature is subject to the following limitations:

• A user's new username must not already exist on the system.
• If the username specified in the Username column does not already exist on the system, a new user will be created with the specified username, and any value in the New username column will be ignored. 
• If a user is an "Approver" (you may have this labelled differently), you will also need to update the profile data for each user where the user is listed as the approver (to the new username value). The updated username will not automatically propagate to these related users (we expect propagation to be added in a future release).
• If you have a Discourse discussion forum, you should not use this feature, as the changes are not propagated to the discussion forum at this time. Where this is used with a discussion forum, users are likely to have a new forum account created on their next visit to the discussion forum, and be permanently locked out of the original forum account. This is not something we are currently able to resolve for you. 

Email addresses

Where possible, you should define email addresses for each user, because this enables email alerts such as enrolment confirmations, content completion reminders and others to be sent to users. It is also needed if you want to support self-service password resets. However, Civica Learning supports email accounts with no email addresses and the system is not reliant on them.

Where you specify an email address, this must be correctly formed, with an email alias separated by the @ symbol from the email domain.

Groups

You can add a user to one or more groups at import time by including one or more Group columns in the CSV file. So for example, to create a new user account for Neil Smith, and you want this account placed in a Managers group and a Finance group, the CSV should contain at least the following information:

If you specify a group name that doesn’t exist, the new group is automatically created.

Passwords

If you specify a password, the user account is created with the specified password. You must ensure that passwords meet the complexity criteria defined for your Civica Learning instance. If you do not specify a password then the user is prompted to provide a password when they first login.

If you update users by using the batch import system, if you provide a password the user's existing password will be overwritten. If you do not provide a new password then the user will continue to use their existing password.

Approvers

Various operations performed by users can require an approval process. Examples include users enrolling onto courses or sessions, submitting tasks and registering independent learning activities (ILAs). To support the approval process, Civica Learning must be able to identify the relevant approver for each user. One way of specifying the approver is by using the Approver column in the batch CSV import file. If present, this must contain the username of the approver for the specified user account.

Organisational units (OUs)

Organisational units (OUs) are a construct for organising users and you can use them to model your organisational structures both internally and externally. OUs are used for content targeting, role assignment and reporting user selection. When importing your users via the CSV process, it's important that the relevant OUs are specified. You can use zero, one or many of the following columns to define the OU in which each user account should be placed.

• Division. The division (often referred to as the business unit or department), is the primary hierarchy to represent an organisation’s structure.
• Location. A user’s geographic location.
• Position. A user’s job title or role.
• Cost Centre. Used to organise users into business units for internal billing and financial tracking (e.g. training spend).
• Grade. A user’s level within the organisation often based on pay grade.

Within the CSV file, OUs are represented as path based strings. Here are some examples:

• /division/civica/cm group
• /division/civica/content master
• /location/united states/washington/redmond
• /location/united states/california/los angeles

Account states

User accounts can be in the active or inactive state. To specify the account state, in the Account state column, enter active or inactive. If you omit this column, accounts default to the active state.

Login mode

Each lms instance can be configured to use SSO or Forms authentication, or a hybrid of the two authentication modes (see the article - Explained: Using Single Sign-On (SSO) with Civica Learning).

Where your lms uses hybrid authentication, when importing users, you need to specify the type of authentication that the new user accounts should use. This is done using the Login mode column in the CSV import file. The values you can set for Login mode are as follows:

• sso - where an account will use SSO authentication
• forms - where an account will use Forms authentication

Note: Where your lms instance is configured to use hybrid authentication, the bulk user import template file, which can be downloaded from the Import users dialog, will automatically include the Login mode column. Where you do not specify the login mode for a user, the user will  default to using SSO authentication.

Note: You can specify the Login mode for a user on the user's Profile page, using the Login mode option.

Sending welcome emails

When you first import and create user accounts, you can optionally choose to send each user a welcome email. To do so, in the Send welcome email column, enter Yes. This email uses one of the two following templates depending on whether or not you specify a password.

• Account - created with a specified password
• Account - created without a password

Related

• How To: Batch import user accounts
• How To: Batch delete user accounts
• How To: Batch export user accounts
• Explained: Using Single Sign-On (SSO) with Civica Learning