How Jira Cloud Migration Assistant links your data

In most cases, the Jira Cloud Migration Assistant will add data to your cloud site without overwriting existing data. However, there is an exception when it comes to managed issue types Epic and Story, which can overwrite existing issue types of the same original names in the destination site during migration. This means you can move to a new or existing cloud site, but it's important to plan for this specific scenario if you're using these issue types. If the cloud site already has data, the migration assistant might link the data instead of re-migrating it. This page explains how the migration assistant decides what to do with the data.

Records of entities

The Jira Cloud Migration Assistant will save a record of each entity (e.g., workflow or custom field) it migrates for the first time. In subsequent migrations to the same cloud site, the migration assistant checks if it already has a record of that entity and the entities are identical (i.e., they have the same underlying properties).

The migration assistant tracks what has been migrated and what has changed between migrations. This prevents:

• shared configuration (workflows, custom fields, schemes, etc.) of a project not matching between source and destination sites

• unnecessary duplicates (i.e., multiple copies of the same entity)

Tracking changes to entities

An entity can be deleted or modified after we’ve migrated that entity. For example, a custom field may be deleted in the destination site, or a new custom field option may be added in the source site.

This is why we keep track of entity field content and ensure it stays consistent over different migrations. The migration assistant lets you re-migrate a shared configuration entity if the entity has been:

• deleted from the destination site

• modified in the source or destination site

If an entity in your migration has the same name as an entity in the destination site, we will create a new entity with the original name and a “(migrated)” tag. We will then migrate your data along with this new entity.

For example, if an entity called Screen A in your migration has the same name as an entity in the destination site, and the entity has been modified, Screen A will appear as Screen A (migrated) in the destination site after migration.

If an entity in your migration has not been deleted from the destination site or the entity has not been modified, we will link your data to the existing entity in the destination site. We will not re-migrate this entity.

We will roll out this logic for all entities. Currently, this logic only applies to these entities:

• Custom field

• Custom field scheme

• Field configuration

• Field configuration scheme

• Screen

• Screen scheme

• Issue type screen scheme

• Permission scheme

• Issue security level

• Issue security scheme

• Filter

• Workflow

• Workflow scheme

Preventing unnecessary duplicates

We’re currently rolling out changes that will merge two entities only if their underlying fields are identical. For example, the priority entity will only be merged if the name and color fields are identical.

If an entity in your migration has the same name as an entity in the destination site, and the underlying fields are not identical, we will create a new entity with the original name and a “(migrated)” tag. We will then migrate your data along with this new entity. 

For example, if an entity called Priority A is being migrated and it’s not identical to the entity that exists in the destination site, Priority A will appear as Priority A (migrated) in the destination site after migration.

If an issue type in your server to cloud migration has the same name as a managed issue type in destination cloud site, a new issue type will not be created. Instead, the name of the issue type in the destination site will be updated to match the name from server since server is considered source of truth.

To work around this, create a new non-managed issue type in the Server/Data Center instance, bulk edit all desired issues to be the new issue type and then migrate. That way, the existing managed issue type in cloud will be unchanged, and then the new unmanaged type will also be present.

We will roll out this logic for all entities. Currently, this logic only applies to these entities:

• Issue status

• Priority

• Resolution

• Issue type link

• Project category

• Project role

• Issue type

• Issue type scheme

• Custom field’s options

Handling renamed Epic or Story issue types during migration

While the Jira Cloud Migration Assistant usually adds data to your cloud site without overwriting existing data, there's one specific scenario where overwriting can occur: when migrating renamed managed issue types like Epic and Story.

For instance, suppose you have two instances: Instance A (source) and Instance B (destination). In Instance A, you've renamed the issue type "Story" to "User Story". When migrated to Instance B, which already has a "Story" issue type, it will get overwritten by "User Story", not creating a duplicate but replacing the original.

To prevent overwriting of issue types during migration:

Option 1 - Before Migration:

1. In your source instance, navigate to Settings > Issues.

2. Select Issue types.

3. Select Add Issue Type and create a standard issue type type with your desired name.

4. Use the bulk edit feature to change all relevant issues to use this new issue type.

 Option 2 - After Migration:

1. In your destination cloud site, navigate to Settings" > Issues.

2. Select Issue types.

3. Locate the overwritten issue type and select Edit.

4. Rename the issue type back to its original name.

Multiple duplicates

Multiple duplicates may be created for an entity for a number of reasons. These will appear as Custom field A (migrated), Custom field A (migrated 2), Custom field A (migrated 3), and so on.

Duplicates may be caused by:

• a default entity existing in both the source and destination sites

• the server instance or cloud site being reset between migrations

• some data being deleted between migrations

We recommend performing your tests in a separate site to your production migration to avoid duplicates. Any changes that need to be made to the cloud site after migration can only be performed by site admins.

Users and groups

User migration uses the same logic. If a user's email address already exists in the destination site, it will not be re-migrated. Learn more about user migration

Server groups that already exist in the destination site will be merged. This means that some users may receive escalated permissions through the migration. Learn how groups and permissions are migrated

More information and support

We have a number of channels available to help you with your migration.

• For more migration planning information and FAQs, visit the Atlassian Cloud Migration Center.

• Have a technical issue or need more support with strategy and best practices? Get in touch

• Looking for peer advice? Ask the Atlassian Community.

• Want expert guidance? Work with an Atlassian Partner.