Goal

Export users from one directory and import them into another, without breaking references.
If you are using an IdP which is supported by a native User Sync connector (Azure, Okta, Google GSuite, KeyCloak, OneLogin), you should be using that instead.

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.

Requirements

1. SAML SSO 3.5.4 or later or User Sync 1.4.4 or later
2. SAML SSO versions before 5.0 and User Sync before 2.0 require the Excel connector to be installed first, please read here
3. Target Directory must by in Read-Write mode
4. 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 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 as. 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 really 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'd 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 member 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 to not delete it immediately, you should keep it for a bit, just as a precaution.

Step 5: Authentication

Migrating doesn't copy passwords of the users. Most of the times 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 login 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 login with a user, either via SAML or that local password you've set temporarily.
The user should notice no difference to before the migration.

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.