Migration Process and Use Cases

• 1: Migration Playbook
• 2: Recipes
• 2.1: Confluence Macro Usage
• 2.2: Getting a list of pages per space [on-premises]
• 2.3: Find out why some pages won't migrate
• 2.4: How to Make Sure the Space Inventory Shows All Spaces

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

2 - Recipes

2.1 - Confluence Macro Usage

In the Confluence Administration, in the vertical left menu, click Macro Usage.

This will open a page that displays which macros are in use and the number of pages on which they appear:

The link to this page is admin/pluginusage.action (on-premises) or admin/macro-usage (Cloud).

Clicking on any of the macro names opens a search results page showing pages that use this macro.

The link for this kind of macro search is dosearchsite.action?cql=macro = "aura-tab" (here searching for the aura-tab macro).

Feel free to provide me with this list, e.g. for a demo or just for informational purposes.

2.2 - Getting a list of pages per space [on-premises]

Getting pages per space

This script returns a list of page metadata like content ID and title.

Run the following SQL script on the Confluence database. IMPORTANT: Replace MYSPACEKEY with the key of the space you want to get the page info for:

select contentid, contenttype, title, content_status, spacekey
from content left join spaces on content.spaceid = spaces.spaceid
where (contenttype='PAGE' or contenttype='BLOGPOST') and prevver is null and content_status='current' and spacekey='MYSPACEKEY';

Note: the space key is case SeNsItIvE.

Getting the page count per space

This script returns the page count for a space.

Run the following SQL script on the Confluence database. IMPORTANT: Replace MYSPACEKEY with the key of the space you want to get the page count for:

select count(*)
from content left join spaces on content.spaceid = spaces.spaceid
where (contenttype='PAGE' or contenttype='BLOGPOST') and prevver is null and content_status='current' and spacekey='MYSPACEKEY';

Note: the space key is case SeNsItIvE.

Getting the most recent page change per space

This script returns the timestamp of the most recently modified page or blog post for every space.

Run the following SQL script on the Confluence database.

SELECT
    spaces.spacekey,
    MAX(content.lastmoddate) AS most_recent_change_date
FROM
    content
LEFT JOIN
    spaces ON content.spaceid = spaces.spaceid
WHERE
    (content.contenttype = 'PAGE' OR content.contenttype = 'BLOGPOST')
    AND content.prevver IS NULL
    AND content.content_status = 'current'
GROUP BY
    spaces.spacekey
ORDER BY
    most_recent_change_date DESC;

2.3 - Find out why some pages won't migrate

Sample Situation

You have migrated a Confluence space that contains 3000 pages. Yet, when looking at the target site’s Site Pages library, you can only see 2900 pages. That’s 100 pages missing.

What’s up with those 100 missing pages? Why won’t they migrate?

What are possible root causes?

There are many reasons why pages fail to migrate. Some of them are temporary.

Here is a list of common issues:

• Connection Issues
  • when downloading content from Confluence, there was a service or connection issue
  • when creating a page in SharePoint Online, there was a service or connection issue and page or attachment creation failed
• Not enough Disk Space
  • there is not enough disk space for WikiTraccs to download all page attachments
• “Interesting” Page Content
  • a page contains content that WikiTraccs has never seen before and that it can’t handle well

WikiTraccs has mechanisms built-in to deal with some of those issues. For example, attachment upload and SharePoint page creation will be retried a couple of times to work around temporary connection issues. Missing disk space will cause the migration to be paused, until space is available again.

What to try first?

The first thing you should do is run the migration again, until the number of migrated pages stabilizes.

After the first migration run, 100 pages might be missing (for example due to unstable networking conditions). The second migration run might migrate another 50 pages. And the third migration run doesn’t change that.

Now what you are dealing with is the 50 pages that are still missing.

How to diagnose this?

The first thing we need is to look at the progress log files: Using progress log files to get insights.

Use the __30-aggregated-info progress log file to learn about the expected number of pages and the missing number of pages.

Use the __10-not-yet-migrated-pages progress log file to learn which pages are missing. This file contains page IDs that can be used to look up those pages in the common log files.

Take note that new progress log files are created with each migration run and that each space (or CQL selector) gets its own set of progress log files. So make sure to look at the most recent ones.

The ultimate tool to diagnosing why a page didn’t migrate are the common log files: Common log files.

Using the page IDs from the __10-not-yet-migrated-pages progress log file, we can look up corresponding log messages in the common log file(s) of a migration run.

Ultimately, the common log files should tell what was going on with those pages.

How to solve this?

Sometimes the common log files show something obvious, like a system being down, an authentication failing, or connection errors. This might help you inferring solutions.

But often it’s easier to send me the log files via email, for further diagnosis: [email protected].

Make sure to send the progress log files and also the common log files for a migration run.

2.4 - How to Make Sure the Space Inventory Shows All Spaces

Sample Situation

You open the Confluence Space Inventory, which is a SharePoint list that contains basic information about all Confluence spaces.

The Space Inventory list is created by WikiTraccs and populated with rows when you click the Update Space Inventory and WikiTraccs Site button:

Click to update the Space Inventory.

Let’s say you did this, look at the Space Inventory, and information about some spaces is missing.

What are possible root causes?

The most common causes are permission-related; the migration account might not be allowed to see all spaces.

Other possible causes include:

• there have been new spaces created since the last update of the Space Inventory
• you are looking at the wrong (outdated) SharePoint site and Space Inventory list, which can happen when experimenting and handling a lot of test sites (note: yes, this happened)
• space permissions or migration user permissions changed since the last update of the Space Inventory

What to try first?

You should update the Space Inventory.

When WikiTraccs shows the login dialog for Confluence, make sure to log in to Confluence with an account that is allowed to access all spaces. Or, if you are using token authentication, make sure to use the Personal Access Token of a migration user that is allowed to see all spaces.

Update the Space Inventory by clicking the Update Space Inventory and WikiTraccs Site button. You can click that button as often as you want, WikiTraccs will check every time if your spaces are present.

How to detect this situation in the first place?

Look up the Confluence space count in the Confluence administration and compare this number with the number of rows in the Space Inventory list. They should match.

Note: WikiTraccs adds information about both current and archived spaces to the Space Inventory.