Handling of Historical Key Conflicts in Jira Cloud Migrations
Platform Notice: Cloud and Data Center - This article applies equally to both cloud and data center platforms.
Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
Check how the logic between historical keys for work items and projects works on Jira Cloud when migrating.
Solution
Overview
When you move an work item to a different project or rename a project, the work item keys change.
However, Jira reserves all previous historical keys, so if you try to access your work item using the link (pointing to its historical key), it will still work.
These historical key reservations were not migrated until the Jira Cloud Migration Assistant (JCMA) 1.4.3.
Now that both your Data Center and cloud sites may have clashing historical work item keys, we had to take measures during migration to resolve those conflicts, and you should know how we are doing this.
What can go wrong
Let's assume ALPHA -1 is a work item belonging to project ALPHA in the cloud instance. It was later moved to another project, BETA, and its new key is BETA-5.
Before moving the work item, you may have saved the link somewhere; for example, you may have bookmarked it in the browser.
After it became BETA-5, the old link pointing to ALPHA-1 continues to work because it redirects your browser to BETA-5.
Now, let's say the ALPHA project no longer exists in the cloud, and you are migrating an entirely different, unrelated project, ALPHA, from your Data Center instance, which also happens to have a work item with the key ALPHA-1.
Since your cloud instance can only return one result when searching for work item ALPHA-1, we have a choice to make.
In this case, we would resolve the conflict in favor of the Data Center's version of ALPHA-1 because it is the work item's current/active key, which takes priority over a historical alias.
This would lead to a side effect where your bookmark to ALPHA-1 will now point to a different work item, ALPHA-1, which was migrated from the Data Center and will no longer redirect to BETA-1.
On the other hand, if you had ALPHA-1 bookmarked, say, on a page of your Confluence Data Center instance, which was also migrated to the cloud, the same conflict resolution logic would result in the desired behavior, where ALPHA-1 would still point to the correct work item after migration.
These are just two possible scenarios requiring conflict resolution, so you must understand how we resolve these clashes.
Clash resolution logic
To put it simply, the resolution logic follows two simple rules:
The current (active) key wins over a historical one
Clashes between two historical keys are resolved in favor of the cloud version
As before, we don't allow clashes between two current keys for projects or work items.
Here's a detailed breakdown of possible clash scenarios and how we will resolve those:
For projects:
Data Center Key is | In the Cloud | Who wins? | Details |
|---|---|---|---|
Active | Does not exist | N/A | There are no clashes, and the project gets migrated. |
Active | Active or Historical | N/A | Migration is not allowed, and pre-flight checks block it. |
Historical | Does not exist | N/A | There are no clashes; the historical key gets migrated and will become a historical key for its active project in the cloud. |
Historical | Active or Historical | Cloud | The Data Center's historical key will be effectively ignored. After migration, this project key will be pointing to what it was pointing to before - the Active or Historical cloud's version. |
For work items:
Data Center Key is | In the Cloud | Who wins? | Details |
|---|---|---|---|
Active | Does not exist | N/A | There are no clashes, and the work item gets migrated. |
Active | Active | N/A | Migration is not allowed, and pre-flight checks block it. This situation implies that the same project exists in the cloud. |
Active | Historical | Data Center | The active version wins. After the migration, the link pointing to this work item will no longer redirect to the cloud's Active version but will render the Data Center's migrated Active version. |
Historical | Does not exist | N/A | There are no clashes; the historical key gets migrated and will become a historical key for its active work item in the cloud. |
Historical | Historical | Cloud | The Data Center's historical key will be ignored. After the migration, this work item key will point to the cloud's version of the work item, which is what it was pointing to before. |
Historical | Active | Cloud | The existing Active cloud version will shadow the historical key from the Data Center. After the migration, this work item key will be pointing to what it was pointing to before - the Active Cloud's version. The difference with the previous case is that we will still import the Data Center's historical key as a history of its current Data Center work item. Still, it will be inactive until you delete the Active work item or the Active project shadowing it. |
What we have planned for the future
The clash resolution logic described above should be sufficient for most migration scenarios.
Still, as demonstrated above, depending on your situation, it may or may not result in changes to links post-migration.
We will consider adding more flexibility to our migration logic in the future, which could let you choose which side should win in conflict resolution—the Data Center or the Cloud.
Was this helpful?