Talk:Upload users
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
- 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.
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
1Roles
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.
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 , - 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: