Migrating Confluence Data Center or Server to Cloud with bitvoodoo apps

Partial Cloud migration of our documentation

🌰 In a nutshell: We at bitvoodoo migrated our app documentation from Confluence Data Center to Cloud. You can access it via docs.bitvoodoo.app. While migrating to Cloud, we heavily relied on our Confluence apps/tools Viewtracker – Analytics for Confluence and Redirect for Confluence. Truthfully, It did require a lot of work, but it was worth it. Read on for all the details.

Access Part 2 of the Cloud migration checklist for a rundown of Confluence Cloud features, its editor and macros.

---

Hi, I am Cora, the technical writer at bitvoodoo 👋. I’ve been in charge of bitvoodoo’s app documentation since early 2020, juggling roughly 20 app-doc spaces in close collaboration with our developer team. As bitvoodoo has been using Atlassian tools since 2008, we have built our documentation – and our entire intranet, on that matter – on Confluence Server & Data Center.

Ever since Atlassian announced that they would abolish their server products, I heard this nagging voice inside my head: “Your Confluence documentation should be done on Cloud, too”. The voice refused to be ignored in spring 2021, by which time bitvoodoo had four cloud-ready Confluence apps/tools on the market.

If we wanted to act credibly and keep up with the latest developments, we would have to use Confluence Cloud daily. The app documentation as a subset of our intranet seemed a good starting point. If we could migrate the Confluence documentation without major hiccups, we would tackle the big challenge: Migrating the entire bitvoodoo intranet to Confluence Cloud.

Confluence Cloud Migration Guide for Content

Performing the migration seemed like a Herculean task in the spring of 2021 when everybody was working remotely and hesitant to take on more assignments. Some of the tasks, truth be told, looked incredibly tedious:

1. Deciding which pages to migrate to Cloud.
2. Performing the actual migration to Cloud.
3. Archiving Data Center or Server spaces.
4. Rewriting existing Confluence links.
5. Getting rid of our custom-made Enterprise Theme and other handy macros.
6. Familiarizing ourselves with the Cloud editor.
7. Converting migrated content from the legacy editor into the new Cloud editor.

In its entirety, the task looked overwhelming. So we decided to be agile about it and split the main task into clearly laid out sub-tasks. It probably won’t surprise you that we used Jira for this part of the project. But this article is about Confluence, and I won’t explore any project management details here. I will focus on the tasks necessary to migrate Confluence content from Data Center or Server to Cloud instead.

To make the process more easily digestible, I will focus on the first four items in this article along with some Confluence Cloud migration best practices. Points 5-7 are covered in Part 2 of this migration checklist.

Deciding which pages to migrate to Confluence Cloud

Atlassian states it clearly in its guide to Confluence Cloud Migration: It is essential to assess the content on your existing system and decide which content is worth migrating to Cloud at all. Remember that each page containing a custom-made user macro or a specific app’s macro will be a hassle to migrate.

Perform a data-driven content audit before migrating to Confluence Cloud

It is essential to ask yourself: Does this page still spark joy? Is it still relevant? This assessment can be painful for content managers and technical writers who deeply care about their content. Instead of going into emotional debates about which content may stay and which should go, it is better to focus on hard facts:

• Which content attracts how many views? Since our app documentation is public-facing, we were especially interested in page views by external users.
• Which content has received likes, comments, or is on users’ watch list? (Truth be told, the app documentation usually isn’t where content goes viral 😉. Still, we have seen comments and likes before, depending on the permission scheme of Confluence.)
• Which content is outdated and should be updated, deleted, or archived?

What better tool for this migration task than our own Confluence app, Viewtracker – Analytics for Confluence? Here’s how we proceeded to find content with very few views (the respective documentation pages are linked below):

• We accessed the Content & Usage Report within the Analytics Cockpit of the Confluence administration panel.
• We filtered for content with fewer than 20 views using the built-in filter options. (Why 20? We set a minimum of 20 views for pages to be considered relevant. This is an arbitrary number; it might be very different in your case.)
  

• We set the date range to “This year” to accumulate data from various months.

These settings resulted in a table listing all content with fewer than 20 views this year:

• We now looked closely at the pages below the minimum count and eliminated quite a few of these.
• We could also have exported the filtered report as a CSV file, but that’s not strictly necessary.
• The filters can be adjusted to see the most popular content, pages without edits, new content, etc. Many use cases of this report are covered in the blog post How to use the Viewtracker Content & Usage Report.

Alternatives to our content audit

💡Update in 2024: Using Viewtracker’s Instance Report, we could have accumulated even more relevant data on the number of pages, attachments, attachment storage, etc. Sadly, this report was only released after our migration, but we strongly encourage you to give this report a try if you carry out a Cloud migration in 2024.

Of course, it is also possible to use Search Engine Optimization (SEO) tools like Google Search Console to uncover which Confluence content is worth migrating to Cloud. However, this would only work for public-facing Confluence content that is indexed. Viewtracker delivers far more granular information than standard SEO tools.

Side effects of the Confluence content audit

The content audit had quite a few welcome side effects.

• We found content that was still relevant but needed to be linked more prominently.
• Some pages’ content could (and should) have been inserted into other pages. Now was a good opportunity.
• We stumbled across pages that had been outdated for years. It was time to get rid of them once and for all.
• We even found pages with restrictions that should have been removed months ago.

While the audit was time-consuming, we think it was worth taking the time for this late spring cleaning.

Migrating to Cloud with Confluence apps/tools

