Jira Cloud migration: choosing the right tool for the job

Atlassian recently announced the decommissioning of their Server products by February 2024. This leaves a lot of companies with a choice: whether they move to Data Center or to Cloud. If you haven’t yet decided on the best option for you, ensure you read our blog about the important differences between the two: Are you ready for Jira Cloud or Data Center?

This blog will focus on the migration from Jira Server to Cloud, covering the different migration options and processes based on my own experiences and real-world cases. 

However, as mentioned this is by no means a one-size-fits-all process – there are a lot of variables which can impact your path to Cloud. This means that you may encounter different issues on your migration journey than are discussed in this blog.

Pre-migration

There is a lot of work to do before a migration. 

Firstly, you must ensure that your Server instance is ready for the migration. What exactly this entails depends on your chosen migration option. Different options have different limitations which you need to be aware of, and we will go through these options later on.

But regardless of your choice, the migration event is always a great opportunity to undertake some housekeeping in Jira. This may ease the migration process and will make the admins’ life easier on the other side as well.

Common things to consider

Atlassian has a lot of documentation scattered throughout their site about migration to Cloud, and a good place to start is their pre-migration checklist. 

Atlassian offers three different migration options:

• The Jira Cloud Migration Assistant
• Site Import
• CSV Import

Email addresses and user directories

Whatever option you choose, you must ensure that your users have unique email addresses, since this is a requirement in Cloud. In Server it is possible to use the same email addresses across different users – which is often done for test user purposes – but this won’t fly in Cloud.

If you want to integrate to an external user directory, or if you wish to set up single sign-on (SSO), you will need to set up Atlassian Access as well. This should be completed before the migration in order to smooth the onboarding process of your users.

User awareness

You should remember your users' needs from the very start of your planning. In advance of any migration, you should let your users know the following:

• When the migration will happen.
• How to log in to the new Cloud instance, as this may feel a lot different than what they’re used to.
• If you’re making any changes to your currently installed apps – adding, deleting or expecting different behaviors from some apps.
• Any potential downtime during the migration.
• When they should switch to using the Cloud site.

You should also create a fallback plan if the migration fails and you need to postpone. 

Communication throughout is vitally important for a smooth Cloud onboarding process and can save you a lot of questions following the migration. Create guides for common use cases and FAQs to offer a higher level of self-service, too.

Apps

No matter which migration option you choose, you will have to consider apps migration as a separate thing – none of the migration options handles app data for you. 

Indeed, some apps still don't even exist in Cloud. If you are using an app that doesn’t, you will have to decide what to do with it. 

Perhaps there’s another app you can use instead? If so, how do you migrate existing data to the new app? Or maybe you don’t really need the app after all – in which case the migration might be a convenient time to get rid of it.

Some of the popular apps which exist in both Server and Cloud have created a separate tool to help migrate the app data to Cloud. Many other apps at least have some documentation about the process. An example is EazyBI, which has an integrated database migrator tool. This works great for getting all your BI reports migrated to EazyBI Cloud. 

An opposing example is Scriptrunner, which might have a more troublesome migration process. Scriptrunner doesn’t have access to the Java API in Cloud, meaning some features have to be rewritten to work in Cloud. Other features, such as Behaviors, don't exist in Cloud Scriptrunner.

App migration case study

To make clear what issues you may encounter during the app migration, I want to share a bad experience I encountered from the real world. 

The app in question is able to render HTML formatting in issues. The app wasn’t needed anymore – which was lucky, since it doesn’t exist in Cloud – but the problem was that when removing it, all the HTML formatting would become visible in every issue, making it almost unreadable. Fortunately the app vendor had created scripts to remove this HTML formatting but all the scripts needed to run against the Jira database prior to the migration in order to scrub away the HTML formatting, just to make the issues readable when entering the Cloud site. 

Create a plan for user and app migration

Regardless of which migration option you choose, I strongly recommend an explicit plan for user and app migration.

Before the migration, you need to decide how everything should work once complete. Otherwise it will be a pain figuring it all out whilst letting your users into the Cloud site.

Migration options decision tree. Inspired by Atlassian: migration method comparison

Jira Cloud Migration Assistant

The Jira Cloud Migration Assistant is Atlassian’s recommended approach. But before jumping to any premature decisions, hold your horses and read on – because the Migration Assistant still lacks features which may make it a bad choice for you.

The benefits of Jira Cloud Migration Assistant

The great thing about the Migration Assistant is that it’s very easy to use. Install the app just as you would any other, and let it guide you through the migration. The Migration Assistant also lets you migrate a single project as a test migration instead of your whole instance, which saves you a lot of time. This is also a neat feature if you're looking to consolidate projects from more instances, or just a subset of projects from one instance, into the same Cloud instance. This makes the Jira Cloud Migration Assistant a great tool for migrating simple projects.

It also helps you create an app migration plan, although it’s pretty basic. It mostly just tells you whether your installed apps exist in Cloud or not, and in some cases it suggests that you contact the developer to clarify migration options. 

You can also make notes and mark each app as needed or not in Cloud. This might give a nice overview of your apps, but I personally do not find it very useful since you can easily look up the compatibility yourself and still have to investigate the app migration options separately. 

Atlassian is planning to add support for some apps into the Migration Assistant. When this happens, I believe it will take the tool to another level of helpfulness.

The limitations of Jira Cloud Migration Assistant

Unfortunately, the Migration Assistant has some limitations as well. The first one you need to be aware of is the version limit. The minimum Jira version required is 7.6.0 – hopefully you are already on this version or newer, since this version reached end of life on 14 November 2019. Otherwise you will find yourself looking into an upgrade session before the migration. 

I’ve used the Migration Assistant from Jira versions 8.X which have worked pretty solidly, besides the limitations.

Speaking of which, there are a lot of things the Migration Assistant doesn’t currently migrate. Atlassian has provided a list of what does and doesn’t get migrated here. As you can see, the list is quite long, so I want to highlight several commonly used features that are not migrated:

• A lot of workflow functions
• Some custom fields
• Mail handlers
• Global permissions
• Jira Service Desk Projects
• Dashboards
• Confluence links

Do note that Confluence links from Jira issues are not migrated. This means that if you're linking your Confluence content to Jira issues (which you should), this option will most likely not suit you.

I imagine these issues could be a deciding factor for many companies when choosing whether or not to use the Migration Assistant. 

What you need to keep in mind

The Migration Assistant isn’t a complete solution yet. The app is very much a work in progress, receiving regular updates, and you must always have the newest version of the app installed in order to use it.

So prepare to keep upgrading the app throughout your migration process. Hopefully this doesn’t break anything – but it has been known to happen!

Site Import

Another option to handle your migration is the site import. You create an XML backup from your Server and upload this and your zipped attachment folder(s) to your Cloud site. The process is fairly simple and seems quite solid, although this option also has some limitations to consider.

The site import handles almost everything for you, including all the features lacking support in the Migration Assistant app. This alone could make it the go-to solution for many companies migrating to a fresh Cloud site. 

This option also requires a minimum version of Jira Server to be supported, although this is a bit more blurred. The site import might work between v7.0 and v7.13, with some known issues. The recommended version is 7.13.1 and newer. 

You must also be aware that this is an all-or-nothing solution. All existing data in your Cloud site will be overwritten (besides your users). This also means that you can’t pick and choose what data to migrate from your Server.

The process itself is time consuming, especially if your zipped attachments exceed 10GB. You would then have to split these in to two or more attachment folders in order to avoid timeouts when importing in Cloud.If your XML backup exceeds 10GB you would also have to contact Atlassian support to assist with the import. 

Assuming you prepared your userbase in advance, at least  the site import is not very error-prone.  

CSV Import

The final migration option is the CSV import. This option lets you pick and choose individual issues to migrate, but cannot migrate entire projects or other things. This makes it a useful option for consolidating data from different projects or from different Jira instances. 

It is a more basic solution and might not be the primary option if you’re migrating to a fresh Cloud site. But since it hasn’t got the same version requirements as the other options, it can be a viable option for basic instances from older Jira versions.

You could also consider this a complementary option to one of the other migration methods. 

Migration – our essential recommendations

I recommend creating an Atlassian Migration support ticket before the migration. As soon as you have an exact date for the production migration, let Atlassian know so they can help you swiftly if assistance is needed. They usually react quickly and can help you overcome obstacles. 

Conduct all the test migrations you need to be comfortable with the process and end result. If you are using the Jira Cloud Migration Assistant, this is easy since you don’t have to migrate everything every time. 

Remember to test the app data migrations. If Atlassian has to fix some things in your Cloud site after the migration, make sure they do it in relation to your test migration as well. You want to ensure their fix solves the issue in a satisfactory manner.

Expect the unexpected, too. In my experience, running into issues during the test migrations is a given. You can hopefully avoid most trouble by planning well in advance, but you will still inevitably run into issues. This is exactly why you run your test migrations. 

Maybe you are trying out the Migration Assistant, but discover some of your workflows are using workflow functions which are not migrated. Perhaps an app is behaving differently in Cloud than what you were expecting. Or maybe some users have login issues caused by a new Atlassian Access setup.

The issues may vary, but one thing is for certain: you will want to fix them all before the final migration.

Also remember to document precisely what steps you take during the test migrations – you only want to take the right steps during the production migration. Depending on the complexity of your Server and organization, a migration process can easily stretch up to six months, and you will not remember the small test steps you tried months previously.

Post-migration – what to expect

Expect questions and requests from your users after they start using the Cloud site. Some questions will inevitably concentrate around the different user interfaces that your users have to adapt to; others will be about changed functionality. Remember to document answers to common questions to save you the hassle of answering the same questions over and over again.

Hopefully only a few requests will relate to issues about things that have broken or failed during the migration. Just remember to use Atlassian and the app vendors’ support if needed.

Once everything is complete, there is only one thing left to say: welcome to Cloud and congratulations on the successful migration!

You can now enjoy not having to maintain servers or schedule updates. Just keep in mind that you should still aim for a high level of Jira hygiene to make life easier for admins and your users.

Atlassian is working hard to smooth out the migration process as much as possible. New functionality and tools are released often, so please note some of the points raised in this blog may be redundant when reading this. 

If you have any questions about Jira Cloud Migration, or would like me to elaborate on anything discussed in this blog, please feel free to contact me at mads.mosbaek@eficode.com. I’d be happy to help and hear your thoughts about the migration process!