Uploading Users

The upload users tool allows an administrator to perform multiple tasks at once, including but not limited to:

• Adding users
• Modifying users
• Suspending or deleting users
• Renaming users
• Resetting users' password
• Enrolling users in courses or programs
• Adding users to cohorts, which can represent groups, departments, institutions or other logical groupings
• Specifying the preferred theme for users (multi-site only)

Step-by-step Guide

To upload users:

1. Create a CSV (comma separated values) file that contains the user information
2. Go to Site administration > Users > Accounts > Upload users
3. Add the file to upload
4. Follow the instructions

Note that it is usually not necessary to manually upload users in bulk with Upload users. To keep maintenance work down, you should first consider automating this procedure via the "Automated Upload" functionality provided by Dual Code.

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

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.

Valid Upload File for Testing

Here is an example of a simple valid upload file:

username,password,firstname,lastname,email,course1,group1,cohort1
jonest,verysecret,Tom,Jones,jonest@someplace.edu,math102,Section 1,year 3
reznort,somesecret,Trent,Reznor,reznort@someplace.edu,math102,Section 3,year 4

We strongly recommend that you test a file that contains fields you proposed to use with one user before attempting a file upload for the first time.

Valid Fields

The following fields are required when adding users:

username,firstname,lastname,email

The password field is optional if the "Create password if needed" setting is chosen (default).

• If the password is included, values should meet the requirements for the site's Password policy
• To force password change for a particular user, set the password field to "changeme"
• If omitted, a password will be generated for each user and welcome e-mails will be sent out

The following fields are optional when adding users. To provide values other than the default for these optional fields, include one or more of these in your upload file:

institution,department,city,country,lang,auth,timezone,idnumber,icq,phone1,phone2,address,url,description,mailformat,maildisplay,htmleditor,autosubscribe

Here are some additional tips regarding the optional fields

• Auth: The valid values are "manual", "ldap", "oauth2" and "saml2". These values are case-sensitive.
• Country: use a country TWO LETTER CODE, such as "CA" for Canada
• Some fields have a maximum number of characters that are allowed (notably institution should be at most 40 characters long).
• Maildisplay, htmleditor and autosubscribe can be set from an import screen

Custom User Fields

You can find more information regarding custom user fields here. 

When uploading an Associated input field, please ensure to use the custom profile name (e.g. profile_field_employeeID) instead of the target field (e.g. idnumber). 

Custom User Field Names

For this example, let's assume a custom user field name called "genre" (i.e. the unique shortname for that field).

When uploading information for a custom user field, you should use the following convention in the header of the CSV file:

profile_field_genre

The custom field must exist before you run the upload function.

Dates in Custom User Fields

When adding a Date/Time custom user field, the date format must be YYYY-MM-DD. For example, to show a date of September 1, 2017, the date must be 2017-09-01.

Assigning a Theme

If your learning environment has multiple sites (e.g. see /wiki/spaces/Healthcare/pages/34844303), you can specify the theme to be used by individual users by using the "theme" column

theme

Each theme available in your system has a unique identifier, which is displayed in the theme's settings page. Using the example below (see image below), I would enter the value "adaptable" in the "theme" column in the CSV file to associate the user to the Adaptable theme.

Special Fields

Special fields are used for suspending or deleting.

suspended, deleted

Assigning System Roles

Users (usually System Administrators or Course Creators may also be assigned during and upload.

sysrole1,sysrole2,sysrole3

To assign the roles, you would use the "sysrole1" column. Multiple roles can be assigned to the same person using sysrole2, sysrole3, etc. fields. The numbers must go up in sequence starting at 1.

The values must be one of the following (case-sensitive):

• For the System Administrator role, use "manager" (without the quotes)
• For the Supervisor role, use "supervisor"
• For the Course Creator role, use "coursecreator"

You can also unassign system roles by entering the same shortname of that role prefixed with a minus symbol: '-'. If the user is currently assigned to that role, they are removed from it. If the user is not currently assigned to that system role, the field value is ignored. However, the field value must refer to a system role that does exist on the system, otherwise an error will occur.

Enrolment Fields

To register users in programs, simply enter the program ID (i.e. the auto-incremented ID generated by the database, not the "ID Number" field that you enter in the web form) using the following headers in the CSV file:

program1,program2,program3

To enrol users in courses, simply enter the shortname of the course using the following headers in the CSV file:

course1,type1,role1,group1,enrolperiod1,course2,type2,role2,group2,enrolperiod2

In the above example, type refers to the role to be used for associated course enrolment. Value 1 is default course role, 2 is legacy Teacher role and 3 is legacy Non-editing Teacher. You can use role field instead to specify roles directly. Use either the role short name or id (numeric names of roles are not supported).

Users may also be assigned to groups in courses (group1 in course1, group2 in course2, etc.). A group is identified by name or id (numeric group names are not supported)

You can set the enrolment duration, in days, for each course (enrolperiod1 for course1, enrolperiod2 for course2, etc.).

Cohort Field

You can add users to cohorts. Cohort ID numbers or non-numeric cohort IDs of existing cohorts must be used (names are not allowed).

cohort1

Other Rules

There are a few other rules to keep in mind when preparing your CSV file:

• Commas within a field must be encoded as &#44 - the script will decode these back to commas
• For Boolean fields, use 0 for false and 1 for true
• To prevent users from receiving a large number of e-mails from courses or forced subscription forums, use the maildigest field. The options for this field are:
  • 0 = No digest
  • 1 = Complete digest
  • 2 = Digest with just subjects

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.)

