Migrating Jira from Cloud to OnPrem

April 19
blog author


Sr. Technical Lead - Atlassian Expert

Migrating Jira from Cloud to OnPrem

One of the great things about the Atlassian stack, is that it is so easy to get started. Then after a short time, you can barely resist the urge to tell everyone in your organization that they should start using it and get rid of that ridiculously bloated and complex spreadsheet that only a "Master in Excel" could decipher what it is really doing and more importantly, how to use it!

After sometime, your organization has fully adopted working with the Atlassian tools, you have tons of projects running at full speed, you have a decent understanding of how the tools work, everything is great! Until its not...usually these things do not creep up on you, there were signs, slow system performance, maybe some availability issues or you have integrated with some other systems or extended Jira or Confluence in some way.

Then there is that "bespoke" app that some developer wrote and then left the company that uses the Jira Cloud REST API... we have all been there.

Then finally,  things such as, requests from users that ask for something that is beyond the capabilities of the Atlassian Cloud offering. Which, leaves you scrambling to find a solution in the market place, only to find out that it doesn't exist there.

Then you say no problem I will write the add-on myself! Only to find out the Atlassian Connect API doesn't support what you need it to do... but the server version does. Now what? You are in the cloud, you have not had to worry about being the sys admin on the server because Atlassian "graciously" handles that for you. But now, you have outgrown the cloud solution and its time to take ownership of your Jira and or Confluence instances.

So what do you do? There is a lot of helpful documentation from Atlassian that outlines moving Jira Cloud version to an on premise server. You may have already tried it and realized its not exactly a straightforward operation. There are a lot of little nuances, steps, hidden issues or even completely random issues that seemingly come out of no where with absolutely no explanation as to why you are experiencing them.

Don't feel like you are alone, this happens to everyone.. even me!! I have been working with the Atlassian tool stack for over 13 years and to this day, I come across things that I have never experienced before, especially migrating out of the cloud to server.

Just in the last two months I have ran into "random bugs" doing migrations and merging several systems into a single instance, that cannot be explained, even by Atlassian.

So how do you deal with them?

There are a myriad of solutions for each and every different issue and even the unique ones, you just have to understand what the system is telling you. When migrating out of the cloud, it is supposed to be pretty straight forward, make a server backup of your cloud environment which, packages the attachments, the xml files and configures them to be installed on a server.

Then you setup your server environment in your data center or AWS and restore it. If everything goes as planned you are good to go with a few minor tweaks but what happens when it doesn't go as planned? Start with looking at the logs, they will usually tell you what the problem is. There is also a tool from Atlassian that help called the "Atlassian XML cleaner".

This has been very helpful when migrating instances of Jira and Confluence. We run this every time we migrate, its function is to remove invalid characters from the XML.

Atlassian notes:

However, that is not my experience, so whenever we do a migration, we run this little gem which, helps avoid failed restores.

Another example is when you are importing projects or restoring you get this cryptic error.

The reason for this error is not outputted in standard logging, so you must turn on DEBUGGING for the importer package. You can do this by following these steps.

The issue here is that during the export from the cloud a string value was dropped. Atlassian could not explain the why but we figured out the root cause and how to fix it. Here is a description of the problem and the solution.

Within the first line of customfieldvalue.xml, it is missing a stringvalue or textvalue completely, which is causing the null reference.

<CustomFieldValue id="10011" issue="10160" customfield="10270"/>

Above is the problem line. This line is missing the entire stringvalue. For example, here is a working line and how the data should look.

<CustomFieldValue id="25154" issue="14977" customfield="10270" stringvalue="MobileUI - Mobile_UI_1"/>

This is easily fixable by editing issue number 10160 and adding a value for the "test case id" custom field. At which point you would need to re-export the data from the corrected JIRA instance. Alternatively, you may be able to edit the XML directly and pull a valid entry from another field based on the desired text as well, either method should work

The process for doing a migration out of the cloud to a server environment is as followed.


These are just a few examples of issues our Appnovation Team of Atlassian Experts have run in to, just in the past few weeks from the date of this article. You never know what your going to come across. Here at Appnovation we migrate Cloud instances to server instances, merge several Jira and Confluences instances in to single instances on a regular basis.

Appnovation is Gold level partner with Atlassian and would be happy to help you with your next Atlassian Jira migration or whatever it may be.

We have tools and the talent to get you over the finish line.