New article
Recently updated
Changing Usernames
Who is this article for?
Administrators responsible for managing users in Mazlan Home.
Admin Console access is required.
You can change the usernames of existing users in bulk. Use this when a user's username was entered incorrectly, to match SSO attributes, or your organisation changes its email domain or subdomain.
Currently, you change usernames by importing a CSV file. The process and file format are the same as importing and exporting users. The only difference is the extra NewUsername column.
Before you begin
Considerations
- Encoding - CSV file must be saved using UTF-8 encoding.
- Headers - First row of your CSV must contain the column headers, exactly as they appear in the exported file.
- Delimiter - Each column must be separated by a comma. If you use Microsoft Excel, check that the export settings use commas, not semicolons or tabs.
- Organisation specific - Each CSV file is specific to a single organisation, represented by the subdomain of your Mazlan Home sign in URL. Do not include users from multiple subdomains in one file.
- Case sensitivity - The Username value in your file must match the current username exactly, including upper and lower case. If it does not match, the row is rejected.
- Welcome emails - The welcome email behaviour follows your organisation's communication settings. Refer to this guide for organisation communication settings.
Building your CSV file
The easiest way is to start with an export of your current users. This gives you all the columns you need, with the current values.
Export your user list
- Open the Admin Console.
- Go to User Management.
- Click Export.
Add the NewUsername column
- Open the exported file in a spreadsheet application.
- Add a column with the header NewUsername. You can place it anywhere in the file. We recommend placing it next to the Username column.
- For each user you want to rename, enter the new username in NewUsername. Do not change the Username value. It must stay as the current username.
- For users you do not want to rename, leave NewUsername blank or remove their records in the CSV file to save time and avoid accidental changes.
- Save the file as a CSV file with UTF-8 encoding.
Note
A change in letter case only, for example jdoe to JDOE, counts as a username change.
Columns
The Username and NewUsername columns work together. For all other columns, refer to the article on importing users.
| Item | Description | Values |
|---|---|---|
| Username |
The current username of the user you want to change. Used to find the user in Mazlan Home. |
Required and cannot be empty or null. Must match the current username exactly, including case. |
| NewUsername |
The new username for the user. Optional. Leave blank if the username should not change. |
Supports the following:
|
How each row is handled
| Username | NewUsername | Result |
|---|---|---|
| Matches an existing user | Different from the current username | The username is changed. |
| Matches an existing user | Blank | The user is updated as usual. The username does not change. |
| Matches an existing user | Same as the current username | The username does not change. Other columns are still updated. |
| Does not match any user, or differs in case | Filled | The row is rejected. No new user is created. |
| Does not match any user | Blank | A new user is created, as in a normal import. |
Name clashes
Before the import starts, Mazlan Home checks every new username against the users in your organisation as they were at the start of the import. A row is rejected if:
- The new username is already used by another user. This also applies if the names differ only in case.
- The new username belongs to a user who is also being renamed in the same file. For example, if one row changes alice to bob and another changes bob to alice, both rows are rejected.
- Two or more rows use the same new username. All of these rows are rejected.
To swap usernames, first rename one user to a temporary username, then import a second file to complete the change.
Importing your CSV file
To import the file:
- Open the Admin Console.
- Go to User Management.
- Click Import.
- Click Import again.
- Upload your CSV file by selecting it or dragging it into the window.
The system will automatically validate the file to ensure that all required headers are present and that data is formatted correctly.
- If any issues are found, a list of errors is returned for correction. Fix the errors in your file and import it again.
- Once validated, the CSV file is processed. Existing users are updated, and usernames are changed where a NewUsername is provided.
- Review the Import history screen. It shows the number of records imported successfully. If a row could not be changed, for example because of a name clash, the screen shows which record failed and the reason. The other rows are still processed.
- Click Close to complete the process.
Note
After a username is changed, the old username no longer exists. If you import the same file again, the rows that were already changed are rejected. Remove those rows or update the file before you import again.