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, as you can also use this method to add or update individual accounts.
As this method is workload intensive, 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:
- From the quick-access menu go to Users > Accounts > Upload users.
- Upload the file you wish to use (see creating a file for details on constructing the file first).
- If needed you can adjust the upload settings (CSV delimiter, Encoding, and Preview rows but these can be left as the defaults if you are using a CSV (comma delimited) file).
- Click the Upload users button.
- Configure the settings on the Upload users preview screen.
- Click the Upload users button.
- You will be presented with a summary of the information to be uploaded, along with any errors.
- 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.
Creating a 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 spreadsheet 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).
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 , to prevent confusion. The script will decode these back to commas when the file is uploaded.
If you are including Boolean fields then 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 interface.
Example
Below is an example you 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]ail.com,security1,nzoffice,newusers
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.
| Field | Description | Notes |
|---|---|---|
| username | Username can only contain alphabetical lowercase letters, numbers, hyphen (-), underscore (_), period (.), or at sign (@). | Required field. |
| firstname | The user's first name. | Required field. |
| lastname | The user's last name. | Required field. |
| Email is in the form, [email protected]. | Required field. | |
| password | Password field is optional when Create password if needed setting is chosen (default).
| 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:
| - |
| country | Use a country two letter code. | - |
| 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 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 | You must create the custom fields before importing the upload users file. |
| oldusername | Used for changing of usernames. | - |
| deleted | Use this to delete a user with 1 or you can use 0 to add a user that has been deleted. | - |
| suspended | Use this to suspend a user with 1 to suspend and 0 to unsuspend 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 The example above would add the user Bailey Barker as follows:
| Enrolment fields should use matching suffixes e.g. course1,group1,role1,course2,group2 |
| group | Group 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 |
| type | Type 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.
| Enrolment fields should use matching suffixes e.g. course1,group1,role1,course2,group2 |
| enrolperiod | Enrol 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 |
| enrolstatus | Enrol 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:
| - |
| 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:
| 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.
You can bulk upload users to a specific tenant using the Tenant default value if you have multitenancy enabled.
Users 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.
| Setting | Description | Notes |
|---|---|---|
| Upload type | The Upload type specifies how to handle existing accounts. | - |
| Add new only, skip existing users | The 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 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 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 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 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. | 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 changes | Ignores 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 change | The 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 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 their password during the user's next login attempt. | - |
| All | All of the users in the uploaded file will be forced to change their 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.
| - |
| 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.
| - |
| 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.
| - |
| 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 log in 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.
| - |
| 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.
| - |
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:
$username = preg_replace('/[^-\[email protected]_a-z0-9]/', '', $username);
