Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Published by Scroll Versions from space TL25PMS and version Evergreen

You can upload users to add new users or to update existing users, including changing passwords and roles. It is not necessary to upload multiple users you can also use this method with individual accounts. 

As this is a more workload intensive method for adding/updating accounts it is also recommended you consider other authentication methods.

Difference to HR import

The Upload users menu does not include the hierarchy position, organisation position, manager name/ID, or job assignment fields. Therefore if your site includes these fields the Upload users menu is not suitable.

HR import uses users' ID numbers to identify records to update. If you have records that don't have an ID number then you can use the User Upload function to add data to this field, and then use HR import to add hierarchy data.

Uploading users

To upload one or more users with the upload users method follow these steps:

  1. From the Site administration menu go to Users > Accounts > Upload users.
  2. Upload the file you wish to use (see creating a file for details on constructing the file first).
  3. If needed you can adjust the upload settings (CSV delimiterEncoding, and Preview rows but these can be left as the defaults if you are using a CSV (comma delimited) file).
  4. Click the Upload users button. 
  5. Configure the settings on the Upload users preview screen.
  6. Click the Upload users button. 
  7. You will be presented with a summary of the information to be uploaded, along with any errors. 
  8. If you are happy with the information to be uploaded and there are no errors, click the Continue button. 

Once the users have been uploaded you will be returned to the initial upload page where you can repeat the process if required. If you want you can navigate to the browse users page to check all the records were uploaded. 

Upload users results page with example data found further down the page in the Examples section.

Creating a file 
Anchor
creating_file
creating_file

You will need to create a file for upload and this file needs to follow a few specific rules.

It is advised you use a spread sheet program to create the file and save it as a CSV (comma delimited) file. This is because the file must not contain spaces and should use a comma (or other delimiter) only. You can open the file with a simple text editor to check it is correctly formatted before uploading it. 

Within the file, the first line should contain all the valid field names you wish to include (e.g. username,password,firstname,lastname,email,course1,group1,cohort1). The following lines in the file should contain the relevant user details for upload (e.g. ajones,6789,Addison,Jones,[email protected],security1,nzoffice,newusers).

Note

It is advised that you create a test file with only one user's details (these can be dummy details if you want) before running a large upload, so that you can make sure the file has been constructed properly. This way it is easier to fix any issues before compiling a larger file. 

Formatting notes

You should avoid special characters such as quotes and commas as these may not translate well when uploaded. If you do need to use a comma then encode it as &#44 to prevent confusion. The script will decode these back to commas when the file is uploaded. 

If you are including Boolean fields the use 0 for false and 1 for true.

Some fields have a maximum number of characters that are allowed (notably institution should be at most 40 characters long). 


When entering dates (for example in custom profile fields) use the ISO standard format YYYY-MM-DD, eg. 2014-06-19 which will then be properly localised in the interfaced.

Example 

Below is an example use can use to test uploading. Notice that on the first line the column headings are in bold, this has been done to distinguish them from the user details underneath in this example. You do not need to use bold formatting in your uploads for the site. 

username,password,firstname,lastname,email,course1,group1,cohort1
ssmith,12345,Sam,Smith,[email protected],hr101,ukoffice,newusers
ajones,6789,Addison,Jones,[email protected],security1,nzoffice,newusers

Example file using the details mentioned above.

You can download the example shown above via this link: upload_users_example.csv

Available fields

The table below contains a list of available files for uploading. The required fields are noted in the notes column and all other fields are optional, so you can use as many or as few of them as you wish.

FieldDescriptionNotes
username

Username can only contain alphabetical lowercase letters, numbers, hyphen (-), underscore (_), period (.), or at sign (@).

Required field.
firstnameThe user's first name.Required field.
lastnameThe user's last name.Required field.
emailEmail is in the form, [email protected].Required field.
passwordPassword field is optional when 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 emails sent out. Note that this only works when adding new users.
Warning

Note that if the password field is empty and new passwords are created then users will be notified by email. This could result in a very large number of emails being sent if you have a lot of users.

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
  • 2 = Digest with just subjects
-
country

Use a country two letter code. 

-
authThe 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 log in.-
profile_field_xxxxx

If you have custom profile fields you can optionally include these in the upload file by entering in the format profile_field_xxxxx where the custom profile field name is xxxxx (i.e. the unique shortname).

Ensure you use all lowercase for the shortname. For example if you have a custom field for department then it would be entered in the file asprofile_field_department.

