Overview

This document describes best practices for moving projects between Jira server instances. The described migration processes are performed with the help of the Configuration Manager for Jira add-on. In addition to moving Jira projects, the described approach can be used for consolidating efforts such as merging multiple Jira instances.

Definitions

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

• Development – A free-for-all one or many 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.
• Configuration snapshots are created using the Configuration Manager for Jira add-on 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

Data

This guide presents how to run a transparent, end-to-end migration with no data loss. The majority of the data objects are handled out-of-the-box by the Configuration Manager for Jira. All exceptions and ways to handle them are listed in the Limitations sections of this guide.

Process

The moving of projects between Source (Production 1) and Target (Production 2) instances will result in changes in your Target (Production 2) instance. We recommend that you follow the  Test -> Staging -> Production procedure. Before the migration, a significant analysis should be performed. These activities are grouped under the Analysis phase in this guide. The major difference between the process of moving projects and rolling-out configuration changes is that in the first case scenario all user-generated data needs to be transferred, which requires a 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; see Application Migration Specification.
• Development - during this stage Migration Procedure document is developed and tested on the test server.
• Staging - during this stage the Migration Deployment procedure is staged and tested on the staging server.
• Production - during this stage the migration deployment procedure is executed in the official production environment.

Planning

The following planning steps described in the Test-Staging-Production procedure use case should be completed before the migration:

• 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 condition of both, source and target, instances and fix any detected issues. System health assessment should be performed with Jira Integrity checker and Configuration Manager for Jira Integrity Check.

Stages

Stage One: 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

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

1. Add-ons and Versions

   Both Prod 1 and Test Server meet the following requirements:

   • • Running the same Jira version
     • Have the same set of add-ons with matching versions

2. User Management Normalization

   If both production servers are using the same external user directory, there should be a full match between the users and groups on both serves. If the match is not full, an analysis should be performed to identify gaps and conflicts. 

   Example

   1. 1. Gap: On Prod1 Jane Smith has username jsmith, while on Prod 2 server her username is jane.smith
         
      2. Conflict: Both servers have user John Smith with username jsmith, but the usernames correspond to two different people

   Similar issues apply to user groups.

   Typically, the list of conflict and potential matches should be prepared and then the business users should provide information 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 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 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.

3. "As is" strategy

   In most cases, the issues and project configuration are moved to the new production server "as is" without any modifications. Any 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. For more information on the migration process with transformations, contact Botron's service team.

   Example

   The Bug issue type might be part of different workflows on the two server instances. When you move a project with that issue, users have to choose between two options. In the "As is" case, the various projects use different workflows for the same issue type. 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.

4. 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 done with the Configuration Manager for Jira change and impact analysis feature. Prior to the 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 doing 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 order following that of a Jira menu.

   2. This analysis is a great opportunity to optimize the usage of custom fields and reuse them between the two system instead of creating new ones. This will greatly improve the performance of the server.

5. Default Schemes

   Any default schemes used on the Prod 1 server by the migrated projects should be changed. To change the default schemes: 
   1. Copy the used default scheme.
   2. Rename the newly created scheme.
   3. Associate the project(s) with the new scheme.

6. Quality Strategy

   A quality strategy should be developed and agreed upon by all stakeholders. The recommended quality strategy consists of test plans for each of the phases, and a post-migration remediation plan.
7. Test Plans

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

1. Filters - number of issues, issue ordering, column layout
2. Dashboards - layout (columns, rows), gadgets & gadget content
3. 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
4. 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)
5. Security
   1. Projects - role memberships, access and operations for different roles
   2. Boards, Filters, and Dashboards - ownership and operations
6. 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 is 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 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 a SLA for response and resolution. 

Stage Two: 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

Each of the migration tasks should be properly documented and put in an ordered list. It should include any input data and enough details so that it can be repeated consistently.

The recommended approach for documenting is a structure of tasks and steps to accomplish each task.

1. For each of the data or configuration changes included in the AMS document, execute the required steps.

2. Create 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 

   Issues support is still in Beta mode. We're making our best to provide official support for this with Configuration Manager 5.0.

   

