Configuration Manager is a Jira plugin developed by Botron Software which offers several features to simplify the migration of configuration and data between Jira instances. It can be used to perform migrations between different servers for Jira Core, Jira Software, Jira Service desk and some 3rd party apps. To carry out the migration, the plugin needs to be installed on the source and target instances. A snapshot file containing the configuration (workflows, schemes, custom fields, etc.) and data of a single project, multiple projects or the entire system can be created on the source instance. The snapshot file is portable and can be deployed on the target instance without any loss of data and functionality.
Before preparing a fusion plan, an audit needs to be carried out on the instances to assess their health. The audit helps us to understand the size and complexity of the instances, and hence identify the potential risks involved in performing the fusion. If one of the applications is significantly larger and more complex than the other (in terms of number of configuration objects, number of issues, etc.), it is recommended that the data be migrated from the less complex instance to the more complex instance to reduce the risks.
Once the audit is complete, a procedure can be prepared which details the different steps of the migration. It is recommended to first execute the procedure in a staging environment to test it. Once the fusion procedure has been tested and validated, it can be executed in a pre-production environment. The steps involved in performing the fusion of two Jira instances are described below.
1. Alignment of Jira application and plugin versions
- Both instances need to be running the same Jira version. If they are running different versions, an upgrade needs to be performed.
- All plugins present on the source instance need to be installed on the target instance with matching versions.
2. User Normalization
The users and groups present in the source instance need to be present in the target instance before the projects are migrated. If users or groups are missing during the migration, 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.
- Before migrating the users/groups, perform an analysis to determine the gaps (e.g. same user has different user names on both instances) and conflicts (e.g. different users have the same user name on both instances, groups are duplicated on both instances). Each gap and conflict needs to be resolved.
- All LDAP Active directories which are present in the source instance need to be created on the target instance and synchronized.
- All internal groups present in the source instance need to be created in the target instance and users added to the internal groups.
3. Correction of Integrity check errors
- Configuration Manager contains a tool called Integrity Check which needs to be run on both the source and target instances before the creation of the snapshots.
- The tool can be run by going to Configuration Manager > Integrity Check, select all integrity check options and click on Run Integrity Check. It returns a list of errors and warnings for objects which are in an inconsistent state.
- All errors need to be corrected since they prevent snapshot creation and deployment. The warnings do not prevent the creation and deployment of snapshots.
Integrity Check Report
4. Default Schemes
During the migration, all default configuration objects present in both instances will be merged. To avoid any errors arising from the merge of these configurations, perform the following actions on both instances for all projects which use default schemes,
- Create a copy of the used default scheme.
- Rename the newly created scheme.
- Associate the project(s) to the new scheme.
5. Migration of projects
Create a snapshot:
To create a snapshot containing the configuration and issue data of multiple projects, go to Configuration Manager > Snapshots.
Click on Create Snapshot in the Snapshots Screen
Select Snapshot Type: Project with Issues and specify the projects to be contained in the snapshot
When creating a snapshot, it is possible to add the filters and boards which make references to the projects in the snapshot. However, these filters and boards might reference other projects which have not yet been migrated. It is recommended to migrate the filters and boards after all the projects have been migrated. Hence, the options Include Project Filters and Include Project Boards should be left unticked during the snapshot creation.
Project attachments can be added during snapshot creation, however, this increases the time needed to create and deploy snapshots. Instead, it is recommended to copy the attachments folder to the target instance server and provide the path to the folder during the deployment.
Snapshot Created – Details are present in the audit log
Once the snapshot is created, it can be deployed on the target instance. When the two instances are linked via an Application Link, the snapshots can be selected from the menu Configuration Manager > Deploy > From Linked Instance.
Target Instance – Deploy Snapshot Screen
To deploy a snapshot, click on Deploy.
In the screen that follows, provide the path to the attachments folder present on the target instance and click on Next.
Provide path to attachments folder on the target instance
On clicking ‘Next’, the Configuration Manager performs an impact analysis and displays a report with details of all the changes that will be applied to the target instance. The impact analysis should be reviewed to identify gaps and conflicts. Once these are resolved, recreate the snapshot and deploy it on the target instance.
Impact Analysis (If any error occurs during the snapshot deployment, all changes are rolled back.)
6. Migration of Filter, Boards, and Dashboards.
After all the projects are migrated, the filters, boards, and dashboards can be migrated using a system configuration snapshot.
To create the snapshot, go to Configuration Manager > Snapshots > Create Snapshot and select Snapshot Type: System Configuration.
The following options need to be ticked during the creation of the system snapshot.
- Include all Filters
- Include all Boards
- Include all Dashboards
Create System Configuration Snapshot
Click on Create to create the snapshot. Before deploying the snapshot, Review the impact analysis to identify if there are any gaps or conflicts.
7. Post Migration actions.
Once the migration of projects is complete, post-migration actions may need to be carried out on the merged instance. These could include actions such as:
- Recreating the links that exist between the source instance and other applications.
- Manually migrate the configuration of plugins which are not supported by the Configuration Manager, e.g. Tempo.
- If the source instance was linked to a Confluence application, the page links to the Jira issues and Jira macro references need to be updated in the Confluence database.