Project Name and Project Key Conflict When Migrating Using Jira Cloud Migration Assistant (JCMA)
Platform Notice: Data Center Only - This article only applies to Atlassian products on the Data Center platform.
Note that this KB was created for the Data Center version of the product. Data Center KBs for non-Data-Center-specific features may also work for Server versions of the product, however they have not been tested. 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
When migrating from Server/DC to cloud, the Jira Cloud Migration Assistant runs a set of pre-checks to verify the Source and Destination do not have Projects with the same name or project key.
Identify
Verify the Jira Cloud Migration Assistant app is installed. Create a new migration plan and select all projects or the desired projects you would like to migrate. Run the pre-check for the migration plan to scan the source projects and compare them with the destination projects on the cloud. If there is a conflict the output will look like the following:
Notice the Project section includes a dropdown arrow that can be extended. Selecting that will provide you with the exact projects that have a conflict:
Solution
Delete the Duplicate Project in Cloud
Make sure that the project in scope is one that was previously migrated by the JCMA and not a project that was already in production.
When you run a migration plan, data is migrated to the cloud. This data is never deleted by JCMA so any subsequent migration plan with the same project will fail to be migrated because the project already exists in the cloud. If you run into this scenario when running multiple tests, select Move to Trash from within the Project settings or while on the Project dashboard. Make sure to delete the project from the trash afterward:
- Choose
> Projects. - Select Trash from the sidebar.
- Find your company-managed project and select ••• > Delete permanently.
Rename the Project on the Source Instance
If there is already an existing Project on the destination cloud site that is different than the source, the recommended approach is to rename the project on the Source instance.
Editing the project key and/or project name
- Choose Administration (
) > Projects, and select the relevant project. - Locate the project that you'd like to change.
- Select Edit in the Actions column of the project you want to change.
- Edit the project key and project name, and click Save details. Only project types for applications you have installed will be available.
What to expect after editing a project key
The project will immediately begin re-indexing. This needs to complete before continuing with the migration plan. You can allow the re-index to run in the background. Critical changes are noted here: Editing a project key. Among those changes are as follows:
Post-update tasks
- Fix the project entity links — When you connected Jira to another Atlassian application, entity links would have been automatically created between your Jira projects and the relevant "projects" in other applications, e.g. Confluence spaces. If you change the key of a Jira project, you will need to fix the project entity links, as described in Creating links between projects.
- Updating Jira Software agile board filters - If your Jira Software agile boards use the old project key, the board filters may need to be updated to reflect the new project key. Otherwise, the board might not display issues from the renamed project.
Broken links
- Links will appear to work on the source environment because they reference the original project key. However, once this project is migrated to the cloud, the links that still referenced the original project key will now be pointing to the cloud project. Here is a scenario that explains this behavior:
- The Migration plan fails because there is a Source project ABC and an existing project ABC on the Destination cloud site.
- The user changes the Source project from ABC to DEF to eliminate the conflict.
- Links on the Source appear as https://jira.server.com/browse/ABC-123. After editing the project key, this link will redirect users to https://jira.server.com/browse/DEF-123 because Jira is aware of the original project key.
- After migrating this project to the cloud, the link https://jira.server.com/browse/ABC-123 will be broken. It is possible that Atlassian support can update the base URL to point to the destination cloud. However, ABC-123 is the issue key of the existing project in the cloud and there is no longer any reference to the original project key from the source that retains this reference in the cloud.
- The recommendation is to update these links manually on the source so that they point to the new project key DEF-123. Do this prior to migrating.
JQL queries
- While the filters will appear to work on the source instance, they must be updated prior to migrating. Similar to links, these filters will reference the old project key and this data will not be preserved in the cloud. Only by updating the JQL queries can you best ensure that the data is migrated correctly. It's best to update board filters, dashboard filter gadgets, and any other global queries with the new key.
Development tools
- This functionality will be broken once the project is migrated to the cloud.
- Please make sure the expectation is set with all impacted users/developers.
- Any development tooling will need to be reconfigured for the new project key. Make sure to check if the reconfiguration can occur on the development tool in use. That might not be the case for all of them.