On this page:

Introduction

This document describes best practices and recommendations for moving projects between Jira server instances. The described approach can be used for consolidating efforts, such as merging multiple Jira instances.

For this document, we'll assume the following definitions:

Development: a free-for-all one or many test environments where users can play with cutting-edge or risky changes.
Staging: a pre-production environment, where the systems administration team can establish exact procedures prior to rollout. The staging should be a clone or close replica of the production environment.
Production 1 (Source): your live instance where the project(s) originate, expecting minimal downtime and well-tested changes.
Production 2 (Target): your live instance where the project(s) should be moved, expecting minimal downtime and well-tested changes.
Test server: Jira instance that is a replica of Production 2 (Target) and is used in the Analysis and Development phases for testing purposes.
Configuration snapshots are created using Configuration Manager for Jira app and represent the state of your Jira configuration objects and their relations to each other at a given point in time. There are two types of configuration snapshots:
- Project snapshot: contains the configuration of a number of selected projects (with their schemes, workflows, fields, etc.).
- System snapshot: contains the entire configuration of a single Jira instance (projects, workflows, schemes, screens, etc...).

Architecture Strategy Recommendations

The moving of projects between Source (Production 1) and Target (Production 2) instances will result in modifications for your Target (Production 2) instance, so we'd recommend you follow the Test - Staging -Production procedure. Before starting the procedure, a significant analysis should be performed - these activities are grouped in a separate phase called Analysis. The major difference between the process of moving projects and rolling-out configuration changes is that in the first scenario all user-generated data needs to be transferred, which requires significant up-front analysis. The process of moving multiple projects between Jira instances is comprised of four major stages:

Analysis - during this stage an analysis of the conflicts and gaps between the project configurations is performed captured in Application Migration Specification document.
Development - during this stage Migration Procedure document is developed and tested in the test server.
Staging - during this stage the Migration Deployment procedure is staged and tested in a staging server,
Production - during this stage the migration deployment procedure is executed in the official production environment.

Licensing

Only the Target production Jira instance is required to have a commercial license. The other Source production Jira instance can use either a commercial or a trial license.

Two free developer licenses will be needed for the Development and Staging Jira instances.

Planning

All planning steps described in the Test-Staging-Production procedure use case should be completed:

Prepare the staging environments & keep them synchronized
Install Configuration Manager for Jira
Track changes with change request tickets
Plan disruptive & non-disruptive changes during maintenance windows
Prepare communication strategy

Additionally, you should include the following planning steps:

Prepare backup of both production servers
Assess the health of both source and target instances and fix the detected issues. System health assessment should be performed with Jira Integrity checker and Configuration Manager for Jira Integrity Check.

Stages

First Stage - Analysis

Overview of the first stage:

Jira Instances: Production 1 (or a clone), Test Server (clone of Production 2)
Goals: Prepare Application Migration Specification (AMS) document
Users: Jira System Administrator, AD admin, DBA.
Tools Required: Configuration Manager for Jira

AMS document

The abbreviation AMS stands for Application Migration Specification. This document allows you to effectively communicate the configuration conflicts and changes planned to target Jira systems to the different stakeholders during a migration. Then, all parties in the migration can agree on configuration changes and conflict resolution strategies that will be executed on the target Jira system.

AMS allows you to ease your migrations and the communication between all stakeholders. You can customize its structure and information to suit the requirements of a particular migration. The document should contain information about each configuration change coming from the source Jira instance and the end result or conflicts on the target Jira instance.

AMS can serve as:

Contract between the source and target Jira instance stakeholders, and the migration execution team. All changes that will be performed on the target instance during the migration are agreed upon before applied.
Artifact of your change management process.
Report allowing all stakeholders to understand the impact of each change.
Document containing all the decisions agreed by you and the customer.

Below is the list of recommended analysis. If they outline any changes that need to be made, the changes should be included in the AMS document:

Apps and Versions
Both Prod 1 and Test Server meet the following requirements:
- Running the same Jira version
  - Have the same set of apps with matching versions
User Management Normalization
If both production servers are using the same external user directory there should be a 100% match between the users and groups on both serves. If this is not the case, an analysis should be performed to identify gaps and conflicts.
Example
1. Gap: On Prod1 Jane Smith has the username jsmith, while on Prod 2 server her username is jane.smith
  - Conflict: Both servers have user John Smith with username jsmith, but the usernames correspond to two different people
