This article was written by Kamil Beer, an Atlassian Engineer at iDalko.
Migrating the Atlassian tools is always a hot topic. Changing your deployment type is certainly possible, but it requires some good consideration before execution. So in the first part of the series, “Best practices: Maintaining the Atlassian Stack”, I analyze how to migrate Jira in detail.
I’ll also walk you through all the necessary steps you have to take before, during, and after migrating your Jira. So if you’re looking for the ultimate guide to a secure migration, keep on reading.
Before we get to the content, you might want to download this worksheet:
Here’s an overview of what we’re going to cover in this extensive guide:
Chapter 1- Before you Migrate Jira: What Deployment Models Should I Choose for my Atlassian Stack?
Before I get to the part where I’ll discuss how to migrate Jira in full detail, let me start by going over the deployment models that we have. There are many paths to traverse in the Atlassian world, along with the risk of choosing the wrong one when choosing the deployment model for your Atlassian Stack. How to deploy Jira? What rules should I set up? And how about security? How to maintain the application? As an admin, you probably asked yourself these questions already.
Luckily, these paths have been already trodden by many experts, including those at iDalko. And they are what our new series of articles will cover, Atlassian stack best practices, based on our experience.
Alright, so you have decided to use Jira – or Confluence or Bitbucket – to help you out. Great! You searched how to install it and met the first crossroad. Where should the application run?
On Cloud or on Server?
And they don’t even mention the third option: Data Center. So, what is the right choice?
In this chapter, I’m going to describe the deployment choices, upsides, and downsides. It’s useful to both novice and veteran administrators especially before you migrate your Jira.
Cloud
Simply put: Cloud means Atlassian hosts the application.
Cloud deployment has been around since 2008. Atlassian started offering a development platform with Jira, Confluence, SVN, Crowd, Bamboo, Fisheye, and Crucible called Jira Studio. In 2011, a product named OnDemand allowed the use of separate applications, unlike the bundled Jira Studio. In 2013, Jira Studio was discontinued and OnDemand was named Cloud in 2014.
So, with Cloud, you don’t need to provide the application infrastructure or perform any complicated server administration tasks. But there are other things to consider, detailed below.
To (not) keep it simple, there are four types of Cloud deployments:
Cloud Free, introduced in March 2020, allows you to use Jira Software, Core, Service Desk, Confluence, Trello, Bitbucket, and Opsgenie for free. It’s a good introduction, but the limitations don’t make it very production-viable (e. g. Jira lacks permissions, Bitbucket is limited to 5 users).
Cloud Standard is the most common Cloud solution. This article will talk about its upsides and downsides in detail.
Cloud Premium is a more powerful Cloud Standard. It has a 99.9% uptime SLA, unlimited file storage, and 24/7 support. New features include IP Allowlisting and Project Archiving. For small teams, users cost twice as much (e. g. a user in JSW costs $7 for Cloud Standard and $14 for Cloud Premium). But the more users you have, the lower will be the price increase.
Cloud Enterprise (in Early Access) goes even further. With unlimited users, a 99.95% uptime SLA, the ability to choose Data Residency and “guaranteed integration with many essential enterprise SaaS tools”, it’s certain to be a dream come true for many teams, but also at a cost that won’t make it accessible to most of them. You can try it out here.
Now that we covered the Cloud types, let’s see what Cloud Standard has to offer.
Upsides
You pay per user, not in bulk. In Cloud, you pay for every active user in the application. But in Server or Data Center, you purchase licenses in bulk. In Server, the price tiers are 10/25/50/100/250/500/2000/10000+.
You probably noticed the large jumps – and yes, this certainly means that once you hit 501 users on Server, you need to purchase the way more expensive 2000-user license including all apps you use. In Cloud, you would pay for that one extra user only. This, however, only applies to the Cloud monthly subscription. Yearly cloud payments still have their own user tiers.
Pricing example – Jira Software
No hardware costs. You don’t need to buy or rent servers, nor take care of their maintenance, scaling, deprecation, cooling, or electricity. You don’t have to hire employees to do that for you. This is taken care of by Atlassian that hosts all of its cloud solutions via AWS. These servers are located all over the world for better access and performance.
And while you still need an administrator, all the necessary tasks are done via the UI.
Easy upgrades. You don’t need downtime, time-consuming deployments on dev and test instances, or partaking in the arduous process of an instance upgrade. Upgrades are done on the background by Atlassian. You simply come to an upgraded instance with new features one day.
Downsides
Reduced customization and support of popular software. Customization of Cloud applications is severely limited: you can only use some apps from Server, or they might miss some key features you were used to (e. g. Scriptrunner, JEMH).
Some popular enterprise software, like Active Directory, isn’t supported either. You will have a hard time with integrations. Various system settings are missing (no Priority schemes), others cannot be customized (e. g. your own URL).
No custom domain. Whenever you register a Cloud application, it will have a “.atlassian.” second-level domain like this: https://yourname.atlassian.com/. This is currently not possible to change – the difficulties in doing so have been described by the lead developer of this feature here.
Reduced number of users. On Cloud, the maximum number of users is 5000. This might be a problem in large organizations, as you would then need to federate into multiple instances.
Subscription model. Unlike Server, which has perpetual licensing (the initial price is for the application and year-long maintenance that you don’t need to pay again), Cloud requires either monthly or yearly payments to remain working. This is a standard SaaS model. However, it means that once you no longer need any upgrades and still want to use the application, you need to pay for the instance or lose your data. Or you have the option to migrate Jira to a Server instance.
Server
Simply put: Server means you host the application.
Important note: Atlassian announced the end of Server era as of February 2, 2021, so that is the end of new server license sales and you can no longer purchase or request a quote for a new server product. There will also be an update on new prices for server renewals and upgrades and the customers have the option to renew their maintenance until February 2, 2024
Jira 1.0 was made in 2002 to work on-premise. And other applications later including Confluence, Bitbucket, Crowd, Fisheye, and Crucible all became ready for local deployment as well.
So, what do you need when deploying locally? Certainly, your own/a hosting provider’s server to run the application (Linux, Windows Server, AWS, or Azure are all options), a database, a file system, and an administrator that can put it all together. In the beginning, the help of some other IT technicians might also be necessary. And while it all may seem like a large investment, it’s just well worth it.
Upsides
User-friendliness. Sure, you might need to upgrade on your own once in a while, but nobody will drastically change your application or its features without you. If you want to keep it as is, after your users spent a long time familiarizing themselves with the tool, nothing stands in your way.
New (Cloud) UI or old (Server) UI?
In Cloud, features appear and disappear, just like the UI that many users complained about in the links above. In Server, once you set your instance up, that’s how it will remain. Few people like changes but if they are necessary, you can approve them first, or do a rollback later. And what helps with this is…
Perpetual model and developer licenses. Once you buy an Atlassian server license, you get the application and a year of maintenance. Paid maintenance means access to new upgrades and to a very helpful Atlassian Support channel.
After the maintenance expires, you can extend it for 50% of the cost of the current license user tier for another year. But even if you don’t, you can still keep using the application. Before the maintenance expires though, you should upgrade to the latest stable version.
You also get a developer license, which is a copy of your production license you can use for non-production servers, for example, a staging instance for upgrade testing, app trials, or important changes, a test instance for your users to play around and learn the application, or for an archive instance for old projects/spaces/repositories.
Still, from time to time, various security vulnerabilities surface, and one of the solutions is to upgrade the application. If you don’t have active maintenance, this might become a big problem, but even then, you can…
Keep your Atlassian stack in a private network. Unlike the Cloud instance, which is visible to anyone, you can put the Server instance inside your VPN. This is both a good step, security-wise, and also a way to fend off hacking attempts when visible on the internet. Recently, Atlassian has released a beta version of a feature that allows IP whitelisting on Cloud Premium, but a true application integration inside a private network is still missing.
Security aspects get even more complicated on Cloud with third-party apps, as the data they process aren’t hosted by Atlassian but by the vendors. This might cause GDPR non-compliance. On Server, everything remains on your machine.
Keeping Jira or Confluence in a private network is still one of the most requested capabilities for enterprise deployments.
Availability. There’s no guaranteed uptime for a Cloud Atlassian application. When your Cloud instance is down, you submit a ticket to Atlassian Support… and wait. If you use Server, then the uptime is up to you. If you prepare your infrastructure for it, impressive results and low downtime can be achieved e. g. via a clustered Docker pipeline, even in enterprise environments.
While Atlassian guarantees 99,9% uptime for Cloud Premium plans, this still means about 45 minutes of downtime monthly, and that is in theory and given perfect circumstances.
Access. You can access the file system and the database and perform various tweaks and custom integrations. Your filesystem can be scaled as the instance grows, which is not the case with Cloud, which has 250 GB file space as the maximum.
Downsides
Atlassian’s investment. A couple of Atlassian Summits focused almost solely on Cloud and Data Center. There aren’t that many impressive new features made for Server (e. g. Automation for Jira or Jira Suite Utilities still remain a paid app, unlike on Cloud).
Bulk user pricing and other pricing issues. We already mentioned paying for the necessary hardware, software, staff, etc. Another hurdle might concern licensing, with big differences between user counts (if you have 501 users, you need to buy the 2000 user license) – including apps. Some of this can be resolved by omitting maintenance for select apps or the main instance at your own risk.
There were also Atlasssian’s large price increases in October 2019. Users who bought 3 or 5 years of maintenance before have undoubtedly made the right choice. More increases are expected to happen in the future, as the prices have risen almost every year in the past decade.
Atlassian can’t help remotely. On a Cloud instance, in case it comes crashing down, Atlassian technicians will log in to your instance as system administrators and check what’s wrong. On Server, they can help only via the helpdesk, which is still very useful. You also need to provide various logs and files, ideally in the form of a support zip.
Data Center
Simply put: Data Center means you host the application, utilizing the power of several servers.
Data Center deployment was first made available for Jira 6.4 in 2014 and then for version 7.0 in 2015, when Jira was split into Jira Core, Jira Software, and Jira Service Desk.
Other tools quickly followed suit, with Confluence Data Center already being available in September 2014 and Bitbucket Data Center (named Stash by then) in March 2015. In August 2017, Crowd entered the Data Center family.
But what exactly does the Data Center deployment bring?
First, it runs the application on several servers. What this means is that it provides better performance and can sustain a heavier load than a Server instance.
Second, it provides a backup solution. Server A might be down, but your application will still run from servers B and C. Neat and useful when you need high uptime, for instance, for documentation or a support service desk.
Upsides
True High Availability (HA). On Server and Cloud, there is a single point of failure. On Data Center, you can connect to as many servers as you want and ensure that they will keep you online. Also, the time you wait to get your Cloud or Server site backup is no more an issue.
Performance at scale. When your Jira Server instance grows to about 200 000 issues, you have to do some really advanced stunts to keep it running well. As you distribute the load between several servers with DC, you can scale the instance even further. It’s also a way to ease the pressure on a fast-growing application that you already scaled as much as possible. Again, you can always add more servers hosted either locally or on AWS/Azure to improve performance.
SSO 2.0 An interesting benefit is the addition of SAML connection to Azure AD, ADFS, and several other identity providers. This allows a single sign-on and authentication into Atlassian tools. Note that for SSO, you can choose either Crowd or your local identity provider, not both.
Example diagram of a Data Center deployment
Downsides
The cost. With the exception of Bitbucket, the starting tier of Data Center is 500 users (Jira/Confluence) or 50 agents (Jira Service Desk) at $12,000 yearly. And that’s just the main application – you have to add the price of any third-party apps to this mix. Clearly, this deployment is feasible mainly for the enterprise. While Bitbucket DC available from 11 users up certainly seems interesting, one has to weigh the value it’d really bring when compared to a regular Server instance.
Licensing model. Even though you host Data Center, the licensing model is different from Server. You need to pay the same cost every year.
Cluster limitations. While Data Center can be deployed on several servers, you have to prepare the rest of the infrastructure for High Availability, too. This means the filesystem (e. g. using GlusterFS) and the database (many database vendors nowadays offer a HA solution). They also all have to be compatible and supported, which might not always be easy.
Deployment Limitations
Now that you know the main properties of the three deployments, there is another point to consider: some applications can be deployed only in Cloud, some only on the Server version, and only a few can be deployed in Data Center. Thankfully, there is a large overlap – see below.
Summary
Cloud, Server, Data Center are the deployment options an Atlassian administrator should know about. While Cloud might prove useful in scenarios where you don’t have a server available to host your data, Server might be more useful when you do and when you run more and more use cases and customizations. Data Center becomes relevant once you reach the enterprise scale.
This chapter introduced them all in-depth. But maybe you already chose your hosting, but it doesn’t work as well as initially planned. You might be even considering migrating to a different one.
So in the next chapter, I’ll explore everything about the preparation before you migrate Jira.
Chapter 2- Prepare to Migrate Jira: Analysis and Clean-up
In the previous chapter, we covered the Atlassian tools deployment models and their ups and downs. But in case you already have a Jira instance up and running, this chapter will help you get fully prepared to migrate Jira.
So maybe you found out that a critical feature you need in Jira isn’t on Cloud. Or that you need to update your Confluence without scheduling Server downtimes all the time. Or that your numerous dev teams need a better performing, always-online Bitbucket – perhaps in a Data Center. This chapter is for those stuck in this situation to help them successfully migrate their Jira instance.
Moving your application from Cloud to Server, vice versa, and even to Data Center is certainly possible. But every platform has different requirements, behaviors, and even looks different, so it’s necessary to first put together a game plan. What is required to execute a Jira migration in the best way possible?
Here I’ll cover the two steps regarding the preparation; Analysis and Cleanup.
Analyze the New Platform before you Migrate Jira
The first step of this journey is about taking a hard, honest look at whether the new platform suits your needs, what will change, and if migrating Jira is even possible. There are several angles to this:
Price
It’s necessary to take into consideration potential price change is essential. To illustrate, we compared the costs of Jira Software for 100, 1000, and 2000 users on Cloud, Server, and DC. We included five popular apps: Tempo Timesheets, eazyBI, JMWE, ScriptRunner, and Xray, and created a quote for five years (June 2020).
For Cloud, we used Standard annual pricing and saved two months of payment from the monthly model. For Server, the prices contain maintenance paid every year. You can, however, not pay for the maintenance and still use the application.
No discounts have been applied, so these are the official prices from Atlassian in USD, cumulative over the years.
During the first two years, Cloud was priced similarly to Server. From the third year on, the price difference leaned more in favor of Server. The hosting and staff costs aren’t included in the Server price, nor is the decision to not renew maintenance. Doing so might be useful if you’re isolated behind a firewall and less vulnerable to security exploits.
Jira Software – 1000 users
The 1000-user tier is available on Cloud Standard. On Server, you can buy either a 500 or a 2000-user license. But even here, we see that the more time passes, the better the price for Server gets. The 1000-user Data Center remains priced mostly better than its 2000-user Server counterpart.
Jira Software – 2000 users
In a large instance, the Cloud/ Server price difference becomes much more visible. Here, Data Center comes as a viable option priced between Cloud and Server.
Compliance and Security
What should you also consider when changing deployments is the GDPR. If you’re in Europe and want to migrate to Jira Cloud, think twice. Many companies sign contracts or NDAs with customers or suppliers saying that confidential information remains on local servers. This drastically changes in Cloud, as data may be stored anywhere. Thus, all those agreements will need to change as you move from Server/ Data Center. In enterprises, these revisions might take years.
If you work behind a firewall, you will need to whitelist 7 domains, a large number of IP ranges, the required Amazon/ Cloudflare services, and various third-party app sites for Cloud. Atlassian instructs that you should allow everything with a service name “Amazon” or “Cloudfront”, several IPs to receive notifications, and yet another set of IPs for Trello and Bitbucket. You can read more about it here. You’d have to do that on every firewall. Even the Server products will need whitelisting, mainly for the Atlassian Marketplace.
Another point is your user base. Let’s say you use Crowd, connected to your Active Directory, and providing SSO on Server. Or you’re using Atlassian Access with Azure AD or GSuite and are moving on Cloud. The crowd isn’t available on Cloud – and you will need to buy an extra app to integrate GSuite and ADFS on Server. What will be the authenticator (or SSO provider) post-migration?
Also, Cloud Standard supports only 5000 users, in case you have an enterprise Server/DC deployment and want to migrate Jira to Cloud, so beware!
If you are migrating Jira to Server instead, know that you will have to strengthen your application server yourself. That means building up a proxy, providing an SSL certificate, changing ports for SSH, deploying an application like fail2ban.
User Experience
Most of us resist change, and changing an application you use daily is a big one. Users will be startled even by different colors, not to mention various buttons not being where they used to be. And the users finally learned where is what and how it works.
Or they might hate the new design. There was a significant pushback after the 2017 Cloud UI change, so much so that Atlassian reverted to the old UI at the end of 2019. User resistance is something to be prepared for, no matter which platform you’re migrating to.
You can mitigate this by providing learning resources for users and giving them early notice. Atlassian has a great library of free training and we at iDalko have prepared a user guide for you with which you won’t get lost!
Features
If you use integrations on Server, then they might not work on Cloud at all. Direct database access will not be available, so you will have to rebuild what you can in REST API. Legacy systems will be heavily impacted and integrating COBOL or FORTRAN software just seems hard to imagine. Same for custom hacks or apps. It could be impossible to transfer them on Cloud, Atlassian vets all Cloud apps and upholds strict standards for them. And well, apps on Cloud and Server are written differently, too.
Cloud apps are written in “Atlassian Connect”, a framework different from the Java one on Server. On Server, an app is installed directly into the software, but a Cloud app is a separate web application connected, for instance, to Jira by REST API. Read more about this type of deployment here.
Apps like Power Admin, JMCF, or Rich Filters simply do not have a Cloud variant. However, it’s safe to say that as the more popular the app, the higher chance is to see it on all deployments. Some apps have limited features, like Scriptrunner’s very different feature set. Others might not migrate data correctly, easily, or at all.
While you can’t easily transfer all apps/ integrations from Server to Cloud or vice versa, it’s useful to first test whether all features have been migrated using a demo instance. And second, to check all app differences in the vendor’s documentation.
If you’re migrating to Cloud, a demo instance might be more difficult, as your best bet is a trial version. There are rumors of a sandbox environment, but only on the Cloud Premium deployment.
Other Considerations
How much downtime can you afford? Cloud Standard has no guaranteed uptime.
What monitoring changes (via Nagios, Grafana…) will you need to do?
When migrating from Cloud to Server, your application administrator will acquire extra duties – he should administer the server, too.
How will you maintain your backups when moving from Jira Cloud to Server?
Clean up the Instance before Migrating your Jira
Did the analysis go well? Good! The next step is tidying your instance up so that you do not carry over old data or unused configuration. Even if you didn’t migrate Jira in the end, it is a helpful procedure to do once or twice a year.
So, how to do it? There are many ways, but let’s mention the most common steps. We will properly focus on how to perform a cleanup in one of our next articles.
Archiving Projects, Spaces, and Repositories
If you have been using Jira, Confluence, or Bitbucket for some time already, chances are you have many of these that users don’t use anymore. These may be finished projects, old documentation or training tools, duplicates, and so on that are unnecessarily taking up database and file space.
A good way to determine if a Jira project is used is to sort its issues by their updated date. With a third-party app like Rich Filters or Power Admin, finding the last updated date is even easier.
Confluence shows space activity on every space’s default home page. If you use Better Content Archiving, you will see which pages are edited and read in each space. In Bitbucket, every repository has a last commit date.
Archive Jira/Confluence/Bitbucket by simply taking a backup, confirming its integrity, and delete the old content from production.
Deleting Old and Duplicate Objects
After removing the projects, many workflows or custom fields won’t be used anymore. You should remove them, as the admins will later have trouble finding the ones they need. And having too many fields slows Jira down when searching and viewing issues. Watch this video to find out more.
You will find unused objects in each of their respective sections, for Workflows, Screens, various schemes… or you can use Power Admin or Optimizer for Jira (paid) to do this usage check for you.
To check if a custom field is used, a handy query to use is <name of field> IS NOT Empty to see how many issues actually use this custom field.
Removing Unused Users
This will save you money and improve security. Whenever a user leaves or stops using the application, the best practice is to deactivate them. However, sometimes you may forget and their accounts will remain active. As an access point, this is a security risk and it makes license usage higher. Unused accounts should be removed before you migrate your Jira instance.
It isn’t easy to check which users are active unless you want to dig in the database (and only on Server/ Data Center) or manually check every user. A useful app that shows users who haven’t logged in for some time or at all is User Management for Jira, available for Jira, Confluence, and Bitbucket.
Checking for Errors
When migrating to Cloud, don’t migrate misconfigurations. So unless you will rebuild everything from scratch, checking the application logs and the instance integrity helps identify errors in the current configuration and their cause.
You can either read your logs manually or use the Jira/Confluence Log Analyzer that scans your log for errors and points you to relevant Atlassian KB articles. You can also use the free Integrity Check app for yet another scan for misconfigured boards, dashboards, and Jira projects.
App Usage Audit
Thousands of apps are available, free to use for 30 days. So it’s tempting to try them all out. They will remain installed after the trial period, though. Or maybe you run an app that was popular once, but users stopped using it. Don’t migrate unused apps that take space and raise the costs. Same with the apps with redundant features, like Jira workflow modifiers or Confluence table enhancers.
You can find the usage of some apps with Power Admin or Admin Toolbox, mainly workflow apps like JMWE, JSU, or ScriptRunner.
Apps that bring new features and create new objects, like portfolios in Portfolio for Jira (now Advanced Roadmaps), BigPicture programs, or Object Schemes in Insight can be audited by checking the last updated date of each of the objects they create, in addition to simply asking their users.
Lastly, there are apps without a clear usage trace, like various gadgets or macros. Search for them in the database, using the apps’ name. For example, type in com.qotilabs.jira.rich-filters-plugin to search for all Rich Filters gadgets.
Summary
Once you’ve decided which deployment model suits you best, it’s time to migrate Jira to your desired destination. But the migration would be way smoother and less time-consuming if you prepare for it, analyze the platform and the possible changes, and run a good clean-up.
Are you all done and ready to migrate Jira? Then let’s move on to the next chapter on planning your Jira migration.
Chapter 3- How to Effectively Plan it all before Migrating Jira
In the previous chapter, I analyzed whether to migrate Jira or not, and I also provided some handy tips on how to clean up the application before executing the migration. Here, I’ll focus specifically on planning the migration and what the steps to execute this big operation are in small, manageable chunks.
Alright! Your instance is clear as day and you are certain of moving it someplace else. We’ll help you consider the necessary migration steps and avoid any pitfalls on the way.
We will cover the Cloud to Server and Server to Cloud migrations, with Jira as the application we will be moving.
Server to Cloud
Migrating to Jira Cloud has become very popular lately due to Atlassian wanting to move Server customers to Cloud.
JCMA’s features resemble Configuration Manager, a popular Jira project migrating app: not only do you choose the projects to migrate, but also specific users and groups. JCMA is available for Jira 7.6 and higher and CCMA for version 5.10. and up.
Another way to migrate Jira is by doing a regular Site Import.
As with Server, you should be aware of all Cloud limitations. For instance, the app availability, loss of customizability, the user limit, the maximum attachment size, and various other “showstoppers”. You can read more about this in the first article of this series here.
Again, first, you will need a valid license. What helps is Atlassian’s “Extended migration trial” that allows you to use the Cloud site until your Server/ Data Center license expires. This means that you don’t have to worry about co-terming or paying for an extra license while you are still on Server. You can try it out in either Cloud Classic or Cloud Premium for a minimum of 2 months.
With this license, you can establish a staging server and troubleshoot your future Cloud production site including the necessary time to test all integrations. Before, the only option you had was a trial version for 7 days with an extension possible via Atlassian support.
The only downside to the Extended migration trial is that it doesn’t apply to apps. So you might need to ask the app vendors separately for a similar license.
Atlassian support promises extra help during the migration process should any problem arise, so make sure to let them know in advance.
A new term you will see on Cloud is an Organization. This is a global control panel where you define who can access which application. You can also connect your user directory to an Organization to manage Atlassian users in the same domain. Find more info here.
Another thing to watch out for that concerns users is that members of a group with the same name as a group on Cloud will get migrated to the Cloud group. And that means they will gain all Cloud permissions!
As you will be migrating from Server, which might have been accessible only, for example, through a VPN, you might want to double-check your public filters and dashboards and reduce their visibility. Most importantly, review the Public Signup option that allows users to create their own accounts.
When importing Jira together with Confluence, review the Confluence Cloud Importer feature called “Jira Macro Repair”. This is used when macros in Confluence fall apart, run it if your macros don’t work.
Site Import or Migration Assistant?
Using the Site Import method, you’ll be creating a Server backup file, which you’ll import on Cloud later. The files in the archive need to be structured like this:
If you have a large instance, the best practice is to import attachments and the XML backup separately or even to split the attachments/ logos/ avatars folders and import them in parts. Read this guide on how to do so.
Then, check the XML files for specific errors that might cause the import to fail, such as invalid characters, duplicate clustered jobs, and more. We have included these revision steps in the runbook. You can read about how to fix these errors in the Site Import documentation. Also, the import itself usually stalls around 50% and 90% mark – this is normal.
Finally, create a copy of your install + data folder and a database dump just in case.
Let’s have a look at the Server to Cloud migration runbook. Steps exclusive to the Site Import will be colored blue, while steps exclusive to the Migration Assistant will be colored green.
So we went over what awaits you after the migration, whether to Cloud or to Server: what to prepare for, be it the user, license, or hardware requirements. We have also prepared checklists for both types of migrations.
Summary
The next chapter will focus on the actual technical steps when we’ll create a staging platform, we’ll involve users in testing and remind you what not to forget after the migration is done.
Chapter 4- Staging, Testing, and Execution: It’s Time to Migrate your Jira
Alright, we’ve planned how to migrate Jira and went over what not to forget whether moving to Cloud or to Server. Now, we’ll set up a staging instance, mention how other users could help and what to have prepared after you’re finished.
You know what to do before, during, and after you migrate Jira, so let’s do it.
But hold on! You better try it on a staging server first.
In this chapter, we’ll show you how to create one, and after that’s done, you can read through our test case for user acceptance tests. Finally, we’ll address post-migration support and the few things you shouldn’t forget when it’s over.
Staging Server Migration
So what is a staging server? And why would you want to use it, anyway?
A staging server is a testing platform identical to future production. “Platform” can mean the whole application server (Server) or at least the application (Cloud). Basically, you test the Jira migration here first. You will find out how much work, how much time and downtime will the actual production migration take, and you’ll also discover various errors, and how to prevent them. So how do you create a staging server?
Below, we’ve prepared a guide (Site Import method for Cloud) that mainly covers the technical steps. On a complex instance, you might need to perform additional verifications as outlined in Chapter 3.
Migrating to Cloud:
Create a server backup. On Server, choose System -> Backup System and name it.
Prepare two zip files.
The first one will contain activeobjects.xml and entities.xml – find them in your server backup file in JIRA_HOME/import. Call it e.g. “data_import.zip”.
The second one will contain the JIRA_HOME/attachments, JIRA_HOME/logos, and JIRA_HOME/avatars folders. Call this one e.g. “media_import.zip”.
Use a free development instance, a Cloud Free instance, or a paid subscription. However, the first two are limited when it comes to the number of users.
When your instance is set up, go to System -> Restore System. Choose “Import data” and upload “data_import.zip”. Then, choose Import Media and upload “media_import.zip”. The importer will let you know about any errors before proceeding.
User Acceptance Testing
After the staging instance is online and the major issues are fixed (see the runbook in Chapter 3 for the particularly nasty ones), the next step is involving your users. User acceptance tests (UATs) allow the admins to delegate a part of their work and ensure that everyone can use the new environment smoothly.
Who do I need?
A varied team. To have as much of the application covered as possible, each tester should work with the tool differently. The UAT group might include:
A regular user that works with the tool every day
A power-user with broad permissions (let’s say a PM or a Scrum Master)
A user that works with additional parts of the application (e.g. with apps, integrations)
A user that gets reports from it (to see if the data he pulls are correct).
The more testers, the better – for a rule of thumb, 5 users with different roles should suffice.
You can also involve your team leaders in the UAT. As a migration changes the application’s look substantially, the managers will most likely want to get involved so that their teams won’t feel lost after the production migration. And if the team leaders learn the how-tos first, they will be able to pass them on later.
How long for the tests?
A week or two should be sufficient to iron out common errors. Create a Jira issue for every tester, connect it to a test case page in Confluence and ask the users to fill it out as they test. When finished, they can assign their findings to the responsible person.
What do they do?
UATs concern the features that everyone usually works with. Here is a sample Jira test case for your testers (add specific features of your application in it). If users struggle with anything in particular, it might be a good idea to elaborate on it in your training materials.
If the UATs went well, if all errors were fixed, and there’s nothing left to do… Then it’s time.
There aren’t many new technical things that haven’t been covered. What changes, however, is that this time, it’s serious!
If you’ve migrated to Cloud, you don’t need to create a new site. You can simply reset the old one by canceling and reactivating the subscription.
The best way to proceed with the migration is to schedule it on the weekend to have enough time to fix any problems that might arise. Also, as a reminder, make sure to:
Have a migration plan and a schedule accessible to everyone involved, for instance, the DB administrator, the server administrator, etc., with means to contact them – a phone number and an email.
Put an announcement banner on the old instance sending the users to the new instance.
Set the permissions to read-only on all projects/ spaces/ repos.
Send a global email to all users on Friday. Make sure it contains:
A description of what is happening (We will be moving our Jira… )
A link to the new instance they will use from Monday (The link to it is here…)
Who and how to contact issues (For questions and bug reports, contact…)
A summary of changes, link to training videos, and documentation
That all work they do from a certain point in time (let’s say Friday at 6 pm) will be lost (this should also be the time to set the application read-only).
Post Migration Support
Post-migration support is about making sure your users transition to the new instance smoothly. And even though they might encounter problems, you’re there for them!
In the Friday message, tell users where they can get help. This is very important – otherwise, they might feel lost. You can point them to a support email, but a better option is to create a Jira project dedicated to user support where they can create a ticket – even anonymously, if their account doesn’t work (don’t forget to set the project permissions and what the anonymous user can see).
This way, you are setting up future effective governance of Atlassian-tools requests, bugs, and changes and avoiding chasing emails and undocumented calls.
Many users will see the new application for the first time and will be confused. Others, who perhaps should have tested the instance, but haven’t, will encounter issues. They might have a problem with something that worked well on the old instance, or even in staging. They may even request whole new features.
Documenting the types of raised tickets helps resolve possible misunderstandings down the line. Either way, make sure that during the first two post-migration weeks, you are ready for an extra workload and your Atlassian Engineers are there to help.
Conclusion
In this guide, I tried to cover everything you need to take into consideration before, during, and after the migration. Even if you’re already a Jira user, it’d be a good idea to review each deployment model with its own upsides and downsides again to make the best choice before you migrate Jira.
We then went over the process of preparation where you need to analyze the new platform and clean up your instance. In chapter 3, step-by-step planning for a Server to Cloud migration was discussed in detail and a couple of checklists were also provided to help you migrate more easily. And finally, in the last chapter of this article in the series of maintaining the Atlassian Stack, we discussed the execution, the staging server and user acceptance testings, and the post-migration support.
Here’s all you needed to know about how to migrate Jira. So if you have followed the guide thoroughly, we should congratulate you on a successful migration!
