How to edit the CSV file with users

There are some differences between the CSV files in simple and advanced experience. Choose the one you’re using below.

Editing the CSV file in the simple experience

In the simple experience, using the CSV file is one of the options you can choose to fix users. You need to use a separate CSV file for users with invalid and duplicated emails.

Before you begin

Using the CSV file is available only in the Jira Cloud Migration Assistant.

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 to 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:

NewEmail

The pre-generated email addresses are always valid so they meet the requirements and let you
migrate. Note that these emails aren't actually working and your users won't be able to log in
with them. Such emails let you migrate your users, preserving both their activity and identity,
but not the access. 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 (Jira user directory, external directory).

How to use this field to merge duplicated users

If you use an email address that already exists in cloud or is shared by other users
in this file, the users will be merged. Note that merging isn’t supported with the ‘Migrate all data at once’ migration option.

Tombstone

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.

Recommendations

Here are all the options you can do with this file:

• For users that should exist in cloud, but don't need access: use default values.

• For users that should exist in cloud and need access: set 'NewEmail' to a working email.

• For users that should be merged together: set 'NewEmail' to the same address for all of them.

• For users that should be deactivated: set ‘Tombstone' to ‘true'. In this case, the email address from the ‘NewEmail’ column won’t be used, but it’s still required that this column has a value. You can leave the default email address unchanged or add a valid address.

Editing the CSV file in the advanced experience

The advanced experience is entirely based on using the CSV file, without any automatic options to choose from. You use a single CSV file for all users.

Before you begin

Using the CSV file is available only in the Jira Cloud Migration Assistant.

Good to know

• 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:

What the columns mean:

• 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.

• ErrorType: Problem with the email address, either invalid, duplicated, or none if the user’s email address is correct.

• OldEmail: Current email address.

• NewEmail (editable): For users with invalid or duplicated emails, it’s a pre-generated email address that is valid and unblocks the migration. For users with correct emails, it’s their original email address.

• Tombstone (editable): Controls whether a user should be migrated as Former user. The values are True or False.

• AccountType: User type, either a regular user or a customer from Jira Service Management.

How to edit users in the CSV file

Here’s a summary of all actions you can apply in the file, with details on how each action affects a user.

Assigning new emails to users

To assign a new email, change the email address in the NewEmail column to any valid email address. By default, the column includes the following emails:

• For users with correct emails, it includes their original email address.

• For invalid or duplicated users, it includes a pre-generated email address that is valid and unblocks your migration. Note that these emails aren’t actually working and you need to change them if you’d like these users to be able to log in after the migration.

The pre-generated email addresses are based on user ID and a domain most common in your user directory.

Merging users together

To merge users together, use the same email address for all users you’d like to merge. You can merge any users, even if they’re not actually duplicated.

The merged account created after the migration:

• Is one of the merged users (chosen randomly) with content and activity from the remaining accounts

• Includes permissions and groups from all merged users, including admin permissions, and permissions from deactivated users

Migrating users as former users

To migrate users as former users, change the value in the Tombstone column to true.

A former user:

• Is deactivated, can’t log in, and can’t be restored

• Doesn’t consume a license

• Has every activity, such as comments or history, preserved but displayed under the name ‘Former user’

• It’s a container that groups activity from all former users, for example deleted users