Migration Playbook

Confluence to SharePoint Migration Phases - General Guidance

Proof of Concept Phase

• Plan the transformation from Confluence to SharePoint
  • Organize transformation workshops or whatever other format is suitable for you
  • Identify workloads
  • Get external help if necessary
• Focusing on SharePoint: Get to know SharePoint!
  • SharePoint and Microsoft 365 can be overwhelming for technical and non-technical people alike, especially if those services are new
  • Manually transform workloads from Confluence to SharePoint; involve key users to review the results in SharePoint
  • When it comes to pages: play around, create SharePoint pages, use web parts, try to rebuild some Confluence pages and get to know the possibilities and limitations; WikiTraccs is also bound by those
• Test tools that integrate or migrate content
  • Think about migration vs. integration for each workload
  • Running a first test migration with WikiTraccs can help deciding if such migration tooling is an option

Decision

• Which workloads should be migrated from Confluence to SharePoint Online?
• Which workloads will be rebuilt manually in SharePoint? Where can a migration tool like WikiTraccs help?

Analysis Phase

• Which spaces should be migrated? (Recommendation: clean up)
• Which spaces should be migrated to which SharePoint sites?
• How many spaces are to be migrated? How many pages? How many attachments (number, size)?
  • WikiTraccs does not yet have a pre-migration scan feature (feature request); insight during and after the migration is given via the migration progress log files
  • those numbers can help estimating migration times, and help deciding which spaces should be migrated first - or cleaned up
  • watch out for large spaces, see Migrating large Confluence spaces to SharePoint
• Do permissions need to be migrated? (Recommendation: no)
• Map Confluence use cases to SharePoint
• Define SharePoint replacements for Confluence macros (Consider how WikiTraccs handles macros)
• Define key users for spaces that check migration results in the user acceptance test phase

Test Migration Phase

• Run the test migration (see playbook below)
• User acceptance test phase (UAT)
  • Let key users check the SharePoint pages that were created by WikiTraccs
• Adjust settings, mappings etc. and remigrate content from Confluence to SharePoint as needed

Production Migration Phase

• Run the production migration (same playbook as test migration)

Hypercare Phase

• Provide support to users, foster end-user adoption

Migration Playbook with Focus on WikiTraccs

The following sections focus on using WikiTraccs as migration tool.

Prepare the Confluence to SharePoint migration

SharePoint Online

• register an Entra ID application so that WikiTraccs is allowed to create content in SharePoint, see Registering WikiTraccs as app in Entra ID
• install third-party apps in SharePoint to provide replacements for Confluence macros (have a look at WikiPakk, the SharePoint page tree)
• prepare a target environment for migration tests (SharePoint)
  • option: create and use a developer tenant by Microsoft
  • option: create and use test sites on the production tenant
  • option: …
• provide a migration account for SharePoint Online (test environment, production environment)
• create one WikiTraccs site to hold metadata around the migration (“engine room” for WikiTraccs)
• create target sites in SharePoint where migrated pages will be created
  • configure permissions of those sites
  • make the migration account for SharePoint site collection administrator

Confluence

• provide a migration account for Confluence (test environment, production environment)
  • note: as of the time of this writing WikiTraccs only reads in the source Confluence environment; so it should be safe to use the production environment for tests - WikiTraccs behaves like a user that clicks really fast
• set the language of the Confluence migration account
  • this defines the language that macro snapshots appear in, like the Attachments macro (see this comment on how to set the language)
• set high rate limits for Confluence to not get throttled by Confluence during the migration

WikiTraccs

• allow access to endpoints required for the Confluence to SharePoint migration, see Required Endpoints
• download and run WikiTraccs, update the space inventory, see Getting Started on how to do this
• configure the Confluence space to SharePoint site mapping via the space inventory, see How to map Confluence Spaces to SharePoint Sites
  • note: this is important to properly transform cross-space links
• configure WikiTraccs via settings dialog
  • How should Confluence pages with translations be migrated to SharePoint?
  • Insert the “Page Attachments” section into SharePoint pages?
  • Any macros to ignore when migrating Confluence content? See Ignoring macros when migrating pages from Confluence to SharePoint.
  • …
• document the WikiTraccs settings you chose

Other

• check that key users have access to test environments

Run the Confluence to SharePoint migration

• check if there is a new WikiTraccs release available and if yes, update WikiTraccs
• run at least one test migration (migration mode “migrate content”)
  • measure migration times
  • document migration issues, fix as needed
• map Confluence users and groups to Entra ID principals
  • start the update migration run (migration mode “update ‘created by’ and ‘modified by’”)
• (optional) configure permission mapping
  • start the permission migration run (migration mode “update permissions”)
  • note: migrating permissions is not recommended due to technical differences in how Confluence and SharePoint handle permissions

Evaluate the results of the Confluence to SharePoint migration

• check the migration results
  • Are there additional macros that need to be added to the macro ignore list? See Ignoring macros when migrating pages from Confluence to SharePoint for details.
  • Check the Recent Pages (WikiTraccs) view of the Site Pages library and search for irregularities. Any pages with Failed Transformations count of 9001 need to be deleted and remigrated. See Measuring page migration success for details.
  • Check that the latest migration progress log files are present for each space. Check their contents to verify that all pages have been migrated. See Monitoring Confluence to SharePoint Migration Progress for details.
• either clean up or manually migrate Confluence pages that have more than 2 MB of text content or have overly long titles, see the Known Issues page for details.
• check feedback from key users
• search the documentation and get in touch if something seems not right

Repeat as needed

Repeat the migration as needed. You can delete any SharePoint page that has been migrated from Confluence to SharePoint and restart the migration. Missing pages will be detected and remigrated.

Clean up

Proceed with the following steps after having finished the migration:

• delete the locally stored attachment files that WikiTraccs downloaded during the migration; you can find those attachments in the attachment registry
  • see here on where to find the attachment registry: File Storage
• archive the WikiTraccs site
  • don’t delete the site, restrict access instead
  • WikiTraccs stores the raw storage format XML for each migrated Confluence page (since v1.9), so it’s recommended to keep the site around in case you need to check or further process raw page contents at a later time