Process of Migrating Atlassian
Applications from Server to Cloud

Intro

Atlassian offers their applications in three distinct deployment options and moving between them have historically been challenging. This blog explores the process for migrating Jira and Confluence from Server to Cloud based on a recent migration we completed for one of our large clients.

Migrating User Management

If you are migrating both Jira and Confluence from server to cloud, we strongly encourage an order of operation due to user management issues. We advise migrating Jira first, then Confluence. Luckily, when we worked with our client’s migration, we did not have to worry about associated user management issues because they use both Okta and Atlassian Access. The impact of using Okta and Atlassian Access is that while the migration had some user related issues, Okta overwrites this and automatically fixes the problems.

Improving the Migration Experience

You can really improve the migration experience for your users if you can use a proxy to redirect old links to the new URL. We’re sharing a sample configuration below. The purpose of this configuration is to demonstrate the ease of set-up. Please note that the specifics in this section will depend on your Server deployment details.

Apache with mod_rewrite

RewriteEngine on
# Jira
RewriteRule	"^(.*)$"  "https://<Site Name>.atlassian.net/$1"  [R,L]
# Confluence
RewriteRule	"^(.*)$"  "https://<Site Name>.atlassian.net/wiki/$1"  [R,L]

Apache with RedirectMatch

# Jira
RedirectMatch "^(.*)$" "https://<Site Name>.atlassian.net/$1"
# Confluence
RedirectMatch "^(.*)$" "https://<Site Name>.atlassian.net/wiki/$1"

Jira Server to Jira Cloud

The primary guiding document Atlassian provides for this can be found at https://confluence.atlassian.com/jirakb/migrating-from-jira-server-to-jira-cloud-779160826.html The quality of this document, and the ease of the migration has improved in recent years, but we still found a few gaps that we wanted to highlight.

  • Jira will happily import workflows which have Conditions, Validators, and Post Functions for which there are no corresponding Cloud Apps (formerly called plugins / add-ons).
    • Go through all transitions and look for non-standard Conditions, Validators, and Post Functions in use to ensure that you have a continuity plan once you migrate to Cloud.
  • You need to audit user email addresses to ensure they comply with Atlassian ID requirements. The primary concerns are:
    • All emails must end in a TLD. For example, john_doe@company is not valid and will block the import.
    • All emails must use a valid domain. For example, serviceaccount@example.com is not allowed. This is important to note that example.com is a valid, but protected domain (RFC2606). Some people use this intentionally for accounts that should never be accessible.
    • If any username happens to start with addon_ they need to be renamed or deleted. This username prefix is reserved for Apps which you get from the Atlassian Marketplace. You are unlikely to hit this issue if you have not moved off Atlassian Cloud in the past.
    • If any two users have duplicate email addresses, then you will need to change them to each have a unique email address. You can identify these users using:
      select email_address, count(*) from cwd_user group by email_address having count(*) > 1
  • You will likely have to clean up invalid characters in your backup before importing into Atlassian Cloud. Take a moment to look over https://confluence.atlassian.com/jira/removing-invalid-characters-from-xml-backups-12079.html and integrate it into your migration procedure.
  • The security of User Info, Project contents, Dashboard, Filters, and Agile Boards in a Server deployment is often provided in-part by Jira running inside of your corporate network. When you migrate to Cloud, past security decisions can come back to bite you.
    • Check all of your Permission Schemes to ensure that none of them grant access to Group: Anyone.
    • Check your Browse Users Global Permission to ensure this is locked down.
    • Make sure that you are not leaking data via public Dashboards, Filters, or Agile boards by running this query before exporting your data. This query will require that people at least authenticate before seeing these assets:
      update sharepermissions set sharetype = 'loggedin' where sharetype ='global';
  • Large attachment imports are currently not working consistently and can take a very long time to complete. As a result of the amount of manual labor required, and rework needed, this portion took us nearly two days to get all of our clients’ data into Cloud. We knew this was a high-risk area ahead of time, and warned their users that attachments might not be consistent at the time we went live. In the end, we were lucky and got this done in time.
    • We identified that the full flow looks like so:
      1. Upload archive
      2. Processing completes (this is the step where we saw it fail on a regular basis)
      3. You click a continue button
      4. Attachments are imported on the backend
    • We found that if your attachment archive was larger than a few GB, it was likely to fail. As a result, we went through the above loop with only a few projects at a time. For example:
      • zip -r ABC-JKL.zip data/attachments/{ABC,DEF,GHI,JKL}
    • Sometimes this wasn’t enough, and we had to try over and over until it finally completed. One archive wouldn’t work on our end, and we had to ask Atlassian Support to help us.
    • You can speed this process up by doing steps 1 and 2 from above in parallel in multiple tabs in your browser, but steps 3 and 4 have to be done in serial across all of your tabs. In practice, you can use 4 tabs to upload everything, and then when they become ready, you have the final portion of the import happen one at a time.
  • You may end up with some broken icons post migration, this article will help you resolve it https://confluence.atlassian.com/jirakb/how-to-upload-custom-priority-icons-788961156.html

Confluence Server to Confluence Cloud

Historically, the migration process here was very similar to Jira’s migration process. In recent times, a new (and in our opinion – excellent) migration tool has been built that makes this process dramatically easier. You can read the instructions here: https://confluence.atlassian.com/confcloud/cloud-migration-assistant-for-confluence-959303217.html The main benefit of this tool is that it does the migration on a space-by-space basis. The benefit is that if everything except for one space works, the effort required to continue your work is drastically lower than doing a full re-import.

  • We had one space that wouldn’t properly export until we raised the heap of the system to be over 6GB. We don’t know what caused this, but we did confirm that this space was triggering OutOfMemory errors in the Confluence logs.
  • If you need to re-do the import while testing, cleaning up spaces in the Cloud application by hand can be a huge pain in the butt. If you encounter this, the best thing to do is reset Confluence entirely. See the documentation at https://confluence.atlassian.com/cloudkb/how-to-reset-atlassian-cloud-instance-to-the-original-default-settings-including-removal-of-all-data-691012037.html If you do this, remember to create a fake space before attempting to import data, otherwise the importer will not work.
  • You may end up with some broken Macros. You can fix these by going to https://<SITENAME>.atlassian.net/wiki/admin/jim-validator/view.actionand running the Jira Macro Repair tool.

Beware of Migration Issues

Following the migration, we identified a few known issues. Review the following to help prepare your migration ahead of time:

  • By default, Jira’s keyboard shortcuts do not work.
    • The workaround: Users can visit their JIRA profile and turn off the labs option.
  • Timezone information on a per user profile will be lost.
    • Timezone information on a per user profile will be lost.
  • Confluence short links like https://confluence.example.com/x/PywS will not migrate properly into the new environment. If you run a proxy to rewrite your old URL and forward it to the new site, this will likely lead to a lot of confusion. We’re continuing to investigate if there is a good fix available here. We recommend you try and identify short links throughout your company, and replace them with full URLs prior to the migration.

Migrating Atlassian Applications

Learn more about Atlas Authority’s migration services or contact us to discuss the steps we took to move our large client’s Jira and Confluence instances from server to cloud.

We promise we don't send spam