Summary

The Jira Cloud Migration Assistant saves records of entities and tracks changes to entities. This prevents:

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

• unnecessary duplicates – multiple copies of the same entity.

How the Jira Cloud Migration Assistant works

The Jira Cloud Migration Assistant is non-destructive, so it 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 will check to see if it already has a record of that entity. 

• If an entity in your migration has the same name as an entity in the cloud site, and we have a record of migrating it, we will link your data to the existing entity in the destination site. We will not re-migrate this entity.

• If an entity in your migration has the same name as an entity in the cloud site, and we don't have a record of migrating it, we will modify the name by adding (migrated) to avoid duplicates and ensure there's no data loss (we cannot guarantee that a field with the same name is exactly the same field). For example, an entity called Custom field A will be renamed to Custom field A (migrated) after migration.

Duplicates

Sometimes it's necessary for configuration entities to be duplicated when a migration is done. In some cases, like migrating data from different scopes/server instances, duplication can be good because it ensures that entities with the same name but different underlying properties don't get merged.

What you see on the server:

What you can potentially see in Cloud:

Duplicate entities will be flagged as “(migrated), (migrated 1), (migrated 2) etc.” in the destination site depending on the number of migrations that were affected by this behavior. Large amounts of duplication (e.g. 20 duplicates for each custom field) may cause performance issues.

Possible causes for 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:

• Entities with the same name are being migrated from multiple server or Data Center instances into a single cloud site

  Click here to expand...

  Test Server Instances

  One example use case is that a customer clones their production site to a test instance in Server. This test instance is stand-alone and has its own server-id, so it's logically a totally different server instance. You then attempt migrations from the test instance to the destination cloud and all config entities get migrated.

  When testing is done, you remove migrated projects from the cloud site, but removing projects doesn’t delete config data. With the next attempt to migrate e.g. a production run from your Server Production instance, all config data will get duplicated as JCMA doesn’t check for any existing overlap.

  Consolidating multiple server(cloud) instances in one cloud instance 

  Similar to the scenario above, but if you try to migrate from  n(number of servers), JCMA has no way of checking the migrated entities from other servers, so it will duplicate the elements by design.

• Default entities that come out of the box with cloud that are also in a migration plan from server

  Click here to expand...

  This case affects all migrations. There are some Jira default entities that exist by default in fresh Jira server and cloud instances. If some of these entities exist in the both cloud and server instances, it gets migrated from server instances to the cloud as currently there is no mechanism for checking existing default entities.

• Migrating data in stages, first with Jira Site Import then followed by the Jira Cloud Migration Assistant from the same server or Data Center instance, will cause shared configuration entities to be duplicated. 

• For custom fields, fields could be duplicated if one of these are true:
  • The fields have different data types
  • The fields have different descriptions - even minor changes in the description text will mean that fields will not match
  • The fields have different field contexts

Possible workarounds to prevent duplicates

1. The easiest way to prevent duplicates if you will be testing from multiple Server instances (e.g. production mirrors) is to use a non-production test Cloud environment. This will allow you to test from as many servers as you'd like without polluting the content in your Cloud production instance and ending up with multiple duplicates caused by testing. This is especially critical if you have existing data in your Cloud instance since there's no documented programmatic way of cleaning up duplicate entries. 
   1. In order to wipe the duplicates for a new test run, completely reset the site and restart migration from a new server
2. If you need to perform a merge from multiple server instances, then one way to prevent duplicates is by merging the server instances first before migrating with the migration assistant. We understand this is not always possible, so if you must migrate from multiple server instances to the same cloud destination, then we recommend testing to get an idea of the duplicate items that will come. 

Tracking changes to entities

The longer the time between migrations, the more chance there is of an entity being deleted or modified. If you are merging Jira instances and you need to take a phased approach, we recommend  ensuring that  few  people as possible have access to the  Jira Administration Console  in both cloud and server and coordinate with your team to put a freeze on shared entities changes until the full migration is complete. This can be accomplished via permission management in your Jira instances.

Still need help?

Have you checked all the listed suggestions but couldn’t address the error message, please engage with our support team for further assistance.