Performing the actual migration from Data Center/Server to Confluence Cloud

After establishing and preparing the relevant Confluence content, we could migrate it to our new Cloud instance in a matter of hours. We used the Atlassian Migration Assistant and didn’t encounter any significant problems. There is a mass of material on the Confluence Cloud migration process provided by Atlassian, so I will not go into any details here.

Of course, we also migrated our loyal Viewtracker – Analytics for Confluence app to Cloud. Conveniently, Viewtracker has an automated cloud migration path, as pointed out by Atlassian.

Archiving Data Center or Server spaces

We then archived the Confluence documentation spaces on Data Center or Server. Since there is no built-in workflow to archive spaces on Data Center or Server, we changed the space permissions instead. They used to be public (i.e., accessible to anonymous users). Now, they are restricted to Confluence administrators. This step was necessary to avoid duplicate content and user confusion (which content is relevant, the one on Data Center or Cloud?) and drive documentation viewers to the new Confluence Cloud instance.

How to redirect existing Confluence links

Once the migration from Data Center or Server to Confluence Cloud is complete, we can address the following task: How to redirect page viewers to the new Confluence documentation pages on Cloud?

As you may recall, we only performed a partial Confluence migration (only the app documentation) to Cloud, with most pages remaining on the Data Center. We needed to ensure that existing links would not be broken after the migration for user experience and SEO purposes. Here’s an incomplete list of links that needed to remain valid:

• links from bitvoodoo macros to the documentation
• bookmarks in browsers
• backlinks of all kinds (blog posts, social media, Marketplace Listing, etc.)

Working with “Redirect to URL” Macros to redirect Confluence pages

To create a page-by-page redirect, we used the Redirect for Confluence tool by bitvoodoo. It contains the macro “Redirect to URL” that lets you redirect a Confluence page to any other URL. Here’s how we proceeded:

1. For every relevant page (see above) on Data Center or Server, we edited the page and inserted the “Redirect to URL” macro.
2. We set the new Confluence Cloud page’s URL as “Destination URL”.
   Note: We used the complete URL, not the Tiny Link created when sharing a page. Our reasoning behind this: the URLs should contain relevant keywords instead of a jumble of characters and numbers to benefit SEO. The app pleasantly surprised us: The redirects still work if pages are moved or renamed on Cloud.
3. We created a spreadsheet of the redirections to keep track of the process.

Recap: Tools utilized for the migration to Confluence Cloud

1. Viewtracker – Analytics for Confluence: Helps in evaluating the Confluence content worth migrating based on numerical data such as the number of page views, likes and comments.
2. Redirect for Confluence: Helps in redirecting users to a new page after migration by setting up an HTTP 301 redirection.

Measuring impact: Checking the indexing status of the new Cloud domain upon migration

No online project is complete without measuring user signals. So, we set up a new Google Analytics property for our Confluence Cloud documentation. It allows us to monitor user behavior and identify problems like broken links. So far, we have not noticed any major issues or heard anything negative from customers.

Indexing the Cloud pages in Google seems to take a long time: Even over two years later, multiple old documentation pages are indexed, and the SERPs are often far from ideal. However, when clicked, the search results are directly opened in the Cloud instance. We are still puzzled by this behavior but happy that the redirections work swiftly.

Update: In autumn 2023, we decided to use Scroll Viewport for our app documentation. This meant setting up even more redirections, this time from the cloud instance to the new URL docs.bitvoodoo.ch. Fortunately, we are champions with redirections at bitvoodoo 😅.

Conclusion

Performing a Confluence Cloud migration from a Data Center or Server is never an easy task. It requires a clear vision, much attention to detail, and using Cloud migration best practices. Naturally, the migration with its multiple subtasks should be a team effort.
We were pleasantly surprised at how smoothly the migration process to Confluence Cloud itself worked. Still, many steps to take before and after the migration kept the bitvoodoo app team occupied for multiple weeks.

Pros & Cons of a partial migration from Confluence On-Premise to Cloud

In our case, migrating only parts of our knowledge base to Cloud had pros and cons.

➖ Cons

The manual redirection of documentation links caused extra work. This would not have been necessary if we had migrated our entire knowledge base. Also, indexing the migrated content on Google would have been more straightforward with a complete migration. Still, using the Confluence app Redirect for Confluence was an excellent alternative to manually rewriting links.

➕ Pros

• We used the documentation as a trial balloon so the product team could familiarize themselves with Confluence Cloud and all its quirks before the entire company took the leap.
• We found an additional use case for bitvoodoo’s app Viewtracker – Analytics for Confluence: Assessing which Confluence content was worth migrating in the first place based on concrete numbers was very helpful.

More learning steps in our Confluence Cloud migration

We spread the word about migrating to Confluence Cloud at bitvoodoo, which led other space owners to request a Cloud migration of “their” spaces. This was granted for spaces without any app-specific macros. However, many spaces need to complete the content assessment described above before a Cloud migration makes sense.

As stated in the beginning, there were more learnings involved in our migration from Confluence Data Center or Server to Cloud process:

• Getting rid of our custom-made macros and those from our app Enterprise Theme.
• Familiarizing ourselves with the Cloud editor.
• Converting migrated Confluence content from the legacy editor into the new Cloud editor.

These are covered in Part 2 of this migration checklist. Read on for the complete picture.

Are you in the process of migrating Confluence Data Center or Server to Cloud? Reach out to bitvoodoo to learn more about migrating to Confluence Cloud.