If your custom field is a menu then ensure you use one of the corresponding options in the user detail record entry. For example the custom field department might have three options HR, Marketing or Training. You would therefore just enter one of these into the value for the user details.

username,firstname,lastname,email,profile_field_department
bbarker,Bailey,Barker,[email protected],HR
skellen,Spencer,Kellen,[email protected],Marketing

You must create the custom fields before importing the upload users file.
oldusername

Used for changing of usernames.

-
deletedUse this to delete a user with 1 or use 0 to add a user that has been deleted.-
suspendedUse this to suspend a user with 1 to suspend and 0 to unsuspended the user. -
course

You can enter multiple courses by using the header course and a number e.g. course1,course2, etc. The other enrolment fields then need to use the same numerical suffix.

The course field uses the course shortname as the values in the user details entry.

For example:

username,firstname,lastname,email,course1,group1,course2,role2
bbarker,Bailey,Barker,[email protected],hr101,ukoffice,security1,learner

The example above would add the user Bailey Barker as follows:

  • To the course shortname HR101 as a member of the UK office group in a Trainer role.
  • To the course shortname security1 in a Learner role.
Enrolment fields should use matching suffixes e.g. course1,group1,role1,course2,group2
groupGroup may be used to assign users to groups in a course, using name or ID (numeric group names are not supported).Enrolment fields should use matching suffixes e.g. course1,group1,role1,course2,group2
typeType sets the role to be used for the enrolment. Enrolment fields should use matching suffixes e.g. course1,group1,role1,course2,group2
role

You can add a role in a few different ways.

  • Role shortname (numeric names of roles are not supported)
  • Role ID
  • As a value, using the following:
    • 1 for default course role
    • 2  for legacy Trainer role
    • 3 for legacy Non-editing Trainer
Enrolment fields should use matching suffixes e.g. course1,group1,role1,course2,group2
enrolperiodEnrol period may be used to set the enrolment duration, in days, for each course.Enrolment fields should use matching suffixes e.g. course1,group1,role1,course2,group2
enrolstatusEnrol status can suspend users from a course when set to 1 or left blank for enrolled.Enrolment fields should use matching suffixes e.g. course1,group1,role1,course2,group2
cohort

You can use the cohort field to add audiences. This optional field takes the format; cohort1

Internal audience ID numbers or non-numeric audience IDs of existing audiences must be used; names are not allowed.

-
mnethostid

This field is optional:

  • Existing MNetusers can be added to courses, groups or audiences as below:
    • enrolling to courses: username+mnethostid+course required.
    • adding to group: username+mnethostid+course+group required.
    • adding to cohort: username+mnethostid+cohort required.
    • suspending/reviving accounts: username+mnethostid+suspended required.
  • All other operations are ignored. You can not add users, delete them or update them (such as change names or email, profile fields, etc.)
-
sysrole

System role is an optional field that takes the format; sysrole1,sysrole2,sysrole3 etc.

Users may be uploaded to a system role (usually Manager or Course Creator) by entering the shortname of that role. 

Other roles can only be uploaded if they have already been assigned in the system context. Find more information on the Roles page about custom and system roles.

Multiple roles can be assigned using sysrole2, sysrole3, etc. fields. Note that the number suffix in no way relates to the number suffixes on the enrolment fields. 

The numbers must go up in sequence starting at 1.

Users can also be removed from a given system role by entering the shortname of that role prefixed with a minus symbol: '-'. 

If the user is currently assigned to that role, they are removed from it. If the user is not currently assigned to that system role, the field value is ignored. However, the field value must refer to a system role that does exist on the system, otherwise an error will occur.

Optional fields

You can also enter other fields as listed below:

  • institution
  • department
  • city
  • lang
  • timezone
  • idnumber
  • icq
  • phone1
  • phone2
  • address
  • url
  • description
  • mailformat
  • htmleditor
  • autosubscribe
If you are using the optional idnumber field then Totara will check for duplicates.

The default values for many user profile fields can be set on the Upload users preview screen.

Upload users preview screen showing the Default values section underneath the Settings section.

Users preview settings 
Anchor
preview_settings
preview_settings

Once you have added your upload file you will be taken to the Upload users preview screen where you can configure a range of settings to better control the upload of your user data. 

Upload users preview screen with example data found further up the page in the Examples section.

Warning
Errors updating existing accounts can affect your users badly. Be careful when using the options to update.
SettingDescriptionNotes
Upload type

The Upload type specifies how to handle existing accounts.

