Upload users via CSV

Site: Titus Community
Course: Moodle for Admins
Book: Upload users via CSV
Printed by: Guest user
Date: Wednesday, 18 September 2019, 10:26 AM


Uploading multiple users to the platform using a CSV file

1. Introduction

There are a number of ways in which users can be created on a Moodle platform. The preferred method will vary depending upon how your organisation works. This document contains instructions on how to bulk upload users by uploading a populated CSV file into the platform. It is possible to use this same method to suspend accounts, update existing account information and more.

2. Uploading Users

When uploading users to the platform via a CSV file there are certain required fields that must be included in this file along with a number of additional optional fields that can be included in order to auto enrol users into courses and groups etc.

CSV = Comma separated values

CSV files are most commonly associated with spreadsheet editing software such as Microsoft Excel. When creating a new CSV file from scratch it is best advised to create a new spreadsheet document first within Excel, enter your user information then when ready to import, save the file as a CSV file (not an XLS file which is default for Microsoft Excel).

It is worth noting that you should avoid using special characters in field information such as quotes or commas.

2.1. Required fields

The following user identification fields (column headers) are required when uploading a CSV file.

username, firstname, lastname, email

When a CSV file is uploaded, validity checks are performed for:

  • Username can only contain alphabetical lowercase letters , numbers, hypen '-', underscore '_', period '.', or at-sign '@'
  • Email is in the form: name@example.com

2.2. Passwords

The password field is not a required field but if included it should meet the requirements for the site’s Password Policy found under Site administration -> Security -> Site Policies.

The password field is optional if the 'New user password' setting on the upload screen is set to "Create password if needed and send via email" but is required if the setting will be set to "Field required in file".

2.3. Force Password Change

To force users to have to change their passwords once they’ve logged in, set the password to “changeme”. If left blank, a password will be generated for each user (during the next Cron job) and welcome emails sent out if this setting is ticked upon CSV upload. The text for the welcome email is in the language settings in Site administration > Language > Language customisation with a String identifier of 'newusernewpasswordtext'.

2.4. Enrolment fields

You may optionally enrol users in already existing courses using manual enrolment. Manual enrolment must be enabled from within a course in order for this to work when uploading a CSV file.

You can use fields in the upload file of this type:

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

The headings above that can be used in the CSV file, each (they must) have a numerical suffix attached to them, meaning you can manually enrol users to multiple courses if required.

  • course# - This is the shortname (not fullname) of the course. Providing the course is present, the user will be enrolled in that course. This field is the ONLY required field for a successful enrolment. All the others are optional.
  • type# - This sets the role to be used for the enrolment. A value of 1 is default course role (normally Student), 2 is legacy Teacher role and 3 is legacy Non-editing Teacher.
  • role# - This may be used to specify roles directly, using either role short name or the role id (numeric names of roles are not supported). Usually you will use the role name that is the shortname of the role as defined in Users > Permissions > Define roles, eg. student, editingteacher. If the role column is left out, the users will be enrolled in the course with the default role, which is normally Student.
  • group# - This may be used to assign users to groups in a course, using the group name or id (numeric group names are not supported). If the group does not already exist, it will be created.
  • enrolperiod# This may be used to set the enrolment duration, in days, for each course. If not explicitly set here, all the users will get the duration as set in the Manual enrolment method of the course (which defaults to 0 - meaning unlimited.)
  • enrolstatus# - This is set to active by default for any newly enrolled users. If set to 1 it will suspend users in the course. If a 0 is entered in this column then a user will be enrolled in this course but set as inactive/suspended.

2.5. Optional user fields

You are able to to provide one or more of these optional user fields in your CSV file below.

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

Most of these above are user profile fields or user preference fields that belong to the user profile and are the filled in either by the user or upon creation. Some of these fields require specific formats.

Please note that commas within a field must be encoded as &#44 - the script will decode these back to commas. For Boolean fields (true or false) with only two values, use 0 for false and 1 for true.

Key optional field formats include:

  • country - You must use the country TWO LETTER CODE, in upper case, eg AU,ES,GB,US. These are all UPPER CASE.
  • lang - You must use the two letter (or extended four letter) code as defined in the Moodle language packs, e.g. en, es, en_us, de, in Site administration > Language > Language packs.
  • auth - The auth field must be used if the site uses an alternative authentication method, such as LDAP, as otherwise the authentication method will default to manual and users using a different authentication method won't be able to login. Use the shortname codes defined in Plugins > Authentication for the various types, e.g. manual, nlogin, ldap, cas, mnet, db, none. If you do not include an auth column, then newly created users will be created with the manual account type.
  • timezone - Should be in the format as found in the Location settings in terms of Zone/Region, eg. Australia/Sydney, Asia/Kathmandu, Europe/Madrid, etc. The entry is case sensitive so Europe/London will work but europe/london will not.

2.6. Cohort membership assignment

You can also assign users to any already existing Cohort (a cohort is a site level group) by using only the "username" and the "Cohort ID" with just two fields in the file. Note that this is an exception to the usual case where the firstname, lastname and email address of the user are required.

  • cohort# - This is the format to use to add a user into a cohort. You are able to add users into multiple cohorts using a numerical suffix, e.g. cohort1, cohort2, etc.

Internal cohort id numbers or the non-numeric Cohort IDs of existing cohorts must be used (do not use the full name of the cohort.) (Note that cohort id is what is usually known elsewhere as the "shortname".)

Here is an example CSV file:


2.7. Set system roles

Users may also be assigned to already defined system roles, using the shortname of the system role as defined in Site administration > Users > Permissions > Define roles (only for roles with a system context defined.)

sysrole1, sysrole2, sysrole3