How-to merge JIRA instances UPDATED

jiralogo A situation developed where two independent installations of JIRA needed to be combined into a single installation. The problem, however, is no native built-in capabilities to allow for this. This would not be such a simple task, however, someone developed a process to achieve this goal. Still not a simple task. This process has not been updated in a while, and I discovered after following the process I did not have a complete set of correct results. There are several reasons for this.

One reason is that I used the entitymodel.xml, parser.xsl, and parsergen.xsl files provided within the author’s process. After comparing the contents of the entitymodel.xml provided by the author and the one provided in the JIRA 3.12.2 download, I noted many differences between the two files. There was also an error generated from by the entitymodel.xml, relating to to dtd. So, I removed that line of from the entitymodel.xml file that was provided by the JIRA 3.12.2 installation.

<!DOCTYPE entitymodel PUBLIC "-//OFBiz//DTD Entity Model//EN" "<a href="http://www.ofbiz.org/dtds/entitymodel.dtd">http://www.ofbiz.org/dtds/entitymodel.dtd</a> ">

The final mistake that I had made, was using the parser.xsl that was provided by the author. I didn’t pay too much attention to the fact that it was only provided as a “sample”. This creates a whole new problem. How to create a parser.xsl file? After a couple of hours of research and testing, I figured out how to do this. Here is my take on the “How-to merge JIRA instances”.

How-to merge JIRA instances
Prerequisites

  • JIRA (two instances running at the same version)
  • The Saxon XSLT and XQuery processor (tested with saxonb8 and saxonb9.1)
  • entitymodel.xml – This XML describes the Entity Model of JIRA and is part JIRA (…\atlassian-jira\WEB-INF\classes\entitydefs\)
  • parsergen.xsl – This XSL takes the entitymodel.xml as input and generates a XSL (parser.xsl) that is capable of parsing the JIRA backup XML (located in the bottom of this article in the appendix.)
  • parser.xsl – This XSL is provided as an example output of the ParserGen XSL + EntityModel XML
  • Backup xml JIRA instance A (i.e. instanceA.xml)
  • Backup xml JIRA instance B – target xml (i.e. instanceB.xml)
    Look at Atlassian JRA-1604 to see a backup and restore feature build into JIRA.

    Note: Both JIRA instances should be the same version. If not, upgrade the instance of JIRA to the version as the other instance you want to have the final backup imported into. Then create backups of both instances.

Create Workspace
Create a folder and place the following files in it:

  • entitymodel.xml
  • parsergen.xml
  • saxon9.jar
  • instanceA.xml
  • instanceB.xml

Build the parser.xsl
From the command prompt in your folder, execute the following command to generate the parser.xsl

java -jar saxon9.jar entitymodel.xml parsergen.xsl > parser.xsl

Build a combined raw backup
From the command prompt in your folder, execute the following command to generate the newbackup-translated.xml.

java -Xmx600m -DentityExpansionLimit=1200000 -jar saxon9.jarinstanceA.xml parser.xsl targetxml= instanceB.xml > newbackup-translated.xml

Note: This process make take a while. A 25 MB backup file may take approx. 25 minutes.

Manual Edits and Exceptions
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. 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 the 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 Tabs

Lost Information

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

Attachments

One comment offered the following solution to the attachment migration. Since the script renumbers the old JIRA issues with a 222 prefix, the attachments from the old JIRA are no longer reachable. A resolution is to run this Linux script on the attachments directory for the old JIRA installation. When complete, move the contents of the old attachments folder to the new JIRA installation. The new JIRA installation will automatically recognize the attachments.

find . -type f | sed 's/\(.*\)\/\(.*\)/mv "\1\/\2? "\1\/222\2?/' 

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.

find . -type f | sed 's/\(.*\)\/\(.*\)/mv "\1\/\2? "\1\/222\2?/' | sh 

Appendix

parsergen.xml
The parsergen.xml file is the only element to this equation that I have not been able to validate as requiring an update.

  parsergen.xml (22.3 KiB, 1,035 hits)