This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Migration Process and Use Cases

This section has information about the migration process and common use cases.

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

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

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

WikiTraccs

  • 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

Other

  • 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

2 - Recipes

This article’s children provide recipes for common situations.

2.1 - Confluence Macro Usage

This article explains how to determine which Confluence macros are in use and how frequently they are used.

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]

This article contains information on how to get the pages per space for an on-premises Confluence instance.

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

This article contains information about possible causes of pages not migrating, how to find out more about those pages and specific issues, and how to solve those issues.

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.