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

Talk:Upload users

From MoodleDocs

Hopefully I have modified this to be more precise and retained the accuracy, while including pitfalls to watch for. Dennis German 22:53, 28 November 2010 (UTC)

I copied text from the help file to this page. Please let me know if this is not the way to go. I felt that the Docs should be self-sufficient without the "online help files". --Samuli Karevaara 02:39, 1 September 2006 (CDT)

Hi Samuli, it's not necessary to copy all help file text into the documentation wiki, however it can sometimes help. --Helen Foster 03:09, 4 October 2007 (CDT)

Possible inconsistency or lack of clarity

It's not obvious whether these two sections contradict each other:

Note: If a user is already registered in the Moodle user database, this script will return the userid number (database index) for that user, and will enrol the user as a student in any of the specified courses WITHOUT updating the other specified data
By default Moodle assumes that you will be creating new user accounts, and skips records where the username matches an existing account. However, if you set "Update existing accounts" to Yes, the existing user account will be updated.

Is the former an exception to the latter? Does adding an existing user to a course and/or group count as 'updating'? --David Scotson 13:37, 6 September 2006 (CDT)

What is meant "set "Update existing accounts" to Yes" ?? Where can i find it in moodle?

As far as I can tell, uploading users with "update" off doesn't affect enrollments in any way. This is from personal experience and from looking at the code. The help file is incorrect.

