Migration Playbook

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

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

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

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
  • 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 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.