This page last changed on Jun 18, 2009 by rosie@atlassian.com.
This page has been deprecated. Please refer to the documentation on restoring a project from backup, which supersedes this document.

There are a number of tools and procedures available, that make it possible to merge projects and issues of several JIRA instances into a single instance. This may be useful, for example, if you have several JIRA instances in your organisation, and would like to combine them into a single instance for easier management and administration.

Merging JIRA data from multiple JIRA instances is not a straightforward process at the moment, and unfortunately we do not have extensive tools that get the job done completely. There are however a number of tools contributed by the community, which will be described here. Please note that none of these tools are officially supported by Atlassian. Also, most of these tools involve some customisations and/or a number of manual steps. For more information see JRA-1604.

CSV Export and Import

This procedure involves creating a CSV export of your data in one JIRA instance, then importing this CVS data into another JIRA instance using the CSV importer. This will not include all data (e.g. Attachments, Change history, ...), but it provides the easiest way of migrating projects into a single JIRA instance.

As of JIRA 3.2, the Issue Navigator Excel View has been vastly improved and a lot more fields can be included in the export. In order to merge data from two JIRA instances, you will need to

  1. Export the issues of interest, using the Issue Navigator Excel view. In order to do this, search for all the issues you would like to move (do one project at a time). Click on the 'All fields' Excel view, and save the resulting Excel file, as a CSV (comma-separated-values) file.
  2. Copy the CSV file to a temporary directory on your new JIRA server. (Note that the directory needs to be readable by the account that is used to run your JIRA instance.)
  3. Navigate to your new JIRA instance in a browser and import the CSV file using the CSV importer.

Data that won't be migrated includes:

  • Attachments
  • Change History
  • Comments
  • Issue Links
  • Issue Watchers & Voters
  • Permission Schemes for the Project
  • Notification Schemes for the Project
  • Groups

The CSV Export and Import method is the easiest approach to merging two JIRA instances. Novice users should follow this approach. Whilst some data can't be migrated using this procedure, all the information stored in an issue's fields will be migrated.

SOAP Extraction and Insertion - Swizzle

JIRA provides a SOAP API to query and update its data. Using this API it is possible to pull information from one JIRA instance and push this information to another instance. In order to do this, you will need to create a SOAP Client to carry out this operation. Fortunately there's already been a client contributed by the JIRA community.

Swizzle is an open-source project that aims to extract data from an unconsumable source and turn this data into a consumable form. With regards to JIRA this means extracting data from one JIRA instance and turning it into a form that can be imported by another JIRA instance. Swizzle in fact includes a JIRA Migration module which is aimed directly at making the migration of data from one JIRA instance to another possible.

Swizzle achieves the migration by extracting data via JIRA's SOAP interface and turning this data into a Jelly script, that can be executed on another JIRA instance. In order to carry out a data migration using Swizzle, please follow its instructions as closely as possible.

In order for Swizzle to work correctly, you will need to setup your JIRA instances using the following settings:

  • You are not using HSQL as your DB on the destination JIRA.
  • XML-RPC is turned on in the source JIRA.
  • Issues are publicly viewable (attachment and subtask data fetched via HTML) in the source JIRA.
  • The required Issue Types are available in the destination JIRA, and have the same names.
  • You have file system access on the destination JIRA.

Despite being able to migrate more data than the CSV method described above, Swizzle still suffers from various limitations:

  • Custom fields are not migrated.
  • Links between issues are not migrated.
  • Issue Watchers are not migrated.
  • Permission Schemes are not migrated (a "starter" scheme will be created).
  • Groups are not migrated (a yourproject-developers group will be created; anyone who has been assigned an issue will be added to this group).
  • Notification Schemes are not migrated (the JIRA default will be used).

Swizzle provides a more complete data migration than a CSV migration; however, it is also more difficult to carry out. This should only be considered by power users who are not afraid to execute Java code from the command line and modify XML files and Jelly scripts directly.

Merging XML Backup or Databases

The procedures outlined in this section are not for the faint of heart. Modifying XML backups or the database directly should only be done if you know what you are doing! It is very easy to get your data into an inconsistent state using this method.

Merging XML backups or modifying the database directly is the most difficult, but can also be the most complete data merge mechanism described in this guide. This section will not list a definitive guide for how this can be carried out (as this would simply be too difficult to list consistently for all the different versions of JIRA), but provide a few pointers and external resources that will be useful.

When merging JIRA data, the main things to worry about are:

  • Ensure no clashes occur in primary keys of any entity (e.g. users, groups, issues).
  • If primary keys are changed, ensure that all the relevant foreign keys are changed.
  • Ensure that each issue key and project key is globally unique.
  • Ensure that global items are not duplicated. For example, JIRA supports only one mail server, so please ensure that only one is used. Similarly, the global options, such as 'whether unassigned issues are allowed' must be defined only once.
  • Ensure that, after the merge, each entry of the SequenceValueItem entity has seqId value set to a larger value than the maximum primary key value of the corresponding entity. The entries for the SequenceValueItem are used to generate the next primary key of a new record.
  • Review the Database Schema for JIRA.

A set of instructions has been contributed by the JIRA community that makes this procedure easier, using XML backups produced by JIRA. Please follow the instructions outlined here for merging two JIRA XML backups safely.

Merging two JIRA instances via XML or the database is by far the most difficult method. It involves a lot of manual steps and has by far the greatest potential to corrupt your data. It may, however, yield the most complete data migration of all the procedures described here.

Document generated by Confluence on Oct 06, 2009 00:26