Howto merge JIRA instances

 This page has been deprecated. Please refer to the documentation on restoring a project from backup, which supersedes this document.

Merging 2 jira instances together using a modified atlassian-data-utils xml parser.

USE AT YOUR OWN RISK. This procedure worked well in our environments. Please test your merge result very good before you put it into a live environment.

!! READ THE WHOLE DOCUMENT BEFORE YOU BEGIN. THERE ARE SOME IMPORTANT NOTES WRITTEN DOWN !!

Prerequisits

  1. Backup xml JIRA instance A
  2. Backup xml JIRA instance B

Note: Both JIRA instances should have run the same version. Upgrade both instances to the version you want to have the final backup imported in. Than create the backups of both instances.

java -Xmx600m -DentityExpansionLimit=1200000 -jar saxon/saxon8.jar instanceA.xml parser.xsl targetxml=instanceB.xml > newbackup-translated.xml

Note: This process takes a while. 25 MB backup file took approx. 25 minutes.

Next, manually copy all entries from the newbackup-translated.xml file into the instanceB.xml file but keep in mind the listed exceptions below:

EXCEPTIONS

  1. The list of “SequenceValueItm” elements could not be the same as in the instanceB.xml. Copy all elements and overwrite the existing elements.
  2. OSPropertyEntry[@entityName=jira.properties] elements may only exist once! Either overwrite the elements in instanceB.xml with the elements in newbackup-translated.xml or simply don’t copy them.
  3. The most difficult task: Alter all workflows prior to coping them over. There are 3 xml values that need to be changed. For the first two elements with a number >= 10000, place “222” in front of it. For the last one the number should be > 13
    • 10000 TO 22210000
    • 10010 TO 22210010
    • 16 TO 22216
  4. OptionConfiguration –> should point to the existing Default Issue Type Scheme

AFTER IMPORT

  1. Go to “Permission Schemes” > “Default Permission Scheme” and remove all duplicate permissions
  2. Go to “Issue Types” > “Issue Types Scheme”-tab and remove the 2nd un-associated Issue Type Scheme from the list.
  3. Go to “Screens” –> Default Screen, Resolve screen e.d and clean up the duplicate Field Tab’s

LOST INFORMATION

  1. The SearchRequest elements are not copied to the newbackup-translated.xml file. The content is XML and it is too hard to change that during the copy process. Therefor all users with a custom portal page will loose their custom defined filters.

FILES

20 thoughts on “Howto merge JIRA instances

  1. I have to say, this is outstanding work, Arjen. Last week I completed a merge of 2 different JIRA systems, each with XML files ~ 40MB in size. As you can imagine these were massive repositories, and your tool did the job quite well considering the complexity involved.

    The thing I did screw up on was step #3. There is a lot of art in searching and replacing on the fields in question. And in fact, after restoring the new XML file, I had an issue with a duplicate screen scheme (2 with the same ID) in the database. The result was that I was stuck with a read only JIRA. After tracking down the dupe scheme I was able to find and delete one, and after that it worked just fine.

    One thing I’d like to contribute is attachment migration. Because your script takes all the old issues and renumbers them with a “222” prefix, all the attachments from the old JIRA are no longer reachable. To resolve, you can run this UNIX script on the attachments directory for the old JIRA (I hope this text survives the blog comment system):

    # find . -type f | sed ‘s/\(.*\)\/\(.*\)/mv “\1\/\2” “\1\/222\2″/’

    …then move that folder to the new JIRA. The new system will pick up the location correctly.

    Thanks again for such an impressive tool and for your contributions to the JIRA community.

  2. OK, the formatting was good, but the script is wrong. Here is the corrected shell script:

    find . -type f | sed ‘s/\(.*\)\/\(.*\)/mv “\1\/\2” “\1\/222\2″/’ | sh

    If you want to see what will get run as a sanity check, leave off the “| sh” part at the end, and you’ll see the list of “mv” commands the script will pop out.

  3. Thanks. I’m glad i’m able to help somebody with this “tool”. I will wait with any further improvements as Atlassian itself is currently implementing some kind of backup and restore functionality for individual projects. I hope their solution will be more advanced than this script 😉

  4. I was referred to your site to merge 2 Jira instances. I used the tool and followed the instructions, using v3.13.1. Works pretty well, mostly. I noticed that Project Roles were lost, which affects the notification scheme and the permission scheme. This will require quite a bit of post merge cleanup work. Is this a known issue? Is there a work around?
    Also, is there a script to update the attachment names, for a windows based system?
    Other than that, it is mostly removing duplicate issue types, priorities, resolutions, etc.
    Thanks
    Russ

  5. Hi Russ,

    Due to the effort that Atlassian has put in restoring and backup of single projects, this tool is no longer maintained. Also the Project Roles are new features right?

    Perhaps you can have a look at the new version of jira

  6. The new version of Jira does have single project import, but that still leaves one to manually migrate (or recreate) all the users, fields, screens, permission, workflows, schemes, etc. I was hoping to use this tool to accomplish that.

  7. I see. I didn’t knew that. Perhaps it is worth it to keep this tool alive. If i can find the time i will see what i can do.

  8. The new project import process is outlined here – http://www.atlassian.com/software/jira/docs/v3.13.2/restore_project.html

    Note that before you import that project you need to manually create the users, workflows, custom fields, groups, roles, workflow schemes, screens, screen schemes, status, issue types, priorities, resolutions, permission schemes, notification schemes, field configuration schemese, etc.

    So all you get from the import tool is the project data, versions and components. The rest has to be there before you import. So it is better than nothing, but still an incomplete solution.

  9. I have stopped working on this procedure the moment Atlassian has implemented its own restore procedure. It is still a very time consuming activity to restore individual projects from a backup.

    The parser.xsl is in de file-list at the bottom of this post.

  10. did do the merge but i get now a problem when closing an issue: the fix version number is not saved. same issue when editing the fix version number. the only way it works is when opening a new issue.

  11. got it fixed: Go to “Screens” –> Default Screen, Resolve screen e.d and clean up the duplicate Field Tab’s

Leave a Reply