Move Projects (with Issue Data)

On this page:

Description

Moving project(s) between different Jira servers is a quite common scenario. The goal is that the project is transferred to the target Jira server transparently with no loss of data or capabilities.

The different parts of the projects that need to be transferred are:

  • configuration

  • Scrum and Kanban boards

  • filters

  • dashboards

  • issues

  • issue links

  • comments, labels, work log entries

  • attachments

  • Service Desks and all related configuration data

  • apps, their configuration, and data

  • all other user-defined data

 

 

Configuration Manager handles all of the above with the exception of some 3rd party apps' configuration and user-defined data (preferences, favorites).

  • Configuration Manager's support for issue data migration was developed from the ground up and does not rely on Jira's Export/Project import, meaning it does not inherit any of its limitations (including issue history, ranking, reports, links, and other problems listed in this section). 

For best performance and to avoid potential OutOfMemory errors for large snapshot deployments make sure you increase the Java heap for your Jira. You can use the Jira sizing guide as a reference, and double the heap numbers for very large deployments. A rough guideline is 12-16GB for moving a project with 100 000 issues (attachment files moved separately).


~ 1 hour

2 Jira Servers* 

Project Snapshot

New Project Mode

Medium

Supported

*2 Servers are required. Production 1 (Source) and the Production 2 (Target) system.

Licensing

You need two paid commercial licenses, one for the Production 1 (Source) and one for the Production 2 (Target) system.

 

 


Steps

This use case has several phases:

  • User Management Normalization

  • Project Configuration and Issues transfer

  • Apps Configuration and Data

User Management Normalization

Jira users, groups, and roles are an integral part of the Project Configuration - permissions, notifications, workflows, etc. Any users, groups, and roles used in the project that you are attempting to move will be included in the project snapshot, and during deployment, Configuration Manager will attempt to create them on the target server*. This will work for most cases but might have the following limitations:

  • User with id johnsmith from the Source might already exist on the Target with a different id - john.smith or jsmith, for example. In this case, Configuration Manager will create a new user with id johnsmith, which won't be accurate.

  • The user with id johnsmith from the Source and the user with the same id on the Target might be a different actual user. In this case, Configuration Manager will NOT create a new user with id johnsmith, which won't be accurate.

  • The users will be created and will increase the user count, which might have license implications.

  • The users/group creation might not be successful - due to the lack of a writable directory.

As of version 4.1.1 and later Configuration Manager has the option to exclude changes in Roles on deployment, which means that users and groups referred to only by roles will not be created on the target server. 

Project Configuration and Issues transfer

  1. Source: Create a project with Issues snapshot for the project(s) you are moving, including all filters, agile boards, and dashboards.

Configuration Manager provides two ways to handle moving attachment files. Read more about Moving Attachments here.

 

  1. Target: Deploy snapshot

a. Use New Project deployment mode, provide project name and key, they should not match any existing projects. Note - if the snapshot includes multiple projects, you won't be able to specify separate new project keys; instead, CMJ will try to find matching projects on the target instance (by project key), and if there is no match for any project, a new one will be created.

b. Review the change and impact analysis in the Analyze step of the deployment. You will see that many new objects will be created (marked with Add or A icon ), and some configuration elements will be modified as well (marked with Modify or M icon). The modified elements appear because there are underlying configuration elements with the same name and type in the snapshot and the Target Jira system. If some of the modifications are not desired, then the configuration on the Source system has to be modified and the process restarted.

Usage of default schemes is not recommended. If they are used, the default schemes on the target server will be changed and this will lead to a great number of changes.

c. Review the issue import analysis page for the issues that will be added to the specified projects.

d. Proceed with the deployment once the analysis shows the desired changes and impact.

App Configuration and Data

Several of the most popular apps in the area of custom fields and workflow extensions are supported by Configuration Manager. For the rest of the apps, we developed a Service Provider Interface (SPI), which allows app vendors to integrate their apps with Configuration Manager. If the apps that you use are not listed on the List of Integrated Apps page, please contact the app vendors with a request for integration with Configuration Manager.

Issues Import

Importing the issues into the Target Jira server can be accomplished with the native Jira Project import tool. This tool can successfully accomplish the task of importing the issues but has many known issues and limitations - check the limitations section on this page Jira Project import tool. In summary, the following are the biggest issues:

  • Issue History problem - this is probably the most critical issue that makes the issue history unusable - https://jira.atlassian.com/browse/JRA-35604

  • Does not handle a case where there are multiple fields of the same type with the same name, the one with a lower field ID will be used.

  • The "Agile Ranking" is not handled, and the Agile board order won't be preserved. Other Agile-related issues - https://jira.atlassian.com/browse/JSW-13788, https://jira.atlassian.com/browse/JRA-34338,

  • The "Agile Sprints" data won't be imported if using a Jira version lower than 7.0. -https://jira.atlassian.com/browse/JRA-28748

  • Any missing users will be created in the internal directory, if the User Management Normalization phase is successfully completed, this should not be a problem. If users are missing and cannot be created, then the import stops. Note that if the 'Do not merge changes in project roles' option is selected, Configuration Manager will not try to create users and groups referred only by roles. 

  • Any remote links, including the ones to Confluence pages, won't be handled https://jira.atlassian.com/browse/JRA-30460.

If you think that is something too risky or time-consuming for you, please contact our services team for assistance.

Automation

Automation of the above steps can be accomplished using the public REST API.

During the deployment, CMJ creates all issue links that are exported with the snapshot as long as the destination issues exist in the target or in the snapshot.

Example:
In my instance, Project A and Project B have linked issues. I deploy only Project A to my target instance. Then, I deploy Project B. All issue links between Project A and Project B will be created as long as the project keys are not changed during the deployment!

 

For more information on deploying snapshots with issue data, please refer to:

https://appfire.atlassian.net/wiki/spaces/CMJ/pages/198116612