Note: You are currently viewing documentation for Moodle 2.2. Up-to-date documentation for the latest stable version is available here: Upload users.

Upload users: Difference between revisions

From MoodleDocs
(Upload user process quick steps for those in a hurry)
 
(45 intermediate revisions by 12 users not shown)
Line 1: Line 1:
{{Accounts}}
{{Accounts}}
<p class="note">'''Please refer to [[TOC_with_notes#Accounts|these notes]] before editing this page.'''</p>
An administrator can upload multiple user accounts via text file in ''Settings > Site administration > Users > Accounts > Upload users''.
Location: ''Site administration > Users > Accounts > Upload users''
The upload users link allows the site administrator to load multiple user accounts from a text file as [[Authentication|authenticated users]] on the Moodle site.  


There are many robust options for uploading information (fields associated with a user) with this method: from enrolling users in multiple courses with course specific [[Roles|roles]] to updating user information in the [[User profile]] to deleting users from the site.
There are many robust options for uploading information (fields associated with a user) with this method: from enrolling users in multiple courses with course specific [[Roles|roles]] to updating user information in the [[User profile]] to deleting users from the site.


[[Image:Upload users preview.png|thumb|Upload users preview in Moodle 1.9]]
''Tip:'' It is usually not necessary to upload users in bulk with Upload users. To keep maintenance work down you should first explore forms of authentication that do not require manual maintenance, such as [[External database authentication|connecting to existing external databases]] or letting the users create their own accounts ([[Self enrolment]]). See [[Authentication]] for more information.


:''Tip:'' It is usually not necessary to upload users in bulk with Upload users. To keep maintenance work down you should first explore forms of authentication that do not require manual maintenance, such as [[External database authentication|connecting to existing external databases]] or letting the [[Internal enrolment|users create their own accounts]]. See [[Manage authentication]] for more information.
[[File:Upload users initial 2.0.JPG|thumb|center|Initial upload users screen 2.1]]


==Upload user process==
==Upload user process==
Line 22: Line 20:
# Returns to Upload users screen
# Returns to Upload users screen


==Updating users preview==
There are settings for the kind of Upload user function you want to perform on the "Upload users preview" page.
[[File:Upload users preview 2.0.JPG|thumb|center|Upload users preview in Moodle 2.x]]


==Upload users file format==
===Updating existing accounts===


