Page Comparison

The upload users tool allows a System Administrator to perform multiple tasks at once, including but not limited to:

...

To upload users:

1. Create a CSV (comma separated values) file that contains the user informationDetails about the valid format for the CSV file can be found later in this article.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 uploadthe "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.

...

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

...

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

Image Removed

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:

...

.

...

...

Advanced Capabilities

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

...

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

Image Removed

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 ArticlesRelated Articles

• Creating a CSV File for User Uploads
• Scheduling User Uploads
• /wiki/spaces/Healthcare/pages/34850644
• Uploading Users Fails Due to Duplicate Emails
• Managing Custom User Profile Fields

...