3. Download the configuration snapshot.  If your Jira configurations are being tracked via tickets, the snapshot should be attached to the appropriate tickets.
4. Deploy configuration snapshot to Test Server and validate proposed configuration changes.
   
5. It is crucially important to make sure 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.
6. Update the ticket with the required deployment time for the snapshot deployment.
7. Execute the test plan for test stage
   1. If the tests fail, they have to be resolved. Restore your backup on the clone of Production 1 and the Test Server and resume from step 1.
   2. If the tests pass, attach the Migration procedure to the migration ticket and proceed to Stage 3.

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

Stage Three: 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:

1. Verify the migration procedure and conduct an UAT.
2. 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:

1. Execute each of the tasks from the migration procedure without any modifications.
2. Estimate the required downtime.
3. Perform development stage tests.
4. Perform the UAT tests.
   
   

• If both the development phase test and the UAT are successful, declare successful staging and proceed to production.
• In the case of failure, depending on the type of issue(s), either change the deployment procedure and repeat the staging or go back to development phase to correct the issue(s).

Stage Four: 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.

The steps of this stage are as follows:

1. Create full backups of both production servers.
2. Restrict the user access to Production 2 server.
3. Execute each of the tasks from the migration procedure as they are captured without any modifications.
4. Execute development stage tests.
5. Execute the UAT tests.
6. If both the development phase test and the UAT are successful, declare successful migration and open the access for the users.
7. If not successful, depending on the type of issues found there are two options:
   1. Apply changes/fixes to Production 2 server and rerun the UAT tests.
   2. Restore the backups and reschedule the production deployment until the issues are resolved.

Limitations & Workarounds

There are certain system limitations that need to be considered:

• Add-ons data: Certain add-on custom field configuration, add-on workflow property configuration any other add-on data outside of Jira configuration objects might not be included. A custom solution needs to be developed.
• Jira Service Desk: Jira Service Desk-specific configuration is not supported OOTB. It will be added in future releases of Configuration Manager.

Suggested workarounds regarding limitations and other known issues include:

• Scripts - API level scripts can be developed to migrate any data not handled by Configuration Manager for Jira. Great choice for scripts development is using the ScriptRunner add-on.
  
• Manual - If the amount of configuration is not extensive it can be manually added to the target Jira.
  
• Professional Services - Botron's team of solution architects can develop a custom solution that migrates any type of data.
  

Common issues

We have identified several common issues during deployments, which could negatively impact the data portability process. Some of the more common issues include:

• Integrity Check errors which prevent the snapshot creation/deployment. In order to preserve the integrity of the target/production server. Configuration Manager Integrity check is executed every time a snapshot is created or deployed. All critical errors reported should be resolved in order to continue. Details information can be obtained here.
• Differences in Jira versions: differences in source-target Jira versions, specifically major versions.
• Application permissions/licenses:  for 7.x, e.g. deploying a software project when the user performing the deployment doesn't have permissions to create software projects; or the Jira Software application isn't installed/licensed
• Proxy/firewalls: this may be problematic for large instances when creating a snapshot or before the Analysis phase when deploying, otherwise there shouldn’t be any issues with the deployment itself. This is worked around by increasing any timeout limits on the proxy servers and disabling the firewall blocking rules.

Frequently Asked Questions

1. Is my entire configuration and all the issues are going to be moved to production automatically using Configuration Manager for Jira?
   Yes. The entire configuration, captured in the configuration snapshot, will be rolled-out. All the issues to the selected projects as well. Some add-ons configuration and data which are not supported by Configuration Manager for Jira won't be moved. The supported objects are listed here.
2. Can I move projects to a server with a newer server instance to an older server instance?
   It is strongly recommended that both productions servers are on the same version. The opposite adds unnecessary complexity.
3. How long does it take to move multiple projects?
   Depending on the user management normalization, the amount of data and the other analysis. It can take anywhere from several hours to few weeks.
4. Can custom add-ons data be moved using Configuration Manager?
   Yes. Configuration Manager can be extended to handle any custom add-ons. Contract Botron's services team for more information.

Need Help?

If you cannot resolve the problem yourself, you can contact us for assistance via the following communication channels

• Send email to support@botronsoft.com
• For training or services specific information contact at services@botronsoft.com