How To Migrate Users With The User Sync Excel Connector
Goal
Export users from one directory and import them into another, without breaking references.
If you are using an IdP that is supported by a native User Sync connector (Azure, Okta, Google Cloud Identity, KeyCloak, OneLogin), you should be using that instead.
Important
The Excel connector is designed to make changes to your user directory based on 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.
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
Target Directory must be in Read-Write mode
An admin user in the default internal directory who is not part of the migration
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 source directory.
Step 2: Modify the file to prepare for import to the internal directory
The Excel file contains as many lines as users in the directory. Below is one sample line and all the original columns:
Make sure, that all mandatory attributes are present:
ATTR_EMAIL
ATTR_FULLNAME
Leave the ATTR_NAME field as it is. This is important for migrating the user properly and not breaking any references.
Remove unaffected users
Delete all lines corresponding to users that you don't want to migrate.
It is not advised to change values in the columns available. While you could add more groups to each user, it's way safer to do that after the migration.
As mentioned in the beginning already:
Don't include the admin user you are logged in with. Once you change the directory position later (see further below), you'll lock yourself out.
Step 3: Import the users again
Use the transformed file to import your users into the target directory following the instructions in this article:
How to Import Users with the Excel Connector
Step 4: Verify the Results, Change Directory Order, Disable Source Directory
If your target directory is already above the directory you've exported the users from, then you should already see the users as members of that directory.
In Jira you'll see that by looking at the Directory column in the user browser:
In Confluence you need to click on the user first and see a list of directories, if in multiple.
The one at the top should be the target directory.
So if the user is still shown under the source directory (the source directory is the first in their Confluence user profile),
move the target directory above it, before you can verify the results.
Everything else should look as before, all the historical references should have been preserved (profile, issues assigned & reported, pages, etc.).
This is the point where you can disable the source directory. We advise you to not delete it immediately, you should keep it for a bit, just as a precaution.
Step 5: Authentication
Migrating doesn't copy the passwords of the users. Most of the time a migration is a preparation to authenticate the users afterwards with SAML,
and no passwords are stored in that case locally either.
You could still set a password for one of the migrated users to log in locally if the target directory allows that.
Usually, you migrate to the Jira/ Confluence internal directory where this would work.
The final test requires that you disable the source directory and log in with a user, either via SAML or that local password you've set temporarily.
The user should notice no difference.
Optional Steps
Once you've migrated the users successfully, you might want to Bulk rename users, also using the Excel Connector.
This would be required, if your usernames need to match the NameID on the IdP you are using for SSO.