Migration Playbook

This article provides topics that should be covered in different phases of the Confluence to SharePoint migration.

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


  • 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)?
  • 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


  • 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


  • 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
  • document the WikiTraccs settings you chose


  • 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
  • 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
Last modified March 8, 2024