Important Update Effective February 1, 2024!
Due to recent changes in Jira and Confluence, we've made the tough decision to discontinue the OpenID Connect (OIDC)/OAuth app and no longer provide new versions for the newest Jira/Confluence releases as of January 31, 2024.
This is due to some necessary components no longer shipping with Jira/Confluence, which would require some extensive rewrites of the OIDC App.
How To Bulk-Rename Users With The User Sync Excel Connector
Goal
Rename users in the internal directory in bulk without breaking references to Jira issues, Confluence pages, etc. Excel formulas can be used to apply the same transformation to usernames, for example by appending a domain name.
Important
The Excel connector is designed to make changes to your user directory based on an input that can be manually edited and transformed. Always test in a staging or dev environment first to understand the consequences of your operations and prevent any negative impact.
If you have doubts about the process or questions, please do not hesitate to contact us via https://www.resolution.de/go/support.
Please note that Jira doesn't support updating filters and mentions upon renaming usernames. There's an open Atlassian ticket for that though: https://jira.atlassian.com/browse/JRASERVER-70685.
Requirements
- SAML SSO 3.5.4 or later or User Sync 1.4.4 or later
- SAML SSO versions before 5.0 and User Sync before 2.0 require the Excel connector to be installed first, please read here
Step 1: Export Users
Export your users from the selected directory following the instructions in this article:
How to Export Users with the Excel Connector
The connector will export every user in the directory selected.
Step 2: Clean the file to prepare the rename in bulk operation
The excel file contains as many lines as users in the directory. While each line contains many columns, only few are needed for renaming users.
Below are two sample lines and all the original columns:
Remove unaffected users
Delete all lines corresponding to users that won’t be renamed in the import.
Remove not Required Columns
Remove all columns starting with column E, the ATTR_GROUPS column.
Only the following existing columns are required:
ATTR_NAME
ATTR_FULLNAME
ATTR_EMAIL
- ATTR_ACTIVE
You only need to keep ATTR_ACTIVE if you want to make sure that inactive users stay inactive when being renamed.
Add another new column after ATTR_ACTIVE and call it ATTR_NEW_NAME
This needs to contain the new username.
In the following example, you can see a user called user4 which would be renamed to user-4 in the next step.
Before you import it back, remember that the excel file must be cleaned following two general rules:
The file must contain only the users that you want to rename.
Usernames must be unique
Follow these recommendations:
Delete every line pertaining to a user that won’t be renamed
Make sure there are no empty lines in between each user line
make sure each ATTR_NEW_NAME column contains the new username value
make sure you don't provide the same ATTR_NEW_NAME twice, as this will result in errors
Please also be advised about the following:
Don’t ever upload the same excel file twice with the import connector!
Doing so will result in duplicate users, with a second batch of original user & usernames unassigned to any groups.
Renaming users might lead to an increase of user licenses
Example: you've migrated users from a directory using the Excel connector as well. You want to rename the users afterwards.
That will result in users having a different username meaning they're counted towards the total user licenses.
Solution: disable the source directory in a case like this, that's the goal of a migration anyway.
Directory order
Before renaming users that way, the directory in which the users are getting rename should ideally be at the bottom of the directory list.
If not, renaming might fail for some users, if their account exists in another directory with the same name already.
After the bulk operation, you should move the directory at the top of the list again or at least above the first directory in the list which has users in it with the same name.
Step 3: Import the users to rename them in bulk
Use the transformed file to import your users into the target directory following the instructions in the article linked below.
The import with the reduced amount of columns and one column providing the new username will result in bulk renaming users.
How to Import Users with the Excel Connector to Bulk Rename
The result summary should contain the number of users who have been renamed:
You can delete the connector again afterwards