Upload & Manage Users Using a CSV Text File
This article provides the information you need to successfully upload & create multiple user accounts to your Lambda Learn LMS using a .CSV (comma separated values) text file.
TOPICS
Upload User Process Using a CSV File
There are multiple methods to bulk create and manage user accounts in your Lambda Learn LMS. The simplest method is to create a file commonly referred to as a .csv (comma separated values) text file and to upload it to your LMS. With this method you can accomplish several tasks, such as, enrol users in multiple courses with course specific roles, to updating user information in the User profile, even to "deleting" users from your site.
The following are the basic steps you take in the process of uploading users using a CSV text file:
STEP 1: Create the CSV Text File
‘Flat file’ is the name of a simple data file formatted so that each row contains one user account, and each column contains values for a particular field of the account. The flat file can be created using a simple text editor, such as Notepad++, or using a spreadsheet such as MS Excel or Google Sheets.
Required Profile Fields
Each new user account on a Lambda Learn site requires the following minimum information: username, firstname, lastname, email. The screenshot below shows you what a basic user upload csv text file looks like in a text editor.
It is important to keep in mind that each value is separated by a comma - with NO additional space before or after the commas.
When using a spreadsheet your file would look like this:
 |
NOTE |
|
As you already are likely to know, unless you consciously select a specific file format, your software will save a newly created file in its own default format - i.e. as .txt in Notepad++; and as .xsl in Excel.
When creating your file using either of these programs, you must save it as a .csv file type.
|
Optional Profile Fields
More commonly, organizations like to keep some further information as part of their users’ profiles. To provide values other than the default you can include one or more of these optional user fields:
| password,institution,department,city,country,lang,auth,timezone,idnumber,icq,phone1,phone2,address,url,description,mailformat,maildisplay,maildigest,htmleditor,autosubscribe,interests,theme |
Use these fields if you want to add additional information to user profiles
| country - use the country TWO LETTER CODE, in upper case, eg AU,ES,GB,US. These are all UPPER CASE. Using "au" or "es" or "USA" 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. |
| lang - use the two letter (or extended four lettter) code as defined in the Moodle language packs, e.g. en, es, en_us, de, in Site administration > Language > Language packs. |
|
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.
Timezone setting is need for: mailformat, maildisplay, htmleditor, autosubscribe.
|
| maildigest To prevent users from receiving a large number of emails from courses or forced subscription forums use the maildigest. The options for this field are 0 = No digest, 1 = Complete digest and 2 = Digest with just subjects. |
| maildisplay allows you to set the email display option for a user. The options for this field are 0 = Hide my email address from non-privileged users, 1 = Allow everyone to see my email address and 2 = Allow only other course members to see my email address. |
| theme User themes may be added by using 'classic', 'boost' or the name of any other installed theme. |
|
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 auth method won't be able to log in. 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.
You can set "auth" to "nologin" in your csv file which will mean that then created users cannot login.
|
In order for the LMS to know which exact fields in the user profiles will be populated with the data in our file, a header row indicating what field data is carried in each column needs to be inserted to the very top, as shown in yellow highlight in the image below:
|
NOTE |
| The ordering of the columns do not matter, so long as the correct field names are written to the top of each column. |
User Passwords
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".
The password field is required if the setting is "Field required in file".
If included, values should meet the requirements you have set for your 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 (during the next Cron job) and welcome e-mails sent out. The text for the welcome e-mail is in the language settings in Site administration > Language > Language customisation with a String identifier of 'newusernewpasswordtext'.
Custom Profile Fields
These are optional and depend on whether you have created any custom profile fields in your site. The name of the header in file is of the form 'profile_field_xxxxx' where xxxx is the unique shortname of custom user profile field name as you created it.
The field name should match the case of the profile field shortname. So, for instance if the shortname of your custom profile field is all upper case, for example, DOB, then use a header of profile_field_DOB to match the case, not profile_field_dob, which will produce a "is not a valid field name" error.
Likewise, a mixed case shortname such as Dob should have a header of profile_field_Dob. (The exception to this is if the shortname is all lower case, then any case will work in the field header, which is a historical quirk: but best practice is to match the case and you will avoid errors.)
For custom profile fields that are dates, use the ISO standard format YYYY-MM-DD, eg. 2014-06-19 which will then be properly localized in the interfaced. For example, a field called dohire for "date of hire", the fields could be:
username,firstname,lastname,email,profile_field_dohire
blumbergh,Bill,Lumbergh,blumbergh@example.com,1990-02-19
pgibbons,Peter,BGibbons,pgibbons@example.com,1996-06-05
tsmykowski,Tom,Smykowski,tsmykowski@example.com,1970-01-01 |
Enrolment Fields
You may optionally enrol users in already existing courses using manual enrolment. Only manual enrolment is done this way; if the manual enrolment method is disabled in a course, then no enrol is done.
You add fields in the upload file of this type:
| course1,type1,role1,group1,enroltimestart1,enrolperiod1,enrolstatus1,course2,type2,role2,group2,enroltimestart2,enrolperiod2,enrolstatus2 |
Use these fields if you also want to enrol users as you upload them
| course# is the shortname of the course, if present the user will be enrolled in that course. Do not use the fullname of the course or it will generate an error. This field is the ONLY required field for a succesful enrolment. All the others are optional. |
| type# sets the role to be used for the enrolment. A value of 1 is default course role, 2 is legacy Teacher role and 3 is legacy Non-editing Teacher. |
| role# 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 enroled in the course with the default role, which is normally student. |
| group# may be used to assign users to groups in course, using name or id (numeric group names are not supported). NOTE: if the group does not already exist, it will be created. |
| enroltimestart# may be used to set the enrolment start time, for each course. If not explicitly set here, the enrolment start time is set to be today. |
| enrolperiod# 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# is optional as by default all newly enrolled users are set to active. If used a value of 1, it will suspend users in the course and if a user is previously set as inactive / suspended then a value of 0 will unsuspend them and make them active again. |
For details on bulk user creation and course enrolment using a *.csv text file, see Create and Enrol Users with a CSV File.
|
NOTE |
|
Header fields must have a numeric suffix such that type1,role1,group1,enrolperiod1 and enrolstatus1 all apply to course1 for course1 to coursen.
Even if you are just doing one course enrolment, you must still use the number 1 on the heading name, i.e. course1,role1, etc. Do not use the bare headings without numbers, e.g. course,role, etc as those will generate an error.
|
Cohort Membership Assignment
You can assign users to any already existing Cohort 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# is the form to use and like enrolment in courses, you have to add a number to each header, so cohort1,cohort2, etc.
Internal cohort id numbers or non-numeric Cohort IDs of existing cohorts must be used; do not use the full name are not allowed. (Note that cohort id is what is usually known elsewhere as the "shortname".)
Here is a sample CSV file:
username,cohort1,cohort2
student1,nursing,Springclass
student2,nursing,Springclass
student3,nursing,Springclass |
When your file is ready, proceed to the next step of file upload.
STEP 2: Upload the CSV
To start the upload process, navigate to Site administration > Users > Accounts > Upload users.
On the Upload users page that opens, click on the 'Choose a file...' button and navigate to the csv file you want to upload. There will be additional settings, but you may leave those as their default values.
Confirm that you have selected the correct file, and click the ‘Upload users’ button.
 |