-
Add new only, skip existing usersThe default Totara upload type. It creates a new user account for each new record in the uploaded file. If an existing username is found (i.e., the username 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 neededCreates 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 for username 'jsmith' an additional user account is created with a 1 appended to the username to produce user 'jsmith1'.-
Add new and update existing usersCreates 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 onlyIgnores 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 Totara can create a new password (if one is not provided) or require a password in the uploaded file. Create password if needed creates a default password for the new user account if one is not provided in the uploaded file. 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.

Warning

Note that if passwords are created then users will be notified by email. This could result in a very large number of emails being sent if you have a lot of users.

Existing user details

The Existing user details options are only available when the Upload type allows existing user accounts to be updated. It specifies how Totara should process user detail information for existing users.

-
No changesIgnores user detail data in the upload and leaves the existing user account data unchanged.-
Override with file

Overwrites data in the existing user account with the data provided in the uploaded file.

-
Override with file and defaults

Overwrites data in the existing user account with data provided in the uploaded file and fills in the default values for existing user details when no data is provided in the uploaded file.

-
Fill in missing from file and defaults

Adds data in the existing user account with data provided in the uploaded file if the field is empty (does not already contain data) and fills in the default values for existing user details when no data is provided in the uploaded file.

-
Existing user password

The Existing user password option specifies how to handle password data for existing user accounts when Existing user details is set to overwrite data.

-
No changes

Ignores password field in the uploaded user file and leaves the existing user account password untouched.

-
Update

Overwrites the existing user account password with the password provided in the uploaded file.

-
Force password changeThe Force password change option specifies when to tag a user account so that the next login attempt will require the user to change the user's password.-
Users having a weak password

If the user account has a weak password as defined by the site's password policy then the user will be forced to change the password during the next login attempt. This option is not shown if there the site does not have a password policy, in other words $CFG->passwordpolicy must be set to see this option.

-
None

None of the users in the uploaded file will be forced to change the password during the user's next login attempt.

-
AllAll of the users in the uploaded file will be forced to change the password during the user's next login attempt.-
Allow renames

If the uploaded file contains the special oldusername field, it is possible to rename a user from the oldusername to a new username. The default setting is to not allow renames. Keep in mind that renaming a user will require the user to use the new username when logging in.

  • No ignores the oldusername field and leaves the existing user account's username field unchanged.
  • Yes allows the existing user account's username to be changed by the data provided in the uploaded file's username field. The oldusername will be searched for and then updated with the data provided in the username column.
-
Allow deletes

If the uploaded file contains the deleted special field, it is possible to use the upload file to delete existing user accounts. The default setting is to not allow deletes. Keep in mind that deleting a user account will prevent that user from logging in. As a protection, site administrator user accounts cannot be deleted with this method.

  • No ignores the deleted special field in the uploaded file and leaves the existing user account unchanged
  • Yes allows the existing user account to be deleted when the value of the of the deleted field is 1.
-
Allow suspending and activating of accounts

If the uploaded file contains the suspended special field, it is possible to use the upload file to either suspend or make active (unsuspend) existing user accounts. The default setting is to allow suspending/activating of existing user accounts. Keep in mind that suspending an existing user account will prevent that user from logging in.

  • Yes allows the existing user account to be suspended when the value of the of the suspended field is 1.
  • No ignores the suspended special field in the uploaded file and leaves the existing user account status unchanged.
-
Prevent email address duplicates

It is possible, but not recommended to upload users with duplicate email addresses. By default, uploading users with duplicate email addresses is prevented.  Further, since the ability for users to login with their email address it is even more important that duplicate email addresses be avoided. To allow duplicate email addresses, go to Site administration > Plugins > Authentication > Manage authentication. You can tick Allow accounts with same email. Then on the upload users screen you will be allowed to change the Prevent email address duplicates setting. However, doing this is not recommended. For more info, see the Managing authentication page.

  • Yes prevents user accounts from being created from the uploaded if an existing user account already has the same email address as found in the uploaded file's email column.
  • No allows user accounts to be created if an existing user account already has the same email address found in the uploaded file's email column.
-
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 standardises 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).
-

For those seeking a more technical explanation, the process for standardising the usernames consists of ensuring the characters are all UTF-8 (fix_utf8) encoded, converting the username to lower case, and then stripping out non-letters/non-number characters (unless $CFG->extendedusernamechars is set to true) with something similar to: 

Code Block
$username = preg_replace('/[^-\[email protected]_a-z0-9]/', '', $username);
Panel
borderColor#d3d3d3
borderStylesolid
titleOn this page

Table of Contents
maxLevel4
minLevel2