Deleting Accounts

If the "deleted" field is present, users with value 1 for it will be deleted. In this case, all the fields may be omitted, except for username. After uploading the file, be sure to change the "Upload type" to "Update existing users only" and the "Allow deletes" option to "Yes".

Tip: When you delete a user, you delete all the information associated with the user, including grades, certificates of completion, and their history. It is therefore recommended to suspend users rather than deleting them. A similar field is called "suspended" is available for suspending. This enables a user account to be temporarily disabled rather than completely removed.

Deleting and uploading accounts could be done with a single CSV file. For example, the following file will add the user Tom Jones and delete the user reznort:

username,firstname,lastname,deleted
jonest,Tom,Jones,0
reznort,,,1

Renaming Users

The username is considered a key in the system for many functions such as uploading learning records and attendance records. You can change the value of the username just like any other field, as long as "Allow renames" is set to "Yes'.

In other words, if you had to change the username for a user where username=jsmith and idnumber=12345, you could create the following CSV file. In the "User mapping" section you would map the idnumber from the CSV file to the idnumber field in the system, and set "Allow renames" to "Yes". This would change the username from jsmith to jdoe. (Note that while "idnumber" is suggested in here, you can use any unique identifier in the user's profile.)

username,idnumber
jdoe,12345

Tip: Moodle "out of the box" suggests to use a field called "oldusername" to rename users. This is because Moodle "out of the box" doesn't support user mapping. If you do have a CSV file with the "oldusername" column because you've migrated from Moodle "out of the box" to Dual Code's system, you can still rename users by ensuring you set the proper mapping and other fields in the user upload wizard properly as per the screenshot below.

Encoding File Format

On the initial "Upload user" screen, you may select the file encoding format from a pull down list. These include UTF-8 (the default), ASCII, ISO-8859-1 to ISO-8859-11 or any one of over 36 formats. You need to make sure that your CSV file matches the encoding format that you select here.

Other Hints

Spreadsheet

If you use a spreadsheet program such as Microsoft Excel to create your CSV file, check the resulting output in a text editor before you upload it. It is possible to get trailing commas on each line from an empty field if you have added and deleted columns of information prior to saving the final file. Also check the character encoding. A CSV file is a simple text file (ASCII or Unicode) that can be used to upload user accounts.

Excel translates passwords that begin with - (minus) or + (plus) as zero, even when saving as CSV and saying "Yes" to "Keep this format, and leave out any incompatible features." Check for this before uploading, as a zero halts the upload process.

If you use a formula in Excel to create fields (for example, the concatenate function to create a username), then remember to copy the cells with the formula and use special paste with values checked to make them into an acceptable data for a CSV file.

The upload will also fail if you have trailing spaces at the end of your data fields. Often, this cannot be removed with a simple Find " " and Replace with "". If information has been copied from web sources than it is possible to include non-breaking spaces which will prevent your upload from being completed correctly. To find these invisible spaces, use the Find and Replace function in Excel. In the find field, hold alt and type 0160. Leave the replace field blank.

Country

The country should be written as a two letter code, in capitals. For example, use CE for Canada or NL for the Netherlands. Using "ca" or "nl" as a country code will result in a database error.

If you are having trouble working out the two-letter code for a country, you can consult the list of country names and code elements available on the ISO Website. A common error is to use UK for United Kingdom; it should be GB.

Field Size Limits

Some fields have maximum character lengths. Typically the file will import to the preview list screen but not finish the process. Common fields to cause problems are "Institution" which is limited to 40 characters, and "City", also limited (20 characters). The error will be "User not added - error".

All Fields

All the fields that are valid are listed below, except for any custom fields you may have created:

firstname, lastname, username, email, city, country, lang, timezone, mailformat, maildisplay, maildigest, htmleditor, ajax, autosubscribe ,institution, department, idnumber, skype, msn, aim, yahoo, icq, phone1, phone2, address, url, description, descriptionformat, password, auth, deleted, suspended, course1, type1, role1, group1, enrolperiod1, course2, type2, role2, group2, enrolperiod2, program1, program2, cohort1, cohort2

Related Articles

• Page:
  Uploading Users
• Page:
  Importing Users
• Page:
  Viewing the Results of a User Upload Job
• Page:
  Uploading Users Fails Due to Duplicate Emails

See Also

• Video: Moodle 2 Administration Adding users using a CSV file