Migrating Content to Another Confluence Server (and/or Upgrading Confluence)

Over the course of my career as a tech writer, I've also had the responsibility to maintain a Confluence server or two. In that time, I've performed several Confluence upgrades. Each upgrade has had unique challenges to migrate content from one server to another but they all have common steps that needs to be handled. Those steps include migrating plugins, user macros, and customizations, update and/or revise any automation scripts that depends on your Confluence server, content migration, and testing all the above.

In this month's post, I'm posting my list of common considerations for migrating Confluence to a new version. Below, you will find a checklist of steps that will ensure your migration goes smoothly. While there is no silver bullet in a complete migration process in the sense of which steps one should take first, in my experience, the order should look something like this:

1. Build a test server with the new version of Confluence
2. On a test server,
1. Install necessary plugins
2. Migrate user macros
3. Migrated customizations
4. Copy content
5. Duplicate and customize any scripts that depends on your Confluence server
3. Test everything!
1. Do the plugins work? If not, why not?
2. Do the user macros work?
3. Does the customizations act and function as they did before?
4. Does your scripts still work?
5. Is all your content present and accounted for (page content, attachments, links, features, etc.)?
4. Upgrade or update necessary plugins as needed
5. Update broken or malfunctioning user macros
6. Revise any customizations as needed
7. Test again with fresh eyes: Have someone outside your team do a test run on a space that you have copied over for testing your migration settings
8. Have a plan in place in case the switch over date encounters issues that prevents the migration from completing on time or failing all together
9. With testing and fixing nearly done, announce a switch over date that includes any downtime, list of deprecated features as well as new ones, and set your user's expectations accordingly

Plugin migration

1. Generate a list of plugins that needs to be installed in the new Confluence instance.
• Confirm usage of plugins. There's multiple ways of accomplishing this. One way is to use Confluence's own search engine to find any and all used macros of a plugin. First, generate a list of all the enabled macros that is packaged with your plugins. Second, in the search field (with the filters set to search all spaces), enter this: macroName: <macro>*. This will return a list of pages that use the plugin macro in question.
• Ensure deprecated plugins doesn't have any impact on our users. On your test server, you can check if an uninstalled plugin has any effect on your content. This can be accomplished in many ways such as brute forcing a review of every page that utilize your plugins or you can write scripts that checks the rendered HTML versions of your content for error messages.
• Generate a handful of pages that utilizes each active plugin in the current server. Once these pages/spaces have been migrated to the new server, you'll want to check these pages to ensure that the plugins are working properly. I found have these "uber plugin" pages rather useful to one spot to view the behavior of the plugins that will get migrated. One should note though, some plugins won't be compatible with others and some may slow the server down. Depending on how many plugins you have installed, you may want to split up your uber plugin page into one page for every 15-20 plugins installed.
2. Confirm that the current plugins are compatible with with the newer version of Confluence. This can be done by checking your admin section for any messages from the vendor about compatibility issues.
3. Install required plugins on the new server.
4. Report and track issues with the plugins.
5. Configure the plugins with the same settings as they were defined in the older server. This will ensure that your users have the same experience with the plugins as before the migration took place.
6. Clean up or archive pages that have uninstalled plugins. While this may be an optional step, if a page has become useless due to the unistalled plugin, there is a good chance that said page has outlived it's usefulness and can be archived.
7. Inform team of the migrated plugins were successful (with/without any notes about broken or archived pages, plugins removed, and their impact).

User macro migration

1. Generate a list of user macros:
• Confirm usage of macros. This can be accomplished by searching for macroName: <user macro>* in the search field.
• Ensure deprecated macros doesn't have any impact on our users. If they do, confirm that the page is still needed or not by your users. Chances are, they won't mind archiving this page.
• Generate a page that utilizes each required user macro. As noted before, you may need to split the user macros up between multiple pages.
2. Install required macros on test server.
3. Test user macros for compatibility issues.
4. Report, track, and fix issues for user macros.
5. Backup up revised macros (e.g. Github repositories, local backups, text files with the code, etc.).
6. Document changes to revised macros as necessary.
7. Inform team of the migrated user macros were successful (with/without any notes about broken or archived pages, user macros removed, and their impact).

