Migration Playbook

Confluence to SharePoint Migration - General Guidance

Proof-of-Concept (PoC) Phase

• Plan the transformation approach
  • Conduct migration-planning workshops (or another appropriate format)
  • Identify workloads
  • Engage external expertise if required
• Familiarize the project team with SharePoint Online and Microsoft 365
  • These services can be overwhelming for both technical and non-technical stakeholders when newly introduced
  • Manually re-create representative Confluence workloads in SharePoint; involve key users to review the results
  • When assessing pages: experiment with SharePoint pages and web parts, attempt to reproduce selected Confluence pages, and note both possibilities and limitations (WikiTraccs is constrained by the same factors)
• Evaluate migration / integration tooling
  • Assess “migrate versus integrate” for each workload
  • A first test migration with WikiTraccs will help determine whether automated tooling is appropriate

Decision Gate for WikiTraccs

• Confirm which workloads will be migrated versus rebuilt manually in SharePoint Online, and where WikiTraccs adds value

Analysis Phase

• Identify spaces to be migrated (recommendation: clean up first)
• Map each Confluence space to its target SharePoint site
• Quantify scope: number of spaces, pages, and attachments (count and size)
  • WikiTraccs currently lacks a pre-migration scan (feature request); insight during and after migration is provided via the migration progress log files
  • These figures support migration-time estimates and prioritization of spaces for migration or clean-up (see also How much time will a Confluence to SharePoint migration take?)
  • Pay particular attention to large spaces (see Migrating large Confluence spaces to SharePoint) when migrating from Confluence older than version 7.18
• Decide whether permissions will be migrated (recommendation: do not migrate)
• Map Confluence use cases and macros to SharePoint equivalents (see how WikiTraccs handles macros)
• Nominate key users who will validate content during User-Acceptance Testing (UAT)
• Define governance, compliance, and security requirements (site provisioning model, site lifecycle)
• Establish communication and change-management plan (stakeholder matrix, training approach)

Test Migration Phase

• Execute the test migration (see playbook below)
• User-Acceptance Testing
  • Key users validate SharePoint pages generated by WikiTraccs
• Refine settings, mappings, and - if needed - re-migrate selected content

Production Migration Phase

• Execute the production migration (same playbook as test migration)
• Monitor progress and address exceptions in real time

Hypercare Phase

• Provide post-migration support and foster end-user adoption
• Decommission Confluence, and archive migration artefacts

Migration Playbook for WikiTraccs

The following sections focus on using WikiTraccs as the migration tool.

Prepare the Confluence to SharePoint Migration

Grant Access to 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 SharePoint target environment for migration tests
  • Option: Create and use a developer tenant by Microsoft
  • Option: Create and use a test tenant
  • Option: Create and use test sites on the production tenant
• 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

Grant Access to 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

Ensure Prerequisites for and Configure WikiTraccs

• Allow access to endpoints required for the Confluence to SharePoint migration (see Required Endpoints).
• If you operate in a locked-down network, review Locked-down environments for alternative download options.
• Verify that the migration workstation meets the hardware and software prerequisites.
• 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
• Activate the WikiTraccs license (see WikiTraccs License Activation).

Run the Confluence to SharePoint Migration Pass 1 - Content and Attachments

• Check if there is a new WikiTraccs release available and if yes, update WikiTraccs
• Run at least one test-migration pass (mode “migrate content”).
• For large projects, consider running parallel WikiTraccs migrations to increase throughput.
  • Measure migration times
  • Document migration issues, fix as needed

(Optional) Run the Confluence to SharePoint Migration Pass 2 - Author & Editor Metadata

• 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
  • Check the Recent Pages (WikiTraccs) view of the Site Pages libraries 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.
  • Review the WikiTraccs common log files for warnings and errors (*.WarningsAndErrors.log).
  • 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. Note: This is not required for most migrations.
  • Consider applying macro transformation templates to customize macro placeholders. See Macro Placeholders and Transformation Templates. Note: This is not required for most migrations.
• 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

(Optional) Run Page Refinement Pass - Fix Broken Links

• Enable Page Refinement mode in WikiTraccs (v1.28+) to analyze and update already migrated pages.
• Start with Log Broken Links to create a report of links that point to non-existing SharePoint pages. See Log Broken Links.
• If the report looks reasonable, run Fix Broken Links to automatically replace those links with the correct SharePoint URLs. See Fix Broken Links.

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 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, 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

Decision Overview

The following table summarizes key decisions to be made during a Confluence-to-SharePoint migration, recommendations, and where you need to take action.