Can some more clarity be added about csv file types, it seems that the instructions for uploading files for user accounts say just .txt files ( Since a CSV file is a simple text file (ASCII or Unicode) maybe it should be listed as a acceptable file type for uploading. GM 05/28/08 Moodle rooms assignment 14.1

Changes in 1.9

It is worth noting that in version 1.9 the interface for batch-uploading users is significantly different than in 1.8 and previously. In 1.9 the options have been split into two pages; first the file gets uploaded and parsed, then you tell Moodle what you want it to do with that file. E.g. you do not get to choose whether the file should update existing accounts until page 2.

This page needs serious work for 1.9

In MoodleSpeak of 1.9 this page can use some serious work. I suspect the language is left from older versions of Moodle.

In short: Upload Users is about Authentication, Flat File is about Enrolment. Flat File is probably a poor name but we can not do anything about it except not use it on this page. While both Authentication and Enrolment use a special text file for bulk uploads, each has a different set of data fields and each is processed differently by the interface.--Chris collman 15:08, 24 July 2008 (CDT)

Proposed changes July 2008

This page requires a review. Please do so and remove this template when finished.

I (Chris Collman) have walked through 3 or 4 Upload users and snapped some screen shots on a local host in 1.9. Since I am "new" at this process, I will propose changes to the page in hopes someone who is more about the process will catch errors.

While this page should contain much of the same information as help, it should not be a duplication of help. This page should have lots of links.

  • NOTE: For example, at the moment I am showing every option in say default. Many of these options should be (but are they?) shown in other parts of the documentation. I have not checked. Instead of showing every possible option here, we could have a link to another part of MoodleDocs that would show the options in case the site administrator forgot or did not know what they were.
  • NOTE: if this page is long, consider placing back to TOC links after topics, with the TOC heading trick in its own heading.

INTRODUCTION Location: Administration > Users > Accounts > Upload users

The upload users utility is a simple but powerful way to upload user information into Moodle. It is possible to either create authenticate users, or to create authenticate users and enrol them into an existing course in one process.

  • Note: that recent versions of Moodle have tools to keep the site administrators personal maintenance work down besides this particular form of manual authentication. For example, connecting to existing external databases or letting the users create their own accounts. See the Authentication section in the admin menus.

The user data text file must follow a certain format, as described below. It might be useful to review [[course settings]] and [[User profile settings]] before reading this page. If a course, Group course settings, or user profile field does not exist or is not enabled, the Upload user process will NOT create it.

Basic Steps

The uploading users process uses 3 screens and has many options to consider.

1 User upload screen

Open up the Upload users screen in Site Administration >Users>Accounts>Upload users

Initial Upload user screen Moodle 1.9
Upload file
Use the browse button
CSV delimiter
Review and change if necessary the separating value (In Moodle 1.9 these are: comma, colon, semi colon and tab (/t)
Encoding language
Should match the Moodle site. For examples Unicode or UTF-8
Preview rows
Set the number of records to display in the next preview screen

2 Upload user preview screen

There are 4 parts to this screen: Preview of text file, Settings, Roles and Default values.

Top of Upload user preview screen Moodle 1.9


Preview of text file

At the top of the page are the first records in the file. It is always a best practice to look at them to make sure the field information is in the correct place.

Settings

Upload type:

Add new only, skip existing users
Add all, append counter (a number) to name if needed
Add new and update existing users
Update existing users only

New user password: (Will not effect existing users passwords)

Field required in text file
Create password if necessary

Existing user details

No changes
Override file
Override with file and defaults
Fill in missing with file from defaults

Existing user password

No changes
Update

Allow renames

Yes or No

Allow deletes

Yes or No

Prevent email address duplicates

Yes or No

Select for bulk operations (this can make global changes to all users like Bulk user changes)

No
New users
Updated users
All users

Roles

You may assign a user any one of 3 Roles when using Update user. Each user in the text file may have been assigned a role (see below) and that will appear in the Type1 (or roles) column in the preview section.

Select the role from a pulldown menu for each of the numeric types. For example, we could change type 3 from a non-editing teacher to an editing teacher.

(Original Student) typeN=1 Type 1
(Original Teacher) typeN=2 Type 2
(Original Non-editing teacher) typeN=3 Type 3

In moodle 2.0

(Original Student) typeN=0 Type 0
(Original Manager) typeN=1 Type 1
(Original Teacher) typeN=2 Type 2
(Original Non-editing teacher) typeN=3 Type 3

Default values

Notice there is an advanced settings button. Values placed in these screens are referred to in the [[Settings section on this page]] when the term "defaults" is used.

Bottom of Upload user preview screen Moodle 1.9


Choose an Authentication method (Advanced setting)

Manual accounts
No login
[[Email based self-registration]]

Email activated

This email address is enabled
This email address is not enabled

Email format (Advanced setting)

Pretty HTML
Basic text

[[Email digest type]] (Advanced setting)

No digest, single email per forum post
Complete, daily emails with full posts
Subjects only, daily emails with subjects only

[[Forum auto-subscribe]]

No, don't automatically subscribe me in forums
Yes, when I post subscribe me to that forum

When editing text (Advanced setting)

Use standard web forms

AJAX and Javascript (Advanced setting)

Yes, use advanced web features
No, use basic web features

City/town

Fill in the default you want to use

Select a country (Advanced setting)

Use the pulldown menu to select a default country

Timezone (Advanced setting)

Use the pulldown menu to select a default country

Description (Advanced setting)

A field with the HTML edit tool to put in a standard user description

Web page (Advanced setting)

Institution

Fill in the default you want to use

Department

Fill in the default you want to use

Phone (Advanced setting)

Fill in the default you want to use

Mobile Phone (Advanced setting)

Fill in the default you want to use

Address (Advanced setting)

Fill in the default you want to use

Upload users results screen

This screen reviews some of the changes that have been made.

  • Always exciting, did the site administrator fill in all the options correctly? If not, start to plan the steps to fix the errors.
  • As a best practice is is a good idea to perform a quality control check of some users and a course to makes sure the upload users command had the intended results.

Upload file format

Users may be imported, enrolled in courses and organised into Groups via a text file that has separated values. In older versions of Moodle the separating value was always a comma, so we will use that in our examples.

Review of basic format

  • Each line of the file contains one record
  • Each record is a series of data separated by commas
  • The first record of the file is special, and contains a list of fieldnames. This defines the format of the rest of the file.

Required fieldnames

These fields must be included in the first record, and defined for each user

username, password, firstname, lastname, email

Default fieldnames

These are optional - if they are not included then the values are taken from the primary admin

institution, department, city, country, lang, auth, timezone

Optional fieldnames

All of these are completely optional. Many of them are described in under default settings on this page or in User profile settings.

idnumber, icq, phone1, phone2, address, url, description, mailformat, maildisplay, htmleditor, autosubscribe, maildigest, course1, course2, course3, course4, course5, group1, group2, group3, group4, group5, type1, type2, type3, type4, type5
  • The course names are the "shortnames" of the courses - if present then the user will be enrolled as students in those courses.
  • Group names must be associated to the corresponding courses, i.e. group1 to course1, etc.
  • maildigest : 1 = no digest, 2 = complete, 3 = subject

Tips on upload file creation

  • Commas within the data should be encoded as &#44 - the script will automatically decode these back to commas. CHRIS QUESTION: WHAT ABOUT PUTTING DOUBLE QUOTES AROUND FIELD, DOES THAT PRESERVE EVERYTHING INSIDE? Wonder if Flat file tips will apply here.
  • For Boolean fields, use 0 for false and 1 for true.
  • Types are used to tell Moodle whether the user is a student or a teacher if a corresponding course exists (e.g. type2 corresponds to course2). In earlier versions of Moodle there were only 3 choices: 1 = Student, 2 = Editing Teacher, and 3 = Non-editing Teacher. If type is left blank, or if no course is specified, the user is default to student.
  • For courses, use the short name for the course
  • Note: If a user is already registered in the Moodle user database, this script will return the userid number (database index) for that user, and will enrol the user as a student in any of the specified courses WITHOUT updating the other specified data.
  • Older Moodle version tips
    • Turn email off: The parameter emailstop must be set to 1 if the email address should not work. If you set it to 0 then the email address is switched on. If you want to have all the email addresses active then you do not need the additional parameter in your upload file.
    • Force password change: Set the password field for desired users to changeme.
  • Roles are new in 1.7: Note that since roles have been added in Moodle 1.7, there is a new (better) fieldname to use for enrolments and that is role. You can use role field instead of the legacy type field to specify roles directly - use either role short name or id (numeric names of roles are not supported). CHRIS QUESTION: IS THIS A VALID STATEMENT WITH 1.9? I READ THIS AS SAYING THE FIRST LINE THAT CONTAINS "Type1" IN THE EXAMPLE, MAYBE CHANGED TO READ "role". Wonder if the instructions in 1.9 Help should call it role.

Sample Upload user text file

Here is an example of a valid import file:

username, password, firstname, lastname, email, lang, idnumber, maildisplay, course1, group1, type1
jonest, verysecret, Tom, Jones, jonest@someplace.edu, en, 3663737, 1, Junk102, Section 1, 1
reznort, somesecret, Trent, Reznor, reznort@someplace.edu, en_us, 6736733, 0, Junk102, Section 3, 3

(Text copied from Upload users help file.)

Tips and Tricks

  • When updating existing accounts you can change usernames as well. Set "Allow renames" to Yes and include in your file a field called oldusername. ( CHRIS'S QUESTION: Pre 1.9 Moodle instruction?)
  • Caution: any errors updating existing accounts can affect your users badly. Be careful when using the options to update.
  • Prior to Moodle 1.9, the file must have the same encoding as your language pack. In Moodle 1.7 and 1.8 it is always UTF-8. In Moodle 1.9 onwards, the encoding may be selected.
  • The country should be written as a two letter code, e.g. BE for Belgium, NL for the Netherlands, and should be written in capitals. If not, it gets abbreviated to two letters, which can cause an invalid country entry in the database.
  • Caution: If you enroll someone into a group via this method and the group doesn't already exist it will be created automatically. This is pretty handy actually but you must make sure that your group names created this way contain at least one non-numeric character. If you don't Moodle will create multiple identically named groups in the same course, each with just one member. I think it has something to do with comparing numbers as numbers vs. comparing numbers as strings.

Spreadsheet tips

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.

  • A csv file is a simple text file (ASCII or Unicode) that can be used to upload user accounts
  • It is possible to get trailing commas on each line from an empty field in the spreadsheet if you have added and deleted columns of information prior to saving the final file
  • In the spreadsheet, check the character encoding in the output file settings
  • Caution: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.

See also

  • Flat file which is used just for Enrolments but is similar in terms of format. CHRIS QUESTION: IS IT AS FULL FEATURED WHEN IT COMES TO ENROLMENTS AS UPLOAD USER?

Using Moodle forum discussions: