• Products
  • Documentation
  • Resources

Update users based on the CSV file

Updating users based on the CSV file is one of the options to fix invalid and duplicated email addresses when migrating your users to Cloud.

About the CSV file

A separate CSV file is generated for users with invalid and duplicated email addresses, so you need to handle each of these cases separately. The CSV file that you download from the migration assistant always contains the default data identified during the latest assessment, even if you already uploaded a modified file.

Good to know

  • We recommend choosing one of the automatic options instead of updating the CSV file. We provided the file in case these options are too generic for you, for example if you’d like to apply a different solution to only select users.

  • You can modify existing users in the file, but you can’t add or delete users. If the number of users in the uploaded CSV file is different than in the original file, you won’t be able to upload it.

Example CSV file

Here you can see the data from a sample CSV file generated for users with invalid email addresses:































  • UserKey: User key. For users created in earlier Jira versions, it should be the same as the username.

  • UserName: Username, the primary identifier in your self-managed instance.

  • Type: Problem with the email address, either invalid or duplicated, depending on the file.

  • OldEmail: Current email address.

  • NewEmail: Pre-generated email address to unblock the migration. The domain chosen is the most common one among your users, so it should resemble your actual domains. You can edit this value.

  • Tombstone: Controls whether a user should be migrated as Former user in Cloud. The values are True or False. You can edit this value.

How to edit the CSV file

The values you can change in the CSV files are NewEmail and Tombstone:


The pre-generated email addresses are always valid, so they meet the requirements of the migration assistant and let you migrate. Note that all these emails aren’t actually working and your users won’t be able to log in with them. These emails only let you preserve the activity and identity of your users. If you'd like some of them to keep access, you can change the value to an address your users have access to. However, in the case of active users, we recommend that you update their emails directly in the source (e.g. Jira user directory, external directory). Such users will be counted towards your license if they're migrated into a group that has product access granted.

For more info on granting product access, see Update product access settings.


You can change this value to true if you'd like to migrate select users as Former user. Such users will have their activity preserved, but not the identity. Every interaction they ever made, such as adding a comment, will be displayed under the name Former user.

Invalid vs. duplicated email addresses

The CSV file is adjusted to invalid email addresses and works well with this case. It allows you to specify the two main automatic options from the migration assistant:

  • Migrate users as Former users (Tombstone column)

  • Create new emails (NewEmail column)

You can use the file if you’d like to mix these options in a more granular way than available in the migration assistant.

As for duplicated email addresses, we consider the automatic options to be more beneficial. With a number of duplicated accounts, the best option to fix them is by merging them, which isn’t available when using the CSV file. The benefit of choosing the CSV file would be the case where you’d like to generate new email addresses for the majority of duplicated users and then modify these addresses for select users (NewEmail column) or migrate some of them as Former users (Tombstone column).

Additional Help