TIP
|
|
As a best practice, we strongly recommend that you test the upload process with a file that only contains the top 3-4 rows of your master user data file, before going ahead with uploading the complete user data.
This test upload will give you the chance to catch any glitches in the process and to review what the resulting new user accounts will look like.
After confirming that these initial accounts were created as intended, you will be ready to upload the complete file.
|
STEP 3. PREVIEW UPLOADED DATA & CONFIGURE SETTINGS
Once your file has been uploaded, you will be presented with a preview of the data that has been uploaded.
Users Preview
The preview window gives you a glimpse into the end result. This is the place to catch major formatting-related issues.
Upload Users Settings
These settings determine how the data in your file will be processed. Below is a brief overview of these settings:
 |
There are various settings to better control the desired upload behaviour. These settings are found on the "Upload users preview" page.
|
Upload type
The Upload type specifies how to handle existing accounts.
- Add new only, skip existing users is the default Lambda Learn upload type. It creates a new user account for each new record in the uploaded file. If an existing username is found in the uploaded file matches an existing username, that record is skipped. By skipping the existing user account, the data in the existing record is not touched (in contrast to the "Add new and update existing users" option) and a second new user account is not created (in contrast to the "Add all, append number to usernames if needed" option).
- Add all, append number to usernames if needed creates a new user account for each record in the uploaded file. If an existing user account is found, a new account will be created with a number appended to the username. For example, if a user account for username 'jsmith' already exists and a new record in the uploaded file contains a record forusername 'jsmith' an additional user account is created with a 1 appended to the username to produce user 'jsmith1'.
- Add new and update existing users creates a new user account for each new user in the upload file. If an existing user account with the same username is found, the account information is updated by the data in the uploaded file.
- Update existing users only ignores any new users found in the upload file and updates the user account if a matching username record is found in the uploaded file.
|
|
New user password
When creating a new user account, Lambda Learn can create a new password (if one is not provided) or require a password in the uploaded file.
- Create password if needed and send via email creates a random default password for each new user account if one is not provided in the uploaded file, and emails the user their user information and new password.
- Field required in file requires that a password be provided in the uploaded file in order. If a password is not provided, an error is generated and the user account is not created. No notification of this user information or password is sent to the user.
|
|
Standardise usernames
Standardise usernames is used by default to convert the username to all lower case and to strip out illegal characters. It is possible to not standardise the usernames; however, doing so is not recommended.
- Yes standardizes usernames found in the uploaded file before updating existing or creating new user accounts so that the username contains only lowercase letters and numbers.
- No skips standardising usernames found in the uploaded file so that the newly created or updated usernames will be exactly as they are in the uploaded file (not recommended).
|
|
Select for bulk user actions
By default, no users are selected.
- No No users are selected.
- New users Only newly created users are selected for bulk user actions.
- Updated users Only updated user accounts are selected for bulk user actions.
- All users All users found (existing updated users and newly created user accounts) in the uploaded file are selected for bulk user actions.
|
Default Values
This section of the screen offers you quick access into the default values for user profiles on your site. This gives you the option to modify the values so that the profiles of the newly uploaded/updated users will reflect these modifications.
One setting worth noting is the first row in this section which allows you to ‘Choose an authentication method’. If you set different authentication methods to be used with different groups of users on your site, you have the option to set these different preferences for groups of users ‘per flat file’.
Step 4: Confirm & Review Results
This is the moment when the user accounts are actually created or updated. Once the process is complete, you are presented with a ‘results’ screen. In addition to listing the new/updated users, the bottom of this screen will give you the total number of users created, as well as if there were any errors.
BEST PRACTICES & COMMON MISTAKES
-
Ensure that you have saved the file in .csv format.
-
Ensure that the field names are entered correctly on the top row of the .csv file.
-
If using a text editor to create your CSV file, remember to place consecutive commas with no space between when certain fields are empty for certain users, in order to correctly match the user information to the correct field names.
-
Country code convention: use two letter abbreviation (eg. United States = us, Canada = ca)
-
Field size limits must be within your site maximum.
-
Duplicate email entries used without selecting ‘update existing accounts’ as upload type will cause user account conflicts and cause the upload to fail.
-
We recommend using UTF-8 encoding on the file.
