Good Practices for your Confluence to SharePoint Migration
Often I get asked about best practices around Confluence to SharePoint migrations and WikiTraccs.
Please note that I am not directly involved in migration projects. If there is a perfect project where the client doesn’t need my help because WikiTraccs does its job, I’ll never hear from them.
What I hear about are issues. Issues with tooling, but also non-technical issues.
Recommendations
Here’s a collection of things I recommend.
Prepare users for SharePoint
I often hear phrases like “Leadership has decided” to proceed with moving content to SharePoint. However, some users may not have had any prior experience with SharePoint. Familiarize them with SharePoint or, at the very least, help them anticipate that SharePoint will be different from Confluence.
Test the migration
Perform a test migration using WikiTraccs. Evaluate the results. Purchase only, if the results match your expectations. Depending on how well your stakeholders know SharePoint, expectations vary wildly.
Expect layout changes. SharePoint is no Confluence. SharePoint doesn’t offer the same formatting and layouting features as Confluence. You’ll see that for example with images, where SharePoint is not capable of showing them side by side 😔.
Prepare for macros being gone
Most of the Confluence macros don’t exist in SharePoint. Identify key use cases that exist in Confluence and rely on specific macros or metadata. Manually try to rebuild those cases in SharePoint. WikiTraccs might help you with that, but you will also have to think about using extensions like PnP Search web parts. You’ll probably also use services outside SharePoint to re-implement those use cases, like the Power Platform, Loop, Teams, or others.
Prepare your service desk for hypercare questions
After the migration users will ask questions. Provide them with a channel to get those questions answered.
Example questions:
- Why does the table of contents doesn’t update in SharePoint?
- Answer: because the list of links is static and the table of contents macro is gone.
- Why are child pages not showing up on the page?
- Answer: because the children macro is gone.
Don’t do a permission migration
Confluence and SharePoint behave differently when it comes to permissions. Confluence can have page hierarchies. In Confluence, you can restrict pages to a more narrow circle of users with each hierarchy level. In SharePoint, there is just one level. Multiple levels of Confluence page restrictions need to be combined to just one SharePoint page.
For a more complex hierarchy of restrictions in Confluence it is nearly impossible to map that 1:1 to SharePoint.
That being said, WikiTraccs supports migrating permissions, to the extend it is possible. But a permission migration might give you a headache.
Archive older content to one site
Identify old Confluence content to archive and migrate this content to one SharePoint archival site.
Skip personal Confluence spaces
Prepare users to manually move content they need from their personal spaces.
Don’t change networking infrastructure during the migration
One client upgraded Confluence to TLS 1.3 during the migration. This caused issues in combination with Windows 10. Everything can be solved, but this can cause interruptions that should be prevented during a migration.
Plan all target sites before the migration
You should know which Confluence content will be migrated to which target SharePoint site. Enter target site URLs in the Space Inventory list. This is required for the link transformation to be successful throughout the migration as WikiTraccs will look up those sites when transforming cross-space links.
Note that WikiTraccs doesn’t create those sites, you create them, or choose from existing ones.
Check the WikiTraccs settings
The blue WikiTraccs window has a menu bar with a Settings option. Click that and click through the tabs in the Settings window to familiarize yourself with the settings. Some choices are to be made like whether blogposts should be migrated or not.
Use migration waves for larger space counts
You can define migration waves. If you have hundreds of spaces, it might be beneficial to not choose all at once for migration, but to give them wave numbers and migrate each wave separately, or even (some) in parallel.
Bring the page tree to SharePoint Online
The number one missing productivity feature in SharePoint with regard to pages is the page tree. WikiPakk finally brings the page tree to SharePoint.
Repeat migration runs
During longer migration runs there can be connection issues that prevent single pages to migrate. Re-run the migration to get those pages over as well.
With WikiTraccs, you can re-run the migration multiple times. Before each run, WikiTraccs checks which pages are missing in SharePoint and only migrates those that are missing. This proved beneficial especially in environments with an unstable internet connection.
Only when a migration run doesn’t seem to migrate any more pages you go ahead and look at the progress log files to check the final result.
Check the playbook
The Migration Playbook provides guidance about configuring WikiTraccs and evaluating migration results.
Additional topics
Some additional topics that often come up.
How many SharePoint sites do we need?
I cannot answer that as this is up to your information architecture.
What I often see is a 1:1 relationship between spaces and sites. So, all pages of a Confluence space are migrated to a target SharePoint site.
How long will the migration take?
This is hard to answer as it depends on a number of factors. The FAQ has some thoughts about that: How much time does it take to migrate?