Customizations to Confluence

Migrating customization between different versions of Confluence can be tricky. Between major versions, the framework and page layout changes which will adversely affect any customization you made using HTML, CSS, JavaScript, jQuery, frontend/backend libraries, and so on. While it may be tempting to go back to a "vanilla instance" of Confluence, if your users come to rely and use these customizations, you'll have to justify not migrating them.

Out of all the migration steps, this one is the trickiness due to their intertwined nature of your custom code and Confluence's. My advice here is to map what your customizations use to hook into Confluence. For example, if a customization relies on the page layout to always have a body element with a nested div element with the class of "content", make sure the newer version of Confluence has that same page layout. If it doesn't, map it out and adjust your customization accordingly.

Again, in my experience between major versions, I had to make adjustments or keep an eye out for custom features that involves the following web features:

• HTML: Atlassian tries to keep current with the latest HTML standards. You should too.
• CSS: Classes, ids, and element selection in the CSS files change as well. Check your custom CSS files for any changes you need to make as well.
• JavaScript: Keep your JavaScripts current and confirm that if the script hooks onto any element, that the element is still there as your script expects it to be.
• jQuery: Atlassian keeps current with industry standards on which version of jQuery it utilizes. If you scripts use jQuery, confirm that the newer version doesn't adversely affect your customizations.
• Libraries: Aside from jQuery, Confluence uses many other front-end libraries. You can include any library you like as well but make sure it still works with the new server.
• Confluence features: If you use a combination of native and 3rd party plugins, user macros, and/or customizations to achieve a non-vanilla feature, you'll need to ensure that this feature still works.

Content migration

With your plugins, user macros, and customizations migrated, you should start migrating production content.

1. Generate a list of spaces to migrate.  Confirm with our users that their team's spaces needs to be migrated. If not, archive the space using any method you deem worthy. Word of advice: it never fails that 1 in 20 users will ask you the whereabouts of a page that didn't get migrated 2-4 weeks afterward. I have been fortunate enough that we keep the old server around for just that purpose but if you find yourself in a different boat, I would recommend dumping an deprecated space to HTML documents, organization, and place them somewhere you can find them in the future. You may end up migrating the deprecated space anyway but mark it as "archived".
2. Lock a space prior to migration. This will ensure that no new pages will appear on the old server while migrating this space's content to the new server.
3. Migrate approved spaces. Track which spaces have been migrated.
4. Test migrated spaces: refer to your list of pages that have plugins and user macros that need to be checked. Do a spot check of a dozen or so random pages from the migrated space to ensure the content was properly migrated without any errors. Note: this could be automated using a combination of scripts to extract the content, parse the HTML documents looking for error messages, broken links, missing images, and report on which page and what error message(s) was found.
5. Report, track, and fix issues with migrated spaces.
6. Inform teams that their spaces have been migrated.
7. optional: Archive old spaces in the old or new server or in a non-Confluence repository.

Test scripts and external dependencies

1. Ensure that any script you utilize with Confluence works as expected. For example, if you have a plugin that generates a REST API for you to generate HTML docs for publication (pretty specific), then you should confirm that the REST URL and related scripts still generate content in a consistent form.
2. Review, test, and update your scripts accordingly.
3. Document any changes to your scripts. If the changes affects the public consumption of your content, inform your audience.
4. Back up your scripts. It is a good practice to have the old scripts archived.
5. Announce to your users, if they rely on the output of said scripts, that everything works as it should or if you've made any improvements.

There you have it. Hopefully, this guide will help alleviate any future issues with your next Confluence upgrade.