Migration Playbook

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

Confluence to SharePoint Migration Phases

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

Prepare the Confluence to SharePoint migration

  • allow access to endpoints required for the Confluence to SharePoint migration, see Required Endpoints
  • configure Azure AD so that WikiTraccs is allowed to create content in SharePoint, see Registering WikiTraccs as app in Azure AD
  • install 3rd-party apps in SharePoint to provide replacements for Confluence macros (page tree, table of contents, …)
  • 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
  • provide a migration account to authenticate with SharePoint, for:
    • test environment
    • production environment
  • provide a migration account to authenticate with Confluence, for:
    • 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
  • check that key users have access to test environments
  • set the language of the migration account used to access Confluence (this defines the language the static Attachments macro snapshot is transformed to) (see this comment on how to do this)
  • create “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
  • download and run WikiTraccs, and 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

Run the Confluence to SharePoint migration

  • check if there is a new WikiTraccs release available and if yes, update
  • run test migration (migration mode “migrate content”)
    • measure migration times
  • (optional) configure user and group mapping
    • start another migration run (migration mode “update ‘created by’ and ‘modified by’”)
  • (optional) configure permission mapping
    • start another migration run (migration mode “update permissions”)

Evaluate the results of the Confluence to SharePoint migration

  • check migration result metadata provided by WikiTraccs
  • 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 test 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 attachments that WikiTraccs downloaded during the migration; you can find those attachments in the attachment registry
    • the default location of the attachment registry is C:\Users\<username>\AppData\Local\WikiTraccs, unless you changed it via the configuration
  • 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 November 19, 2023