* Each line contains fields '''separated''' by commas (or other delimiters) without quotes (") and no trailing delimiter
By default Moodle adds new user accounts and skips existing users lines where the <code>username</code> matches an existing account. Set "Upload Type" to '''Add  new and update existing users''', and existing user account will be updated.
* The first line is special, and contains fieldnames defining the format for the rest of the file.
*Add all, append number to usernames if needed
*Add new and update existing users
*Update existing users only
There are also fields settings to force password change, allow renames, allow deletes, prevent email address duplicates, standardise usernames and select for bulk operations(new users. updated users, all users).


'''Warning''': errors updating existing accounts can affect your users badly. Be careful when using the options to update.
===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 the the Upload users results screen.
[[File:Upload users results 2.0.JPG|thumb|center|The 2.0 results screen, everything went well]]
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 upload users file==
The upload files have their fields separated by a comma (or other delimiter).  The first line contains the valid field names.  The rest of the lines (records) contain information about each user.
'':Tip:'' If you are not an expert, 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 you site or enroll users in a course.
'':Tip:'' You can use a spread sheet program to create the file with the required columns and fields. 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:
Here is an example of a simple valid upload file:


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


===Fields that came be included===
===Fields that can be included===
'':Tip:'' 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.  demo.moodle.net might be a good place to see if your test file works.


*'''Required fields''': In any order
*'''Required fields''':  
:<p><code>username, firstname, lastname, email</code>
:<p><code>username, firstname, lastname, email</code>
:Validity checks are performed for:
:Validity checks are performed for:
Line 45: Line 71:
**If included, values should meet the requirements for the site's [[Site_policies#Password_policy|Password policy]]. To force password change for a particular user, set the password field to <code>changeme</code>.  
**If included, values should meet the requirements for the site's [[Site_policies#Password_policy|Password policy]]. To force password change for a particular user, set the password field to <code>changeme</code>.  
**If omitted, a password will be generated for each user (during the next Cron job) and welcome e-mails sent out (not working in v2.0.2?).
**If omitted, a password will be generated for each user (during the next Cron job) and welcome e-mails sent out (not working in v2.0.2?).
**Note: the text for the welcome e-mail is in the language settings.


*'''Optional fields''': To provide values other than the default include one or more of these
*'''Optional fields''': To provide values other than the default include one or more of these
:<p><code>institution, department, city, country, lang, auth, ajax, timezone, idnumber, icq, phone1, phone2, address, url, description, mailformat, maildisplay, emailstop, htmleditor, autosubscribe</code></p>
:<p><code>institution, department, city, country, lang, auth, ajax, timezone, idnumber, icq, phone1, phone2, address, url, description, mailformat, maildisplay, htmleditor, autosubscribe</code></p>
*Country- use a country TWO LETTER CODE
*Some fields have a maximum number of characters that are allowed (notably institution should be '''at most 40 characters''' long).  See hints below.
*Maildisplay, htmleditor and autosubscribe can be set from an import screen in Moodle 2.0.


*'''Custom profile field names''': (Optional). xxxxx is the real custom user profile field name (i.e. the unique shortname)
*'''Custom profile field names''': (Optional). xxxxx is the real custom user profile field name (i.e. the unique shortname)
:<p><code>profile_field_xxxxx</code></p>
:<p><code>profile_field_xxxxx</code></p>
: Create the custom fields BEFORE importing. Use the standard header. The "shortname" for your custom field is xxxxx (NB: as at v2.0.2, the shortname must be all lowercase, otherwise won't be recognised). The first record must include "profile_field_xxxxx".
: Create the custom fields BEFORE importing. Use the standard header. The "shortname" for your custom field is xxxxx (NB: as at v2.0.2, the shortname must be all lowercase, otherwise won't be recognised). The first record must include "profile_field_xxxxx".
:'''Example''': To create a custom field "genre", you must write a shortname "genre" in the new field, and write "profile_field_genre" in the header of the .csv file.
:'''Example''': To create a custom field "genre", you must write a shortname "genre" in the new field, and write "profile_field_genre" in the header of the .csv file.
: For custom profile fields that are a menu, use the corresponding menu number (index).
:'''Example''': if your custom field is department and there are three choices - HR, Marketing,Training- then HR would be 0, Marketing would be 1, and Training would be 2.


*'''Special fields''': Used for changing of usernames or deleting of users
*'''Special fields''': Used for changing of usernames or deleting of users
Line 58: Line 93:
   
   
*'''Enrolment fields''': (Optional):
*'''Enrolment fields''': (Optional):
:<p><code>course1, type1, role1, group1, enrolperiod1, course2, type2, role2, group2, enrolperiod2</code> etc.
:<code>course1, type1, role1, group1, enrolperiod1, course2, type2, role2, group2, enrolperiod2</code> etc.
**<code>course</code> is the "shortname" if present the user will be enrolled in those courses.
 
** <code>type</code> 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.
:*<code>course</code> is the "shortname" of the course, if present the user will be enrolled in those courses.
** You can use role field instead to specify roles directly - use either role short name or id (numeric names of roles are not supported).
:* <code>type</code> 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.
** Users may be also assigned to groups in course (group1 in course1, group2 in course2, etc.).
:* You can use role field instead to specify roles directly - use either role short name or id (numeric names of roles are not supported).
*** A group is identified by name or id (numeric group names are not supported).
:* Users may be also assigned to groups in course (group1 in course1, group2 in course2, etc.).
** From Moodle 2.0, you can set the enrolment duration, in days, for each course (<code>enrolperiod1</code> for <code>course1</code>, <code>enrolperiod2</code> for <code>course2</code>, 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 (<code>enrolperiod1</code> for <code>course1</code>, <code>enrolperiod2</code> for <code>course2</code>, etc.).
 
{{New features}}*'''Cohort field''': (Optional):
:<code>cohort1</code>
 
:Internal cohort id numbers or non-numeric Cohort IDs of existing cohorts must be used, names are not allowed.


Commas within  a field must be encoded as &#44 - the script will decode these back to commas.
Commas within  a field must be encoded as &#44 - the script will decode these back to commas.
Line 72: Line 113:
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.
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.


==Updating existing accounts==
==Advanced potentials of Upload user==
By default Moodle  creates new user accounts, and skips lines where the <code>username</code> matches an existing account. Set "Upload Type" to '''Add  new and update existing accounts''', and existing user account will be updated.
===Templates===


Include  fieldname <code>oldusername</code> to updating existing accounts and change usernames.  In the preview options, Set "Allow renames" to '''Yes''.
''Note: This section needs checking and updating if necessary for Moodle 2.0. Please do so and remove this note when finished.''
'''Warning''': errors updating existing accounts can affect your users badly. Be careful when using the options to update.
 
==After preview==
After the preprocessing, depending on the contents of the upload, the following may be available before final user creation
*Settings
** New user password
** Existing user details
** Existing user password
** Allow renames
** Allow deletes
** Prevent email addess duplicates
** Select for bulk operations
 
* Default values
** Authentication method: Manual account |no login | EMail-based self-registration
** Email display: Allow only other course members to see my email address | hide .. from everyone | allow anyone ...
** Email format Pretty HTML | plain text
** Email digest type: none|complete subjects
** Forum auto-subscribe: no |yes when  I post
** When editing text: use HTML| standard web forms
** AJAX and Javascript: yes|no
** city/town
** country
** timezone
** Preferred language
** Description
** Web page
** ID number
** Institution
** Department
** Phone
** Mobile Phone
** Address
 
==After results ==
Users which were not added, will NOT be auto-enrolled in courses
 
----
 
Open another moodle browser and
* Site administration
** Courses
*** Add/edit courses; select the category, and the course
* Course administration
** Users
*** Enrolled Users
**** Enrol users and select the users flagged from other window
 
==Templates==


The default values are processed as templates in which the following codes are allowed:
The default values are processed as templates in which the following codes are allowed:
Line 146: Line 138:
* %-l%+f = doeJOHN
* %-l%+f = doeJOHN
* %-f_%-l = john_doe
* %-f_%-l = john_doe
* http://www.example.com/~%u/ = http://www.example.com/~jdoe/ (if the username is jdoe or %-1f%-l)
*<nowiki> http://www.example.com/~%u/</nowiki> results in  <nowiki>http://www.example.com/~jdoe/</nowiki> (if the username is jdoe or %-1f%-l)


Template processing is done only on default values, and not on the values retrieved from the CSV file.
Template processing is done only on default values, and not on the values retrieved from the CSV file.
Line 152: Line 144:
In order to create correct Moodle 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.
In order to create correct Moodle 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.


When the "New username duplicate handling" setting is set to Append counter, an auto-increment counter will be append 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.  
When the "New username duplicate handling" setting is set to Append counter, an auto-increment counter will be append 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.
 


 
===Deleting accounts===
==Deleting accounts==


If the <code>deleted</code> field is present, users with value 1 for it will be deleted. In this case, all the fields may be omitted, except for <code>username</code>. After uploading the file, be sure to change the "Upload type" to "Update existing users only" and the "Allow deletes" option to "Yes".
If the <code>deleted</code> field is present, users with value 1 for it will be deleted. In this case, all the fields may be omitted, except for <code>username</code>. After uploading the file, be sure to change the "Upload type" to "Update existing users only" and the "Allow deletes" option to "Yes".
Line 164: Line 154:
  username, firstname, lastname, deleted
  username, firstname, lastname, deleted
  jonest, Tom, Jones, 0
  jonest, Tom, Jones, 0
  reznort, , , 1  
  reznort, , , 1


==Encoding==
==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.
In Moodle 1.8 the file must be UTF-8. In Moodle 1.9 onwards, the encoding may be selected from a large list, including ISO-8859-1.


==Hints==
==Hints==
Line 179: Line 168:


If you use a formula in Excel to create fields (for example, the concatenate function to create a user name), 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.
If you use a formula in Excel to create fields (for example, the concatenate function to create a user name), 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 can not 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===
===Country===
The country should be written as a two letter code, in capitals. For example, use BE for Belgium or NL for the Netherlands.  Using "be" or "nl" as a country code will result in a database error.
The country should be written as a two letter code, in capitals. For example, use BE for Belgium or NL for the Netherlands.  Using "be" or "nl" as a country code will result in a database error.
:''Tip:''  If you are having trouble working out the two-letter code for a country, you can consult this Moodle source code file /moodle/lang/en_utf8/countries.php [http://cvs.moodle.org/moodle/lang/en_utf8/countries.php?view=markup&pathrev=MOODLE_19_STABLE or click here for a 1.9 STABLE list].
:''Tip:''  If you are having trouble working out the two-letter code for a country, you can consult this Moodle source code file /moodle/lang/en_utf8/countries.php [http://cvs.moodle.org/moodle/lang/en_utf8/countries.php?view=markup&pathrev=MOODLE_19_STABLE or click here for a 1.9 STABLE list].
ISO Website: [http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm]
 
The full list of [http://www.iso.org/iso/country_names_and_code_elements country names and code elements] is also available on the ISO Website.
 
===Field size limits===
Some fields have maximum character lengths.  Typically the file will import to the preview list screen but not finish the process.  Turn on debug to see the fields that are too long.  Common fields to cause problems are "Institution" which is limited to 40 characters, and "City", also limited.  The error will be "User not added - error".
 
===All fields listed here===
: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, oldusername , deleted, course1, course2, course3, course4


== See also ==
== See also ==
Moodle Docs:
 
*[[Flat file]]
*[[Flat file]] enrolment
* [[User profile fields]] for details of how to include data about custom user profile fields in the upload users file


Using Moodle forum discussions:
Using Moodle forum discussions:
*[http://moodle.org/mod/forum/discuss.php?d=36851 Can I auto enroll from Excel?]
*[http://moodle.org/mod/forum/discuss.php?d=36851 Can I auto enroll from Excel?]
*[http://moodle.org/mod/forum/discuss.php?d=58215 Making Email Optional]
*[http://moodle.org/mod/forum/discuss.php?d=97903 Uploading users to custom roles]
*[http://moodle.org/mod/forum/discuss.php?d=97903 Uploading users to custom roles]
*[http://moodle.org/mod/forum/discuss.php?d=181259 User upload option: standardise usernames]
*[http://moodle.org/mod/forum/discuss.php?d=181259 User upload option: standardise usernames]
*[http://moodle.org/mod/forum/discuss.php?d=144569 Matriculacion con flat file csv] - discussion in Spanish
*[http://moodle.org/mod/forum/discuss.php?d=144569 Matriculacion con flat file csv] - discussion in Spanish
[[Category:Authentication]]
[[Category:Enrolment]]
[[Category:Groups]]


[[fr:Importer des utilisateurs]]
[[fr:Importer des utilisateurs]]
[[ja:ユーザのアップロード]]
[[ja:ユーザのアップロード]]
[[zh:上传用户]]
[[de:Nutzerliste hochladen]]
[[ru:Загрузка пользователей]]

Latest revision as of 01:18, 24 January 2013

An administrator can upload multiple user accounts via text file in Settings > Site administration > Users > Accounts > Upload users.

There are many robust options for uploading information (fields associated with a user) with this method: from enrolling users in multiple courses with course specific roles to updating user information in the User profile to deleting users from the site.

Tip: It is usually not necessary to upload users in bulk with Upload users. To keep maintenance work down you should first explore forms of authentication that do not require manual maintenance, such as connecting to existing external databases or letting the users create their own accounts (Self enrolment). See Authentication for more information.

Initial upload users screen 2.1

Upload user process

Here is an outline of the process:

  1. Create file for uploading
  2. Go to Settings > Site administration > Users > Accounts > Upload users
  3. Add file to upload
  4. Upload users preview - check settings and default user profile settings
  5. Upload users preview - click "Upload users"
  6. Upload users results - shows list of users, exceptions made in upload and summary of number of users
  7. Upload users results - click "Continue"
  8. Returns to Upload users screen

Updating users preview

There are settings for the kind of Upload user function you want to perform on the "Upload users preview" page.

Upload users preview in Moodle 2.x

Updating existing accounts

By default Moodle 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, and existing user account will be updated.

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

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

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

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 the the Upload users results screen.

The 2.0 results screen, everything went well

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 upload users file

The upload files have their fields separated by a comma (or other delimiter). The first line contains the valid field names. The rest of the lines (records) contain information about each user.

:Tip: If you are not an expert, 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 you site or enroll users in a course.

:Tip: You can use a spread sheet program to create the file with the required columns and fields. 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

Fields that can be included

:Tip: 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. demo.moodle.net might be a good place to see if your test file works.

  • Required fields:

username, firstname, lastname, email

Validity checks are performed for:
  1. username can only contain alphabetical lowercase letters , numbers, hypen '-', underscore '_', period '.', or at-sign '@'
  2. email is in the form: name@example.com .

  • Password field: "password" field is optional if "Create password if needed" setting is chosen (default).
    • If 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 (during the next Cron job) and welcome e-mails sent out (not working in v2.0.2?).
    • Note: the text for the welcome e-mail is in the language settings.
  • Optional fields: To provide values other than the default include one or more of these

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

  • Country- use a country TWO LETTER CODE
  • Some fields have a maximum number of characters that are allowed (notably institution should be at most 40 characters long). See hints below.
  • Maildisplay, htmleditor and autosubscribe can be set from an import screen in Moodle 2.0.
  • Custom profile field names: (Optional). xxxxx is the real custom user profile field name (i.e. the unique shortname)

profile_field_xxxxx

Create the custom fields BEFORE importing. Use the standard header. The "shortname" for your custom field is xxxxx (NB: as at v2.0.2, the shortname must be all lowercase, otherwise won't be recognised). The first record must include "profile_field_xxxxx".
Example: To create a custom field "genre", you must write a shortname "genre" in the new field, and write "profile_field_genre" in the header of the .csv file.
For custom profile fields that are a menu, use the corresponding menu number (index).
Example: if your custom field is department and there are three choices - HR, Marketing,Training- then HR would be 0, Marketing would be 1, and Training would be 2.
  • Special fields: Used for changing of usernames or deleting of users

oldusername, deleted

  • Enrolment fields: (Optional):
course1, type1, role1, group1, enrolperiod1, course2, type2, role2, group2, enrolperiod2 etc.
  • course is the "shortname" of the course, if present the user will be enrolled in those courses.
  • 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 role short name or id (numeric names of roles are not supported).
  • Users may be also assigned to groups in course (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.).

New feature
in Moodle 2.2!

  • Cohort field: (Optional):
cohort1
Internal cohort id numbers or non-numeric Cohort IDs of existing cohorts must be used, names are not allowed.

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

Advanced potentials of Upload user

Templates

Note: This section needs checking and updating if necessary for Moodle 2.0. Please do so and remove this note when finished.

The default values are processed as templates in which the following codes are allowed:

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

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

  • (-) 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 templates:

  • %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)

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

In order to create correct Moodle 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.

When the "New username duplicate handling" setting is set to Append counter, an auto-increment counter will be append 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.

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

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

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.

Hints

Spreadsheet

If you use a spreadsheet program such as 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 user name), 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 can not 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 BE for Belgium or NL for the Netherlands. Using "be" or "nl" as a country code will result in a database error.

Tip: If you are having trouble working out the two-letter code for a country, you can consult this Moodle source code file /moodle/lang/en_utf8/countries.php or click here for a 1.9 STABLE list.

The full list of country names and code elements is also available on the ISO Website.

Field size limits

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

All fields listed here

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, oldusername , deleted, course1, course2, course3, course4

See also

Using Moodle forum discussions: