Page Comparison

Step-by-step Guide

To upload users:

1. Create a CSV (see Creating a CSV File for User Uploads for more details)
2. Go to Site administration > Users > Accounts > Upload users
3. Add the CSV file to the "File" area
4. Click on the "Upload users" button
5. Follow the instructions

Note that if you are uploading users on a regular basis, you should consider Scheduling User Uploads instead of manually uploading your users. The scheduled user uploads automates the process for you.

Below are some tips and additional details depending on what you are trying to accomplish with the "Upload users" tool

Selecting a Site (for Multi-Site Systems Only)

If your learning environment is configured as a /wiki/spaces/Healthcare/pages/34844303, you will be prompted to select a site. This is a security and error prevention measures to ensure that an administrator, and in particular a Site Administrator, cannot change the information for users not in their site. 

When updating users, the site selection is recursive. In other words, if you have a site structure as per the following (see below) and select "Ontario" for the "Site" setting, any user in "Ontario", "Hospital A" and "Hospital B" will be updated as per the information in your CSV file. Users in "Quebec" or elsewhere in Canada would not be updated.

• • Canada
  • Canada > Ontario
    • Canada > Ontario > Hospital A
    • Canada > Ontario > Hospital B
  • Canada > Quebec

Image Modified

Updating Existing Accounts

By default, your learning environment adds new user accounts and skips existing users lines where the username matches an existing account. Set "Upload Type" to "Add new and update existing users" if you want to update existing user accounts.

• Add all, append number to usernames if needed
• Add new and update existing users
• Update existing users only

Warning: errors updating existing accounts can affect your users badly. Be careful when using the options to update.

Additional Options

There are also fields settings to force password change, allow renames, allow deletes, prevent e-mail address duplicates, standardize usernames, and select for bulk operations (new users. updated users, all users).

The "standardize usernames" option folds usernames to lowercase and strips out illegal characters. This is roughly equivalent to:

$username = preg_replace('/[^-\.@_a-z0-9]/', , $username);

Set Default User Values

You may be able to set default user field values, if the fields were not included in the uploaded file on this page.

Upload user results

After accepting the preview settings by clicking on "Upload users", you should see an "Upload users" results screen. This screen will show you any exceptions or changes that were made to each user in the upload process. For example if you were updating user information, the updated information will be shown. Or if a user was not added that record will be highlighted.

The screen will summarize how many users were uploaded or updated, indicate the number of weak passwords and the number of errors.

File Formats for the Upload Users File

The upload users file has fields separated by a comma (or other delimiter) ONLY - no space. The first line contains the valid field names. The rest of the lines (records) contain information about each user.

Avoid special characters in field information like quotes or other commas. Test a file with only one record before a large upload. Remember, there are other ways to authenticate users on your site or enroll users in a course.

You can use a spreadsheet program such as Microsoft Excel to create the file with the required columns and fields, and then save the file as "CSV (comma delimited)". These files can be opened with simple text editors for verification.

Advanced Capabilities

The following codes will be processed by the upload tool when included as default values:

• %l - will be replaced by the lastname
• %f - will be replaced by the firstname
• %u - will be replaced by the username
• %% - will be replaced by the %

The following modifiers are allowed between the percent sign (%) and any code letter (l, f or u) :

• (-) minus sign - the information specified by the code letter will be converted to lowercase
• (+) plus sign - the information specified by the code letter will be converted to UPPERCASE
• (~) tilde sign - the information specified by the code letter will be converted to Title Case
• a decimal number - the information specified by the code letter will be truncated to that many characters

For example, if the firstname is John and the lastname is Doe, the following values will be obtained with the specified codes:

• %l%f = DoeJohn
• %l%1f = DoeJ
• %-l%+f = doeJOHN
• %-f_%-l = john_doe
• http://www.example.com/~%u/ results in http://www.example.com/~jdoe/ (if the username is jdoe or %-1f%-l)

Code processing is done only on default values, and not on the values retrieved from the CSV file.

In order to create correct usernames, the username is always converted to lowercase. Moreover, if the "Allow extended characters in usernames" option in the Site policies page is off, characters different to letters, digits, dash (-) and dot (.) are removed. For example if the firstname is John Jr. and the lastname is Doe, the username %-f_%-l will produce john jr._doe when "Allow extended characters in usernames" is on, and johnjr.doe when off. (By default, "Allow extended characters in usernames" is always off.)

When the "New username duplicate handling" setting is set to "Append counter", an auto-increment counter will be appended to duplicate usernames produced by the template. For example, if the CSV file contains the users named John Doe, Jane Doe and Jenny Doe without explicit usernames, the default username is %-1f%-l and New username duplicate handling is set to Append counter, then the usernames produced will be jdoe, jdoe2 and jdoe3.

User Mapping & "Strict" Control

You can specify a "key" other than username when updating users. This is useful in the event that your HRIS does not track the user's username, which is typically only in Active Directory. You could for example use this feature to upload users by using their Employee ID as demonstrated in the screenshot below. The "key" must be unique across the system (for single-site systems ) and unique within a site (for /wiki/spaces/Healthcare/pages/34844303). If more than "key is found during the upload, the system will report an error.

If you do not have the username in the CSV file when uploading users, simply map the column from the CSV file (which is displayed in the LEFT pulldown menu next to the "User mapping" field in the screenshot below) to a database column in the learning environment (which is displayed in the RIGHT pulldown menu next to the "User mapping" field in the screenshot below) using the "User mapping" option in the "Upload users" wizard.

If you enable the "Strict" option, the user mapping will ONLY be done on the Employee ID in the example below. In other words, if the Employee ID in the CSV file does not match an Employee ID in the database, then the system will skip the user. If the "Strict" option is disabled, the system will first attempt to match the users by Employee ID and if it doesn't find a match, it'll then make a second attempt and try to match the skipped users by mapping the username in the CSV to the username in the database.

(Note that the username is still required when creating users and as such, this feature is only available when updating users.)

Image Modified