Migration of Jira's historical keys for issues and projects
Situation / problem
When you move an issue to a different project or rename a project, the issue keys change. However, Jira reserves all previous historical keys so that if you try to access your issue using the link (pointing to its historical key), it will still work.
Up until now Jira Cloud Migration Assistant did not migrate these historical key reservations. This was fixed with the 1.4.3 GA release. Now that both your server and cloud sites may have clashing historical issue 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 an issue 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 issue, you may have saved the link to it somewhere, for example, you 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 server instance, which also happens to have an issue with the key ALPHA-1.
Since your cloud instance can only return one result when searching for issue ALPHA-1, we have a choice to make. In this case, we would resolve the conflict in favour of the server’s version of ALPHA-1 because it is an issue’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 issue ALPHA-1, which was migrated from the server 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 server instance, which was also migrated over to the cloud, the same conflict resolution logic would result in a desired behaviour, where ALPHA-1 will still point to the right issue after migration.
This is just two of the many possible scenarios, requiring conflict resolution, so it is important that you 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 favour of the cloud version
As before, we do not allow clashes between two current keys - neither for projects nor issues.
Here’s a detailed breakdown of possible clash scenarios and how we will resolve those:
For projects:
| Server Key is | In the Cloud | Who wins? | Details |
|---|---|---|---|
| Active | Does not exist | N/A | There are no clashes, the project gets migrated. |
| Active | Active or Historical | N/A | Migration not allowed, blocked by pre-flight checks. |
| 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 historical key from the server will be effectively ignored. After migration, this project key will be pointing to what it was pointing before - the Active or Historical cloud’s version. |
For issues:
| Server Key is | In the Cloud | Who wins? | Details |
|---|---|---|---|
| Active | Does not exist | N/A | There are no clashes, the issue gets migrated. |
| Active | Active | N/A | Migration not allowed, blocked by pre-flight checks. This situation implies that the same project exists in the cloud. |
| Active | Historical | Server | Active version wins. After the migration, the link pointing to this issue will no longer redirect to the cloud’s Active version, but will render the server’s Active version that was migrated. |
| Historical | Does not exist | N/A | There are no clashes, the historical key gets migrated and will become a historical key for its Active issue in the cloud. |
| Historical | Historical | Cloud | The historical key from the server will be ignored. After the migration this issue key will be pointing to what it was pointing before - the cloud’s version of the issue. |
| Historical | Active | Cloud | The historical key from the Server will be shadowed by the existing Active cloud version. The difference with the previous case is that we will still import the server’s historical key as a history of its current server issue, but it will be inactive until you delete the Active issue or the Active project that is shadowing it. |
What we have planned for future
The clash resolution logic described above should be sufficient for most of the migration scenarios, but 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 the conflict resolution - the Server or the Cloud.