Similar issues apply for user groups.
Typically, the list of conflict and potential matches should be prepared and then the business users provide information on how to resolve it.
Warning
If the user management is not normalized a wide range of negative effects will take place. All fields where users or groups are used - Assignee, Reporter, etc. might contain the wrong user or group. All configuration objects with users or groups could end up improperly configured - permissions, notifications, workflow customization with users and user group fields, filter and dashboard ownership, Agile board administrators, JQL filters with users or user group fields, issue security schemes etc.
How to resolve gaps and conflicts
The general approach for both gaps and conflicts is to rename the username either on the Prod 1 or Prod 2 servers to ensure consistency. The renaming depends on the solution used for user management Crowd, AD, LDAP.
"As is" strategy
In most cases, the issues and project configuration are moved to the new production server "AS IS" without any modifications. Modifications will need to be transformed to ensure consistency on both Jira instances - this process will ultimately add significant complexity and time to the migration and should be included in the AMS document. For this guide, an "As Is" strategy is used.
Example
The issue type Bug might be part of different workflows on the two server instances. When you move a project with that issue, the users have to choose between one of two options - in the "As is" case, the various projects use different workflows for the same issue type, while in the transformation case the two projects will use the same workflow, thus all the source data will be transformed to match the new workflow.
Configuration Conflicts and Gaps
When migrating projects their names or keys might already exist in the Prod 2 server, this conflict should be resolved by renaming them on the Prod 1 server. The same can happen for custom fields, resolution, priorities, workflow names and schemes. The full list of conflicts and the mappings of their resolutions should be included in the AMS document. The reverse scenario is possible too when two custom fields on Prod 1 and Prod 2 have different names, but the same semantics. In this case, they ought to be merged during the migration.
Tips
1. This analysis of these configuration conflicts and gaps can be performed by using the Configuration Manager for Jira change and impact analysis feature. Prior to migration, the Configuration Manager for Jira enables you to perform a change and impact analysis and provides you with comprehensive details regarding the impact of the changes that will be applied to your Jira instance. By performing this analysis, you will be able to see the projects that will be affected by the change, identify any conflicts and gaps and resolve them. The list of introduced changes and their corresponding conflicts and gaps are grouped in tabs in the same logical order of a Jira menu.
2. This analysis is a great opportunity to optimize the usage of custom fields and reuse them between the two systems, instead of creating new ones. This will greatly improve the performance of the server.
Default SchemesAny default schemes used on the Prod 1 server by the migrated projects should be changed. To change the default schemes, perform the following steps:
1. Copy the used default scheme
2. Rename the newly created scheme.
3. Associate the project(s) with the new scheme
Quality StrategyQuality strategy should be developed and agreed upon by all stakeholders. The recommended quality strategy consists of test plans for each of the phases, as well as a post-migration remediation plan.
Test Plans

Development phase a set of tests should be executed to verify the following:

Filters - number of issues, issue ordering, column layout
Dashboards - layout (columns, rows), gadgets & gadget content
Agile
1. Board views (i.e. backlog, active sprints)
2. Issues, ranking, epics, versions, estimates, time tracking data aggregations
3. Quick filters
4. Sprints ordering & content
5. Reports
6. Project <-> Board associations
Issues
1. Agile data - sprints, epic links
2. Comments
3. History
4. Field values - 3-rd party custom fields, time tracking and estimates, other
5. Issue links
6. Confluence links
7. Bitbucket links (branches, commits)
Security
1. Projects - role memberships, access and operations for different roles
2. Boards, Filters and Dashboards - ownership and operations
Operations - transition through workflow, create/deleted/edit issues, comments ,etc.

Staging phase

the tests from the development phase are executed again and a User Acceptance Test (UAT) is performed by the users of the projects that are being migrated.

Production phase, a subset of the development phase tests are executed plus a limited UAT test. Typically, there is a time limit on how long can these tests be performed in the production. This time limit is aligned with the duration of the maintenance window during which the production phase takes place.

Post Production Remediation Plan - this plan covers the procedures designed to handle any post-migration issues that occurred during the production. It includes an SLA for response and resolution.

Second Stage - Development

Overview of the second stage:

Jira Instances: Clone of Production 1, Test Server (clone of Production 2)
Goals: Prepare Migration Procedure document
Users: Jira System Administrator, AD admin, DBA.
Tools Required: Configuration Manager for Jira

The development stage is the most complex and time-consuming. The steps of this stage are as follows:

Each of the migration tasks should be properly documented and in an ordered list. It should include any input data and enough details that it can be repeated consistently.
The recommended approach for documenting is a structure of tasks and steps to accomplish each task.

For each of the data or configuration changes included in the AMS document, execute the required steps.
Create a project snapshot that includes the projects that are being migrated from Prod 1 server. Include all related to the projects Agile boards, filters, dashboards and issues (issue data support is supported since release 5.0 of Configuration Manager).
Download the configuration snapshot (if your Jira configurations are being tracked via tickets, the snapshot should be attached to the appropriate tickets.)
Deploy configuration snapshot to Test Server and validate proposed configuration changes.
It is crucially important to validate that the proposed configuration changes and impact match the AMS.
1. If they don't match AMS, the changes made in step 2 need to be corrected. Restore your backup on the clone of Production 1 and the Test Server and resume from step 1.
2. If they match AMS - continue.
Update the ticket with the required deployment time for the snapshot deployment.
Execute the test plan for the test stage
1. If the tests fail, they have to be resolved. Depending on the nature of the errors resolutions vary - changing the configuration steps (step 1) or contacting our support team. Restore your backup on the clone of Production 1 and the Test Server and resume from step 1.
2. if the tests pass then attached the Migration procedure to the migration ticket and proceed to Stage 3

The steps described in this stage ought to be repeated several times to ensure that everything runs smoothly and both the proposed changes and the associated tests are successful.

Third Stage - Staging/QA

Overview of the third stage:

Jira Instance: Production 1 (or a clone), Staging Server (close replica of Production 2)
Goals: This is the grand rehearsal of the migration and has two major goals:

Verify the migration procedure and conduct a UAT.
Get an accurate time estimate for the duration of the migration.

Users: Jira System Administrator, AD admin, DBA, business users to conduct UAT.
Tools Required: Configuration Manager for Jira

The steps of this stage are as follows:

Execute each of the tasks from the migration procedure without any modifications.
Estimate the required downtime.
Perform development stage tests.
Perform the UAT tests.
If both the development phase test and the UAT are successful, declare successful staging and proceed to production.
In case of failure, depending on the type of issue(s), either change the deployment procedure and repeat the staging or go back to the development phase to correct the issue(s).

Fourth Stage - Production Deployment

Jira instance: Production 1, Production 2
Goals: Finish the migration in the official Production 2
Users: Jira System Administrator, AD admin, DBA.
Tools Required: Configuration Manager for Jira

The fourth and final stage of the migration process is, for the most part, identical to the staging stage. The major difference being that you'd be working with the actual Production 1 and 2 servers, not their clones.