Blogs

5 min read

3 Simple Tips for a Successful Atlassian Confluence Migration

May 7, 2019 10:39:00 AM

It’s no surprise that Atlassian Confluence has become a mission critical application for your customers and support teams alike. You may find yourself in one of these scenarios:

  • Your company has recently acquired another company (with its own Confluence instance) and you’d like to combine the two

  • You’re using Confluence Cloud and have decided to make the switch to Server in order to leverage a particular add-on

  • You just had a successful product launch

  • People are simply adopting it in droves

Whether it’s making the move from Cloud to Server, consolidating two or more instances, or upgrading your instance to Confluence Data Center, migrating and consolidating Confluence may seem like a daunting task. However, migrating can be stress-free by creating an action plan that includes choosing the right strategy, focusing on the different versions of instances and add-ons, and relentlessly testing for errors. Here are 3 simple tips that will ensure that you have a successful Confluence migration.

Tip 1: Choose a Migration Strategy

Confluence instances come in all shapes and sizes and the particulars of your instance(s) can help you choose an effective Migration Strategy. Here are three examples:

Single Cloud Site to a NEW Server/Data Center instance

Export your Cloud site to XML using the backup manager and restore onto the latest version of Confluence Server following Atlassian’s instructions. Please note, in most cases add-on data will not be migrated as part of the XML backup so check with your add-on vendor to determine if they provide any type of data migration assistance.

Complete Server/Data Center instance to an NEW Confluence Cloud Site

The instructions are similar to migrating from Cloud to Server but in the reverse. There are more restrictions on moving from Server to Cloud, the most important is that your XML backup file must be smaller than 200MB. Consult your version matrix to determine add-on availability and compatibility. See Atlassian’s detailed instructions for migrating from Server to Cloud.

Restoring a Confluence Site from XML will overwrite any existing data. If you need to preserve data in your Confluence see the instructions below for migrating to an existing instance.

Confluence Cloud/Server Site to an EXISTING Confluence Instance

To migrate a spaces or spaces from one site into another existing site you have to use the Space Export method rather than backup/restore. This method can be a bit labor intensive as it involves exporting and importing one space at a time. Again, consult your version matrix for any incompatibilities between Confluence or add-on versions.

Users and content permissions will not be migrated using the Space Export method and will have to be recreated in the target instance.

If you’re migrating Jira at the same time, migrate the Jira project first to ensure that macros are updated to the new Jira location.

Tip 2: Create a Version Matrix

Each Confluence instance is different. When you’re changing platforms or consolidating instances you need to carefully review the differences between Confluence and add-on versions, determine whether upgrades are necessary, and identify any “gotchas” prior to starting your migration. A simple version matrix like the one below is an easy way to quickly identify those items you need to pay special attention to.

Product

Source Version

Target Version

Notes

Confluence

6.4

6.8

  • PostgreSQL 9.2 is no longer supported

Secure Content

2.0.3.1

2.2.0.1

  • Required for 6.8 Compatibility

  • Administrators can reassign ownership to any user

  • Improved Reporting Macro

  • Contact SCB owners with custom messages

  • Secure content blocks look better exported to PDFs

  • Improve performance and UI of secure content admin screen

  • Added Autocomplete in Macro editor key field to help locate pre-existing keys

DocuSign for Confluence

1.1.4.1-GA-6.1

1.1.5

  • Improved tabular output for Envelope List Macro

  • Multi-Select status for Envelope List Macro

  • Confluence 6.6 compatibility

 

Tip 3: Test, Test, Test

Testing is a key component of every successful Confluence migration and consolidation. There are a few areas you should review in your test instance (you do have a test instance right?)  prior to performing your production migration:

Content Formatting

The version of Confluence and Space Theme you choose can sometimes alter the formatting of content when you change instances. Carefully review and compare different page types to ensure that they render correctly and pay special attention to any pages that utilize Space or Global Templates and Blueprints. If you have Space Blueprints in your source instance, make sure they are migrated along with your content to your target instance.

Add-on Functionality

Add-ons can differ between versions and platforms so make sure that you review the usage of add-ons that may be incompatible and consider altering the content in your Source instance prior to migration or consolidation. Also note that add-on data is not often migrated when exporting content from Confluence. Consult your add-on’s documentation and contact the vendor for special assistance.

Space Permissions and Page Restrictions

We discussed earlier that users and content permissions will not be migrated using the Space Export method. Ensure that users and groups exist in the target instance prior to importing your Space and the Space Permissions after import. Page Restrictions will automatically be applied once the groups are in the target instance.

Application Links and Integration Points

Remember to migrate any associated Jira projects prior to migrating Confluence. Test your Jira macro links in the source instance to ensure that they are pointing to the correct Confluence instance. If you’re migrating a complete instance from one platform to another, make sure you update the application links between all of your Atlassian applications. Don’t forget to update any 3rd-party integrations you may have in place and notify any teams who may be accessing content or data through the Confluence REST API that the URL will be changing.

Successful Migration

Needs change over time, and migration and consolidation of Confluence instances can become a stressful endeavor. By following these tips you’ll have some tools to ensure success and keep your teams, users and customers happy.

Written by Bryan Robison

Upcoming Webinars

Webinars

Case Studies

Blog