User Mapping

On this page:

Managing and migrating users

With the Cloud Migration Tool, you can intelligently migrate Jira Server or Data Center users to the cloud by correcting missing and invalid email addresses and resolving conflicts along the way. After creating a migration, selecting projects to migrate, and reaching the Analyze changes phase, you have the necessary tools and control of migrating the desired users to the cloud without errors.

Which users are migrated to the cloud?

Jira users, groups, and roles are integral to the project configuration - permissions, notifications, workflows, etc. Therefore, any users, groups, and roles used in the project you are attempting to migrate will be included in the migration.

After adding projects to the migration, users referenced by configuration elements associated with these projects are included. For example, users assigned to issues in a particular project, assigned as project leads, or single users assigned to project permissions, will be included in the migration.

Learn more about the migration process in our articles.

How are Jira Server/Data Center users migrated to the cloud?

  • Users who don’t have an account on the Jira Cloud site will be invited to join after the migration.

  • Users with emails that exist on Jira Cloud won’t be migrated and are marked as existing.

  • Users who either don’t have an email address or have an invalid email address will be reported as a problem. In these cases, the migration can’t continue as the Cloud Migration Tool can’t determine if the user exists on the Jira Cloud site. Therefore, you first need to resolve these errors and then continue the migration.

Customize mapping between Jira Server/Data Center and Cloud users

Users can be mapped to an account on the Jira Cloud site via custom user mapping. By uploading a custom user mapping CSV file, you can customize the Jira Server or Data Center users’ configuration to fix users without email addresses or with invalid email addresses during migrations.

In addition to these cases, you can change the email addresses of several Jira Server/Data Center user accounts to map all of them to a single account on the Jira Cloud site.

User mapping during a migration

After starting a migration and reaching its Analyze changes phase, you’ll be able to view all the users from the projects in the migration and customize user details if necessary.

Additionally, you’ll be notified of any errors in the user accounts, like missing and invalid email addresses. Besides correcting errors, you could map several Jira Server/Data Center users to a single Jira Cloud account if you would like to.

The Users tab on the Analyze changes phase contains all that information described above, plus the option to customize the user mapping.

How can you customize the default user mapping?

Customizing mapping allows you to change the default mapping between server and cloud users or default source user information. By uploading a CSV file with the server user usernames and email addresses, you can correct missing and invalid email addresses and map several Jira Server/Data Center users to a single Jira Cloud account.

Users that are not customized but have the same email will be mapped to a single Jira Cloud account.

There are four user states you can observe in the Users tab on the Analyze changes pages:

  • NEW User doesn’t have an account in this Jira Cloud site and will be invited to join.

  • existing User with this email exists in this Jira Cloud site.

  • unknown User doesn’t have a valid email address and it cannot be determined if the account exists in this Jira Cloud site. The user either doesn’t have an email address or its email address is invalid.

  • customized User is mapped to an account in this Jira Cloud site via custom mapping.

To customize the user mapping:

  1. Start a migration.

  2. On the Analyze changes phase, move to the Users tab.

  3. Review if there are any users with missing or invalid email addresses.

  4. Click Download mapping to download a CSV file with the default user mapping.
    The downloaded file named cmt_usermapping.csv contains the server users’ email addresses and usernames.

  5. Modify the CSV file to correct missing or invalid email addresses. Also, if you would like to map several server users to a single Jira Cloud account, change their email addresses to match the email address of that Jira Cloud user.

  6. Click Customize mapping to upload the CVS file with the user changes.

  7. After the customizations are applied, you’ll return to the Users tab, where you’ll see that users with changes from the CSV file have the customized tag.

Losing user mapping changes

If you rerun the analysis, you’ll lose any customizations to the user mapping. So, first, resolve conflicts and errors in projects and configuration elements, and then introduce changes to users by customizing their mapping.

After making changes to the user mapping, click Migrate to move on with the migration.