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

Return to the regular view of this page.

WikiTraccs Documentation

1 - Getting Started

This article will guide you to your first Confluence migration with WikiTraccs.

Let’s dive in.

STEP ONE: Download WikiTraccs

Click to open the WikiTraccs download page: DOWNLOAD page.

Download the zip file.

Extract the zip file - it contains two folders WikiTraccs.Console and WikiTraccs.GUI.

In the WikiTraccs.GUI folder run WikiTraccs.GUI.exe.

A blue-ish window opens. We’ll call this just WikiTraccs for the remainder of this page, instead of WikiTraccs.GUI.

Congratulations, you downloaded and started WikiTraccs.

Proceed with the next step.

STEP TWO: Configure WikiTraccs and test connections

The window you opened in the previous step should look like this:

WikiTraccs main view

You will now use this view to configure everything for a first migration.

Select the Confluence base address input field and enter the base address of Confluence. This is the source system whose content will be migrated to SharePoint Online.

Under Confluence authentication type select the authentication type to use. Choose Anonymous to have WikiTraccs access Confluence as anonymous user. Choose Interactive login instead to open a browser window for logging in when starting the migration. Choose Personal Token to use a Personal Access Token (note: available as of WikiTraccs v1.13).

Select the WikiTraccs site input field and enter a SharePoint site address. Now is a good time to create this site.

Select the Try auto-detect from site button to detect the tenant ID. If this doesn’t work enter the tenant ID manually into the Tenant ID input field.

Select the Azure AD Application Client ID input field and enter the ID of the Entra ID application that WikiTraccs should use to access SharePoint.

Under SharePoint authentication type select the authentication type to use. Choose Interactive (MFA supported).

Proceed with the next step.

STEP TWO AND A HALF: Validate the configuration

Validating the Confluence connection settings

Choose the Test Confluence connection button to test the Confluence connection.

With the Anonymous and Interactive Login authentication types, WikiTraccs will open a browser window and automatically navigate to the Confluence base address you entered in step 1. Log in, if you chose Interactive Login as Authentication type in step 1.

Wait for the browser window to close. This is important. It has to close by itself.

A message box in the blue WikiTraccs.GUI window will open and tell whether the test succeeded or not.

Validating the SharePoint connection settings

Choose the Test SharePoint connection button to test the SharePoint connection.

WikiTraccs will show the default Microsoft 365 login experience in any open browser window it finds, or open a new browser window. Select this browser window and log in. A green bar should appear, saying Authentication complete.

Now select the blue WikiTraccs.GUI window again, bringing it back to the front.

A message box will open and tell whether the test succeeded or not.

When both of those tests where successful, select the Prepare WikiTraccs site and update space inventory button. You might have to log in again.

If successful, a message box will open and show you the number of Confluence spaces that were found.

Proceed with the next step.

STEP THREE: Start the migration

First, you need to select the Confluence spaces to migrate.

Choose the Open space inventory to choose source spaces button.

A browser window opens, showing the space inventory SharePoint list. It contains information about all spaces that were found in Confluence. WikiTraccs filled this list when you selected the Prepare WikiTraccs site and update space inventory button in the previous step.

For each element in the space inventory list, choose the RequestTransformation option to include this space in the migration:

Include a Confluence space in the migration.

When you are finished, return to the WikiTraccs window.

Select the Target site input field and enter the address of the target SharePoint site. This site will be the new home for migrated pages. Now is a good time to create this site.

Select the Start transformation button to start the migration.

A new window opens - WikiTraccs.Console - and the migration begins.

Congratulations. Your first migration is running.

Look at the Site Pages library of your target SharePoint site. After a minute or so new pages should appear. Those are the transformed Confluence pages.

1.1 - WikiTraccs Hotspots

This article covers topics that are often hotspots in a demo or while evaluating WikiTraccs as migration tool.

🔥 How does a Confluence migration to SharePoint look like?

  • Watch a video showing the whole process of migrating from Confluence to SharePoint with WikiTraccs: Getting Started.
  • Get more broader input for your migration process planning and validation: Migration Playbook.

🔥 How to test WikiTraccs? How does purchasing and licensing WikiTraccs work?

  • Test WikiTraccs using the free trial version; learn about the differences to the licensed version of WikiTraccs here: WikiTraccs Trial Version.
  • Everything related to purchasing can be found here: Purchasing.
  • There is more information in the FAQ section of the Pricing page.

🔥 How to get started? How to install WikiTraccs? Prerequisites?

  • The video on this pages covers the download and start of WikiTraccs: Getting Started.
  • Registering the Entra ID application - why we need it and how it can be configured - is covered in this blog post: Registering WikiTraccs as app in Entra ID.
  • Confluence versions 6, 7 and 8 are supported; with Confluence Cloud your mileage might vary (see issue #24)

🔥 What can be migrated by WikiTracs? What do the results look like?

🔥 How to migrate permissions, and metadata like page authors and dates?

🔥 What about delta migrations? How to update migrated pages?

  • WikiTraccs won’t touch SharePoint pages that are already migrated; you can delete SharePoint pages and re-start the migration and WikiTraccs will create them again. (Feature Request)

🔥 How can I stay up-to-date about new releases?

  • You should turn on notifications about new releases on GitHub. You’ll never miss a new release.
  • You can subscribe to the blog RSS feed, although this is more to be up to date in general, independent of specific releases.

🌳 How to replicate most-wanted Confluence functionality?

  • Page Breadcrumb: WikiPakk creates a dynamic breadcrumb for every page
  • Page Tree: WikiPakk offers a page tree in SharePoint that resembles what users know from Confluence

1.2 - WikiTraccs Trial Version

This article covers the trial version of WikiTraccs and how it’s different from the licensed (full) version.

How can I get a trial version of WikiTraccs?

WikiTraccs is free to test for everybody migrating from Confluence to SharePoint Online.

Choose this button to go to the download page:

Download FREE WikiTraccs now

You explicitly DON’T need a trial license key. There is also NO credit card information required to get started.

How do I get started with the trial version of WikiTraccs?

The quick start guide has you covered:

Quick start guide >>

It has all information you need to get started with your first trial Confluence to SharePoint migration.

How long can I use the trial version of WikiTraccs?

Unlimited testing time - keep testing as long as you need.

Unlimited spaces - nice.

Unlimited pages - you can migrate as many Confluence pages to SharePoint Online as needed to make an informed decision.

Unlimited size - migrate as many GB as you like.

The license is valid for Confluence Server, Confluence Data Center, and Confluence Cloud.

WikiTraccs will be functional when you need it.

What is the difference between the trial version and the licensed (full) version of WikiTraccs?

There are no functional differences between the trial version and licensed version of WikiTraccs.

In trial mode, WikiTraccs inserts a promotional header, sometimes a footer, and replaces some words in the page with “WikiTraccsTestMigration”.

Here’s a sample promo header:

This stops as soon as there is a valid license key, for all newly migrated pages.

How do I convert the trial version to a licensed version?

Two steps:

  1. You purchase a license key via the Pricing page.
  2. You activate the license as documented here: License Activation.

There is no need to install something new. The license activation will convert an existing WikiTraccs trial installation to the full version.

Note: you need to remigrate all pages after licensing WikiTraccs to have it create them without the trial markers. Simply delete the existing SharePoint pages and run the migration again.

2 - Migration Process and Use Cases

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

2.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.2 - Recipes

This article’s children provide recipes for common situations.

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

2.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;

3 - WikiTraccs Features

This article describes what WikiTraccs is capable of, and its limitations.

WikiTraccs takes the content of each Confluence page and converts it to something SharePoint can understand.

The following sections highlight what you can expect.

Confluence Spaces

WikiTraccs maintains a space inventory containing information about all spaces in Confluence, like space title and space key.

Space information is stored in a SharePoint list. You’ll instruct WikiTraccs to update this space inventory before starting a migration. WikiTraccs then fetches space information from Confluence and adds it to the list.

You’ll use the space inventory list to select spaces to transform. You can also specify which space will go to which SharePoint site.

WikiTraccs stores information about spaces with Current and Archived state. It’s up to you to select spaces for migration. Both types can be selected.

Page Content

Macros

The Known Confluence Macros article describes how WikiTraccs handles macros.

Confluence Task Lists

Task lists are transformed to a text format containing the title of the task and the state indicated by a checkbox emoji. Nested task lists are supported.

Text Formatting

Text and basic text formatting like bold, italics, underline etc. are preserved. There are formattings that can not be reflected 1:1 in SharePoint. It ultimately depends on the capabilities of the SharePoint text web part.

SharePoint has, among others:

  • limited background color support
  • not as many colors available as Confluence - WikiTraccs tries to find a similar SharePoint color, when a Confluence color is not avilable
  • limited nesting capabilities - e.g. you can apply formatting to whole nested sections of content in Confluence, something that SharePoint has limited support for

The source formatting also depends on the history of Confluence (versions, migrations), on the users and on the third party add-ons used. Thus it is an ongoing task to expand the capabilities of WikiTraccs here.

WikiTraccs contains hundreds of conversion rules that cover special cases observed over time and in Confluence instances with a long history.

In Confluence you can select sections of contents, images, headings etc. and let them link to other content. In contrast to that SharePoint just allows to put a link on text or on images.

WikiTraccs tries to de-construct complex Confluence structures. A single link coming from Confluence might be split up into multiple linked text elements plus inline images with the link attached.

When de-constructing complex linked Confluence structures is not possible in a meaningful way, WikiTraccs separates the content and the link. In this case the link will be added as additional content in the SharePoint page.

There are two types of links in Confluence:

  • Soft links, and
  • Hard links

Soft links are inserted with the link tool or from the clipboard and represent the usual way of linking within Confluence. Hard links are page addresses (URLs) copied directly into the content of a page, like text. Hard links can point to resources within Confluence as well, but also external sites.

Soft links between pages are mostly detected and converted. A link on a Confluence page pointing to another Confluence page, space, or attachment will be converted to a link to the corresponding page or file in SharePoint.

WikiTraccs covers a wide range of link types. Transforming hard links to the most recent version of a Confluence page is supported since release 1.6.4.

WikiTraccs will also transform links to other spaces. To do this it needs to know which space maps to which SharePoint site - this is done via the Space Inventory list.

Images

Images from Confluence pages are converted to image web parts in SharePoint pages.

Page Layout

Confluene Page Layouts

Yes, both Confluence and SharePoint have page layouts! WikiTraccs maps Confluence page layouts to corresponding sections in SharePoint. This works well for most of the page layouts.

There is a major drawback, though: pages in Confluence are much wider than SharePoint modern pages. SharePoint pages have a huge margin on the left and on the right. So migrated content from Confluence columns will be put into much narrower SharePoint columns. This might negatively impact the overall appearance.

Section and Column Macros, Panels

With Confluence’s section and column macros you can build arbitrarily nested structures of rows and columns. Those are a nightmare to convert to SharePoint.

WikiTraccs analyzes the sections and columns to find ways to:

  1. correct and simplify the structure (users may create non-sensical, deeply nested behemoths)
  2. map the macros to SharePoint tables

The result of mapping sections and columns to tables may introduce nested tables (tables within tables). And since nested tables are not supported by SharePoint, WikiTraccs will de-nest them (put them one after another).

The same applies to the panel macro - and by that matter to any other macro that is able to nest content into other content. Your mileage will vary widely with those web parts. See also the Nested macros and tables section below.

Page Metadata

The following page metadata is migrated:

  • creator
  • editor
  • creation date
  • modification date
  • page labels
  • source information: page id, parent page id, source space key, page title

Page Languages, Macros with MUI features

There are different products from the Atlassian marketplace available to make Confluence pages multilingual.

As of now WikiTraccs should be able to detect some of those (like Scroll Translations) and will migrate the language with the most content to SharePoint.

Making use of the SharePoint multilingual page features is surely possible, but currently not implemented.

There is an issue for that: Issue Link.

Page History

The current version of a page is migrated. No history is included.

There are currently no plans to reflect page versions in SharePoint. There are open questions from a technical standpoint regarding how page versions and attachments would be reflected in SharePoint.

Please get in touch if missing page versions are a blocker for you. In this case please think about how Confluence page versions and attachments and links to those elements would be reflected in SharePoint so that it solves your use case.

Comments & Inline Comments

WikiTraccs support the migration of footer comments. Those comments will be added as content to the bottom of migrated pages. Migration is optional and can be toggled in the settings.

Other comments like inline comments are not migrated, yet.

Feel free to chime in on this issue: Issue Link.

Drafts, Unpublished Changes and Trashed Pages

Currently none of those pages are migrated. Each page that should be migrated must be published in the clean-up phase before starting the migration.

There is an issue related to that: Issue Link.

Page Attachments and External Images

Each Confluence page attachment is migrated to SharePoint. The attachment files are stored in the Site Assets library, where a folder is created for each SharePoint page.

The main benefit of using the Site Assets library is that SharePoint mirrors any page permission changes to the folder belonging to the page. That means when breaking permission inheritance on a page the permission inheritance for the attachment folder is broken as well. This is a SharePoint out-of-the-box feature.

WikiTraccs also saves external images as page attachments in SharePoint because SharePoint does not allow image web parts to link to external domains. This is a security feature of SharePoint and makes storing those images locally necessary.

Page Permissions

Page permissions can be migrated to a certain extent. Have a look at this blog post for details: Mapping principals and migrating permissions.

Attachment Permissions

Attachment permissions in SharePoint are bound to page permissions. This is an out-of-the-box feature of SharePoint.

Attachment Metadata

Page attachments are migrated, along with the following metadata:

  • Creation Time
  • Created By
  • Last Modified Time
  • Last Modified By

WikiTraccs maps this data to the corresponding out-of-the-box SharePoint fields.

Attachment History

WikiTraccs migrates the latest version of any page attachment.

User @-mentions

SharePoint has limited support for mentions as those are currently only supported in SharePoint page comments but not the page content. Thus Confluence user mentions will be replaced by links in the SharePoint page content. Selecting this link will take the user to the SharePoint search results for the user’s email address (if the email address is known).

If Confluence and Jira are integrated then WikiTraccs tries to get issue information like key, title and link from Jira to insert it in the SharePoint page.

For single Jira issues there will be one link per issue in the resulting SharePoint page.

The Jira issue list will be converted to a static table showing links to Jira issues. If the table had multiple pages, a snapshot of only the first page is migrated to SharePoint. So, for a query that covers 1000 issues only the first 20 or so will be shown. A link to Jira is added to the SharePoint page so you can jump to Jira to see the live issue list.

Other aggregating macros are replaced by placeholders as those macros are not supported in SharePoint.

Nested Macros and Tables

SharePoint Online modern pages are currently limited with respect to formatting and structure. Their structure is very simple and elements mostly cannot be nested.

That is the reason why certain Confluence structures have to be re-build in a non-optimal way. Let’s look at some examples.

Nesting tables is not possible in SharePoint but in Confluence. For this specific case the workaround is to de-nest those tables and put them one after another. Thus the content is preserved but the page might harder to read as a result.

The same goes for macros that contain rich content like the Expand macro, the Panel, Note-like macros and the Section and Column macros. They all allow a degree of nesting that is not possible to re-build in SharePoint.

WikiTraccs tries its best to convert those elements to something that is still legible in SharePoint. But since each source page is unique so might be the transformation needed to convert this content.

Confluence Version Support

WikiTraccs supports Confluence 6 and up, including Confluence Cloud. Confluence 5 and older are not supported.

In any case, please use the free Trial Version of WikiTraccs to check that it works in your environment.

Target SharePoint Site vs. Subsite

WikiTraccs works with sites (site collections), not subsites. Microsoft advises agains using subsites in SharePoint Online:

Classic SharePoint architecture is typically built using a hierarchical system of site collections and subsites, with inherited navigation, permissions, and site designs. Once built, this structure can be inflexible and difficult to maintain. In the modern SharePoint experience, subsites aren’t recommended. In the new “flat” world of modern SharePoint, plan to create one site for each discrete topic, task, or unit of work. This will allow you to easily distribute management and accountability for each content collection and support your ability to move sites around in your navigational architecture without breaking links. Moreover, when a topic is no longer needed, you can easily archive or delete a site with minimal impact.

4 - WikiTraccs Reference

A reference of topics around WikiTraccs.

4.1 - How does WikiTraccs work?

This article describes the basics of WikiTraccs.

Overview

WikiTraccs migrates content from Atlassian Confluence to SharePoint Online.

It does more than a simple migration, though. While migrating it will transform Confluence macros, links, images and more to its SharePoint equivalents. Thus it could be called a transformation rather than just a migration.

If you are looking for a solution that transforms your Confluence content into modern SharePoint Online pages WikiTraccs has got you covered.

How does it work?

The process of getting content from Confluence to SharePoint works roughly as follows:

Confluence export and SharePoint import is done page by page. When interrupted WikiTraccs will continue at the page where it left off. Just start the process again.

Transformations can be configured on a per-space basis. You configure which Confluence space is migrated to which SharePoint site. Multiple spaces can be migrated to the same site.

WikiTraccs stores transformation metrics for each page in SharePoint as metadata of the page. You can sort, filter and review directly in SharePoint to check the transformation result.

How to get started?

Read here to learn how to get started: Getting started

4.2 - WikiTraccs License Activation

This article describes how to activate a purchased WikiTraccs license.

After purchasing WikiTraccs a license key will be shown. Furthermore, an email will be sent to the email address entered into the checkout form.

Create a new, empty file license.txt file in the WikiTraccs.Console folder. Open license.txt for editing. Then copy and paste the license key to this file. Save and close the file.

If WikiTraccs.GUI or WikiTraccs.Console is running, close it.

Start WikiTraccs. It should now recognize the license file.

Verifying that the license is recognized by WikiTraccs

In the blue WikiTraccs window, have a look at the gray text box, it should show license information:

"License found" message after starting WikiTraccs.GUI

During a running migration, WikiTraccs also shows information about the license:

License validity shown during a migration

Troubleshooting

WikiTraccs logs information about any license files it finds, including locations it expects such a file to be.

Check the common log files that the license file is at an expected location. See the following sections for log samples.

License found

If one or multiple license key files could be found, the log contains entries like those:

[ 21:37:42 INF] Trying to find license... | 
[ 21:37:42 INF] Checking if license file exists in: '/home/user/wikitraccs/WikiTraccs.GUI' | 
[ 21:37:42 INF] FOUND license file candidate '/home/user/wikitraccs/WikiTraccs.GUI/license.txt' | 
[ 21:37:42 INF] Found license files, will now read licenses from them: ["/home/user/wikitraccs/WikiTraccs.GUI/license.txt"] | 
[ 21:37:43 INF] License wikitraccs-full-edition-xlarge, valid from 2024-05-13T12:01:00, to 2025-05-13T12:01:00 |

License missing

If no license key file could be found, the log looks like this:

[ 21:59:32 INF] Trying to find license... | 
[ 21:59:32 INF] Checking if license file exists in: '/home/user/wikitraccs/WikiTraccs.GUI' | 
[ 21:59:32 INF] Did not find license file(s) in: '/home/user/wikitraccs/WikiTraccs.GUI' | 
[ 21:59:32 INF] Did not find any license key files. Falling back to Free Edition. Learn where to put the license key: https://www.wikitransformationproject.com/docs/reference/license-activation |

Get in touch if you need help.

4.3 - WikiTraccs FAQ

Frequently (and not so frequently) Asked Questions around WikiTraccs.

This FAQ covers questions folks have while evaluating and using WikiTraccs.

The answers are often short on purpose and nuance might be lost this way. Please refer to the documentation links for an in-depth discussion of the respective topics.

Q: What is the access level needed in SharePoint to migrate spaces to? Same question for Confluence.

A: For Confluence creating a migration account is recommended. The following access levels work for this account: Confluence administrator (recommended), space owner, read-only user. Lesser access means that page restrictions and/or user account information (email address, name) cannot be migrated.

For SharePoint creating a migration account is also recommended. This account should be site collection administrator of SharePoint target sites. Furthermore an Entra ID app registration is required. The app needs delegated permissions, ideally FullControl, but Manage works to an extend. Refer to the linked documentation for details.

Further reading:

Q: What if we don’t have access to a global admin account of SharePoint?

A: You probably don’t need a SharePoint global admin. Here’s what’s needed when preparing the migration:

  • in SharePoint Online, create modern sites and assign the migration account permissions - if self-service site creation is enabled then any user can do this
  • in Entra ID, register an Entra ID application - this can be done by an account with Application Developer role in Entra ID, but see the linked Microsoft documentation for more details; this has to be done once as prerequisite to using WikiTraccs
  • only if a new migration account is to be used for SharePoint: in the Microsoft 365 administration, create a migration account - this needs the User Administrator admin role
  • only for WikiPakk: in SharePoint Online, add the WikiPakk app from Microsoft AppSource to the global tenant app catalog - the user doing this needs to be Owner of the tenant app catalog site, although it more commonly is the SharePoint administrator

Further reading:

A: Yes, mostly. When a Confluence page is migrated to SharePoint, links to other Confluence pages, spaces, and attachments are transformed to point to the respective SharePoint pages. This is true for soft links, that means “proper” Confluence links. See the next question about hard links and why it’s harder for WikiTraccs to handle those.

Link transformation is done based on a naming scheme WikiTraccs uses for SharePoint page names, thus the target page doesn’t need to exist, yet. You can migrate Confluence page Foo that links to Confluence page Bar, without having to migrate Bar. The link will be transformed and points to a (yet) non-existing SharePoint page Bar - until you migrate page Bar. Then the link works.

Note about versioning: the link will always point to the current page version in SharePoint since WikiTraccs only migrates the current page version.

Further reading:

A: Hard links are plain old HTML links that Confluence is oblivious of, from a metadata standpoint. Technically, hard links appear like any other text content on a Confluence page. And also technically, they lack important metadata that is needed to locate the target page - a page ID, page title or space key. Sometimes those links make it into a Confluence page, mostly by pasting text into a page. As long as the target Confluence page does not change much those links work. But upon renaming the target page those links might break.

To transform a Confluence link to a SharePoint link WikiTraccs needs to know which Confluence page or space a link points to. As the needed metadata is only present with soft links and missing for hard links, WikiTraccs might not be able to transform hard links.

Since release 1.6.4 WikiTraccs has basic hard link support. WikiTraccs looks for hard links and tries to figure out the target page. If that is successful the hard link is transformed to a proper page link in SharePoint.

Further reading:

Q: How do you know which spaces and pages can/can’t be migrated from Confluence?

Q: Can I choose which space I want to migrate so I can migrate batches of spaces?

Q: What granularity does the selection of migrating give us? Space-by-Space? Page-by-Page?

A: Migration with WikiTraccs is done on a per-space basis. You choose Confluence spaces to migrate, and which target SharePoint site to use as migration target. All pages from the source space will be migrated to the chosen target.

Technically, there is no restriction as to which Confluence spaces can be migrated. Everything the Confluence migration account sees will be seen, and can be migrated by WikiTraccs.

You choose which spaces to migrate in the Space Inventory, a list that WikiTraccs creates in SharePoint. WikiTraccs stores basic information about each space it finds in Confluence in this list. You then tick a box for all spaces that should be migrated. When starting the migration, WikiTraccs looks at this list to know what to migrate, and to which sites.

Migrating spaces in batches can be done by adjusting the space selection in the Space Inventory: select spaces for a batch, then migrate; for the next batches, adjust the space selection accordingly.

Further reading:

Q: Do the versions of Conflunence pages also get migrated?

A: No. Only the current version of pages and attachments will be migrated.

Q: Is having WikiPakk the only way to keep the left page tree menu like we currently have in Confluence? Is subscription charging the only way for WikiPakk?

A: WikiPakk is the only ready-made option I’m aware of that shows a SharePoint page tree and breadcrumb, for migrated and out of the box SharePoint pages. At this time a monthly subscription is the only supported payment model. A yearly subscription option will be added soon. If you’d prefer another model, please let me know as demand drives development.

Technically you could develop another form of visualization. The metadata that WikiTraccs creates for each migrated page in SharePoint contains the Confluence page ID, parent Confluence page ID and space key. That is all that’s needed to visualize the hierarchy.

Q: If the execution is interrupted during migration, will it restart where it stopped? We have lots of spaces and access restrictions per team.

A: Yes, WikiTraccs is very forgiving with respect to interruptions. The migration can be interrupted at any time and continues where it left off.

Q: Will it also migrate spaces/pages restrictions as well or we will have to do manually? Please, show us how to migrate also the users/team permissions on migrated pages.

A: WikiTraccs can migrate permissions, to the extend possible given the differences between Confluence and SharePoint. In Confluence you have a page hierarchy and access to each page in this hierarchy can be restricted, at each level. SharePoint in comparison has no hierarchy, just a bunch of pages in the Site Pages Library. There is no permission hierarchy on pages in SharePoint.

Furthermore, when moving from Confluence to SharePoint Online, you need to think about groups. Are all groups from all Confluence user directories that take part in the Confluence permission scheme present in Entra ID? WikiTraccs does not create groups.

The bottom line is that permission migrations - while possible to an extent - rarely make sense.

Further reading:

  • Refer to this blog post for instructions on how to migrate permissions, and for a list of capabilities and restrictions with regard to permission migration from Confluence to SharePoint: Mapping principals and migrating permissions

Q: Currently our SharePoint only creates “Modern Pages”, and we cannot create “Wiki Style pages” is that a problem?

A: Perfect, WikiTraccs creates modern pages as well. Classic pages are not supported.

Q: In the target SharePoint site I see in the “+ New” button we now have a new option “Site Page (transformed by WikiTraccs)”, why is this?

A: That’s a new page content type created by WikiTraccs, that is derived from the standard SharePoint content type Site Page. It contains additional fields to hold metadata from Confluence and about the migration. It’s a technical artifact and should be hidden from the user. (#76)

Q: If a page or space makes use of a template (Jira Report / Decision / Sprint Review / etc.) can it be migrated to SharePoint and keep the template working in SharePoint?

Q: If the page has buttons will the button continue to work on SharePoint with same behavior?

Q: There are numerous page templates w/in Confluence. How does WikiTraccs handle page templates (page layout/structure)?

A: WikiTraccs migrates Confluence pages to SharePoint Online modern pages. It transforms the content of Confluence pages to something that can be shown in a SharePoint page, and is limited by what SharePoint has to offer (layouts, web parts, formatting, …). WikiTraccs has no explicit knowledge of templates.

What WikiTraccs recognizes is the use of Confluence page layouts with sections, like “two column section” or “three column section with side-bars”. Those will be translated to SharePoint page sections, which are comparable.

Overall, you can think about it this way: WikiTraccs can do in an automated fashion what you can do manually in SharePoint. If you cannot create something in SharePoint, WikiTraccs can’t do it either. But if you can create it, WikiTraccs could be able to do it as well, if it’s not already doing it.

Further reading:

Q: Will the tool flag if it could not properly migrate a page or space?

A: Yes. WikiTraccs measures migration success on two levels: page and space.

For page content migration success WikiTraccs collects indicators. Those indicators are stored with the page in the Site Pages library. You look at those indicators to find problematic pages, in each target SharePoint site.

For space content migration success WikiTraccs creates progress log files for each migrated space. You can see which pages have been migrated, how many are yet to be migrated, and more.

Further reading:

Q: How does the tool decide if it should create a Team site, Hub site or a communication site when migrating? Can the tool decide this automatically?

Q: Does the tool always require a blank target site in SharePoint?

Q: If we point the tool to target a SharePoint url destination that already has content with same title, will it be overwritten, or the tool will create a new site keeping any existing SharePoint site intact?

A: WikiTraccs does not create SharePoint sites. You need to create or choose target SharePoint sites for the migration. Note: the target sites need to have the Site Pages feature enabled which is on by default for modern sites.

You enter the target SharePoint URLs into the Space Inventory.

Deciding the right type and number of target sites in SharePoint is out of scope of WikiTraccs and would be part of a transformation project of any kind.

Further reading:

Q: Is it better to centralize the migration in one team? WikiTraccs seems to requires us to migrate from the root URL of Confluence, if not, there will be an error.

A: The migration could be done by multiple teams. For that to work you would create clusters of source space and target sites and assign each team one cluster. Each team could use different migration accounts for Confluence and SharePoint. This way each team would only see content from their cluster. Keep in mind that this might break links between pages if WikiTraccs cannot access both the source and target page/space.

Regarding the root URL: WikiTraccs uses the Confluence REST API and needs to know the Confluence base URL to find the correct REST endpoints.

Q: I find it difficult to understand what pages I was selecting comparing against the left page tree view menu. I want to migrate only pages under menu “FAQ”. How can we do that in the “Confluence Space Inventory”?

A: WikiTraccs migrates spaces. It does not allow selecting single pages or parts of the page tree for migration. If you want to migrate only some pages of a Confluence space to SharePoint you need to migrate the whole space and delete the content from SharePoint that you don’t need.

Further reading:

  • Feature proposal to allow selecting pages via CQL query: #77

Q: How much time does it take to migrate?

A: The migration time depends on a number of factors. Let’s look at each of those:

  • SharePoint usage and throttling affects migration time
    • depending on the usage of Microsoft 365 worldwide and the region you are in the speed of SharePoint-related operations can vary; migrating on a weekend might be faster than during working hours
    • also depending on the overall Microsoft 365 service usage clients might be throttled; this means for WikiTraccs that sometimes it has to wait before being allowed to create new content; this is also why it might make limited sense to run parallel migrations - throttling might occur faster
    • throttling can happen at any time, slow cloud perforformance can happen at any time
    • the speed of a SharePoint tenant as well as throttling limits depend on the number of active licenses in the tenant; thus migrating to a SharePoint test environment might be slower that migrating to a production environment
  • page contents affect migration time
    • migrating a simple page from Confluence to SharePoint on average seems to take about 4 to 8 seconds
    • migration time per page will be higher if the page links to page-external content, like Jira issues (causes request to Jira server), external images (causes download of external image), and other Confluence pages, spaces, or attachments (causes additional requests to those Confluence resources)
  • attachments affect migration time
    • each attachment has do be downloaded from Confluence and uploaded to SharePoint Online
    • downloading from Confluence takes time that is dependent on the Confluence instance’s performance
    • uploading to SharePoint can take anything up from half a second
    • larger attachments take more time
  • the number of pages per space can affect migration time
    • when starting and stopping the migration of a Confluence space WikiTraccs requests the list of pages for that space from Confluence, to fuel progress bars and measure migration success
    • for spaces with a large number of pages (say 10000 pages and up) getting the list of space pages can take minutes - this is a known Confluence issue
    • the time to retrieve pages from such a large space can vary; one Confluence instance might return a list of 25000 pages in 20 seconds, another instance might take half an hour
  • Confluence Cloud usage and throttling affect migration time
  • your internet download speed, upload speed, and connection stability affect migration time
    • fast download speed helps getting content from Confluence
    • fast upload speed helps pushing content to SharePoint
    • a stable connection helps preventing retry-loops that WikiTraccs has build in to work around unstable network conditions

WikiTraccs migrates pages one by one and does not parallelize. You can parallelize the migration by running a second WikiTraccs instance on another machine.

Further reading:

Q: Has WikiTraccs ever done a big migration / Enterprise level like ‘big company’?

Q: We Have at least 350 Confluence wiki spaces to migrate to SharePoint. Is there a batch of so many wiki spaces you can do in one run?

Q: We have multiple attachments currently in the Confluence wiki spaces and is there a limit how many attachments can be migrated to a SharePoint site?

A: The largest successful WikiTraccs-based migration that I know of “in the wild” consisted of ~160 spaces and ~200,000 pages. The largest space had ~20,000 pages. Note that I’m not aware of customers that did restriction/permission migrations and would advise against it, as SharePoint works differently that Confluence with regard to permissions.

The largest migration in a test environment has been ~3,000 spaces, consisting of ~120,000 pages, having ~360,000 attachments that where ~850 GB in size - all migrated from Confluences to a single SharePoint target site collection.

In principle there is no defined technical limit to the number of pages or attachments WikiTraccs an migrate, and SharePoint can ingest within its impressive limits. It’s just that migrating and verifying takes longer with every space, page and attachment that is part of the migration.

The “Is there a batch of so many wiki spaces you can do in one run?” question carries additional topics: the concept of a batch and run. In my view a batch would be the Confluence content to be migrated as configured via the Space Inventory list. You defined the size of the batch. A run would be what WikiTraccs does after kicking off the migration. It will migrate the content one page after another.

One note regarding the you can part of the question; this might just be a phrasing issue, but to be clear: The Wiki Transformation Project does not offer consulting services and does not take part in migration projects. The Wiki Transformation Project provides the tool WikiTraccs that can be a vital part of your Confluence to SharePoint migration tool belt, as well as WikiPakk to provide a SharePoint page tree experience that will make users happy.

Further reading:

Q: Do you provide consulting services?

Q: Can you provide more details about the PS costs that you can share?

Q: Are there maintenance fees?

Q: Do you offer any professional services to assist our team, if required?

A: The Wiki Transformation Project provides unrestricted break-fix support via email and GitHub.

Read more about your options here: Support Options

With regard to consulting services (advisory services, premier support, alliance support, etc.): The Wiki Transformation Project does not offer consulting services and does not take part in migration projects. The Wiki Transformation Project provides the tool WikiTraccs that can be a vital part of your Confluence to SharePoint migration tool belt, as well as WikiPakk to provide a SharePoint page tree experience that makes users happy. I might recommend consulting partners though, depending on the region you are operating in.

Further reading:

Q: In your experience what determines the success or failure of a migration project from Confluence to SharePoint?

Q: Do you have a “Default Plan” how we should proceed with such a migration?

Q: What do the success stories have in common?

A: You need to have a plan before thinking about migration tooling.

The Migration Playbook hints at that in the Proof of Concept Phase, Decision, and Analysis Phase.

Providing migration guidance or consulting is out of scope of WikiTraccs. But I might recommend a partner that can help. Get in touch if you are interested in a recommendation.

Q: How long is the trial period for your product (30 days, 60 days or 3 months)?

Q: What limitations are there on using the free eval?

A: When WikiTraccs doesn’t find a license key, it runs in trial (or evaluation) mode.

When running in unlicensed trial mode, WikiTraccs slightly changes the SharePoint pages it creates. It inserts a promotional header, sometimes a footer, and replaces some words in the page with “WikiTraccsTestMigration”. This stops as soon as there is a valid license key.

The trial period of WikiTraccs is as long as you need it to be. There is no end. Try as long as it takes to make an informed decision.

All features are available in WikiTraccs trial mode as well, so you can test them thoroughly. You can perform a test migration of all your Confluence pages; no limits on the number of pages, files, or spaces.

Further reading:

Q: Is the look and feel of the Confluence wiki spaces migrated/transformed to SharePoint site same as in Confluence after it is migrated?

A: This question could refer to the look and feel of the actual Confluence spaces - which will become SharePoint sites - or the look and feel of the wiki pages once they have been migrated to SharePoint.

WikiTraccs does not create or configure SharePoint sites. Creating and configuring SharePoint sites is a manual task that usually is part of a transformational project. This is out of scope of what WikiTraccs can do.

With regard to the migrated Confluence pages the answer is No, the look and feel of the SharePoint pages is not the same as in Confluence.

Confluence and SharePoint are different with regard to layout, styling, metadata, permissions, navigation, user management, and integration with other Microsoft 365 services - so the look and feel will certainly differ. This is something that should be taken into account when introducing SharePoint as Confluence replacement.

I strongly recommend getting to know SharePoint before migrating Confluence content to SharePoint. Create some pages and learn their capabilities.

Please refer to the linked pages for more information about WikiTraccs’ capabilities and visual migration samples.

Further reading:

Q: Do you need to do any type of tweak or adjustment to make the spaces and attachments look exactly same as Confluence wiki spaces in the SharePoint site(s)?

A: It’s impossible to make the SharePoint sites to look exactly like Confluence, or to make the migrated pages look exactly like the Confluence pages. At least with the approach WikiTraccs takes.

The configuration of SharePoint sites is entirely up to you. WikiTraccs won’t do much to a SharePoint site that might be relevant to your use cases.

Migrated Confluence pages will become SharePoint pages - which are different in their capabilities from Confluence pages. For example, Confluence macros are not present in SharePoint. That alone makes a big difference.

Migrated Confluence page attachments stay as they are, as they are just files. SharePoint can store files. WikiTraccs downloads Confluence page attachments and uploads them to the SharePoint Site Assets library, the default place for page attachments in SharePoint. Page attachments can be made visible per SharePoint page via a list view web part, that WikiTraccs can insert at the end of a page.

Q: Are there Confluence standard macros which won’t be migrated?

Q: Confluence allows for many “macros” and application integrations. What happens when WikiTraccs encounters such application integrations?

A: For most macros and integrations it’s technically impossible to migrate them to SharePoint.

You can make an experiment: choose a Confluence macro you’d like to see migrated to SharePoint. In a modern SharePoint page, try to rebuild what that macro does.

Could you rebuild the macro functionality in SharePoint? Good! WikiTraccs could do the same. If WikiTraccs does not yet support your scenario - get in touch, tell me about your solution!

But most likely you won’t be able to find anything in SharePoint that could be a drop-in replacement for your chosen macro. And in this case WikiTraccs cannot find one, either.

Further reading:

Q: Confluence is also integrated with Jira, and most likely utilizing linked/embedded Jira EPICs, FEATUREs, etc. - How does WikiTraccs handle this situation?

A: There are different Jira macros that can be used to show Jira-related content in Confluence pages, as well as link to those contents.

One macro allows to link to a single Jira issue. WikiTraccs converts this macro to a simple hyperlink, that links to the respective Jira issue. When users click those links in SharePoint they are redirected to the external Jira application.

As of this writing, all other Jira macros are replace by a static placeholder text. Corresponding feature request: #102.

Further reading:

Q: Is it a one to one Confluence wiki space migration to SharePoint? So 350 wiki spaces will be migrated to 350 different pages and spaces in SharePoint site?

A: WikiTraccs migrates the pages of Confluence spaces to SharePoint sites. You configure the space to site mapping.

When migrating a space, all pages of this space are migrated.

Each space can go to its own target SharePoint site.

Multiple spaces can go to one target SharePoint site.

Note: Currently it’s not possible to “split” a space, migrating its pages to different target SharePoint sites.

For migrating 350 Confluence spaces to 350 target SharePoint sites the process would roughly be as follows:

  1. create 350 target SharePoint sites and configure them according to your concept; using PnP PowerShell and PnP templates is one common approach to automate site creation
  2. use WikiTraccs to automatically fill the Space inventory list with information about those 350 Confluence spaces
  3. map each space to its target site URL
  4. select spaces to migrate
  5. start the migration using WikiTraccs

Further reading:

Q: Can we do all this in one license or we have to purchase multiple licenses?

A: You buy one WikiTraccs license with the appropriate Page Count Tier and are good to go. There are currently no feature-dependent licenses.

Have a look at the Pricing page for details.

Q: What does the “Page Count Tier” (or “number of pages”) mean?

A: The Page Count Tier refers to the sum of pages and blog posts in the source Confluence environment, at the time of purchase.

The following four tiers are available:

  • up to 10,000 pages
  • up to 50,000 pages
  • up to 100,000 pages
  • over 100,000 pages

Note that this is not the number of pages you plan to migrate. Also note that this is not the number of page migrations that you can do.

Here are examples for illustration:

  • Example 1: There are 20,000 pages and blog posts in Confluence. You plan to migrate all of them. The license needed is “up to 50,000 pages”, because that covers the source environment’s number of pages and blog posts.
  • Example 2: There are 45,000 pages and blog posts in Confluence. You plan to migrate 7000 pages to SharePoint. The license needed is “up to 50,000 pages”, because that covers the source environment’s number of pages and blog posts.
  • Example 3: There are 9,000 pages and blog posts in Confluence. You migrate all 9000 pages. Something happens and you need to migrate 5000 of those pages a second time. The license needed is still “up to 10,000 pages”, because that covers the source environment’s number of pages and blog posts.

Further reading:

Q: Is it per-license cost or do you provide an enterprise license model?

A: The cost is per WikiTraccs license key. The purchased license key is for internal use, sublicensing or providing services to a third party is not permitted. The third party would have to acquire a separate license key.

Further reading:

Q: How many licenses we need to complete the project?

A: That depends on the duration of your project.

A WikiTraccs license key is valid for a 6-month period, starting with the date of the purchase. After 6 month you would need to purchase a new license, that again is valid for 6 month.

You need one such license for WikiTraccs with the appropriate Page Count Tier. Have a look at the pricing page for details: Pricing.

Q: Do you recommend each Confluence space to a SharePoint Online subsite?

A: Microsoft does not recommend using subsites in SharePoint Online, and WikiTraccs cannot migrate to subsites. So, I would advise against it.

Further reading:

4.4 - Prerequisites

This article describes the prerequisites for running WikiTraccs.

Prerequisites of the Migration Machine

Operating System

WikiTraccs runs on Windows.

Tested so far have been Windows 10, Windows 11, Windows Server 2012 R2, Windows Server 2016, Windows Server 2019, Windows Server 2022.

If Confluence only supports TLS 1.3, choose Windows 11 or Windows Server 2022. See the note about TLS 1.3 below.

Hardware

ComponentWorks
CPU64-bit 2.6-GHz quad core processor
RAM16 GB
Operating systemWindows 11 client
ComponentWorks
CPU64-bit 3.1-GHz quad core processor
RAM24 GB
Operating systemWindows Server 2012 R2 Standard

Provide enough storage for all of Confluence to be downloaded. Confluence has 500 GB of attachments? Provide at least 500 GB of hard drive storage.

Software Requirements

A recent version of the Chrome browser needs to be installed (for authenticating with Confluence, refer to the authentication article for details on authentication)

Windows Configuration

The Windows swap file should be at least 12 GB of size. This proved to be helpful in low-memory environments (e.g. only 3 GB of RAM in a Windows VM) to prevent out of memory errors. It probably won’t be necessary with more RAM, but it doesn’t hurt either.

Endpoint Requirements

Refer to the endpoints article on required endpoints.

Security Note

WikiTraccs doesn’t need to run with admin rights, and should not be run with admin rights.

Note that WikiTraccs automatically downloads the Google ChromeDriver that is used to automate the Chrome browser window to show the Confluence login with interactive login. There have been a couple of cases where either this download, or the ChromeDriver have been blocked from running. Unblocking the ChromeDriver or running WikiTraccs with admin rights tended to solve the issue in those cases.

Note about TLS 1.3

When the Confluence server only supports TLS 1.3 connections, you have to run WikiTraccs on a Windows version that officially supports TLS 1.3; those are Windows Server 2022 and Windows 11.

There have been issues reported where the Confluence server was upgraded to only support TLS 1.3 and Windows subsequently failed to properly negotiate a cipher. Please test this scenario before starting the migration or refrain from changing the TLS protocol during the migration. A workaround is available, though, in the form of the WikiTraccs proxy mode.

4.5 - Installation and Update

This article shows how to install and update WikiTraccs.

Downloading and running WikiTraccs for the first time

Downloading and running WikiTraccs for the first time is covered in the Getting started guide, in section STEP ONE: Download WikiTraccs.

It boils down to downloading and extracting a zip file. No installation needed.

Updating WikiTraccs

New releases are published in the WikiTraccs Releases GitHub repository under Releases.

Updating WikiTraccs works as follows:

  1. perform the same steps as described in above section Downloading and running WikiTraccs for the first time, just to a different directory (so don’t overwrite the old version)
  2. (optional) if you configured something via appsettings.json copy this file from the old to the new directory, into the same sub directory (either WikiTraccs.GUI or WikiTraccs.Console)
  3. run WikiTraccs (GUI or Console) from the new directory

You are now running the new version of WikiTraccs.

The settings configured via the WikiTraccs.GUI “blue window” are preserved automatically. Those settings are stored in the current Windows user’s app directory. For details about the location, see File Storage.

You can also back up and restore this file as needed.

4.6 - Settings & Configuration

This article is a resource where you can find configuration options for WikiTraccs.

How to configure WikiTraccs

You’ll start configuring WikiTraccs and your Confluence to SharePoint migration at two places:

  • inside the blue window that is WikiTraccs.GUI
  • in SharePoint lists that WikiTraccs creates, in a SharePoint site you create (the WikiTraccs site)

In most cases, using the blue WikiTraccs.GUI window and the SharePoint lists for configuration is enough.

Some settings, though, aren’t available for visual configuration in WikiTraccs.GUI. For those you need to use another approach that involves a configuration file.

Both approaches are described in the following sections.

The visual and convenient configuration via WikiTraccs.GUI

In WikiTraccs.GUI an often-used subset of configuration options is available for visual configuration.

The following settings and functions are available in WikiTracs.GUI (or a SharePoint list it creates), no need to use the config file for those:

This is everything needed to get a migration going.

One SharePoint list central to configuring WikiTraccs is the Confluence Space Inventory list, or short Space Inventory. This list is created and populated by WikiTraccs when you select the Prepare WikiTraccs site and update space inventory button.

WikiTraccs overall creates the following lists in the WikiTraccs Site when you select the Prepare WikiTraccs site and update space inventory button:

  • Confluence Space Inventory - for you to select what to migrate, and where
  • Confluence User and Group Mapping - for you to map Confluence user accounts to Entra ID accounts (and groups)
  • WikiTraccs Locks - for internal use
  • Confluence Permission Snapshots - for internal use

The following resources have more information:

The more involved configuration via config file and WikiTraccs.Console

More settings are available via WikiTraccs.Console and a configuration file. Only when you want to change those settings you have to use the configuration file.

Use the configuration file for the following advanced scenarios or non-default configurations:

  • changing the configuration often, e.g. for automation purposes
  • using different authentication methods for different target SharePoint sites
  • toggling feature and debug flags not available in the GUI
  • changing the location where Confluence content is stored during the migration
  • manually configuring the Chrome driver for Confluence login in a locked-down environment
  • configuring timeouts for external domains
  • migrating single pages by page ID

The following resources have more information:

4.6.1 - Configuration via WikiTraccs.GUI (blue window)

This article provides information about the settings in WikiTraccs.GUI. The GUI approach allows to easily configure WikiTraccs in a clickable user interface.

This article assumes you are using the blue WikiTraccs.GUI window to configure your migration.

To open the settings dialog, click Settings in the top menu bar.

The following sections describe settings in detail.

Tab “Migration”

Migration Mode

Note: Screenshot of WikiTraccs version 1.17.2; might look different in a recent version.

Mode “Migrate Content”

This mode selects content migration.

Content will be migrated from Confluence to SharePoint. This is probably what you would expect from a migration tool.

You’ll always use this mode first.

WikiTraccs downloads content (pages, attachments, …) from Confluence, transforms it to something SharePoint can understand, and creates corresponding SharePoint content (modern pages, files, …).

Mode “Update ‘Created by’ & ‘Modified by’ (of already migrated content)”

This mode can be used to update the Author and Editor metadata of SharePoint pages.

Background

Confluence pages have an author and an editor. The author created the page and the editor last edited the page. SharePoint pages also have an author and editor.

WikiTraccs can migrate this metadata as well so that the created SharePoint pages have the same author and editor as in Confluence. To be able to do that, WikiTraccs needs a mapping from Confluence user accounts to Entra ID user accounts.

The user mapping is done in the Confluence Users and Groups Mappings list in the WikiTraccs site. Have a look here on how to configure this mapping: Mapping Confluence users and groups to SharePoint. If Confluence accounts and Entra ID account have the same email addresss WikiTraccs might be able to prepopulate the mapping. Otherwise that is a manual task. Using PnP.PowerShell to automate this is recommended if the number of users is high.

What does the update mode do?

Assume that the user mapping list did not yet contain all user mappings when migrating pages (using mode Migrate Content).

After migrating pages, you’ll end up with SharePoint pages having the migration account as author and editor. That’s because WikiTraccs doesn’t know about the corresponding Entra ID account.

But that’s ok. Actually, that is how it’s supposed to work:

  1. You migrate content from Confluence to SharePoint
  2. During the migration, WikiTraccs adds all Confluence users it encounters to the mapping list
  3. You configure the user mapping
  4. You use the update mode to update the author and editor of existing SharePoint pages according to the mapping

So, you first run the migration in Migrate Content mode. Then, after configuring the mapping, you run the migration again, in Update ‘Created by’ & ‘Modified by’ mode.

Mode “Update Permissions (of already migrated content)”

This mode is for applying page restrictions from Confluence to already migrated SharePoint pages.

This blog post has all the details about migrating permissions (and also why you should avoid doing it): Mapping principals and migrating permissions

This mode is two-phased like the Update ‘Created by’ & ‘Modified by’ mode:

  1. You migrate content from Confluence to SharePoint
  2. During the migration, WikiTraccs adds all Confluence users it encounters to the mapping list, plus it stores information about all restrictions in the Confluence Permission Snapshots library in the WikiTraccs site
  3. You configure the user and group mapping
  4. You use the update mode to update SharePoint page permissions according to the mapping

Please refer to the blog post linked above, it has all the details.

Mode “Verify page contents (of already migrated pages)”

Currently, you won’t need this mode. It is kind of “for future use”.

If you want more details, please refer to the release notes of WikiTraccs v1.12.5, section Verification Mode.

Migrate blog posts

Choose whether to migrate blog posts or not.

Choose whether to migrate footer comments or not.

Download external images

Choose whether to download external images or not.

Confluence pages can contain images from external sources. Those images are not in the page attachments, but are retrieved from an external source when opening the page in Confluence.

SharePoint Online doesn’t allow adding images from external non-Microsoft sources. All images that you link to have to be a file in SharePoint, or a related Microsoft-owned service. The reasoning behind this decision is probably user privacy. External images can be used to track user behavior.

WikiTraccs can download external images and “convert” them to SharePoint page attachments, so the images can be shown in SharePoint.

One possible caveat is that - especially older - Confluence pages might link to images that don’t exist anymore. WikiTraccs will still try to download them - which can take time, if the external source is responding very slowly.

If downloading external images is slowing down your migration you can use this setting to toggle it off.

4.6.2 - Confluence Space Inventory

This article is a resource where you can find information about the Confluence Space Inventory list.

Facts about the Confluence Space Inventory

The Confluence Space Inventory - or short Space Inventory - is a SharePoint list that serves the following purposes:

  1. list all Confluence spaces; those can be marked as migration source, making them a space selector
  2. allow configuring additional source content selectors (CQL query selectors, content ID selectors)
  3. serve as the lookup table when transforming Confluence links to SharePoint links

WikiTraccs creates the Space Inventory list and adds information about Confluence spaces.

You use the Space Inventory to select source content to migrate, and to specify target SharePoint sites. WikiTraccs will use this information to decide which content to migrate, and how to resolve links between pages.

The Space Inventory is created and updated by WikiTraccs.GUI when selecting the Update space inventory and WikiTraccs site button:

Note: WikiTraccs.Console will also check and create the Space Inventory, if necessary.

The Space Inventory can be repeatedly updated by selecting the Update space inventory and WikiTraccs site button. Use this to have spaces added to the inventory list that are missing, either because they have been newly created in Confluence, or because they have been deleted from the list.

Accessing the Space Inventory

Selecting the Open Space Inventory to choose source spaces button opens the Space Inventory in a browser:

When the Space Inventory exists, the browser should show the SharePoint list Confluence Space Inventory (WikiTraccs):

If - for whatever reason - the Space Inventory does not exist, the browser will show an error:

If you see above error, make sure to select the Update space inventory and WikiTraccs site button first so that WikiTraccs has a chance to create and update the list.

You can find the Space Inventory without WikiTraccs as well, as it’s just a SharePoint list. Open the WikiTraccs site in a browser, go to Site Contents, and select the Confluence Space Inventory (WikiTraccs) list.

How does it work exactly?

Here’s an image showing how the Space Inventory works:

This image summarized:

  • the Space Inventory list contains multiple source to target mappings that tell WikiTraccs what to migrate, and where
  • each row contains at least the following mandatory information:
    • WT_In_CfSiteId - the Confluence site identifier; this corresponds to the Confluence base URL (example: https://wiki.contoso.com or https://contoso.atlassian.net/wiki)
    • WT_In_CfSpaceKey - a source selector, telling WikiTraccs which pages to migrate; this can be the Confluence space key, but starting with release 1.8 of WikiTraccs this field can also contain a CQL query (example for space key: HR, example for CQL query: label=“archive”)
    • WT_Setting_RequestTransformation - if this is checked, WikiTraccs will migrate all pages covered by the the source selector from Confluence to SharePoint; otherwise this mapping is only used for link resolution
    • WT_Setting_TargetSiteRootUrl - the target SharePoint site for all pages covered by the source selector; this is relevant for migrating pages covered by the source selector, but also for creating the correct links to target pages (example: https://contoso.sharepoint.com/sites/target1); if this is left empty, the default target site URL as configured via WikiTraccs.GUI will be used
  • when starting the migration, WikiTraccs will collect content from all source content selectors that have been chosen for migration, and schedule them for migration; this queue is processed one item after another
  • when a page contains a link to a space, page or attachment, WikiTraccs will look up the SharePoint target site in the Space Inventory and create the link based on the found mapping; if there is no mapping a transformation error will be logged for the page (see Measuring page migration success on where to find this metric)

Using the Confluence Space Inventory

Here are other resources involving the Space Inventory:

To learn more about the source-to-target mapping and about the different source content selectors, refer to the following articles:

4.6.2.1 - How to map Confluence Source Selectors to SharePoint Sites

This article describes how to configure which Confluence content is migrated to which SharePoint site.

WikiTraccs needs to know what to migrate and where to migrate it to. It needs a mapping.

Content to migrate is chosen by source content selectors.

Selectors

A selector tells WikiTraccs which Confluence content to migrate.

The following selectors are supported:

WikiTraccs also needs to know where to create the migrated SharePoint pages. This is done by configuring a target site collection for each selector.

The source-to-target mapping is important for two things:

  1. knowing which Confluence content to get and to which SharePoint site to migrate this content
  2. transforming Confluence links to proper SharePoint links

Getting the mapping right before starting the migration is crucial for link transformation.

Migrate to one target site by default

WikiTraccs, in absence of any other configuration, migrates everything to one default target site.

When using WikiTraccs.GUI you enter the default target site URL into the Default target site input field:

Default Target Site Configuration in WikiTraccs.GUI

When you don’t configure anything else, WikiTraccs will migrate Confluence content to this SharePoint site.

Configure a different target site for selectors

When you want WikiTraccs to migrate content from different source content selectors to different target sites, you configure this mapping in the Confluence Space Inventory list in the WikiTraccs site.

The Confluence Space Inventory list has a column WT_Setting_TargetSiteRootUrl. Enter the target site root URL there.

Target Site Root URL Column

When the WT_Setting_TargetSiteRootUrl column is empty, WikiTraccs falls back to using the default target site URL for that space. It is totally valid to set a target site URL only for some spaces.

In general, when migrating pages, WikiTraccs translates links between Confluence pages to proper links between SharePoint pages.

The target site mapping is important to properly transform links between Confluence pages to links between SharePoint pages.

When migrating Confluence pages that link to other Confluence pages, WikiTraccs looks up the target site URL for the target page. To be able to do that, WikiTraccs finds the selector that contains the link’s target page and uses its target site URL to construct the page’s SharePoint URL. Note that the link’s target page doesn’t have to be migrated yet for this to work as page names follow a well-known naming convention.

The links WikiTraccs creates in SharePoint follow a naming convention. This convention is roughly as follows (for pages):

<TARGETSITEURL>/SitePages/<SPACEKEY>-<PAGETITLE>-<PAGEID>.aspx

(The resulting page file name is stripped of any characters that are not allowed in SharePoint.)

When a Confluence page is migrated to SharePoint and this page links to another page or space that has not yet been migrated WikiTraccs can nevertheless create the link. WikiTraccs doesn’t care if the target exists. It will exist once it will have been migrated.

This allows WikiTraccs to migrate Confluence pages that link to other pages or spaces that have not yet been migrated, while still creating valid links.

4.6.2.2 - How to migrate Confluence Content using Space Selectors

This article describes how to migrate whole spaces to SharePoint.

Selecting whole Confluence spaces for SharePoint migration is the easiest way to map and migrate Confluence content.

Why use a space selector?

With space selectors you tell WikiTraccs what to migrate on a per-Confluence-space basis.

Usual scenarios are:

  • migrate each Confluence space to a corresponding SharePoint site
  • migrate multiple Confluence spaces to one SharePoint site, for example for archiving purposes

If that is a granularity you can work with, do it. It’s easier than CQL query selectors and content ID selectors.

Where to configure space selectors?

Go to the Space Inventory; it should already contain a list of all Confluence spaces WikiTraccs found, when you followed the steps of the Quick Start tutorial.

Set a check mark in the Wt_Setting_RequestTransformation column for every space you want to migrate.

Here’s what the Space Inventory list might look like:

WT_In_CfSpaceNameWT_In_CfSpaceKeyWt_Setting_RequestTransformationWT_Setting_TargetSiteRootUrl
Project AlphaPALPHAxhttps://contoso.sharepoint.com/sites/ProjectAlpha
Project BetaPBETAxhttps://contoso.sharepoint.com/sites/ProjectBeta
MiscellaneousMISCxhttps://contoso.sharepoint.com/sites/Miscellaneous
MarketingMRKThttps://contoso.sharepoint.com/sites/Marketing
SalesSALEShttps://contoso.sharepoint.com/sites/Sales
Customer ServiceSERVICEhttps://contoso.sharepoint.com/sites/CustomerService
HRHRhttps://contoso.sharepoint.com/sites/HR
FinanceFINhttps://contoso.sharepoint.com/sites/Finance
ITIThttps://contoso.sharepoint.com/sites/IT

Note: Other columns have been omitted for brevity.

In the above sample, three spaces have been selected for migration: Project Alpha, Project Beta, and Miscellaneous.

Space selectors are relevant for link transformation.

When WikiTraccs transforms a cross-space link from PAGE_SOURCE to PAGE_TARGET, all selectors in the Space Inventory will be checked if they contain PAGE_TARGET.

Having found a selector that contains PAGE_TARGET, WikiTraccs uses this selector’s WT_Setting_TargetSiteRootUrl value to create the link.

Be sure to fill those WT_Setting_TargetSiteRootUrl columns for all selectors, not only the ones to be migrated.

4.6.2.3 - How to migrate Confluence Content using CQL Query Selectors

This article describes how to use CQL queries to select source pages and how to configure which CQL query selector is migrated to which SharePoint site.

WikiTraccs allows selecting source pages for migration using CQL queries.

Migrating spaces vs. migrating via CQL query

Before release 1.8.0 WikiTraccs only supported the configuration of entire Confluence spaces for migration and for link resolution. This meant that all pages of a given source space would be migrated to the configured target site.

Feedback from clients let to the introduction of an additional, more flexible way to select source pages: pages can now also be selected via CQL query. This allows to select specific pages for migration.

For WikiTraccs the technical difference is minimal, from a page selection perspective.

For you, the difference is also minimal, from a configuration perspective. The Space Inventory list is still used to configure which pages should be migrated to which target. Simply write your CQL query to the WT_In_SpaceKey field.

The following screenshot shows how different CQL queries are used to select pages by their label, migrating each label to a different target site:

Space Inventory list showing CQL query selectors for source page selection.

Note: the field is still named WT_In_SpaceKey since initially only a space key was supported there.

Everything else from the space selector article applies as well, so please refer to this article: How to map Confluence Spaces to SharePoint Sites. The target site can be configured. If there is no target site set, the default target site will be chosen.

There are some consequences though, when using CQL queries.

The consequences of using CQL queries source selectors

Here’s the list of topics that can get more complicated when dealing with CQL queries:

  • Restricted Pages: see note above
  • Link Resolution: Confluence pages linking to other spaces, pages, or attachments require more time to migrate, and put more load on Confluence
  • Query Result Size: using CQL queries you can select a large amount of pages (potentially all)
  • Duplicate Pages: one page can be selected by multiple CQL queries, leading to pages being migrated multiple times

For each CQL query selector you add to the Space Inventory WikiTraccs has to issue one additional request to Confluence for each link it needs to resolve.

Assume you are migrating 10,000 pages, with 2 links to other pages on each of those 10,000 pages. Further assume you configured 100 CQL query selectors in the Space Inventory list. That means that 2*100 callbacks to Confluence would need to be issued for each of those 10,000 pages, amounting to 2,000,000 calls overall during the migration of those 10,000 pages.

Why is that?

To transform links from Confluence to SharePoint, WikiTraccs needs to know which target site a page will be migrated to. But how would WikiTraccs know which CQL query contains which page? To learn this WikiTraccs asks Confluence for each CQL query if a given page is included.

Example:

  • page A links to page B with ID 2000
  • WikiTraccs needs to find out which SharePoint site page B will be migrated to, to create the proper SharePoint link
  • there are two CQL queries configured: label="one", mapped to target site https://contoso.sharepoint.com/sites/one, and label="two", mapped to target site https://contoso.sharepoint.com/sites/two
  • WikiTraccs creates a modified CQL query (label="one") AND (id=2000) to check if page B is covered by CQL query label="one"
    • there are no results - page B is not covered
  • WikiTraccs creates a second modified CQL query (label="two") AND (id=2000) to check if page B is covered by CQL query label="two"
    • there is one result - page B is covered!
  • WikiTraccs now knows that page B will be migrated to site https://contoso.sharepoint.com/sites/two
  • thus the correct link to page B is something like https://contoso.sharepoint.com/sites/two/SitePages/SPC-Page-B-2000.aspx

Note: WikiTraccs does not have to do this when only performing space-based migrations (without any CQL queries), since the target site can easily be looked up via each page’s space key in the Space Inventory list.

Duplicate pages can be created

You can write CQL queries might include overlapping results.

Take for example the CQL queries label="one" and label="two".

If Confluence pages only ever have one of the labels one or two, those selectors choose two disjuct sets of pages. Which is good.

But what about pages having both labels one and two? Those pages will be chosen by both CQL queries, migrating each of those pages two times.

The consequences are:

  • duplicate content in SharePoint as multiple copies of a page are present
  • fuzziness when it comes to linking to those pages as other SharePoint pages can only link to one of the duplicates; which one is not defined

CQL query selectors are relevant for link transformation.

When WikiTraccs transforms a cross-space link from PAGE_SOURCE to PAGE_TARGET, all selectors in the Space Inventory will be checked if they contain PAGE_TARGET.

Having found a selector that contains PAGE_TARGET, WikiTraccs uses this selector’s WT_Setting_TargetSiteRootUrl value to create the link.

Be sure to fill those WT_Setting_TargetSiteRootUrl columns for all selectors, not only the ones to be migrated.

4.6.2.4 - How to migrate Confluence Content using Content ID Selectors

This article describes how to use a list of Confluence content IDs to select source content and how to configure which content IDs are migrated to which SharePoint site.

WikiTraccs allows selecting Confluence source content for migration using Confluence content IDs.

Why use a content ID selector?

If you have complex requirements with regard to which Confluence content is migrated to which SharePoint site, content ID selectors allow for full flexibility.

You’ll prepare a content ID selector for WikiTraccs that looks like this:

123456789;#page,234567891;#page,345678912;#page,4567891234;#blogpost,5678912345;#blogpost

Above selector contains the content IDs of 3 pages and 2 blogs.

How you end up with the list of IDs to migrate is entirely up to you.

You can run a complex database query in an on-premises Confluence environment. Or you can use Excel-based ID filtering on space content reports for Confluence Cloud.

WikiTraccs’ Content ID Format

WikiTraccs needs each content ID to follow this pattern: ID;#TYPE

  • ID is the actual Confluence content ID, like 123456789
  • ;# is a delimiter to separate the ID from the type
  • TYPE is the Confluence content type like page and blogpost (note: more content types will be supported in the future)

Multiple content IDs are delimited by comma, like ID;#TYPE,ID;#TYPE,ID;#TYPE.

Where to configure content ID selectors?

For each new content ID selector you want to create, add a new item in the Space Inventory.

Use the WT_Setting_ContentSelectorValue field to specify the content ID selector value.

Set the WT_In_CfSiteId field to the Confluence base address (like https://contoso.atlassian.net/wiki or https://wiki.contoso.com). Look at the other entries in the Space Inventory and copy the value from those entries that WikiTraccs created for spaces.

Here’s what the Space Inventory list might look like after adding two content ID selectors:

WT_In_CfSiteIdWt_Setting_RequestTransformationWT_Setting_TargetSiteRootUrlWT_Setting_ContentSelectorValue
https://contoso.com/wikixhttps://contoso.sharepoint.com/sites/ProjectAlpha123456789;#page,234567891;#page,345678912;#page,4567891234;#blogpost,5678912345;#blogpost
https://contoso.com/wikixhttps://contoso.sharepoint.com/sites/ProjectBeta101;#page,201;#blogpost

Note: Although content ID selectors are added to the “Space” Inventory, a space key or space ID doesn’t have to be set.

Migrating via CQL query vs. migrating via content IDs

CQL queries allow filtering content by IDs, just like content ID selectors.

But CQL queries in Confluence have one big limitation with regard to restrictions. Restricted contents might be missing from the query result, even when using a migration account that has admin permissions. Have a look at the CQL selector article for details: How to migrate Confluence Pages using CQL Query Selectors.

A WikiTraccs content ID selector does not have this restriction.

Why is that?

When handling a content ID selector WikiTraccs will also try to get chunks of content via CQL queries, to speed up things. WikiTraccs then checks if expected IDs are missing from the CQL query result. If there are IDs missing, WikiTraccs assumes that those are restricted and that the current migration account should be allowed to access them (just not via CQL).

For each ID that is still missing from the query result WikiTraccs will get those one by one via their ID. This will succeed if the content exists and the migration account is allowed to view it.

The consequences of using content ID source selectors

Please refer to the respective section of this article: How to migrate Confluence Pages using CQL Query Selectors. The reasoning about duplicates and links also applies to content ID selectors.

Furthermore, retrieving contents via single IDs for a large selector will take more time than retrieving all contents of a space or CQL query. The more content there is where the migration account is not direct part of the restriction configuration, the longer it takes to retrieve the selector’s content.

SQL Snippets

Using SQL you can get content IDs for your selector from the Confluence database.

Here are sample SQL statements to get them in the right format for WikiTraccs (like 123456789;#page,234567891;#blogpost).

Get the content ID selector that includes ALL Confluence pages and blogposts:

SELECT count(*), string_agg(contentId || ';#' || contenttype, ',') AS contentIdSelectorValue
FROM (
    SELECT contentId, LOWER(contenttype) AS contenttype
    FROM content
    WHERE (contenttype='PAGE' OR contenttype='BLOGPOST')
      AND prevver IS NULL
      AND content_status='current'
    ORDER BY contenttype, contentId
) subquery;

Get the content ID selector that includes Confluence pages and blogposts from space MYSPACEKEY:

SELECT count(*), string_agg(contentId || ';#' || contenttype, ',') AS contentIdSelectorValue
FROM (

	SELECT contentid, LOWER(contenttype) AS contenttype
	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'
    ORDER BY contenttype, contentId
) subquery;

Replace MYSPACEKEY with the key of the space you want to get content IDs for.

Content ID selectors are relevant for link transformation.

When WikiTraccs transforms a cross-space link from PAGE_SOURCE to PAGE_TARGET, all selectors in the Space Inventory will be checked if they contain PAGE_TARGET.

Having found a selector that contains PAGE_TARGET, WikiTraccs uses this selector’s WT_Setting_TargetSiteRootUrl value to create the link.

Be sure to fill those WT_Setting_TargetSiteRootUrl columns for all selectors, not only the ones to be migrated.

4.6.3 - Configuration via Configuration File

This article is a resource where you can find configuration options for WikiTraccs that are set via a configuration file.

Configuring via configuration file

The configuration file works with both WikiTraccs.GUI (the blue window) and WikiTraccs.Console.

The configuration is done in the appsettings.json file. When you run WikiTraccs.GUI then appsettings.json must be placed in same folder as WikiTraccs.GUI.exe. When you run WikiTraccs.Console then appsettings.json must be placed in same folder as WikiTraccs.Console.exe. Create the file, if needed.

Here is a sample of appsettings.json configured for a straightforward content migration (a second sample follows further down, explaining the options):

{
    "CustomSettings": {
        "TargetTenants": [
            {
                "HumanReadableId": "Contoso SharePoint",
                "SharePointRootUrl": "https://contoso.sharepoint.com",
                "ClientId": "76762071-f1a9-4323-a97a-ab24992032fd",
                "Tenant": "82fb6e24-c982-4f08-a009-1916ee226643",
                "AuthenticationType": "interactive",
                "TargetSites": [
                    {
                        "HumanReadableId": "WikiTraccs",
                        "SiteRootUrl": "https://contoso.sharepoint.com/sites/MigrationStore"
                    },
                    {
                        "HumanReadableId": "WikiTraccsDefaultTarget",
                        "SiteRootUrl": "https://contoso.sharepoint.com/sites/DefaultTarget"
                    }
                ]
            }
        ],
        "TransformationMappings": [
            {
                "SourceTenantHumanReadableId": "Contoso Confluence",
                "TargetTenantHumanReadableId": "Contoso SharePoint",
                "TargetSiteHumanReadableId": "WikiTraccsDefaultTarget"
            }
        ],
        "SourceTenantIncludeList": [
            {
                "TenantId": "https://www.contoso.com/confluence",
                "HumanReadableId": "Contoso Confluence",
                "SpaceTransfer": {
                    // note: spaces to migrate are configured via space inventory list in the SharePoint WikiTraccs site
                    "Enabled": true
                }
            }
        ],
        "AttachmentRegistryRootPath": "D:\\FileRegistry",
        // WikiTracs detects Chrome version automatically
        "ChromeDriverVersionOverride": null,
        // WikiTracs downloads Chrome web driver to current directory
        "WebDriverDirPath": null,
        // WikiTracs locates chrome.exe automatically
        "ChromeBinaryPath": null,
    }
}

Here is a complete and documented sample of appsettings.json showing more options for advanced and multi-pass configuration:

{
    "CustomSettings": {
        "TargetTenants": [
            {
                "HumanReadableId": "Contoso SharePoint",
                "SharePointRootUrl": "https://contoso.sharepoint.com",
                // client ID (application ID) of the registered Entra ID Application
                "ClientId": "76762071-f1a9-4323-a97a-ab24992032fd",
                // SharePoint tenant ID
                "Tenant": "82fb6e24-c982-4f08-a009-1916ee226643",
                // How to authenticate with Entra ID; valid options are: "interactive" (supports MFA, use this), "credentials" (no MFA support), "devicelogin".
                "AuthenticationType": "interactive",
                // Optional: configuration for AuthenticationType "credentials", not needed for "interactive".
                "AuthenticationParameterSetCredentials": {
                    "CredentialsUserName": "[email protected]",
                    "CredentialsPassword": "p4ssw0rd"
                },
                // contains all sites used in the migration; two are mandatory: "WikiTraccs" and "WikiTraccsDefaultTarget"
                "TargetSites": [
                    {
                        // This is the "management site" for WikiTraccs that contains space inventory, user and group mapping table etc.; the HumanReadableId MUST be "WikiTraccs".
                        "HumanReadableId": "WikiTraccs",
                        "SiteRootUrl": "https://contoso.sharepoint.com/sites/MigrationStore"
                    },
                    {
                        // This is the default migration target for spaces that have no other target configured; the HumanReadableId MUST be "WikiTraccsDefaultTarget".
                        "HumanReadableId": "WikiTraccsDefaultTarget",
                        "SiteRootUrl": "https://contoso.sharepoint.com/sites/DefaultTarget"
                    }
                ]
            }
        ],
        // Configure migrations here; which source should be migrated to which target:
        "TransformationMappings": [
            {
                "SourceTenantHumanReadableId": "Contoso Confluence",
                "TargetTenantHumanReadableId": "Contoso SharePoint",
                "TargetSiteHumanReadableId": "WikiTraccsDefaultTarget"
            }
        ],
        // Confluence configuration
        "SourceTenantIncludeList": [
            {
                // You MUST use the Confluence base URL as TenantId
                "TenantId": "https://www.contoso.com/confluence",
                // By default, when using interactive Confluence login, the Confluence base URL (as specified by the TenantId) will be opened in a browser.
                // If you need to use an address for authentication that is different from the base URL, you can specify this here. This is optional.
                "AuthUrl": "https://www.contoso.com/confluence/login.action?force_azure_login=false",
                // This can be anything and is used to reference to the source tenant.
                "HumanReadableId": "Contoso Confluence",
                // Add page IDs here to force-migrate those pages.
                "PageIdIncludeList": [
                    "123456789",
                    "234567890"
                ],
                // Migrate SharePoint pages with transformation errors again.
                "ReprocessContentWithErrors": true,
                // Configure content migration here.
                "SpaceTransfer": {
                    // Uncomment this to switch to principal checking mode; this updates the Created by and Modified by fields of pages; configure user mapping first!
                    //"Operations": ["checkprincipals"],
                    
                    // Do migrate content.
                    "Enabled": true,
                    // Handle those spaces; note that this will be merged with the spaces selected in the space inventory list in SharePoint:
                    "SpaceIncludeList": [
                        {
                            "SpaceKey": "AGILE"
                        },
                        {
                            "SpaceKey": "ARCHIVE"
                        }
                    ]
                },
                // Configure permission migration here.
                "PermissionTransfer": {
                    // Do migrate permissions; note: only enable either SpaceTransfer, or PermissionTransfer, _not_ both at the same time.
                    "Enabled": false,
                    // Migrate permissions for those spaces.
                    "SpaceIncludeList": [
                        {
                            "SpaceKey": "AGILE"
                        }
                    ]
                }
            }
        ],
        "ReprocessContentWithErrors": false,
        // Sometimes there are huge wait times if external images don't time out properly. The number of retries and waits can be tweaked here so this does not slow down too much.
        "ExternalDomains": [
            {
                "UrlStartsWith": "https://docs.docker-cn.com",
                "HttpTimeoutRetries": 2,
                "HttpTimeoutSecs": 2
            }
        ],
        // By default WikiTraccs expects chromedriver.exe to be in the same folder as WikiTraccs. It will be downloaded if not present.
        // Here you can change the folder WikiTraccs uses, and also place a pre-downloaded exe there.
        "WebDriverDirPath": "C:\\Users\\user\\Documents\\00_Portable",
        // Only needed in environments where the auto-detection endpoint is blocked; must match the Chrome version (see Troubleshooting > Connectivity for details)
        "ChromeDriverVersionOverride": "72.0.3626.52",
        // Normally WikiTraccs locates chrome.exe automatically.
        // Specify an absolute path to chrome.exe if this fails _or_ you'd like to point to a specific Chrome version.
        "ChromeBinaryPath": "C:\\Program Files\\Google\\Chrome Beta\\Application\\chrome.exe",
        // By default WikiTraccs stores Confluence attachments in the application folder for the current user.
        // Override this location here with an absolute path.
        "AttachmentRegistryRootPath": "D:\\FileRegistry",
        // Those options can aid debugging.
        "Debug": {
            "ClearLocalCacheOnStart": false, // default: false
            // Set this to true to save the storage format of every transformed page to disk. This can be useful for troubleshooting.
            "SaveTransformationInputToDisk": false, // default: false
            // Skip connection checks when starting transformation in WikiTraccs.GUI?
            "SkipConnectionCheckInWikiTraccsGui": false,
            // Ignore errors when preparing a site as migration target (not recommended!)?
            "SkipPreparationResultCheck": false,
            // Skip caching of API responses (space inventory content, Confluence API calls) that would otherwise be cached for some time (often only some minutes)?
            "BypassCaches": false
        },
        "Features": {
            // Trigger update of space inventory? Note that this can also be done from WikiTraccs.GUI.
            "FillSpacesList": false,
            // Transform page tree macro to static tree of links in SharePoint?
            "TransformPageTreeMacro": true, // default: true
            // Transform roadmap macro to image placeholder? Note that the image placeholder does not contain all information (e.g. text is missing).
            "TransformRoadmapMacro": true, // default: true
            // Use a centered dummy image for advanced text control flow around images (>0.1.5)?
            // note: this becomes obsolete in newer versions, due to updates to SharePoint pages by Microsoft; don't bother
            "EnableDummyImageFloatResetForImages": true,
            // Add a link to the source Confluence page?
            "AddLinkToSourcePage": false,
            // Mark formerly merged table cells?
            "TableCellSpanLayoutMode": "UnmarkedAdditionalSlots", // default: "MarkedAdditionalSlots"
            // add attachments section to each page (if there are attachments)?
            "AddAttachmentsSection": true,
            // migrate footer comments (will become page content)?
            // release notes: https://github.com/WikiTransformationProject/wikitraccs-releases/releases/tag/v1.9.0
            "MigrateFooterComments": true,
            // try to resolve hard links?
            // release notes: https://github.com/WikiTransformationProject/wikitraccs-releases/releases/tag/v1.6.4
            "ResolveHardLinks": true,
            // migrate Confluence blog posts to SharePoint
            "MigrateBlogposts": true,
            // promote migrated blog posts as SharePoint news; note: this may cause notifications for users
            "PromoteBlogposts": true
        },
        "WiggleRoom": {
            // set the maximum wait time for callouts to Jira for resolving issue links and issue tables
            // set this to -1 to disable reaching out to Jira while migrating pages from Confluence to SharePoint; this is handy when the Jira application link is no longer functional
            // release notes: https://github.com/WikiTransformationProject/wikitraccs-releases/releases/tag/v1.11.12
            "JiraMaxWaitTimeSec": 60,
            // set the maximum number of parallel uploads when migrating attachments from Confluence to SharePoint
            // handle with care, a number too high will quickly get you throttled by Microsoft
            "ParallelFileOperationsCount": 2,
            // number of seconds to wait after a failed page provisioning (e.g. due to connection loss); a multiplier will be applied by WikiTraccs with each try, this is the base value
            "WaitTimePerProvisioningRetryBaseSec": 20,
            // number of times a page provisioning is retried after failing for whatever reason (e.g. connection loss)
            "ProvisioningRetriesCount": 4,
            // number of results to get with call to the content API (non-body, with expansions)
            // ATTENTION: setting this too high will make content be missing from the migration!
            // there are system limits baked into Confluence: 200 is the maximum for retrievals with non-body expansions, which is used by WikiTraccs when bulk-retrieving information about pages
            "PageRetrievalPageSizeOverride": 200,
            // number of IDs to bundle into one CQL query that will be used to retrieve pages for the content ID selector
            // ATTENTION: choosing a number too high will lead to a Server Error from Confluence; lower the number if that is the case
            "PageRetrievalByContentIdsCqlPageSizeOverride": 500
        }
    }
}

When running WikiTraccs.Console you have to use appsettings.json to configure everything. The program will stop with an error pretty fast if the configuration is missing.

4.6.3.1 - Sample Configurations

This article contains sample configurations for different purposes.

The following configurations can be used to control WikiTraccs.Console without the GUI.

Everything that can be configured via WikiTraccs.GUI can also be configured via a settings file, and more. Save the settings to appsettings.json in the same directory where WikiTraccs.Console.exe is located. Create appsettings.json if necessary.

Run WikiTraccs.Console.exe to start the migration according the configuration.

Sample: Migrate contents of one space

The following configuration migrates the content of space identified by space key demo to the SharePoint site https://contoso.sharepoint.com/sites/migration-test. WikiTraccs site (for under-the-hood tables) and migration target site are the same here.

{
  "CustomSettings": {
    "WebDriverDirPath": "C:\\Users\\user\\00_Portable",
    "SourceTenantIncludeList": [
      {
        "TenantId": "http://localhost:8090",
        "AuthenticationType": "cookie",
        "HumanReadableId": "Confluence",
        "SpaceTransfer": {
          "Enabled": true,
          "SpaceIncludeList": [
            {
              "SpaceKey": "demo"
            }
          ],
          "Operations": [
            "retrievecontents"
          ]
        },
        "PermissionTransfer": {
          "Enabled": false,
          "SpaceIncludeList": []
        }
      }
    ],
    "AttachmentRegistryRootPath": "D:\\FileRegistry",
    "TempPath": "C:\\Users\\user\\AppData\\Local\\Temp\\",
    "TargetTenants": [
      {
        "HumanReadableId": "SharePoint",
        "SharePointRootUrl": "https://contoso.sharepoint.com",
        "Tenant": "b6e543a2-f741-40a3-80c1-97c168702d56",
        "ClientId": "0bf87492-f0bc-4476-a31f-67e016cdf31d",
        "AuthenticationType": "interactive",
        "TargetSites": [
          {
            "HumanReadableId": "WikiTraccsDefaultTarget",
            "SiteRootUrl": "https://contoso.sharepoint.com/sites/migration-test"
          },
          {
            "HumanReadableId": "WikiTraccs",
            "SiteRootUrl": "https://contoso.sharepoint.com/sites/migration-test"
          }
        ]
      }
    ],
    "TransformationMappings": [
      {
        "SourceTenantHumanReadableId": "Confluence",
        "TargetTenantHumanReadableId": "SharePoint",
        "TargetSiteHumanReadableId": "WikiTraccsDefaultTarget"
      }
    ]
  }
}

Snippet: Prevent WikiTraccs from downloading external images

WikiTraccs downloads external images and converts them to page attachments of the SharePoint page. This is because SharePoint prevents showing images from external sources.

Here’s the configuration snippet to disable that and to prevent WikiTraccs from downloading external images:

{
  "CustomSettings": {
    "Features": {
      "DownloadExternalImages": false
    }
  }
}

Snippet: Prevent WikiTraccs from reaching out to Jira

WikiTraccs tries to connect to Jira to properly transform Jira issue and Jira issue list macros when migrating pages from Confluence to SharePoint.

If the application link to Jira does not exist anymore, or WikiTraccs is operating in a locked down environment, you can disable this.

Here’s the configuration snippet to prevent WikiTraccs from reaching out to Jira:

{
  "CustomSettings": {
    "WiggleRoom": {
      "JiraMaxWaitTimeSec": -1
    }
  }
}

Or, instead of disabling, you can set a lower maximum wait time, like 5 seconds:

{
  "CustomSettings": {
    "WiggleRoom": {
      "JiraMaxWaitTimeSec": 5
    }
  }
}

Note that such a low timeout might be sufficient to retrieve details about a single Jira issue, but not to get information about a larger issue list.

Snippet: Max number of IDs in a single CQL query when using the Content ID Selector

When using the Content ID Selector to choose pages to migrate, WikiTraccs groups those IDs into CQL queries to speed up page retrieval. Different Confluence instances seem to tolerate a different maximum number of IDs that are included in a single CQL query.

Choosing a number too high can lead to Confluence returning a Server Error, retrieving no pages at all.

Here’s the configuration snippet to set the number of IDs included in a single CQL query:

{
  "CustomSettings": {
    "WiggleRoom": {
      "PageRetrievalByContentIdsCqlPageSizeOverride": 200
    }
  }
}

Snippet: Change temporary storage folder pathes

Use those settings to control where WikiTraccs stores temporary files:

{
  "CustomSettings": {
    "AttachmentRegistryRootPath": "D:\\FileRegistry",
    "TempPath": "C:\\Users\\user\\AppData\\Local\\Temp\\",
  }
}

Explanation:

  • AttachmentRegistryRootPath
    • all attachments downloaded from Confluence will be stored here
    • those files aren’t removed automatically, you must delete them manually (this can also be done during the migration)
    • WikiTraccs does not currently use those files after having migrated them to SharePoint
    • when files are missing, WikiTraccs downloads them again from SharePoint
  • TempPath
    • certain caching-related files will be stored here
    • the Chrome browser profile for the automated Confluence login session will be stored here
    • temporary storage location for Confluence attachments, before they are moved to the AttachmentRegistryRootPath
    • temporary storage location for the downloaded page HTML (related to resolving hard links)

Snippet: Don’t promote migrated Confluence blog posts to SharePoint news

SharePoint allows promoting regular pages as news article. This will surface those pages in news-related web parts and might notify users.

WikiTraccs normally promotes migrated Confluence blogposts to SharePoint news.

Prevent that with the following configuration:

{
  "CustomSettings": {
    "Features": {
      "PromoteBlogposts": false
    }
  }
}

Snippet: Configuring multi-pass migrations

A configuration file to trigger both permission migration and principal update looks like this:

{
    "CustomSettings": {
        "SourceTenantIncludeList": [
            {
                "HumanReadableId": "Contoso Confluence",
                "TenantId": "https://www.contoso.com/confluence",
                "SpaceTransfer": {
                    "Operations": [
                        "checkprincipals"
                    ]
                },
                "PermissionTransfer": {
                    "Enabled": true
                }
            }
        ]
    }
}

Config File Templates for Debugging Purposes

WikiTraccs has some debug and feature toggles to be used when things don’t go as expected and need to be analyzed.

When debugging, put appsettings.json to the WikiTraccs.GUI folder or the WikiTraccs.Console folder, depending on which program you are running.

Snippet: Generic Debug Configuration Template

Here’s a template of appsettings.json to copy:

{
    "CustomSettings": {
        "Debug": {
            "ClearLocalCacheOnStart": true,
            "SaveTransformationInputToDisk": true,
            // assume the user is logged in when this element is present and enabled
            "ConfluenceAuthCssSelector": "#quick-create-page-button",
            // don't check that the Confluence context path and the path of the JSESSIONID cookie match
            "SkipConfluenceContextPathCookiePathMatching": false,
            "SkipPreparationResultCheck": false,
            // skip connection check when starting the migration from WikiTraccs.GUI (version > 0.1.4)
            "SkipConnectionCheckInWikiTraccsGui": false
        },
        "Features": {
            // force space inventory update when starting a migration
            "FillSpacesList": true,
            "TransformPageTreeMacro": true,
            "TransformRoadmapMacro": true
        }
    }
}

Snippet: “Clear Cache” Settings Template

This setting clears the cache on every start:

{
    "CustomSettings": {
        "Debug": {
            "ClearLocalCacheOnStart": true
        }
    }
}

Snippet: Don’t mark formerly merged table cells

For details on merged table cells see this blog post: How to migrate rich Confluence tables to limited SharePoint tables?

{
    "CustomSettings": {
      "Features": {
        "TableCellSpanLayoutMode": "UnmarkedAdditionalSlots"
      }
    }
}

4.7 - Migration Samples

Want to know how content transformed by WikiTraccs looks like? This page has lots of visual samples.

You’ll find pairs of images in the sections below. The first image shows a screenshot of a Confluence page. The second image shows how the content looks in SharePoint.

Formatting

Confluence Text Formatting

SharePoint Text Formatting

Confluence Headings and Paragraphs

SharePoint Headings and Paragraphs

Confluence Text Alignment and Indentation

SharePoint Text Alignment and Indentation

Confluence Things from the Plus Menu

SharePoint Things from the Plus Menu

Confluence Lists and Task Lists

SharePoint Lists and Task Lists

Layouts

Standard Layouts

WikiTraccs transforms the Confluence layouts to the matching SharePoint layouts.

Confluence Standard Layouts

SharePoint Standard Layouts

Here’s the edit mode of the two pages containing layouts:

Confluence Standard Layouts in Edit Mode

SharePoint Standard Layouts in Edit Mode

Notice how SharePoint only provides one three-column layout. WikiTraccs chooses this for both three-column Confluence layouts.

Sections and Columns

In Confluence users can create arbitrarily nested constructs of sections and columns. Even combinations that don’t make sense are sometimes allowed by Confluence or carried over by faulty migrations. WikiTraccs tries hard to make sense of what it finds.

WikiTraccs converts sections and columns to tables as there is no other equivalent in SharePoint.

Confluence Sections and Columns

SharePoint Sections and Columns

Note: It would be possible for WikiTraccs to convert the simplest section/column configurations to proper SharePoint sections: Issue Link.

Macros

Note: the following list is not complete. Have a look here for a complete overview: Known Confluence Macros

Confluence Info Warning Tip Note

SharePoint Info Warning Tip Note

Note: WikiTraccs won’t use cell background colors as those are not available in the SharePoint text web part (at least for the user). That’s why colored markers and emojis are used to indicate the type of note.

Confluence Code Macro

SharePoint Code Macro

Note: WikiTraccs transforms Confluence code block macros to SharePoint code web parts. But only its content and not the properties, so syntax highlighting will be off. There is an issue for that: Issue Link.

Confluence Panels

SharePoint Panels

Note: The formatting capabilities in SharePoint are very limited.

Confluence Status Macro

SharePoint Status Macro

Confluence Images

SharePoint Images

Note that a hyperlink has been configured for the first image. The user can click the image to navigate to the link. WikiTraccs migrates the link to SharePoint.

Also note that the Google logo on the Confluence page links to an external image. SharePoint does not allow linking to external images, due to security and privacy concerns. WikiTraccs downloads external images and then migrates them as page attachments.

Note: Inline images can sometimes mess up line breaks. WikiTraccs v0.2.0 took a great step in the direction of tackling those issues - check it out!

Links to Content outside a Page

Confluence Links to Pages and other Content

SharePoint Links to Pages and other Content

WikiTraccs changes regular Confluence page links so that they point to the new SharePoint page location.

WikiTraccs will also transform links to other spaces. To do this it needs to know which space maps to which SharePoint site - this is done via the Space Inventory list.

Furthermore, plain text links (“hard links”) are migrated as-is, unless they link to a Confluence page. WikiTraccs should be able to figure those out.

Page Attachments

Confluence Page Attachments

SharePoint Page Attachments

There is more information available in this blog post: New attachments macro transformation

Users and Groups

Confluence Mentions and Profiles

SharePoint Mentions and Profiles

In SharePoint, WikiTraccs creates “mention texts” like in Confluence. Those link to the SharePoint people search where the search field is pre-populated with the mentioned user’s email address.

People profile and image macros are converted to the “mention text” format as well.

Note: When migrating, WikiTraccs needs a certain permission level to access user’s email addresses.

Tables

In Confluence users can do a lot with tables. In SharePoint not so much. Have a look at the Nested macros and tables section in Features to learn more about that.

Confluence Simple Tables

SharePoint Simple Tables

Confluence Table Widths

SharePoint Table Widths

WikiTraccs normalizes Confluence tables and the result can be seen below. Tables are de-nested and merged cells are un-merged:

Confluence Advanced Tables

SharePoint Advanced Tables

Confluence Larger Tables

SharePoint Larger Tables

Note: Wide tables are usually a challenge for SharePoint because SharePoint pages are narrow compared to Confluence. SharePoint shows a scroll bar if the table is wider than the page.

4.8 - Monitoring Confluence to SharePoint Migration Progress - Overview

How to monitor the progress of migration from Confluence to SharePoint? This article explains how.

There are several places to get insights into the migration progress.

View per-page success metrics

To view migrated pages and to check the migration result per page, you go to the Site Pages library of each migration target site.

Learn more here about the metrics you find there for each page: Per-page progress.

View how many pages have been migrated per selector (e.g. per space)

To learn how many pages have already been migrated for a space - or any other selector - and how many pages are yet to be migrated, you look at the progress log files.

Learn more here: Per-selector progress.

General insights into warnings and errors

Warnings and errors that occurred during the migration are written to the common log files.

Filter those log files for messages marked with WRN and ERR.

Live progress indicators

When running a migration, there are certain numbers shown in the blue WikiTraccs.GUI window, in the black console window, and in the log file. Those numbers show how fast the migration is currently going.

Learn more here: Live Progress Indicators.

4.8.1 - Monitoring Per Page Progress

How to get page migration success metrics for each page.

The Site Pages library of every target space contains migrated pages and metadata.

Use the library view Recent Pages (WikiTraccs) to gain insights into the migration success for every single page. The SharePoint page’s metadata also includes the space key and content ID.

Read more about the different metrics here: Measuring page migration success.

4.8.2 - Monitoring Per Selector Progress

This article explains how to get higher-level insights into the migration progress, by looking at each selector and how many pages have been migrated, and how many are still missing.

Using progress log files to get insights

As of release v1.1.0 WikiTraccs provides information about the migration progress in different progress-related log files:

Log files containing information about the Confluence to SharePoint migration progress.

The information you can gather from these files is:

  • How many pages are scheduled to be migrated?
  • Which pages have already been migrated to SharePoint?
  • Which pages are yet to be migrated?
  • Which pages have been migrated but need an update?

See below for a quick rundown of the log files and their content.

The values in those files are separated by tabulator. So it’s nearly CSV, but with tab instead of comma. The file name contains a timestamp, the Confluence site ID as specified in the configuration, the space key, and the last part of the target SharePoint site URL.

Progress log file documentation

xxx__10-not-yet-migrated-pages.txt

This file contains information about Confluence pages that are yet to be migrated.

Sample content:

CASIG	78022359	CA2SIG - Meeting November 29	/display/CASIG/CA2SIG+-+Meeting+November+29
CASIG	78022377	2022-11-22 Standard WG	/display/CASIG/2022-11-22+Standard+WG
CASIG	80773916	2022 12 06 Standards WG	/display/CASIG/2022+12+06+Standards+WG

The tab-separated columns in this file are:

  • Confluence space key
  • Confluence page ID
  • Confluence page title
  • Confluence page URL
xxx__20-migrated-pages

This file contains information about migrated pages. It contains information about existing Confluence pages where a corresponding SharePoint page exists as well.

Sample content:

CASIG	24781062	Climate Action and Accounting SIG Home	/display/CASIG/Climate+Action+and+Accounting+SIG+Home	97652
CASIG	24781122	Meetings	/display/CASIG/Meetings	97653
CASIG	24781124	Member Directory	/display/CASIG/Member+Directory	97654

The tab-separated columns in this file are:

  • Confluence space key
  • Confluence page ID
  • Confluence page title
  • Confluence page URL
  • SharePoint page ID (in the Site Pages library)
xxx__25-update-state-of-migrated-pages

This file contains information about the freshness of migrated pages.

Sample content:

+++
SourceTenantId = "https://confluence.contoso.com/"
PageSelectorType = "ConfluenceSpace"
PageSelector = "CASIG"
CreationDateUtc = 2023-01-21T15:30:07.1691711
SchemaVersion = 2
+++
CASIG	Page	78022313	2022-11-21 Peer Programming Call	/display/CASIG/2022-11-21+Peer+Programming+Call	2022-11-30T22:17:28	2022-11-29T23:17:28 2022-11-29T23:17:28	needsupdate
CASIG	Page	78022335	CA2 SIG - Meeting November 15	/display/CASIG/CA2+SIG+-+Meeting+November+15	2022-11-24T06:52:40	2022-11-24T06:52:40 2022-11-29T23:17:28	uptodate
CASIG	Page	78022347	CA2 SIG - Meeting December 13	/display/CASIG/CA2+SIG+-+Meeting+December+13	2022-12-14T01:46:57	2022-12-14T01:46:57 2022-11-29T23:17:28	uptodate

The file contains a header that is enclosed with +++.

Following the header, the list of page update states starts.

The tab-separated columns are:

  • Confluence space key
  • Confluence content type: Page or Blogpost
  • Confluence page ID
  • Confluence page title
  • Confluence page URL
  • Modification date of the Confluence page
  • Stored modification date of the migrated page in SharePoint (this is the Confluence page modification date at the time of migration)
  • Modification date of the SharePoint page (note: added in release v1.12.24)
  • State of the SharePoint page
    • uptodate: this page is up to date
    • needsupdate: this page has been updated in Confluence since its migration
    • cannotdetermine: metadata in SharePoint is missing, cannot determine if update is needed

Note: WikiTraccs will output additional state values in a verification run.

xxx__30-aggregated-info

This file contains information that could be gathered from the other files, but already aggregated:

Sample content:

Source Confluence Site: https://wiki.hyperledger.org
Target SharePoint Site: https://contoso.sharepoint.com/sites/migration-target
Space Key: CASIG
Blog posts included in migration and calculation: no
Confluence page count for space space CASIG: 292
Migrated SharePoint pages that correspond to found Confluence pages in space CASIG: 259
Migrated SharePoint pages overall for space CASIG: 259
Pages yet to be migrated for space CASIG: 33

If Migrated SharePoint pages overall for space is larger than Migrated SharePoint pages that correspond to found Confluence pages in space then pages turned inaccessible in Confluence (deleted? permission denied?) but the once-migrated pages in SharePoint still exist.

Progress log file cadence

WikiTraccs creates progress log files at specific times:

  • when starting a migration - log files for each scheduled space will be created
  • when stopping a running migration by pressing Ctrl+C in the console window of WikiTraccs.Console - log files for each space handled so far will be created
  • when the migration is done - log files for each space handled so far will be created

This means that multiple progress log files per space will be created. Look at the ones with the most recent timestamp to see the latest progress information.

You can delete or archive old progress log files. Every new migration run will create new files.

Troubleshooting missing pages

Have a look at the troubleshooting recipe: Find out why some pages won’t migrate.

4.8.3 - Live Progress Indicators

How to interpret live progress indicators shown by WikiTraccs.

Live metrics in the blue WikiTraccs.GUI window

Note: those metrics are available as of WikiTraccs 1.22.1

After migrating a couple of pages, WikiTraccs shows speed metrics:

The meaning is the following:

  • 5-7 s/item: the page migration time in the last n minutes was 5 to 7 seconds per page
  • 514-720 /h: the estimated number of pages that will be migrated in the next hour
  • ETA 11/12 22:20 ~ 11/12 22:27 the estimated finish time

For each of the above, the lower number is based on median page migration times. The higher number is based on the 75th percentile. WikiTraccs removes outliers by disregarding very fast and very slow pages, using the interquartile range algorithm. Values are calculated over a period of 60 minutes.

With each migrated page the values will be updated.

Those values will change over the course of the migration. If migration starts with pages that have no attachments, you might see great migration times of maybe 5 seconds per page. But if suddenly pages start to have dozens of attachments, each a couple of megabytes in size, times will go up.

Black console window and log files

Looking at the black console window you’ll get more numbers than in the blue WikiTraccs.GUI window.

You can see those numbers in the common log files as well, as everything shown in the console window is stored there as well.

Live metrics calculated after each migrated page

Note: those metrics are available as of WikiTraccs 1.22.1

Note: as WikiTraccs evolves, the available metrics and wording will change and evolve as well.

WikiTraccs measures the time it spends on different migration-related activities. Different metrics are calculated from thsoe times.

Those metrics are supposed to roughly show how fast the migration is going over a period of time, as well as some additional insights. This can predict future migration times, but only if pages are similar with respect to certain metrics.

Here’s a sample:

[023 21:32:46 DBG MIG  ] [https://contoso.atlassian.net/wiki] Metrics FROM THE LAST 60 MINUTES, covering 21 page-like contents ("items"):
Median time (IQR)    : 23 s/item
Median time          : 55 s/item
75th percentile (IQR): 87 s/item
75th percentile      : 132 s/item
Items per hour       : 41-156 (based on IQR Median and IQR 75th percentile)
Avg links transformed: 2/item
Have files           : 59% of items
File count avg       : 23.9 per item that has files
File size avg        : 502 KB/file
Download speed       : ~451 KB/s
Upload speed         : ~91 KB/s
File size sum down   : 305.8 MB
File size sum up     : 1911.6 MB
Estimated time left for the remaining 322 items: 2.1-7.8 hours (ETA: 12/11/2024 23:36 - 12/12/2024 05:19) (based on IQR Median and 75th percentile)
[023 21:32:46 DBG MIG  ] [https://contoso.atlassian.net/wiki] Time spent in the last 60 minutes (excerpt, overlapping, excluding outliers):
(SharePoint, File, Content)                                 : 11.58 min
(Confluence, File, Content)                                 : 3.19 min
(SharePoint, Page, Content)                                 : 2.03 min
(Confluence, Page, Transformation_Macro_Other)              : 1.57 min
(Confluence, Page, Link_Soft)                               : 0.97 min
(SharePoint, WikiTraccs, Prerequisites)                     : 0.67 min
(SharePoint, Page, Principal)                               : 0.55 min
(Confluence, Page, Principal)                               : 0.47 min
(SharePoint, Page, Metadata)                                : 0.47 min
(SharePoint, File, Metadata)                                : 0.28 min
(SharePoint, Workspace, Metadata)                           : 0.26 min
(Confluence, Page, Transformation_UserMention)              : 0.26 min
(SharePoint, Page, Stub)                                    : 0.25 min
(SharePoint, Page, Configuration)                           : 0.23 min
(Confluence, Page, Link_Hard)                               : 0.21 min
(Confluence, Page, Comments)                                : 0.20 min
(SharePoint, File, Principal)                               : 0.17 min
(Confluence, Page, Permission)                              : 0.14 min
(Confluence, Page, Content)                                 : 0.13 min
(Confluence, Page, Tree)                                    : 0.09 min

Details about above values:

MetricMeaning
Median timeMedian migration time per page
Median time (IQR)Median migration time per page, after removing outliers
75th percentile75th percentile of page migration times
75th percentile (IQR)75th percentile of page migration times, after removing outliers
Items per hourPages migrated per hour, based on IQR Median and IQR 75th percentile
Avg links transformedThe average number of links on those pages; links increase migration times
Have filesThe percentage of pages that have attachments or link to external images
File count avgThe average number of files that were uploaded per page (of the pages that have any files)
File size avgThe average file size
Download speedAverage download speed for downloaded files
Upload speedAverage upload speed when uploading files to SharePoint Online; this also includes several metadata operations, so it will be lower that the ‘raw’ file content upload speed would be
File size sum downAn indicator of downloaded file content; this is not exhaustive and accuracy will be improved in a future release
File size sum upAn indicator of uploaded file content; this is not exhaustive and accuracy will be improved in a future release

Following those metrics is a list of transformation operations that WikiTraccs spent time on. This is a rough indicator of how much time each operation takes.

Most time will probably be spent on (SharePoint, File, Content), which includes file upload to SharePoint, (Confluence, File, Content), which includes attachment download from Confluence, and (SharePoint, Page, Content), which includes SharePoint page creation.

Those values can and will overlap, so their sum will be higher than the actual time spent. For example uploading page content and resolving links can happen in parallel.

Live progress for large attachment lists

If WikiTraccs migrates a page with lots of attachments (“lots” being ~50 and more), you will see intermittend progress output like this:

Applied provisioning chunk 3/4; handled 41/53 of files; that's 46.6 files per minute and 0.3 minutes to go

This shows the number of already uploaded files (41 of 53), how many files per minute have been uploaded (46.6), and - based on those numbers - an estimated finish time (in 0.3 minutes).

4.9 - Known Confluence Macros

This article is a resource where you can find information about known Confluence macros.

How WikiTraccs handles Confluence macros

WikiTraccs contains transformation rules for a range of Confluence macros. They are transformed on the fly and ideally the macro is replaced by something native to the SharePoint world.

If there is no SharePoint way of replacing a Confluence macro then WikiTraccs tries to find an approximation. But often there is just no equivalent for a Confluence macro. In those cases a text placeholder will be used to mark the spot where the macro has been in Confluence.

List of known macros

The following table shows macros that are explicitly known to WikiTraccs and how they are handled.

MacroSupport LevelMacro Transformation Details
Status💚The macro will be transformed to text with a color that tries to match the original (not so many choices here in SharePoint…).
Noformat💚The “no formatting” content formatting will be mirrored in the SharePoint page.
Code Block💚/🟡Code macros are transformed to SharePoint code web parts which provide comparable functionality. But if the code macro in Confluence is part of a table or any other nested structure then there is no 1:1 representation in SharePoint. The web part in this case will be replaced by a placeholder and the web part inserted at a top level place in the SharePoint page.
SharePoint Online Document (by Communardo)🟡The macro will be replaced by a link to the SharePoint document.
SharePoint Online List (by Communardo)🟡The macro will be replaced by a link to the SharePoint site containing the list; the link text contains the SharePoint list ID.
Profile Picture🟡The profile picture will be transformed like user @-mentions in the page (see section below for details).
User Profile🟡The user profile card will be transformed like user @-mentions in the page (see section below for details).
Enhanced Profile (by Communardo)🟡The user profile card will be transformed like user @-mentions in the page (see section below for details).
Jira Issue Link🟡The Jira macro will be replaced by a link to the Jira issue.
Jira Issue List🟡The Jira issue list will be converted to a static table showing links to Jira issues. If the table had multiple pages, a snapshot of only the first page is migrated to SharePoint. So, for a query that covers 1000 issues only the first 20 or so will be shown. A link to Jira is added to the SharePoint page so you can jump to Jira to see the live issue list.
Spreadsheet (by Elements)🟡The spreadsheet macro will be replaced by a link to the file attachment.
View File🟡The file card will be replaced by a link to the file attachment of the SharePoint page.
Office Powerpoint🟡The file card will be replaced by a link to the file attachment of the SharePoint page.
Office Word🟡The file card will be replaced by a link to the file attachment of the SharePoint page.
Office Excel🟡The file card will be replaced by a link to the file attachment of the SharePoint page.
Microsoft Stream Video🟡The file card will be replaced by a link to the video.
Panel, Info, Note, Warning, Tip🟡The macro will be replaced by a table rebuiding the macros’s structure as far as possible; this can introduce nested tables which will be a challenge for page layout (see section below for details on nested tables).
Expand🟡The expand functionality will be lost and the content remains expanded in the SharePoint page.
Gliffy🟡The Gliffy diagram will be replaced by an image of the diagram (that should be present in Confluence as page attachment); if there is no image a placeholder text will be used instead.
draw.io (by //Seibert/Media)🟡The draw.io diagram will be replaced by an image of the diagram (that should be present in Confluence as page attachment); if there is no image a placeholder text will be used instead.
Widget Connector🟡The macro will be replaced by a link to the content it links to (for example a YouTube video), if there is such a link.
HTML🟡The HTML content from the macro will be transformed to a code web part in SharePoint; so the HTML is transformed to code and especially JavaScript will not be executed in the SharePoint page.
Tabs Container, Tabs Page (by Adaptavist)🟡This macro displays multiple tabs which is a challenge because SharePoint has no tabs. So the tabs are each one transformed to “normal” page content and all tabs are added one after another to the page.
Attachments🟡Note that the actual attachments of Confluence pages are always migrated to SharePoint. The Page Attachments macro is migrated as a static view of the macro at the time of migration. So the SharePoint page will show a static table with attachment links and some metadata.
Brikit Theme Press🟡The Brikit Theme Press is recognized by WikiTraccs. Brikit Theme Press layers will be converted to modern SharePoint page sections. Each SharePoint page section will have a number of columns that corresponds to the number of columns in the Brikit Theme Press layer. SharePoint can only have a maximum of three columns in a section, so WikiTraccs will create additional sections if there are more columns in the Brikit Theme Press layer. The content from Brikit Theme Press blocks will be added to the corresponding SharePoint section columns. Note: available as of WikiTraccs v1.16.0.
Page Tree🟡The Page Tree macro is migrated as a static view of the macro at the time of migration. The SharePoint page will show a static tree of page links.
Table of Contents🟡The Table of Contents macro is migrated as a static view of the macro at the time of migration. The SharePoint page will show a static tree of page links.
MultiExcerpt (by Appfire)⏹
Table Filter (by StiltSoft)⏹️Filter functionality is lost, the table remains.
Excerpt⏹️
Single Cite (by Purde Software)⏹️The macro will be replaced by the citation content.
Table Chart⏹️The chart will be replaced by a table of the underlying data.
No Print⏹️The no-print functionality will be lost, the content remains.
Livesearch🔻
Anchor🔻The anchor link will be removed, its text or content remains.
Content by Label🔻
Excerpt Include🔻
Metadata News (by Communardo)🔻
Metadata (by Communardo)🔻
Recently Updated🔻
Profile List (by Communardo)🔻
Include Page🔻
Team Calendar🔻
Jira Chart🔻
Task Report🔻
Content Report Table🔻
Create from Template🔻
Page Properties🔻
Page Properties Report🔻
Roadmap🔻
Page Tree Search🔻
Children Display🔻
Search Results🔻
Create Page🔻
Cite Summary (by Purde Software)🔻
Blog Posts🔻
Display Metadata (by Communardo)🔻
Metadata Overview (by Communardo)🔻
Metadata History (by Communardo)🔻
Content by Metadata (by Communardo)🔻
Other macros🔻/⏹️The macro will be replaced, either by a text placeholder or its body content.

Transformation types:

  • 💚 “nearly 1:1” - there is a SharePoint or HTML equivalent allowing to rebuild the functionality in SharePoint
  • 🟡 “changes in layout or functionality” - transformation with changes to layout or functionality; this is a transformation that is more than just a generic placeholder, but it does not fully meet the original macro functionality
  • ⏹️ “to macro body” - this works for macros that contain “richt text content” which is just normal wiki page content; this transformation type will replace the macro by its rich text content, thus kind of “unboxing” it
  • 🔻 “to placeholder” - transforms to a non-functional placeholder text, showing the macro’s parameters

All macros not explicitly mentioned here are transformed to placeholders, so are either ⏹️ or 🔻. When macros contain rich content then the macro is replaced by its rich content.

4.9.1 - Macro Placeholders and Transformation Templates

This article describes how macro placeholders work and how you can modify them with transformation templates.

Note: Macro transformation templates are available as of WikiTraccs v1.20.6.

What are macro placeholders?

They are text replacements for macros.

When migrating wiki pages from Confluence to SharePoint, WikiTraccs has to transform macros to something that SharePoint understands.

If there is no equivalent to a macro in SharePoint (which is the regular case), WikiTraccs often applies a generic transformation that replaces the macro in SharePoint with a text placeholder.

This generic macro transformation is applied to all macros that are not covered by an explicit transformation rule built-in to WikiTraccs.

How does a placeholder look?

Let’s take the div macro as example. It is part of Adaptavist’s Content Formatting Macros offering.

How does the div macro look before and after having been migrated to SharePoint?

The div macro allows to apply formatting to Confluence page content, like setting the text color.

The following configuration applies a blue text color to the macro content when the macro is shown on the Confluence page:

Macro in edit mode, applying the 'color:blue' CSS style to its content, plus some other things.

Macro in view mode, displaying blue text in the Confluence page.

When migrating this macro to SharePoint, WikiTraccs discards the macro container, pulls its content out, and puts that on the page. A text placeholder highlights that this happened:

So, the result of this transformation is:

  • all content of the div macro has been migrated
  • formatting is gone with the macro container
  • a text placeholder highlights that a former div macro has been removed, but the content retained

Now, sometimes you want to get rid of that 🚧 placeholder text. You can create a custom placeholder to do that.

How to create a custom placeholder?

WikiTraccs allows to apply custom text placeholders in generic macro transformations, using transformation templates.

You can use Handlebars templates to describe how the placeholder for a macro should look. Handlebars is a templating system commonly used in web development.

Let’s say we want to remove the placeholder text for the transformed div macro, just migrating its content.

The Handlebars template to do that looks like this:

{{!-- Don't add placeholder text, just render body --}}
{{Body}}

Some facts about above template:

  • {{Body}} is a variable, referencing the macro body; this tells WikiTraccs to just render the macro body, without additional placeholder text
  • {{!-- --}} marks a comment in the template; this is ignored by WikiTraccs

Using above transformation template, the transformed macro looks like this in SharePoint:

The 🚧 note is now gone.

Where to put the transformation template?

Custom transformation templates are stored as files in a folder.

When using WikiTraccs.GUI (the blue window), find WikiTraccs.GUI.exe and starting there, find the Templates\Transformation folder. Save your template file there.

When solely using WikiTraccs.Console, find WikiTraccs.Console.exe and starting there, find the Templates\Transformation folder. Save your template file there.

The Transformation folder alreads contains files and should look like this (note that this can change in future WikiTraccs releases):

Each of those .hbs files contains a transformation template.

The transformation templates can apply to either

  • a single macro type (like div, or rw-ui-tabs-macro), OR
  • multiple macro types (like english,belarusian,bulgarian,canadian-en,…)

Transforming a single macro type

When you want to transform a single macro type (like div), you save the transformation template in a file that carries the internal macro name in its filename and has the .hbs extension.

The file containing the transformation template for the div macro would thus be named div.hbs.

To reiterate, the steps to create a transformation template for a single macro type are:

  1. identify the internal macro name
    • you can see macro names in the storage format XML
    • note: for our div macro we see ac:name="div" in the storage format XML
  2. create a Handlebars template that describes how the custom placeholder should look
  3. save the Handlebars template in a file, in the Templates\Transformation folder
    • the filename follows the pattern MACRONAME.hbl where MACRONAME is the name of the macro
    • the file extension must be .hbl for WikiTraccs to recognize the file

Transforming multiple macro types

You can also put a special comment as first line into your .hbl file to apply the template to multiple macros, saving you the hassle to create identical files for each of those types.

Here is an example:

{{!-- applyto:english-us,english,belarusian,bulgarian,canadian-en,canadian-fr,catalan,chinese,croatian,czech,danish,dutch,estonian,finnish,french,german,greek,hindi,hungarian,icelandic,indonesian,irish,italian,japanese,korean,latvian,lithuanian,malay,maltese,norwegian-nb,norwegian,polish,portuguese,portuguese-br,romanian,russian,serbian,slovak,slovenian,spanish,swedish,thai,turkish,ukrainian,vietnamese --}}

This tells WikiTraccs to use the template for all the macros listed after the applyto: marker (internal macro names, separated by comma).

The filename doesn’t matter, as long as it has the .hbs ending.

Which variables are available in templates?

The following variables are available in transformation templates:

VariableData TypeMeaning
Bodyn/athe macro body (if the macro has one)
HasBodybooleantrue, if the macro has a body; false otherwise
HasNoBodybooleantrue, if the macro has no body; false otherwise
Details.DisplayNametextmacro display name
TypeAsStringtext‘macro’ for macros, ‘ADF extension’ for ADF extensions, ‘unknown embedding’ otherwise
IsMacrobooleantrue, if the macro is a macro
IsAdfExtensionbooleantrue, if the ‘macro’ is an ADF extension (so, not really a macro, but covered by macro transformation nevertheless)
HasParametersbooleantrue, if the macro has parameters; false otherwise
ParameterCountnumberthe number of macro parameters
Parameterscollectionmacro parameters, if the macro has any; each parameter has a Name and Value property; there is also a Links property that is populated with links parsed from the parameters

WikiTraccs brings some transformation template files along. In the Templates/Transformation folder, have a look at the unknown.hbs.sample file for an advanced usage example, or any of the other files.

Troubleshooting

If your template is not recognized check for the following issues:

  • the template file is in the wrong folder
  • the template file doesn’t have the .hbl file ending
  • the filename doesn’t have the right pattern
  • the macro is already handled by a built-in transformation rule and thus no generic placeholder is being generated (note: there is nothing you can do about that; please get in touch and give feedback)
  • the template is malformed

Check the console log output or common log files to see if WikiTraccs loads your template.

This is how the log looks if a template could be successfully loaded:

Found 3 transformation template files in folder '<path>/Templates/Transformation', will handle one by one: ch.bitvoodoo.confluence.plugins.language.hbs div.hbs rw-ui-tabs-macro.hbs
Trying to load transformation template from file 'Templates/Transformation/div.hbs'
Compiling and registering transformation template for 'div'

Any issues should be visible here as well. You can also look at the logs to learn about the path WikiTraccs loads templates from, if you are unsure where to put them.

4.10 - Security

This section covers security-related topics.

Architectural Overview of WikiTraccs

The following image shows which building blocks are at play when running a WikiTraccs migration.

The building block explained:

Building blockPurpose
Client’s computerA computer running WikiTraccs. Uses Windows as operating system. You control this computer.
WikiTraccs console applications (GUI, Console)WikiTraccs consists of two .NET-based console applications: WikiTraccs.GUI.exe and WikiTraccs.Console.exe. WikiTraccs is portable, no installation is necessary.
ConfluenceThe source Confluence environment that should be migrated to SharePoint. You decide whether this environment is being connected to via HTTP or HTTPS by using the respective URL scheme (http://, https://) in the source address configuration of WikiTraccs.
Confluence migration accountThe account used to log in to Confluence. WikiTraccs uses the session of this account and therefor has access to everything this account has access to.
SharePoint, MS GraphThe Microsoft 365 target environment that will be migrated to. All connections are HTTPS and TLS-secured. For the state of TLS in Microsoft 365 have a look at Preparing for TLS 1.2 in Office 365 and Office 365 GCC.
SharePoint migration accountThe account used to log in to SharePoint. The permission that WikiTraccs has is the intersection of this user’s permission and the permissions configured for the Entra ID app registration.
Azure AD App Registration for WikiTraccsEntra ID app registration that allows WikiTraccs to work with Microsoft services on an API level. See Registering WikiTraccs as app in Entra ID for details.
Locally stored filesWikiTraccs stores files locally on the system it runs. Those files comprise: attachments downloaded from Confluence, log files, caches, WikiTraccs.GUI configuration, debugging-related files (if certain debug settings are turned on)
Client’s migration teamThis is your migration team.
WikiTraccs supportSupport channels, mainly GitHub, email, and Microsoft Teams. Support might ask for log files to diagnose issues. You decide if you want to provide those log files.
Other servicesOther services being used are documented below, and their respective endpoints in the Endpoint reference.

Other services

Google Chrome WebDriver Download

WikiTraccs launches and controls an automated Chrome browser for the Confluence migration user to log in, and to get the session cookies.

This automation requires the Google Chrome WebDriver to be downloaded and run. This is an application provided by Google and needs to match the Chrome version running on the migration machine. So after every Chrome update on the migration machine a matching Chrome driver will be automatically downloaded by WikiTraccs.

The endpoints used to get the WebDriver are listed in the Endpoint reference.

Further Information

4.10.1 - Data Storage and Transmission

This article is a resource where you can find information about stored data and data transmission.

This article covers one of the major concerns with any migration tool: handling of data.

WikiTraccs handles data securely.

Big Picture

WikiTraccs is a console application that connects to both Confluence and SharePoint Online during the Confluence to SharePoint migration.

It downloads content like pages and attachments from Confluence to a local directory. It processes this locally stored data and uploads it to SharePoint Online.

Where does WikiTracc run? Is it a cloud service?

WikiTraccs is not a cloud service. WikiTraccs is a .NET-based console application that runs on a Windows workstation of your choosing.

The workstation WikiTraccs runs on can be any machine: your VPN-connected laptop at home, an on-premises server, a cloud VM - as long as it can connect to and authenticate with both Confluence and SharePoint Online it will work.

And because this question sometimes comes up: No, WikiTraccs does not need to run on the Confluence server.

Where does WikiTraccs store data? Is data being sent somewhere?

WikiTraccs stores data locally on the workstation it is running on.

This locally stored data includes:

  • page contents
  • attachments
  • log files
  • cached data and temporary files

There is no cloud storage involved, apart from SharePoint Online as migration target. Other migration tools use Azure or third-party storage solutions as temporary storage location before data is being moved to SharePoint Online. WikiTraccs does not do that. It directly uploads to SharePoint.

The data never leaves the workstation, except for SharePoint Online, which is the target of the migration.

This article has details on where WikiTraccs stores data on the migration machine: File Storage.

What level of encryption is used for data at rest?

Data at rest in the context of WikiTraccs is content stored on the workstation that is used to perform the migration and to run WikiTraccs. This data is not encrypted and can potentially be accessed by users of this workstation, depending on file system access permissions.

How is data transmission secured?

Connections use TLS version 1.2. For Confluence, some clients run their instance disconnected from the internet and connect via HTTP from their internal network, which WikiTraccs allows.

WikiTraccs uses the Confluence REST API as well as the SharePoint Online API and Microsoft Graph, when it comes to transmitting migrated content.

A complete list of endpoints used by WikiTraccs is shown in the Endpoint Reference.

Can WikiTraccs access all my data?

No, WikiTraccs can only access data you choose to let it have access to.

The access level of WikiTraccs depends on the migration accounts you choose for Confluence and SharePoint.

When starting a migration, you will authenticate with one user account in Confluence, with another user account in SharePoint. Since WikiTraccs accesses data in the context of those user sessions, it can only see what those accounts can see.

Example for Confluence: when starting the migration, you log in with an account that can only see pages from one space. WikiTraccs will only be able to migrate this one space since it cannot access other spaces.

Example for SharePoint: when starting the migration, you log in with an account that is site admin for all migration target sites, but doesn’t have access to other sites in the SharePoint tenant. WikiTraccs now also will only be able to access the migration target sites. Nothing else.

Can Wiki Transformation Project or Heinrich access my data?

No, unless you actively send it to me.

Where can I get an architectural overview, like, a diagram?

Please have a look at the Security article, which dives deeper.

4.10.2 - Endpoint reference

This article is a resource where you can find endpoint information for WikiTraccs.

Required endpoints

The following table lists the required endpoints for using WikiTraccs.

Microsoft 365

Required EndpointPurpose
login.microsoftonline.comAuthentication with Microsoft
aadcdn.msftauth.netAuthentication with Microsoft
login.live.comAuthentication with Microsoft
*.sharepoint.comAccess to store pages migrated from Confluence to SharePoint

Atlassian Confluence REST

WikiTraccs uses the REST endpoints of Confluence.

The REST endpoints are expected under the following URL:

  • <confluencebaseurl>/rest/api/ (on-prem & cloud)
  • <confluencebaseurl>/api/v2 (cloud)

Automatic Chrome WebDriver download

The Chrome WebDriver is used by WikiTraccs to show a browser window for Confluence authentication.

Required EndpointPurposeOwner info
chromedriver.chromium.orgChrome WebDriver version detectionWhois registrant: Google LLC (CA, US)
chromedriver.storage.googleapis.comChrome WebDriver downloadWhois registrant: Google LLC (CA, US)
googlechromelabs.github.io/chrome-for-testing/latest-patch-versions-per-build-with-downloads.jsonChrome WebDriver version information for Chrome starting with version 115Github-Repository owner: Google Chrome team
edgedl.me.gvt1.comHost for Chrome WebDriver downloadsWhois registrant: Google LLC (CA, US)
storage.googleapis.comHost for Chrome WebDriver downloadsWhois registrant: Google LLC (CA, US)

Refer to the troubleshooting section for handling blocked connections to those endpoints.

Optional endpoints

Atlassian Confluence XML-RPC

WikiTraccs uses the REST endpoints of Confluence with one exception.

There is one endpoint of the old XML-RPC API that is being used to read space permissions, since those are not available via the REST API. This endpoint is expected under the following URL:

  • <confluencebaseurl>/rpc/xmlrpc/

Space permissions are currently retrieved by WikiTraccs but not processed during the migration. It currently is no problem when this endpoint is not available, but data about space permissions might be missing when a future release of WikiTraccs starts working with them.

4.11 - Using WikiTraccs.GUI

This section helps with using WikiTraccs.GUI, the user interface for WikiTraccs.Console.

4.11.1 - Source Configuration

Configuring the Confluence source of the migration.

Confluence Base Address

Enter the Confluence base URL into the Confluence base address field.

Source configuration

Note that the base URL might differ from the one the end user sees in the browser address bar.

How to manually check that the base URL is correct?

You can check that the base URL is correct by appending /rest/api/user/current and opening the resulting URL in the browser.

Example: Log in to Confluence. Then, assuming the base URL is https://contoso.com/wiki, open https://contoso.com/wiki/rest/api/user/current in the browser. It should show you information about your current user.

Confluence Authentication Type

Choose Anonymous if Confluence is accessible without a logged in user.

Choose Interactive Login to log in interactively. When starting the migration, WikiTraccs will open Confluence in a browser where you can log in. Then, WikiTraccs takes the session cookies from this browser session and uses them when accessing Confluence. To Confluence this looks like the user that was used to log in is accessing the content.

Advanced Settings

Choose the Advanced button to open the advanced settings dialog.

In the Additional cookie names input, enter the names of additional cookies WikiTraccs should use to authenticate with Confluence. Separate multiple names by semicolon ;.

WikiTraccs checks the presence of those cookies when testing the Confluence connection. The test fails if those cookies cannot be found.

4.12 - Authentication

This article is a resource where you can find authentication information for WikiTraccs.

4.12.1 - Authenticating with Confluence

This article is a resource where you learn about authenticating with Confluence.

The following authentication methods are currently supported:

  • cookie-based authentication
  • personal access token authentication (Confluence 7.9 and later)

With this authentication method WikiTraccs uses the context of a logged-in user account.

To authenticate with Confluence WikiTraccs will open a Chrome browser window.

Log in to Confluence like you normally would. WikiTraccs will use the cookies from the authenticted browser session to access Confluence.

The following diagram shows how WikiTraccs uses cookies to make authenticated calls to Confluence:

Experimental alternative to obtain cookies (compatible with Kerberos)

When WikiTraccs is unable to make authenticated calls to Confluence and all troubleshooting fails, you might try an experimental option introduced in release 1.10.16.

This changes the flow like this:

All requests to Confluence are routed through the browser, in the context of the authenticated user session.

This mode can be activated in WikiTraccs.GUI via Settings > Misc > Proxy Confluence API calls through browser.

Personal Access Token

Note: this option is available as of WikiTraccs v1.13 and works with Confluence 7.9 and later.

Refer to Atlassian’s documentation on how to create a personal access token: Using Personal Access Tokens.

Required permissions in Confluence

The permissions of the Confluence account you log in with determine what can be migrated.

The easiest approach is to log in with a Confluence admin account that has access to all spaces that should be migrated. This allows for content and permission migration.

But maybe you don’t want to use a Confluence admin account. In this case you can also use an account that is space admin in all to-be-migrated spaces. This allows for content and permission migration of those spaces.

The least permissive approach is to use an account that is no admin whatsoever but has normal user permissions like view and edit. This allows for migration of content this account has access to, which might not be all pages. Permission migration is not possible with a non-admin user account.

Certain operations like retrieving user account information or group memberships might be prohibited for non-admin users which might hinder WikiTraccs. If you see such errors in the log try using an account that has more permissions.

4.12.2 - Authenticating with SharePoint Online

This article is a resource where you learn about authenticating with SharePoint Online.

The following authentication methods are currently supported by WikiTraccs:

  • interactive authentication (supports MFA)
  • device-code authentication (supports MFA)
  • client credentials authentication (no MFA support)

Each of those authentication methods requires an Entra ID application to exist in Entra ID. WikiTraccs has to know the ID (“client ID”) of this application.

Prerequisites

When “authenticating with SharePoint Online” you are in fact authenticating with an Entra ID application that must be configured to authorize the access to SharePoint Online. Such an Entra ID application has to either exist or you have to register a new one.

You might have to register a new Entra ID application for use with WikiTraccs. This can be done manually in the Azure Portal or via PnP PowerShell. A sample on how to do this via PnP PowerShell is shown here: Register your own Entra ID App.

The following permissions must be configured for the Entra ID application:

  • delegated permissions in Microsoft Graph: Sites.FullControl.All (note: requires admin consent)
  • delegated permissions in SharePoint: AllSites.FullControl (note: requires admin consent)

What if FullControl cannot be granted? There is a plan B but with less features.

The following permissions will allow migrations as well:

  • delegated permissions in Microsoft Graph: Sites.Manage.All (note: no admin consent required)
  • delegated permissions in SharePoint: AllSites.Manage (note: no admin consent required)

Without full control permissions WikiTraccs will be limited in what it can migrate:

  • page permissions cannot be configured, as WikiTraccs won’t be allowed to do so
  • out-of-the-box SharePoint page and file metadata Created By, Created (Date), Modified By, Modified (Date) cannot be set, as this requires the same permissions as configuring permissions

Ultimately - regardless of the Entra ID application you choose to use - WikiTraccs needs to know the ID of this application and the application has to permit a certain amount of access to the target sites where WikiTraccs will migrate Confluence content to.

Interactive authentication

Interactive authentication allows to sign-in with a user that will be used to access SharePoint Online. Use a user account that has Owner permissions on the target SharePoint site.

With interactive authentication multi-factor authentication (MFA) is fully supported.

Choose Interactive as Target: Authentication type.

Enter the Entra ID application ID into the Azure AD Application Client ID input field. (Note: This ID looks like “31359c7f-bd7e-475c-86db-fdb8c937548e”.) The user must be granted access to the Entra ID application that is used to authenticate with.

Also fill the Target SharePoint Site Address and Target Tenant ID fields.

Select the Test SharePoint connection to test connecting. A dialog window will appear to display the result of this test.

Device code authentication

Available.

Client credentials authentication

Available, but often not feasible due to MFA or CA requirements.

4.13 - Confluence Inventory

How to get information about your source Confluence environment.

Getting information about your source Confluence environment helps estimating migration efforts and durations.

The FAQ item How much time does it take to migrate? has some information about the relationship between content and the time it takes to migrate.

This documentation does not aim to be an exhaustive inventory guide for Confluence. This is not the scope of WikiTraccs. There is software and experienced third parties out there that can cover this part of your migration.

Nevertheless, this section shall serve as a collection of resources that proved valuable in the past. It is likely to grow as time passes.

Have a look at the child pages for more information.

4.13.1 - Getting the Confluence page count

How to determine the number of pages in the source Confluence?

The number of pages directly correlates with migration effort and times. This is why it’s a must to determine the number of pages in Confluence in one of the early phases of your Confluence to SharePoint migration project.

There are different approaches to getting the Confluence page count, described in the following sections.

Getting the page count from the database via SQL

Pro:

  • returns a guaranteed accurate page count

Contra:

  • needs permission to run SQL queries on the Confluence database
  • only works with Confluence Server and Confluence Data Center (not Confluence Cloud)

Connect to the Confluence database and run the following SQL query:

select count(*) from content where (contenttype='PAGE' or contenttype='BLOGPOST') and prevver is null and content_status='current';

Note: Depending on the type of database the SQL query syntax might vary.

Atlassian also has some useful snippets here: How to find the number of pages, blogposts, and attachments.

Getting the page count in Confluence Cloud

Via Space Report

Go to Confluence Cloud administration. In the left menu, click the Space Reports option. Create a report and download it.

Create a space report at '/wiki/admin/space-reports'.

Those reports include a list of all spaces and the content count per space.

Sum up all those content counts for all spaces and you’ve got the overall “page count”.

Here’s an example of calculating the overall count (57170) in Excel:

This number is what determines the Page Count Tier for the WikiTraccs license.

Via Analytics

In Confluence Cloud, you can use the Analytics features to get insights into the number of pages. See the discussion here: Page Count?

Getting the page count from the REST API

Getting the page count from the REST API depends on too many factors like permissions, page restrictions and endpoints used. It is thus error-prone and not recommended.

Third-party solutions

Let me know which third-party solutions you’d recommend: Get in touch.

4.14 - Updating Previously Migrated Pages

This article explains how to update older migrated pages where the original Confluence pages have since been changed

Starting with release v1.7.0 WikiTraccs supports updating migrated pages.

Why update older migrated pages?

Updating older pages is relevant when pages migrated from Confluence to SharePoint are not protected from changes in Confluence, during or after the migration.

When users edit a page in Confluence, but that page already has been migrated to SharePoint, the SharePoint page will be outdated. It does not reflect the current state of the Confluence page anymore.

That’s where the update mode comes in, sometimes also called delta migration.

How to detect pages that have been changed since the last migration?

First, you start a migration to learn about the update state of already migrated pages.

Every time a migration starts, WikiTraccs will check if the SharePoint target site already contains migrated pages (from a previous migration). If such pages exist, it will compare the modification date both in SharePoint and in Confluence. The result is written to progress log files.

Have a look at the documentation about progress log files: Monitoring Confluence to SharePoint Migration Progress > Using progress log files to get insights.

One of those types of progress log files contains information about the update state of already migrated pages; that’s the files with 25-update-state-of-migrated-pages in their name.

Here’s a screenshot showing progress log files for 3 migrated spaces (each having 3 progress log files):

Those spaces have been migrated before and when starting another migration WikiTraccs checked for outdated pages, and found two spaces to have outdated pages.

You can quickly see how many outdated pages there are as WikiTraccs writes this information to the file name of the progress log file, like marker-x-needupdate-y-other.

In the screenshot above, one space has 2 pages that need an update, for the other space it’s 3 pages. One space is up-to-date since the marker part is missing from the file name.

How to tell WikiTraccs to update outdated pages?

You tell WikiTraccs which pages it should update by marking those pages in the progress log files, and copying those files to the WikiTraccs.GUI\input folder.

Here are the steps:

  1. locate a progress log file with 25-update-state-of-migrated-pages and marker in its file name
    • this progress log file contains information about outdated pages
  2. open the progress log file in a text editor - this files contains a header surrounded by +++ (ignore this), followed by multiple lines, each one representing a migrated page (you want to look at those)
  3. take note of the update state near the end of each line, like uptodate or needsupdate
    • a line might look like this: SPACEKEY Page 123456789 Page Title /display/SPACEKEY/Page+Title 2023-08-31T10:16:22 2023-07-10T13:26:24 needsupdate
    • the values in this line (like SPACEKEY, page ID 123456789, etc.) are separated by tabulator (the “tab key”)
    • note: you might know CSV-files, where values in each line are separated by comma or semicolon; here tabulator is used instead
  4. mark pages you want WikiTraccs to update by adding an x to the end of the page’s line
    • make sure to separate the update state value (like needsupdate) and the x you add with exactly one tab character; note: this tab character might already be there
    • the line then should look like this: SPACEKEY Page 123456789 Page Title /display/SPACEKEY/Page+Title 2023-08-31T10:16:22 2023-07-10T13:26:24 needsupdate x - note the x at the end that marks the page for update
  5. save the progress log file when you are finished marking pages for update
  6. now copy this modified progress log file to the input folder, that is located next to the logs folder; note: both the logs and input folder are in the same location as WikiTraccs.GUI.exe, which you used to start WikiTraccs
  7. run WikiTraccs.GUI
  8. start a migration as usual, by selecting the Start transformation button in WikiTraccs.GUI

WikiTraccs looks at the input folder when a migration starts. It automatically processes all progress log files it finds in there. Pages marked for update will now be migrated again, overwriting corresponding existing pages that are present in SharePoint.

After finishing the delta migration, delete the progress log files from the input folder; otherwise WikiTraccs will process them again and again, with each started migration.

How does the delta migration differ from a normal migration?

There are certain differences when WikiTraccs finds and processes progress log files from the input folder.

If there are pages marked for update:

  • WikiTraccs will only migrate those pages marked for update and skip any spaces that have been marked for migration in the Space Inventory
  • WikiTraccs will not remove any files from the input folder
    • you have to remove those files manually, otherwise WikiTraccs will migrate them again and again, for each migration you start
  • WikiTraccs will not write progress log files for updated pages
    • to get updated progress log files, remove any files from the input folder (to end delta migration mode) and start a regular migration; new progress log files will then be created that should reflect that pages are now up-to-date

Notes about limitations of delta migrations

There are some points to be aware of when it comes to delta migrations.

Modification detection

WikiTraccs can detect changes to Confluence page contents, but not attachments or comments. For example, when an attachment is added to a Confluence page, this does not change the modification date of the page and WikiTraccs still sees this page as up-to-date.

This means that Confluence pages where only attachments changed since having been migrated are reported as uptodate in the progress log file.

Note that you can still mark those uptodate pages for update, if you want to force updating pages that WikiTraccs didn’t detect as changed.

Page titles and page links

WikiTraccs derives the file names of SharePoint modern pages from Confluence page titles. That means that changing a page’s title in Confluence can cause the following:

  • duplicate pages being created in SharePoint, since the updated page gets a new file name; WikiTraccs does not rename or remove the existing page
  • page links can break in SharePoint, when other SharePoint pages link to a page by a name that now changed due to the page being updated

Note that this does only apply when page titles change in Confluence between an initial migration and a subsequent delta migration. So those changes should be kept to a minimum between migration runs.

Changes of SharePoint pages

Changed SharePoint pages (that have been marked for update) will be overwritten when running a delta migration.

Keep in mind that when marking a page for update, this will forcefully overwrite the target SharePoint page. Even if this SharePoint page was modified since the initial migration.

Performance

The delta migration is less efficient compared to the initial migration. More requests to Confluence might be made compared to bulk operations being done in the initial migration.

Please get in touch if you encounter any issues, or have suggestions that would make your life easier.

4.15 - Migration Waves

Want to know how content transformed by WikiTraccs looks like? This page has lots of visual samples.

Starting with WikiTraccs v1.18 you can assign waves to your content selectors in the Space Inventory.

When starting a migration, you can optionally specify the waves to migrate.

What are waves?

In the context of WikiTraccs, waves are numbers that you assign to selectors in the Space Inventory.

When starting a migration you can tell WikiTraccs which of those waves it should migrate.

Using waves you can prepare a multi-wave migration where each wave is assigned the same number.

Let’s look at an example:

Wave 1: Project Teams and Miscellaneous

  • Space “Project Alpha” should be migrated to site “/sites/ProjectAlpha”
  • Space “Project Beta” should be migrated to site “/sites/ProjectBeta”
  • Space “Miscellaneous” should be migrated to site “/sites/Miscellaneous”

Wave 2: Client-Facing and Support Departments

  • Space “Marketing” should be migrated to site “/sites/Marketing”
  • Space “Sales” should be migrated to site “/sites/Sales”
  • Space “Customer Service” should be migrated to site “/sites/CustomerService”

Wave 3: Core Operational Departments

  • Space “HR” should be migrated to site “/sites/HR”
  • Space “Finance” should be migrated to site “/sites/Finance”
  • Space “IT” should be migrated to site “/sites/IT”

How to configure waves?

When configuring what to migrate in the Space Inventory, you use the WT_Setting_Waves column to assign a wave it belongs to.

Here’s what the Space Inventory list might look like:

WT_In_CfSpaceNameWT_In_CfSpaceKeyWt_Setting_RequestTransformationWT_Setting_WavesWT_Setting_TargetSiteRootUrl
Project AlphaPALPHAx1https://contoso.sharepoint.com/sites/ProjectAlpha
Project BetaPBETAx1https://contoso.sharepoint.com/sites/ProjectBeta
MiscellaneousMISCx1https://contoso.sharepoint.com/sites/Miscellaneous
MarketingMRKTx2https://contoso.sharepoint.com/sites/Marketing
SalesSALESx2https://contoso.sharepoint.com/sites/Sales
Customer ServiceSERVICEx2https://contoso.sharepoint.com/sites/CustomerService
HRHRx3https://contoso.sharepoint.com/sites/HR
FinanceFINx3https://contoso.sharepoint.com/sites/Finance
ITITx3https://contoso.sharepoint.com/sites/IT

Note: Other columns have been omitted for brevity.

With this configuration everything is prepared for a 3-wave migration.

How to choose waves to migrate?

In WikiTraccs.GUI you can enter waves into the Waves text box right above the Start transformation button:

You can choose multiple waves to migrate.

Here are supported ways of selecting waves:

Wave selection exampleDescription
1Migrate wave 1
1,2,3Migrate waves 1, 2, and 3
1-3Migrate waves 1, 2, and 3
1,4-6,8Migrate waves 1, 4, 5, 6, and 8
-4Migrate all waves up to and including 4
4-Migrate all waves equal to or greater than 4
1,4-Migrate wave 1 and all waves equal to or greater than 4
*Migrate all selectors with wave configuration, but skip selectors with empty WT_Setting_Waves column
Migrate all selectors with checked Wt_Setting_RequestTransformation column

Use cases for waves

Waves are used to partition the migration into different chunks.

Those chunks can then be

  • migrated one after another
  • migrated in parallel by multiple WikiTraccs instances

Have a look at the How to run parallel WikiTraccs migrations blog post about the latter use case.

4.16 - File Storage

This article is a resource describing storage locations used by WikiTraccs.

Storage Locations

WikiTraccs stores data on the workstation it is running on.

Attachment Registry

The attachment registry contains all attachments so far downloaded from Confluence.

The default storage location is the non-roaming AppData folder of the current user. On Windows this typically is C:\Users\user\AppData\Local, on Linux ~/.local.

You can change the attachment registry folder location via the WikiTraccs settings dialog, or via the appsettings.json > AttachmentRegistryRootPath property.

The attachment registry contains:

  • All downloaded Confluence attachments

    • example: AttachmentRegistryRootPath\<subfolders per Confluence site, user and pages>
    • storage requirement: ⚠️ as much space as the accumulating attachments of migrated pages need
    • note: you can safely delete folders and files from the attachment registry subfolders; WikiTraccs won’t use them for anything else than uploading a page and its attachments to SharePoint; if files are missing, they will be downloaded again from Confluence

  • Blob cache for migration-related data

    • example: AttachmentRegistryRootPath\wt-blobs.*
    • example: AttachmentRegistryRootPath\wt-users_*
    • storage requirement: usually < 10 GB

  • In-progress attachment downloads (when using Selenium proxy option; note: non-standard configuration)

    • example: AttachmentRegistryRootPath\WtChromeDownloads
    • storage requirement: as much space as the biggest attachment
    • note: those attachments are moved to the Attachment Registry after downloading
    • note: this folder should ever only contain one file, because each file is moved immediately after being downloaded

  • Chrome driver (chromedriver.exe)

    • note: as of WikiTraccs 1.19.5

Temporary Files

By default, temporary files are stored in the system’s temp folder. On Windows this typically is C:\Users\user\AppData\Local\Temp.

You can change the temporary folder location via the appsettings.json > TempPath property. See this section on how to change the temporary folder path: Change storage folder pathes.

Here’s what WikiTraccs stores at the temporary location:

Confluence Interactive Login Browser Profile
  • Browser profile for Confluence login (with Cookie-based auth methods)
    • example target path: C:\Users\USER\AppData\Local\Temp\WikiTracccs\HTTPS__WIKI.CONTOSO.COM
    • storage requirement: size of a Chrome profile, ~2 GB

Note that USER is your Windows user’s profile name and HTTPS__WIKI.CONTOSO.COM will resemble your Confluence’s base address (with some special characters replaced).

Attachment Registry

  • Temporary storage location for attachment downloads

    • example target path: C:\Users\user\AppData\Local\Temp\WikiTracccs
    • storage requirement: as much space as the biggest attachment
    • note: those attachments are moved to the Attachment Registry after downloading

  • Storage of intermediary transformation files (XML)

    • example target path: C:\Users\user\AppData\Local\Temp\WikiTracccs
    • storage requirement: about ~100-500 KB per migrated page (depends on page content)
    • note: only if setting is enabled
Confluence Selenium Proxy Browser Profile
  • Browser profile for Selenium proxy (only if activated; note: non-standard configuration)
    • example target path: C:\Users\user\AppData\Local\Temp\WikiTracccs\https__wiki.contoso.com\api-proxy
    • storage requirement: size of a Chrome profile, ~2 GB

User Profile Application Data

  • WikiTraccs.GUI configuration file
    • local user profile, WikiTraccs folder, e.g. C:\Users\user\AppData\WikiTraccs\WikiTraccsGui_config.json
    • note: WikiTraccs < 1.12.25 used the temporary folder, e.g. C:\Users\user\AppData\Local\Temp\WikiTraccsGui_config.json
    • storage requirement: < 1 MB

4.17 - Glossary

This article is a resource where you can definitions of terms that are used in this documentation.

What is a Confluence “Page”?

In this documentation, the term page mostly refers to “page-like content”.

Page-like content is:

  • page
  • blogpost
  • whiteboard (Confluence Cloud)
  • database (Confluence Cloud)
  • smart link (Confluence Cloud)
  • folder (Confluence Cloud)

Each of the above will become a page in SharePoint when migrating from Confluence to SharePoint Online.

Note that attachments are explicitly not covered in above list. This is also why the term “content” is (in general) not a good replacement for “page” as it covers attachments as well.

Nevertheless, in some places the term content might be used instead of “page” or “page-like” content. The context should make clear if attachments are excluded or included by that term.

In some places the term item might be used as well.

History note

Historically, with Confluence Server and Confluence Data Center, talking about pages pretty much covered everything, often including blogposts. Saying pages and meaning blogposts seemed ok.

Then came Confluence Cloud. Whiteboards were added. Databases were added. Smart links were added. Folders were added.

Now what? From a migration perspective, they are treated in a similar way in that all of them are migrated to SharePoint and become a SharePoint page.

So, for the time being, when talking about pages the other content types are meant as well. As soon as there emerges a good moniker for “page-like content in the context of a Confluence to SharePoint Online migration” the documentation will likely adopt that.

Term Definitions

TermSynonymsMeaning
Tenant (Microsoft 365)-Refers mostly to a SharePoint Online instance or sometimes the Entra ID that is associated with it, at least in this documentation. Tenants are often referred to by an ID like “170dd63a-3297-6006-8060-493a8304d6fc”. They can also be referred to by a host name like “contoso.onmicrosoft.com”, but that might not always be supported depending on the client used.
Tenant (Atlassian Cloud)-For details on Atlassian’s tenant concept refer to Atlassian Cloud architecture and operational practices. Throughout this documentation the tenant will refer to a specific Confluence instance (which is technically incorrect, but corresponds to the use of “tenant” to refer to SharePoint).
Site (SharePoint)Site Collection, SubsiteUsually refers to a site collection in SharePoint. It can also refer to a subsite in SharePoint, but those are not so widely used anymore in SharePoint Online. When working with sites they are usually referred to by their URL like “https://contoso.sharepoint.com/sites/sitename".
Site (Confluence)-In this documentation, a “site” refers to a Confluence instance. In a broader sense a site can contain multiple other products as well, like Jira. The Confluence site in WikiTraccs is referred by URL to Confluence (like “https://wiki.contoso.com” or “https://contoso.atlassian.net/wiki" ). This might change in the future when WikiTraccs handles more products.

4.18 - Multilingual Pages

Resources that cover migrating multilingual Confluence pages to SharePoint.

How does the translation work in Confluence?

There are third-party apps that enable users to translate pages in Confluence. WikiTraccs currently supports Scroll Translations.

How does the translation work in SharePoint?

SharePoint has a history of more or less usable approaches to multilingual user interfaces and content.

WikiTraccs supports different ways of migrating page translations from Confluence to SharePoint:

  1. migrating only one language, the translation with most content in Confluence
  2. migrating only one language, as chosen via configuration (not yet supported)
  3. migrating all translations to a single SharePoint page (default mode, supported as of WikiTraccs 1.4.2)
  4. migrating each translation to a separate page in SharePoint (not yet supported)

Refer to the following pages for more information

4.18.1 - Info about Scroll Translations

This article provides some background information about the Scroll Translations solution.

What is Scroll Translations? How does it make Confluence pages multilingual?

Scroll Translations is a third-party app by K15t that allows to translate Confluence pages to different languages.

Under the hood Scroll Translations creates a macro for every language the page is translated to. Those macros are stored in the page content.

The user can choose which language they want to see in Confluence. Only one language is displayed at a given time.

WikiTraccs can see all languages at once when it migrates a page and can act on them.

4.18.2 - Migrating all Languages to one SharePoint Page

The easiest apprach to migrating all Confluence page languages to SharePoint.

Please have a look at the release notes of WikiTraccs 1.4.2 for details.

4.18.3 - Migrating to Multilingual Pages in SharePoint Online

This article covers migrating Confluence pages to SharePoint Online, using the out-of-the-box multilingual pages features of SharePoint.

A brief introduction to multilingual SharePoint

Over time, there have been many approaches to multilinguality in SharePoint, both out-of-the-box ones and from third parties.

When searching for information on multilingual SharePoint sites remember to look at the date of information you find. Documentation about multilingual SharePoint pages should be newer than 1-2 years, and for SharePoint Online, not SharePoint on-premises.

There are also different approaches depending on whether you want to translate the SharePoint user interface (list titles, content types etc.), or the content of pages (text, web parts).

We shall focus on modern approaches to translating content of modern pages in SharePoint Online.

Two approaches to make pages appear in different languages are common:

  • providing multiple languages on one page
  • using the out-of-the-box feature for multilingual modern SharePoint pages

The following section looks at the second option, the out-of-the-box feature.

How do multilingual pages work in SharePoint?

Microsoft has an out-of-the-box feature for creating page translations documented here: Create multilingual SharePoint sites, pages, and news.

It is disabled by default and has to be switched on.

When this feature is enabled, a separate page can be created for each supported language. SharePoint takes care of routing the user to the page that matches their profile language.

And that’s basically it. Each language get’s a separate SharePoint page. The pages are connected by metadata.

WikiTraccs can create those translated pages, based on translations it finds in the source Confluence pages.

4.19 - WikiTraccs GUI vs. WikiTraccs Console

This article is a resource where you can find information about the two WikiTraccs flavors.

WikiTraccs consists of two applications: WikiTraccs.GUI and WikiTraccs.Console.

WikiTraccs.GUI is a graphical frontend that can be used to get started quickly without having to learn how to use the configuration file. When chosing to start the transformation WikiTraccs.GUI launches WikiTraccs.Console and passes along the configuration. From then on the work is done solely by WikiTraccs.Console.

WikiTraccs.GUI

A graphical user interface for WikiTraccs.

The initial size of the window might be a bit small depending on the environment you are running WikiTraccs in:

Empty sign-in experience

To make the window larger right-click the console window title bar and select Properties. Increase the size there:

Console window settings

Select OK to confirm the settings.

WikiTraccs.Console

The WikiTraccs console application doing the heavy lifting of transforming content from Confluence to SharePoint. You can skip using WikiGraccs.GUI and start WikiTraccs.Console directly. The configuration then has to be done via the appsettings.json file as described on the Settings page.

4.20 - Known Issues and limitations

This article is a resource where you can find information about known issues and limitations.

Limitations

Pages with more than 2 MB of page text content cannot be created in SharePoint Online. This is a known limitation of SharePoint Online. Note that this does NOT mean page attachments, but actual page content. Pages hitting this limit would be massively long.

When migrating page restrictions, WikiTraccs will only migrate up to 200 user and group restrictions per page.

Overly long page titles break page creation in SharePoint. This is tracked in issue #3.

Changes to a Confluence page’s attachments or comments are not counted as “page change”. The page is detected as unchanged, even if e.g. attachments are added.

Changes to a Confluence pages’s title will duplicate the page in SharePoint, as the file name of the SharePoint page changes. Those kinds of title changes in Confluence might also lead to stale or broken links in SharePoint. If already migrated pages (in SharePoint) link to the newly migrated page (that now has a new name in SharePoint), those links will point to the old page; or be broken if the old page is deleted manually.

The principal/metadata update mode of WikiTraccs currently can only handle up to 5000 attachments per page.

Rich image captions are not supported by SharePoint Online, the text content of the image caption will be used instead.

Confluence Cloud

Migrating databases is not yet supported as there is no endpoint provided by Atlassian to export the data.

Link transformation for sharing links that have been pasted to pages (those contain ‘/l/cp/’ ) is not yet possible. Note that those are not tiny links, which are properly transformed. Discussions about this link format: 1, 2.

At the time of this writing, retrieving inline comments might fail in Confluence Cloud. Note that inline comments are currently not surfaced anywhere on migrated pages, but only stored in the WikiTraccs site with the page storage format XML blob. This inline comment retrieval currently seems to be broken with the Confluence Cloud REST API v2.

Hard links of type create page are left as is, pointing to Confluence. WikiTraccs doesn’t know what to do about them as there is no equivalent in SharePoint. Sample link: https://contoso.atlassian.net/wiki/pages/createpage.action?spaceKey=SPC&title=Page.

5 - Troubleshooting

What if something doesn’t work with WikiTraccs?

5.1 - Connectivity Issues

This article covers how to handle connectivity issues.

The required endpoints are documented in the Endpoint reference.

Testing connectivity

The WikiTraccs GUI allows to test the connection to Confluence and to SharePoint. Select the Test Connection buttons to test.

Messages about blocked connections might look like this:

Connectivity note

Connectivity error

How to handle blocked Google Chrome WebDriver endpoints

WikiTraccs needs to show you a Chrome browser window so you can log in to Confluence. To remote control this browser, WikiTraccs needs a WebDriver program which is provided by Google.

WikiTraccs tries to download the matching WebDriver for the version of Chrome it locates automatically (or for the Chrome binary which is configured to be used via the ChromeBinaryPath setting).

If auto-detection or download fails then manual configuration is necessary. Specifically two configuration options must be set:

  • ChromeDriverVersionOverride
  • WebDriverDirPath

Proceed according to the Chrome version that is installed in your environment.

Determining config values for Chrome version 115 and newer

Follow these steps to determine the right values for ChromeDriverVersionOverride and WebDriverDirPath:

  1. Open the Chrome browser
  2. Open Chrome -> (Three Dot Menu) -> Help -> About Google Chrome
  3. Take note of the version (e.g. 118.0.5993.118)
  4. Open https://googlechromelabs.github.io/chrome-for-testing/latest-patch-versions-per-build-with-downloads.json in a browser; a web page opens, showing a wall of text
  5. On this page, using the search function of the browser, search for the version from the previous step, minus the last part; so in this example the value would be 118.0.5993 (it will be different for you)
  6. This search should yield some results; take note of the version number you see there, in the screenshot below it’s 118.0.5993.70 - this is the value you need to use as value for the ChromeDriverVersionOverride option:
  7. Using this 118.0.5993.70 version we can build the Chrome WebDriver download URL like this: https://edgedl.me.gvt1.com/edgedl/chrome/chrome-for-testing/{version}/win32/chromedriver-win32.zip, so the URL here would be https://edgedl.me.gvt1.com/edgedl/chrome/chrome-for-testing/118.0.5993.70/win32/chromedriver-win32.zip
  8. Open this URL in a new browser tab which will trigger the download of chromedriver-win32.zip
  9. Extract chromedriver-win32.zip and find chromedriver.exe:
    This is the WebDriver.
  10. Take note of the folder path of chromedriver.exe; the path to this folder is the value for WebDriverDirPath, for example C:\Users\user\Downloads\chromedriver-win32\chromedriver-win32

Continue with section How to apply the configuration below.

Getting config values for Chrome older than version 115

Follow these steps to determine the right values for * ChromeDriverVersionOverride and WebDriverDirPath:

  1. Open the Chrome browser
  2. Open Chrome -> (Three Dot Menu) -> Help -> About Google Chrome
  3. Take note of the version (e.g. 86.0.4240.75)
  4. Open https://chromedriver.storage.googleapis.com/LATEST_RELEASE_# in a browser, with # replaced by the version from the previous step, minus the last part; so in this example the URL would be https://chromedriver.storage.googleapis.com/LATEST_RELEASE_86.0.4240 (it will be different for you)
  5. A web page opens and shows a single number (e.g. 86.0.4240.22) - this is the value you need to use as value for the ChromeDriverVersionOverride option
  6. Now open https://chromedriver.chromium.org/downloads in a browser and search for the section ChromeDriver # where # is the version from the previous step, which in our case looks like this:

    Find the right ChromeDriver version

  7. Choose the headline which takes you to the download page for this ChromeDriver version:

    Download ChromeDriver for your platform

  8. Download the right zip file for your platform (Windows, Mac or Linux); the zip contains a single file (chromedriver.exe or chromedriver), which is the WebDriver
  9. Extract this single file to a folder; the path to this folder is the value for WebDriverDirPath

Continue with section How to apply the configuration below.

How to apply the configuration

Refer to the Configuration File page on where to put those configuration values.

Now WikiTraccs skips the WebDriver version check and download. This should resolve connectivity issues to those endpoints.

5.2 - Authentication Issues

This article covers known authentication issues and possible solutions.

5.2.1 - Confluence Authentication Issues

This article covers known authentication issues in Confluence and possible solutions.

What does a Successful Authentication look like?

To authenticate with Confluence using cookie-based authentication, WikiTraccs opens a browser window to let you log in.

Once you are logged in the browser window should close within about 30 seconds. This is normal behavior, indicating successful authentication.

WikiTraccs shows a success message if all authentication cookies could be retrieved. You can stop reading in this case.

If the browser window stays open for a long time after authenticating with Confluence then WikiTraccs is not able to detect your login, for whatever reason. In this case proceed with the troubleshooting sections below.

General Troubleshooting

First, close any open WikiTraccs window and re-start WikiTraccs. Sometimes this resolves issues with authentication. Also close any browser windows that WikiTraccs opened and that is still open.

If re-starting WikiTraccs doesn’t help check if you need additional or different authentication cookies for Confluence. Those can be configured in the advanced authentication configuration dialog. If you are using SSO solutions like Shibboleth you’ll most likely need additional cookies.

Or maybe the Confluence login timed out. WikiTraccs waits for some time for the authentication cookies to appear before giving up. Try to not take too much time for logging in as this might run into a timeout.

Workarounds

If the steps outlined in the previous section didn’t help then something is not right. WikiTraccs might have encountered a yet unsupported configuration of either Confluence or the system it is running on.

WikiTraccs has built-in ways to troubleshoot this. Try the steps outlined in the following sections.

1. Disable Context Path Check for Cookies

WikiTraccs makes assumptions about how the context path of Confluence and cookie data relates. Let’s disable those assumptions.

In appsettings.json, add the following setting:

{
    "CustomSettings": {
        "Debug": {
            "SkipConfluenceContextPathCookiePathMatching": true
        }
    }
}

If appsettings.json does not yet exist, create it and copy above snippet to the file.

If appsettings.json already exists, find the Debug section and add the SkipConfluenceContextPathCookiePathMatching property. Create the Debug section if necessary.

Re-start WikiTraccs and check if authentication now is possible.

If authentication still cannot be detected, proceed with the next section.

2. Provide Cookies manually

WikiTraccs just needs authentication cookie values and does not really care where they come from.

Let’s provide them manually via a text file.

We need to:

  • copy cookies from the browser to cookies.txt
  • copy the user ID to appsettings.json

Open Chrome (or Edge), navigate to Confluence and log in.

Still in the browser, press F12 to open the developer tools, and choose the Application tab.

Under Cookies, select the Confluence domain. A panel on the right side should show cookies.

Check that JSESSIONID is among those cookies. Unless the cookie name has been changed via server configuration. In this case check the configured name.

In the cookie panel, select all rows with the mouse and copy them to the clipboard.

Create a new file cookies.txt in either the WikiTraccs.GUI or WikiTraccs.Console folder (depending on what your are running). Have cookies.txt open in a text editor.

Paste the cookie values from the clipboard to the open text editor and save cookies.txt.

Here’s an animated GIF showing above steps:

Now go back to the browser. The developer tools should still be open.

Choose the Elements tab, expand the HTML head element and search for the ajs-remote-user-key entry:

The ajs-remote-user-key content value.

Put the ajs-remote-user-key content value to appsettings.json like this:

{
    "CustomSettings": {
        "Debug": {
            "AjsRemoteUserKey": "8a848084865dd3b801865dd4dc420000"
        }
    }
}

Having both cookies.txt and the appsettings.json configuration in place, restart WikiTraccs and retry starting a migration.

WikiTraccs now checks if cookies.txt exists and uses the cookie values instead of starting an interative browser login session. This should succeed.

Please get in touch if this still doesn’t work.

How to log out of Confluence?

When you log in to Confluence you can choose the Remember me option to stay logged in. This is very convenient during a migration since you are always logged in to Confluence without having to reenter your credentials.

But how to log out?

The solution is to delete the browser profile of the Chrome browser that WikiTraccs uses to log in to Confluence. The browser profile is stored in a temporary location, which by default is the Temp folder for your Windows user:

C:\Users\<username>\AppData\Local\Temp\<host-name-of-confluence>

  • <username> is your Windows user profile name
  • <host-name-of-confluence> resembles the host part of the Confluence base address, like confluence.contoso.com

Delete the whole <host-name-of-confluence> folder and you should be asked to log in again when starting your next migration. This will also recreate the folder.

Cannot find the folder? Have a look here on more information about this temporary folder and where you might find it: File Storage - Temporary Files

5.2.2 - SharePoint Authentication issues

This article covers known authentication issues and possible solutions.

Empty Microsoft sign-in experience

When starting a transformation a browser window opens for you to sign in to SharePoint Online.

On some systems the browser window might stay empty. This was seen on Windows Server 2012 with Internet Explorer 11. When this happens copy the URL from the address bar, open Chrome, and paste the URL there in the address bar to load the page. Authenticate there.

Alternatively configure the system to show the sign in experience.

Empty sign-in experience

5.3 - Logging

This article is a resource where you can find information about logging.

See Troubleshooting Strategies for different log files that can be used to troubleshoot issues.

5.4 - Troubleshooting Strategies

This article covers issues and how to diagnose them.

Confluence migrations to SharePoint, as migrations in general, are rarely without issues.

WikiTraccs has been tested with Confluence instances of different versions and different ages and has been hardened against common issues. Some recurring issues like broken page content (from past migrations) or inaccessible external images are gracefully handled.

But what if something appears broken nevertheless?

This page shows how such issues can be diagnosed and which data WikiTraccs creates to help diagnosing a Confluence to SharePoint migration that appears stuck.

The easiest way for you is to put all information in a zip file and send it via email to contact -at- wikitransformationproject.com. I’ll take a look.

My goal is to identify the issue, replicate it in a test environment and make adjustments so that the issue can never occur again.

WikiTraccs grows with every Confluence migrated, since each one is unique. My goal is to make this as painless for you as possible. You can help me helping you by providing as much information as possible to replicate the issue in a test environment, so I don’t have to bother you with more questions.

Of course you can also look at the log files. If there are connectivity issues, or authentication issues the error messages are usually pretty clear, hinting in the right direction.

Which information is available to diagnose issues?

WikiTraccs logs detailed information about everything that it’s doing.

Here’s an overview of what is available and helpful for diagnosing issues, more details follow further down.

What?Where can I find it?Why does it help?
Common log filesin WikiTraccs.GUI\logs or WikiTraccs.Console\logs (depending on whether you are running WikiTraccs.GUI.exe or WikiTraccs.Console.exe)Contains detailed information about the whole migration process, including warnings and errors
Progress log filesin WikiTraccs.GUI\logs\<date-folder> or WikiTraccs.Console\logs\<date-folder> (depending on whether you are running WikiTraccs.GUI.exe or WikiTraccs.Console.exe)Contains information about migrated and yet-to-be-migrated pages; see Monitoring Confluence to SharePoint Migration Progress for details
SharePoint Site Pages libraryevery target site for the migration contains information about migrated pagesShows detailed information for every page migrated; see Measuring page migration success for details
Confluence page storage formatfor any open Confluence page choose View Storage Format; note that the Confluence Source Editor plugin has to be installed for this option to be present

Shows the page as WikiTraccs sees it; page structure and macros can be seen, analyzed and reproduced through a technical lens
Confluence page IDs and page titles of missing pagesopen the page properties in Confluence for pages that did not migrate to SharePoint and look at the browser address bar - you see the page ID there; and the page title is the page titlethe log files contain any errors that hinder migration and page IDs and titles help finding the right places in the log files

Common log files

Common log files cover information about the whole Confluence to SharePoint migration.

The log file names follow this pattern:

  • <date>-WikiTraccs.Console.log
  • <date>-WikiTraccs.GUI<date>.log

For each application run new log files are created. Here’s a sample logs folder:

The <date>-WikiTraccs.GUI...txt (note the GUI part) log file is created when using WikiTraccs.GUI, for example when testing connections and filling the space inventory. This file is useful to troubleshoot connectivity and authentication issues.

The <date>-WikiTraccs.Console...txt log file is created as soon as a migration starts and WikiTraccs.GUI opens the WikiTraccs.Console console window. Or when using WikiTraccs.Console standalone. This file is useful to troubleshoot issues that happen while migrating.

Progress log files

Progress log files conver the page migration state for all spaces that are part of the migration.

They are in detail covered in Monitoring Confluence to SharePoint Migration Progress.

SharePoint Site Pages library and page metadata

Once pages have been migrated you should scroll through the Site Pages library to see if there is anything of interest.

This is described in detail in Measuring page migration success.

Specific issues and how to diagnose them

We’ll look at real-world issues and how to diagnose them.

Assume the following migration scenario:

  • source environment: Confluence 6 at http://localhost:8090/confluence, one space 7SE has been selected for migration in the space inventory
  • target environment: SharePoint Online site https://contoso.sharepoint.com/sites/arc42-template
  • the migration is done via WikiTraccs.GUI

The migration is finished when the console window looks like this:

There is nothing left to migrate, the console window can be closed by pressing Ctrl+C.

Issue: Some pages are not migrated from Confluence to SharePoint

The progress log files should tell us more.

But first we look at a successful migration result, to establish a baseline.

Case 1: A successful migration of all pages

There should be 4 log files after successfully migrating one Confluence space:

Of the four files, the first two were created before starting the migration. The last two files were created after having finished the migration.

Here’s the content of the […]aggregated-info.txt file that was created before migrating the Confluence space to SharePoint:

Source Confluence Site: http://localhost:8090/confluence/
Target SharePoint Site: https://contoso.sharepoint.com/sites/arc42-template
Space Key: 7SE
Blog posts included in migration and calculation: no
Confluence page count for space space 7SE: 32
Migrated SharePoint pages that correspond to found Confluence pages in space 7SE: 0
Migrated SharePoint pages overall for space 7SE: 0
Pages yet to be migrated for space 7SE: 32

This shows that WikiTraccs was able to retrieve information about 32 pages in this space and all have yet to be migrated.

Here’s the content of the second […]aggregated-info.txt file that was created after migrating the Confluence space to SharePoint:

Source Confluence Site: http://localhost:8090/confluence/
Target SharePoint Site: https://contoso.sharepoint.com/sites/arc42-template
Space Key: 7SE
Blog posts included in migration and calculation: no
Confluence page count for space space 7SE: 32
Migrated SharePoint pages that correspond to found Confluence pages in space 7SE: 32
Migrated SharePoint pages overall for space 7SE: 32
Pages yet to be migrated for space 7SE: 0

This time there are 32 migrated pages and there are none left to be migrated.

Success. Now we make it more complicated.

Case 2: Pages appear missing

Pages can appear missing when the migration account is not permitted to view all pages.

Here’s an example where a parent page of two child pages has been view-restricted to only the admin account:

Now, when using another Confluence account as migration account, this account won’t see those three pages.

Thus (after deleting all previously created SharePoint pages and starting a new migration) the […]aggregated-info.txt file looks like this:

Source Confluence Site: http://localhost:8090/confluence/
Target SharePoint Site: https://heinrichulbricht.sharepoint.com/sites/arc42-template
Space Key: 7SE
Blog posts included in migration and calculation: no
Confluence page count for space space 7SE: 29
Migrated SharePoint pages that correspond to found Confluence pages in space 7SE: 0
Migrated SharePoint pages overall for space 7SE: 0
Pages yet to be migrated for space 7SE: 29

Only 29 pages are reported for the space that has in fact 32 pages. But 3 of those cannot be seen by the migration account.

The solution in this case is simple: use a migration account that can access all pages that should be migrated.

Case 3: Pages are missing, even after checking permissions

This could be anything, but it should be visible in the log files.

Please send me the log files and page IDs and ideally page titles of pages you’d expect to migrate from Confluence to SharePoint. This information should help to locate any errors related to those pages in the log files.

Please send information via email to contact -at- wikitransformationproject.com.

Issue: The progress bar in WikiTraccs.GUI is stuck

This is caused by pages that have been migrated before and have been updated in Confluence since. It should only happen when migrating the same space at least twice.

The pages that need to be updated can be seen in the progress log files.

The “update mode” feature request is tracked here: Add update mode for already migrated pages.

Technically everything is correct. You need to delete the SharePoint files you want to update, before starting another migration to have them created again.

Issue: The migrated Confluence page doesn’t look good in SharePoint (visual check)

The layout is off? Content is missing? Macros are missing?

There are probably thousands of special cases that can affect the Confluence page migration to SharePoint, hundreds of which are already handled by WikiTraccs.

If there is something wrong with the resulting page please use the options under Contact to get in touch.

Please provide the following for your request to be properly handled:

  • Confluence version
  • a screenshot of the source Confluence page
  • a screenshot of the SharePoint page, with the unexpected parts highlighted
  • the storage format of the source Confluence page - see Get the Confluence Storage Format for instructions on how to get that
  • the page ID and title of the source Confluence page
  • SharePoint page metadata for the affected page, like WT: Text Transferred Percent, WT: Failed Transformations and (most important) WT: Transformation Log (a screenshot is fine, see next section for a sample)

Please report issues via email to contact -at- wikitransformationproject.com.

Issue: The SharePoint page metadata shows Transformation Errors and/or a Text Transferred value that is not equal to 100%

WikiTraccs tracks its migration success per page. It has hundreds of transformation rules built-in.

If WikiTraccs discoveres a new layout or macro it cannot handle, it’ll raise a flag by counting the Transformation Errors or potentially missing text.

Here’s a sample screenshot of such an issue, where certain XML tags caused problems, leading to text being skipped:

To diagnose those issues the same information as in the previous section Issue: The migrated Confluence page doesn’t look good in SharePoint is needed. The most important part is the storage format because this hopefully allows to replicate and isolate the issue in a test environment.

Please report issues via email to contact -at- wikitransformationproject.com.

5.4.1 - Get the Confluence Storage Format

This article covers how to get the storage format of a Confluence page.

The Confluence Storage Format is the technical under-the-hood view of a Confluence page. It’s what WikiTraccs “sees” and transforms when performing the Confluence to SharePoint migration.

How to view the storage format for a Confluence page? See your options below.

Option 1: View storage format in browser (using an app)

This is the most convenient option.

Here’s the Atlassian documentation on how to view the storage format: How to retrieve Confluence Storage Format

It boils down to this:

Open a page, choose the three-dot-menu, and choose "View Storage Format".

A new browser window will open, showing the storage format.

Option 2: Configure WikiTraccs.GUI to save the storage format to disk

WikiTraccs knows the storage format of each page it migrates from Confluence to SharePoint.

The storage format by default is only kept in memory and not persisted to a file.

Here’s how to tell WikiTraccs to store the storage format of every page to a file:

Variant 1: Enable via config file in WikiTraccs.GUI

In WikiTraccs.GUI, go to Settings -> Configure Transformation -> Migration and select the Save page storage XML to disk option.

Variant 2: Enable via config file appsettings.json

  1. Open the WikiTraccs.GUI folder (this is the folder where WikiTraccs.GUI.exe is stored as well)
  2. Create an empty file appsettings.json inside the WikiTraccs.GUI folder
  3. Open the appsettings.json file in a text editor and put the following text in there:
    {
    "CustomSettings": {
        "Debug": {
            "SaveTransformationInputToDisk": true
        }
    }
}
  4. Save appsettings.json
  5. If WikiTraccs.GUI is open: close it and any other (console) windows it opened
  6. Open WikiTraccs.GUI and start a migration

Where can I find the exported storage format XML?

After following instructions of one of above variants, WikiTraccs now stores the storage format for every newly migrated page in a file, in the attachment registry.

The attachment registry is a folder where attachments from Confluence are downloaded to, while migrating. You can find it in the AppData folder of your local user account.

The attachment registry path for a Confluence page looks like C:\Users\<username>\AppData\Local\WikiTraccs\<confluenceuserkey>\<confluencebaseurl>\Attachments\<pageid>.

Here’s an example screenshot:

Attachment registry path for Confluence page 118587415.

The storage format for a page is stored in a file that is named like xhtml_before-<spacekey>-<pageid>.xml.

Now you can access the storage format for every page that is part of your Confluence to SharePoint migration.

Option 3: Use the REST API to view the storage format

You can also use the Confluence REST API to view the storage format of a single page in the browser.

You need two pieces of information to do that:

  1. your Confluence base address (examples: https://confluence.contoso.com, https://www.contoso.com/confluence)
  2. the page ID of the page to get the storage format for (example: 123212321)

Using above information you now build the REST API address using this pattern:

  • CONFLUENCEBASEADDRESS/rest/api/content/REPLACEWITHPAGEID?expand=body.storage,version,container,history,history.lastUpdated,contributors,restrictions,permissions,ancestors&status=current

So, using the Confluence base address https://confluence.contoso.com and page ID 123212321 the address would look like this:

Paste this whole address into the address bar of a browser where you are already logged in to Confluence. This should show textual information about the page (in JSON format). It should contain the text "body":{"storage":{"value":".

When sending information to support, please provide the whole content shown by the browser.

5.4.2 - Get the SharePoint Storage Format

This article covers how to get the storage format of a SharePoint page.

The SharePoint Storage Format is the technical under-the-hood view of a SharePoint page. It’s what WikiTraccs creates when performing the Confluence to SharePoint migration.

Use the REST API to view the storage format

You can use the SharePoint REST API to view the storage format of a single page in the browser.

You need the following information to do that:

  1. your SharePoint site address (example: https://contoso.sharepoint.com/sites/it-support)
  2. the item ID of the page to get the storage format for (example: 33) (Note: you get that item ID from the Site Pages library; find your page there and add the ID column to the current view, if necessary; the number shown there is the item ID)
  3. the title of the Site Pages library, in the site’s default language (examples: Site Pages (for English, note the space!), Websiteseiten (for German))

Using above information you now build the REST API address using this pattern:

  • SITEADDRESS/_api/web/lists/GetByTitle('SITEPAGESLIBRARYTITLE')/items(PAGEITEMID)

So, using example data from above the address would look like this:

  • https://contoso.sharepoint.com/sites/it-support/_api/web/lists/GetByTitle('Site Pages')/items(33)

Paste this whole address into the address bar of your browser where you are already logged in to SharePoint Online. This should show textual information about the page (in XML format). It should contain the text <d:CanvasContent1>.

When sending information to support, please provide the whole content shown by the browser.

5.5 - Troubleshooting FAQ

This article is a resource where you can find information about puzzling situations and possible causes.

Why is there no visible progress?

Situation

You started the transformation, the console window of WikiTraccs is open and shows some log messages.

But then nothing happens anymore. No log messages appear in the console window, it just sits there.

Possible explanations

Maybe you did not select any spaces to migrate. Use the space inventory to select spaces. The console window will also contain hints like got no spaces to handle.

Another reason might be that during migration WikiTraccs got throttled by Microsoft 365. This can cause wait times of several minutes. Look for log messages indicating that throttling is happening.

5.6 - Support Options

This article covers how to report issues and how support works.

What level of service can I expect?

The Wiki Transformation Project provides unrestricted break-fix support for all its offerings. Reported issues will be analyzed and addressed by either implementing fixes or proposing workarounds to minimize disruptions.

Support is best-effort based. Usually, you can expect a response within 24 hours on working days.

After identifying an issue with WikiTraccs, a fix will usually be provided within a couple of days. It might take less time, or more, depending on the complexity of the issue and whether it is possible to recreate the issue in a test environment.

If anything is affecting response times (company holidays, pandemics, …) it will be communicated via a pinned announcement in the respective GitHub issue list.

How to report an issue?

For non-confidential issues, use GitHub. Each GitHub repository provides a public issue tracker where all clients can chime in on issues and benefit from known resolutions. Find the link on the Contact page.

When reporting issues with confidential information, or sending log files, use the support email: [email protected].

Sharing larger files will be done via SharePoint Online. Support will provide you with a sharing link to a folder, where files can safely be stored.

Data location for both Exchange Online and SharePoint Online is Germany.

From which timezone will support be provided?

Support will be provided from Germany, and the timezone will either be CET (Central European Time, UTC+1) or CEST (Central European Summer Time, UTC+2) depending on the season.

Can we have a call?

I try to keep the communication asynchronous. This approach accommodates various time zones and busy schedules, ensuring efficient and flexible communication for all parties involved.

The usual process for issue resolution is as follows:

  1. You raise an issue via one of the aforementioned channels (GitHub, email).
  2. I’ll get back to you with questions, first ideas, links to the documentation, and will often ask for log files; either on the GitHub issue or via email.
  3. You test and get back to me with more information.
  4. <Steps 2 and 3 are repeated as necessary>
  5. The issue is resolved.

But if it becomes clear that we are progressing towards an unproductive back and forth, I’ll propose having a screensharing session to analyze the issue. A Microsoft Teams meeting link will be provided.

Is Microsoft Teams chat available as support channel?

No, please get in touch via [email protected].

How about general inquiries?

When you have general inquiries about using the tools for specific use cases, please get in touch. I’m interested in learning about your challenges and how each tool can be enhanced to better support you.

You can use the community options linked on the Contact page, or via the support email address. Please allow for a slightly longer response time for general inquiries as those will be processed two times a week.

5.7 - Error Messages

This article is a resource where you can find information about error messages.

“Error while launching browser for login”

Variants:

  • “Error while launching browser for login: One or more errors occurred. (Google Chrome not found in registry)”

Interaction leading to this error:

  • selecting the Test connection button to test the connection to Confluence

Causes:

  1. Google Chrome is not installed
  2. Google Chrome is installed, but its executable could not be found at usual places

Solutions:

  1. Install Google Chrome
  2. Use the ChromeBinaryPath setting to manually configure the path to Chrome’s executable

5.8 - Common Warnings and Errors in Log Files

This article collects commonly observed warnings and errors and provides guidance on how to interpret them.

Errors

The following error messages might pop up in log files. Many errors are of temporary nature, for example many connection-related errors. WikiTraccs has retries built-in that can recover automatically.

[024 01:56:59 ERR MIG 123456789 sitename] [PnP.Framework] ExecuteQuery threw following exception: System.Net.WebException: The SSL connection could not be established, see inner exception.
 ---> System.Net.Http.HttpRequestException: The SSL connection could not be established, see inner exception.
 ---> System.IO.IOException: Unable to read data from the transport connection: Connection reset by peer.
 ---> System.Net.Sockets.SocketException (104): Connection reset by peer
   --- End of inner exception stack trace ---
   at System.Net.Sockets.Socket.AwaitableSocketAsyncEventArgs.ThrowException(SocketError error, CancellationToken cancellationToken)
   at System.Net.Sockets.Socket.AwaitableSocketAsyncEventArgs.System.Threading.Tasks.Sources.IValueTaskSource<System.Int32>.GetResult(Int16 token)
   at System.Net.Security.SslStream.<FillHandshakeBufferAsync>g__InternalFillHandshakeBufferAsync|189_0[TIOAdapter](TIOAdapter adap, ValueTask`1 task, Int32 minSize)
   at System.Net.Security.SslStream.ReceiveBlobAsync[TIOAdapter](TIOAdapter adapter)
   at System.Net.Security.SslStream.ForceAuthenticationAsync[TIOAdapter](TIOAdapter adapter, Boolean receiveFirst, Byte[] reAuthenticationData, Boolean isApm)
   at System.Net.Http.ConnectHelper.EstablishSslConnectionAsync(SslClientAuthenticationOptions sslOptions, HttpRequestMessage request, Boolean async, Stream stream, CancellationToken cancellationToken)

Related to a previous connection error:

[004 02:10:12 WRN MIG 123456789 sitename] [https://contoso.atlassian.net/wiki] Got an error while provisioning pages and attachments: Value cannot be null. (Parameter 'clientObject') (this is try 1 of 4) | WikiTraccs.Console.Registries.ConfluenceContentRegistry
System.ArgumentNullException: Value cannot be null. (Parameter 'clientObject')
   at Microsoft.SharePoint.Client.ClientRuntimeContext.Load[T](T clientObject, Expression`1[] retrievals)
   at PnP.Framework.Provisioning.ObjectHandlers.ObjectFiles.CheckOutIfNeeded(Web web, File targetFile, Expression`1[] additionalRetrievals) in ...

[029 23:16:25 ERR MIG 123456789 sitename] [PnP.Framework] ExecuteQuery threw following exception: Microsoft.SharePoint.Client.ServerException: I/O error occurred.
   at Microsoft.SharePoint.Client.ClientRequest.ProcessResponseStream(Stream responseStream)
   at Microsoft.SharePoint.Client.ClientRequest.ProcessResponse()
   at Microsoft.SharePoint.Client.ClientRequest.ExecuteQueryToServerAsync(ChunkStringBuilder sb)
   at Microsoft.SharePoint.Client.ClientRequest.ExecuteQueryAsync()
   at Microsoft.SharePoint.Client.ClientRuntimeContext.ExecuteQueryAsync()
   at Microsoft.SharePoint.Client.ClientContext.ExecuteQueryAsync()
   at Microsoft.SharePoint.Client.ClientContextExtensions.ExecuteQueryImplementation(ClientRuntimeContext clientContext, Int32 retryCount, String userAgent) in ClientContextExtensions.cs:line 191
ServerErrorCode: -1
ServerErrorTypeName: System.IO.IOException
ServerErrorTraceCorrelationId: c68a65a1-c094-a000-bb18-07fa16377196
ServerErrorValue: 
ServerErrorDetails: 
Additional info: 
. 0ms  | WikiTraccs.Console.Program

Above error might be followed by this one:

[006 23:16:25 WRN MIG 123456789 sitename] [https://contoso.atlassian.net/wiki] Got an error while provisioning pages and attachments: Value cannot be null. (Parameter 'clientObject') (this is try 1 of 4) | WikiTraccs.Console.Registries.ConfluenceContentRegistry
System.ArgumentNullException: Value cannot be null. (Parameter 'clientObject')
   at Microsoft.SharePoint.Client.ClientRuntimeContext.Load[T](T clientObject, Expression`1[] retrievals)
   at PnP.Framework.Provisioning.ObjectHandlers.ObjectFiles.CheckOutIfNeeded(Web web, File targetFile, Expression`1[] additionalRetrievals) in ObjectFiles.cs:line 287

You should see the following message after one of above messages: Waiting 0 sec before retrying the provisioning after error - WikiTraccs retries a couple of times which - unless network connectivity is completely lost - often works.

Warnings

Those messages are mostly caused by links to content that has been deleted or restricted. WikiTraccs finds those links and tries to look up the link target - a page, an attachment, a space, you name it. If it cannot access or find that content (and there is no way to tell the difference) it will surface in the log files.

Could not get page info from ID <snip>

Linked page '<page title>' could not be retrieved from Confluence

Info retrieved about linked page |spacekey|_|_|'Page Title'|vL|Page| is missing information needed to generate page file name: Id; cannot create link (might be missing page or no access)

A page could not be found for whatever reason.

'Image' has unexpected content type text/html

Most common cause: an external image is embedded on the page, but accessing this image requires logging in to the external system. WikiTraccs cannot do that.

When WikiTraccs tries to download that image, it will be presented with a login screen instead. This clearly is no image, but a HTML page. Thus the message.

The only way to get rid of this message is replacing the image in the source Confluence file by an image that doesn’t require authentication with an external system.

There is a difference in images between original (8) and transferred page (7).

Note: the numbers will be different, depending on the number of images in the Confluence page.

Most common cause: an external image could not be downloaded, or an image attachment is missing in Confluence. Those images most likely will also be shown as missing on the source Confluence page, indicated by the “broken image” symbol:

Probably nothing to do about that as the image is gone.

Cannot find stored attachment and/or container file name for 'ext-<snip>'

Most common cause: an external image could not be downloaded. This often happens for older Confluence pages that embed images from external web sites. Those sites vanish over the years, breaking the image link.

Nothing to do about that as the image is gone.

TaskCanceledException while downloading file via 'https://shop.contoso.com/wp-mediathek/ER99-navy-800x800.jpg': The request was canceled due to the configured HttpClient.Timeout of 12 seconds elapsing.

Note: the URL name will be different for you.

An external image could not be downloaded because the server did not answer in time. The image is probably gone and nothing can be done about that.

There are multiple attachments with the same name 'Microsoft Teams im Überblick.PNG' on the page; returning the first one

Note: the file name will be different for you.

A Confluence page contains duplicate attachments. This cannot be transformed to SharePoint, so WikiTraccs chooses one of them. In Confluence, this might look like this:

One solution would be to remove those duplicates in Confluence and to migrate the page again.

Cannot determine target site for image attachment of page |spacekey|_|_|'Image file name.png'|vL|Page|; skipping

Note: the space key and file name will be different for you.

A page embeds an image form another page, and WikiTraccs cannot find the source page. The page might be missing or inaccessible.

Verification failed: Attachment file 'file.zip' is broken in SharePoint

Note: the file name will be different for you.

A file seemed broken or missing after uploading to SharePoint - this needs to be investigated as an attachment might be indeed broken or missing. One cause can be badly timed connection issues that leave the file in an intermediary state. WikiTraccs checks each file after upload to detect this condition and warns accordingly.

Note that there are some file types that are forbidden to be uploaded to SharePoint, like aspx and jar files.

The solution is to migrate the affected page again, which will also upload all of the page’s attachments.

[GetClientIdsAsync] Cancelling wait for jiraanywhere after 30 seconds

Trying to get information about a Jira macro time out. This might be a permission issue. When opening the Confluence page, you might see the timeout there as well.

Two options to work around that: increase the timeout and see if data is returned, or decrease the timeout as most successful data retrievals for Jira macros should return faster.

You can configure the timeout in appsettings.json: Snippet: Prevent WikiTraccs from reaching out to Jira.

Information messages of note

[THROTTLED] CSOM request frequency exceeded usage limits. Retry attempt 1. Sleeping for 500 milliseconds before retrying

Microsoft throttled the connection to SharePoint Online, telling WikiTraccs to slow down. WikiTraccs adheres to that.

6 - WikiPakk Reference

A reference of topics around WikiTraccs WikiPakk - the SharePoint page tree and breadcrumb.

6.1 - WikiPakk Installation and Ops

How to install and update WikiPakk

Refer to the following articles for topics around installing and updating WikiPakk.

6.1.1 - Install WikiPakk

How to install WikiPakk

Installation of WikiPakk

The WikiPakk solution has to be installed once in the SharePoint tenant before WikiPakk can be added to SharePoint sites.

WikiPakk is installed via the Microsoft Store AppSource.

After installing the WikiPakk app to the SharePoint tenant, it can be added to SharePoint sites by the respective site owners.

Installation via Microsoft AppSource

The following video covers two topics:

  1. installing the app via Microsoft AppSource to the SharePoint tenant
  2. adding the WikiPakk app to a SharePoint site

Watch:



After adding the app

Head over to the video section on the WikiPakk website to learn more about WikiPakk.

6.1.2 - Update WikiPakk

How to update WikiPakk

Updating WikiPakk

WikiPakk currently does not automatically check for updates, and neither does SharePoint. New versions can be discovered manually via AppSource.

Checking for a new WikiPakk version on Microsoft AppSource

You can see the latest version of WikiPakk in AppSource on this page: Details + support.

In AppSource there will also be a changelog showing the changes per release:

Changelog of WikiPakk as shown in AppSource

Updating WikiPakk in SharePoint

There are two steps to updating WikiPakk:

  1. the SharePoint tenant app catalog needs to be updated with the newest version from AppSource
  2. SharePoint sites that use WikiPakk might need to be updated to use this new version

The following sections describe those steps.

Update the SharePoint tenant app catalog

As SharePoint administrator, open the tenant app catalog as follows:

  1. in a browser, open the SharePoint admin center
  2. in the left navigation, select More features
  3. on the right side, several options to choose from appear; look for the Apps section and select Open:

Entry to the SharePoint tenant app catalog.

  1. the SharePoint tenant app catalog should show a previously installed version of WikiPakk:

WikiPakk, installed from AppSource, showing version 2.3.1.

  1. Switch to the classic experience by selecting the classic experience link:
  1. In the classic experience, in the list of apps, select the WikiTraccs WikiPakk app
  2. At the top of the page, select the FILES tab to expand the ribbon menu (note: only if the ribbon menu is not yet visible)
  3. In the ribbon menu, select Upgrade Store App:

You will be redirected to a screen that displays Downloading from: https://addinsinstallation.store.office.com/appinstall/….

Once the file has been downloaded, you will be prompted to trust WikiTraccs WikiPakk:

  1. Choose Deploy and wait; it might appear that nothing is happening for up to 20 seconds

Once the update has been completed, you should be redirected to the app catalog and the App version number should match the version number listed in AppSource.

Now the new app version is ready to be used in SharePoint sites.

Update WikiPakk in SharePoint sites

In SharePoint, an app can have different versions in the tenant app catalog and in sites that the app had been added to.

The previous section described how to update the app from AppSource via the tenant app catalog. This app version is now higher than in the sites that use the app. We need to update those sites as well so they use the latest version.

To update each SharePoint site to the latest WikiPakk version proceed as follows.

As site owner, or site collection administrator of the respective sites:

  1. In a browser, navigate to a SharePoint site that uses WikiPakk
  2. In this site, navigate to Site Contents
  3. For the WikiTraccs WikiPakk app, choose … > Details:
  1. Choose GET IT to update the app:

After a moment, you will be redirected back to Site Contents. The WikiTraccs WikiPakk app title might display in gray, indicating that the update is still in progress.

After a while (and you might have to refresh the page manually) the app title should display in black, indicating that SharePoint finished updating the app.

For the app, select … > Details again. It should now read Good news - you already have this on your site.

Note: this process can be automated, e.g. with the CLI for Microsoft 365.

You can see the app version as well in WikiPakk as follows:

  1. Select Page Tree to expand the page tree panel on the right side
  2. Select the ? that is displayed at the bottom of the page tree; a window opens
  3. The app version is shown right at the top

If the version shown here is lower than the one of the app you just installed, proceed reading the next section about Caching ssues.

Caching issues

There is one rather ugly behavior when updating SharePoint apps. Sometimes the browser caches old resources rather aggressively, making the app appear being older for users.

This is the case when the version number in the ? dialog of WikiPakk shows a lower version number than the app’s version number.

To solve this different strategies helped different clients:

  • Pressing F5 to reload the page
  • Clearing the browser cache
  • Deleting all service workers via the F12 developer tools

This has to be done in all browsers where caching issues occur.

6.1.3 - Update WikiPakk (staged)

How to update WikiPakk with staging

This article shows how to install an update of WikiPakk to a staging site collection, before rolling out the update to the whole tenant.

This process is different (and has more steps) than the update instructions that don’t involve staging.

Steps Overview

This article describes the following steps:

  1. Create a staging site and activate the site collection app catalog
  2. Install the current WikiPakk app package to the staging site
  3. Add the WikiPakk app to the staging site
  4. Get the latest WikiPakk update from AppSource and install it to the staging site

While all steps are necessary for setting up the staging site, steps 1 to 3 might be skipped if you reuse the staging site for future WikiPakk updates.

Step 1: Create a staging site and activate the site collection app catalog

  1. Create a new site that will be used for staging
  2. Using PowerShell, create a site collection app catalog
    • Here’s a sample script that uses the PnP.PowerShell module to create the site collection app catalog:
      # make sure to install PnP.PowerShell and use PowerShell 7.x
# Install-Module PnP.PowerShell -Scope CurrentUser

# use an account that has admin permissions on the tenant app catalog site; note that even when using a tenant admin account you might have to first grant them those permissions; also, connect to the -admin endpoint, otherwise the cmdlet will complain; it also seems that you need to be SharePoint admin to make this connection, though I am not entirely sure about that
Connect-PnPOnline https://contoso-admin.sharepoint.com -Interactive
# this adds the site collection app catalog; note that it can take a couple of minutes until this is fully functional, but it might also work instantly
Add-PnPSiteCollectionAppCatalog -Site "https://contoso.sharepoint.com/sites/wikipakk-staging"
  3. The Site Contents of the staging site should now show the Apps for SharePoint library:

    Add account to site collection administrators of the tenant app catalog.

Troubleshooting

If you don’t connect to the -admin endpoint, or miss permissions on that level, the following error will be shown:

Add-PnPSiteCollectionAppCatalog: Unable to connect to the SharePoint Online Admin Center at ‘https://contoso-admin.sharepoint.com’ to run this cmdlet. Please ensure you pass in the correct Admin Center URL using Connect-PnPOnline -TenantAdminUrl and you have access to it. Error message: Attempted to perform an unauthorized operation..

If you lack permissions on the tenant app catalog site the following error will be shown:

Add-PnPSiteCollectionAppCatalog: Attempted to perform an unauthorized operation.

Here’s how to add an account to the tenant app catalog site’s admin list:

Add account to site collection administrators of the tenant app catalog.

Step 2: Install the current WikiPakk package to the staging site

We need to get the current WikiPakk app package to add it to the staging site.

  1. Open the tenant app catalog site
  2. Open the Apps for SharePoint library in the tenant app catalog site
  3. Download the current version of WikiPakk:

    Add account to site collection administrators of the tenant app catalog.

    Note: this downloads a WA200005439.cab file
  4. Extract the cab file you downloaded in the previous step; it contains a single sppkg file like f82ae112018660069bacdf301eca7f1c.sppkg
    • note: a cab file is an archive like a zip file; the cab file format is mostly used by Microsoft; you might need additional tools to extract that cab file, depending on your operating system
  5. Open the staging site
  6. Open the Apps for SharePoint library in the staging site
  7. Deploy the sppkg file to the Apps for SharePoint library:

  8. Check that the Enabled column shows Yes, the Deployed column shows Yes, and the App package error message column shows No errors.

Step 3: Add WikiPakk to the staging site

Now that WikiPakk has been deployed to the “local app store” (the site collection app catalog), the app can be added to the staging site.

  1. As site owner, open the home page of the staging site
  2. Click the + New button, then click App to add an app
  3. You now have two WikiPakk apps to choose from: one with a proper app icon (from the tenant app catalog) and one with a generic icon (from the staging site); click Add for the WikiPakk app with the generic icon:

  4. Now wait a minute and go back to the staging site’s home page
  5. The Page Tree button should be visible in the upper right corner; click that Page Tree button to expand the page tree panel, then click the ? in the page tree panel to have a look at the WikiPakk version:

Good, we are now ready to update.

Step 4: Get the latest WikiPakk release from AppSource

The site collection app catalog does not allow us to update the app from AppSource. We thus have to get the lates WikiPakk app package ourselves.

  1. Enter the following address in your browser address bar and press Return: https://addinsinstallation.store.office.com/app/download?assetid=WA200005439
    • note: this address is the same address SharePoint uses to get the latest release when updating the app in the tenant app catalog
    • note: this should download a cab file like Roq9de20691-b34e-410d-a96c-641f230268e9_f82ae112018660069bacdf301eca7f1c.cab
  2. Proceed with this cab file as described in above section Step 2: Install the current WikiPakk package to the staging site, steps 4 to 8; you’ll extract the cab, get a sppkg, upload that to the app catalog and deploy the app

Check that the app has a new version:

Now check the page tree version as well:

That’s it. That was the update. You can now test the update in the staging site.

Note about subsequent updates

Once the staging site is in place, you can reuse it for subsequent updates. This means that above steps 1 to 3 don’t have to be repeated. It’s just step 4 - the actual update - that has to be done.

But you can always discard the staging site and start from scratch.

Wrap-up

In this article we prepared a staging site for WikiPakk updates.

We downloaded the current (old) release of WikiPakk that is currently installed in the SharePoint tenant app catalog. We installed this old release in the staging site.

We then downloaded the latest WikiPakk release from AppSource and updated the WikiPakk app in the staging site.

As result, we have an updated WikiPakk app in the staging site. All other sites in the tenant still use the old WikiPakk releaes from the tenant app catalog.

This allows us to test WikiPakk updates in the staging site before rolling it out to the whole tenant.

6.1.4 - Rolling back an update of WikiPakk

How to roll back an update of WikiPakk

Rolling back an update

You can easily roll back an update and revert to a previous version.

In the SharePoint tenant app catalog, open the Apps for SharePoint library. This library has versioning enabled.

Find the WikiPakk app in the library and revert it back to a previous version, using the out-of-the-box SharePoint version history.

The rollback is effective immediately for all sites WikiPakk has been added to.

6.1.5 - Inventorize WikiPakk

How to get a complete list of sites that use WikiPakk

There is a script for that in the library: WikiPakkInventory.ps1.

This script will check all sites for WikiPakk.

6.2 - WikiPakk Licensing

How to license WikiPakk

Licensing WikiPakk follows this pattern:

  1. purchase a subscription, immediately get a license key
  2. choose or create one or more SharePoint sites to store the license key in
  3. make sure WikiPakk can reach the licensing server to keep the license key fresh

Above steps are covered in more detail in the sections below.

How to get a license key

Purchase a license via the Pricing page.

The license key is displayed in the browser after purchasing and is sent via email as well.

The license key looks like this:

-----BEGIN V2 LICENSE-----
eyJhcGciOiJSUzI8NiisInR5cCI6IkpXVCJ9.eyJ3dHYiOiIxIiwiaXNzIjoiaHR
<snip>
GNLn6lkQTtZw4mG16h8Mz6RvxlZMHq_861O80PE0oerk2oDSX-0E0
-----END V2 LICENSE-----

Where to store the license key

You store the WikiPakk license key in SharePoint. It is kept fresh by WikiPakk (more on that in section “How are license keys refreshed”).

After receiving the license key you have three options where to store it in SharePoint. Choose one:

  1. in all sites WikiPakk will be added to
  2. in one dedicated configuration site (more on that in section “How to dedicate a specific site to store the WikiPakk license key”)
  3. in one well-known configuration site under the URL /sites/WikiPakkConfiguration (you have to create that, use a communication site)

Note: Option 2 and 3 are available as of WikiPakk v2.3.0 (released in June 2023).

Ideally you choose one option, although you can combine them.

WikiPakk searches for a license key in the exact order of above list. First in the local site, then it looks in a site you may have dedicated, then it looks in the WikiPakkConfiguration site, if that exists.

WikiPakk uses the first license key it finds.

In any of those sites, you store the license key in the Description field of the Site Pages document library. This is a quick and easy place to store the license key at, and it is always present.

The next section describes in detail how to store the license key.

How to store the license key in the right place

The following instructions apply to any of the sites you might decide to store the license key in. This means, you follow those steps either in

  1. all sites WikiPakk has been or will be added to, or
  2. one dedicated configuration site you choose, or
  3. the default configuration site /sites/WikiPakkConfiguration

As owner of such site, do the following to store the license:

  1. In a browser, open the SharePoint site
  2. Copy the license key to the clipboard (note: the license key is everything from —–BEGIN V2 LICENSE—– to —–END V2 LICENSE—–, including those delimiters)
  3. Open the Library Settings of the Site Pages library
  4. Find the place to edit the Description of the Site Pages library
  5. Paste the license key into the Description edit field
  6. Choose to Save
  7. Reload open pages that show the WikiPakk page tree or breadcrumb

WikiPakk should recognize first-time license keys pretty fast, and manually updated keys within 24h.

Above steps are also covered in this video:

What if a license key is missing or expired

If no license key can be found, or the license key has expired, a red warning is shown above the page tree, stating that no valid license key could be found.

How are license keys refreshed

The license key is bound to a flexible subscription that can be cancelled on a monthly or yearly basis, depending on the subscription type you chose.

Let’s assume a monthly subscription.

The license key is valid for one month and needs to be refreshed after roughly one month.

WikiPakk takes care of refreshing the license key. When the expiration date is near it will ask a licensing server to exchange the old license key with a new one. The licensing server checks that the subscription is still valid and if it is, returns a refreshed license key that is valid for another month.

How to manually refresh the license key

You might want to manually refresh the license key in case you won’t allow WikiPakk to contact the licensing server.

Here’s a PowerShell that asks for a refreshed license:

$licenseKey = "-----BEGIN V2 LICENSE-----
eyJhcGciOiJSUzI8NiisInR5cCI6IkpXVCJ9.eyJ3dHYiOiIxIiwiaXNzIjoiaHR
<snip>
GNLn6lkQTtZw4mG16h8Mz6RvxlZMHq_861O80PE0oerk2oDSX-0E0
-----END V2 LICENSE-----"
$subscriptionId = "ucpD<snip>YpQMw"

$body = @{ LicenseKey = $licenseKey} | ConvertTo-Json

$result = $null
$result = Invoke-RestMethod -Method Post -Uri "https://graph.wikitransformationproject.com/v1.0/wikipakk/subscriptions/update?subscriptionId=$subscriptionId" -Body $body -ContentType "application/json"
$result.LicenseKey

If you don’t have the subscription ID handy, open https://jwt.ms and paste the license key part between —–BEGIN V2 LICENSE—– and —–END V2 LICENSE—– into the input field.

The decoded license key should now show the subscription ID as subscription:

Decoded WikiPakk license

How to dedicate a specific site to store the WikiPakk license key

Here is how you dedicate a SharePoint site of your choosing to store the WikiPakk license key.

You point WikiPakk to the dedicated SharePoint site via a SharePoint storage entity (a.k.a tenant property).

One option to set a storage entity is via PnP PowerShell.

You need:

  • PowerShell 7
  • with the PowerShell module PnP.PowerShell installed
  • a user account that is in the Owners group of the tenant app catalog site (or site collection admin there)

Here’s a script that will connect to SharePoint and set the storage entity used by WikiPakk:

Connect-PnPOnline `
    -Url https://yourcompany.sharepoint.com `
    -Interactive # ^ use any other site if you don't have access to the root site
Set-PnPStorageEntity `
    -Key "wikipakk.licensesiteurl" `
    -Value "https://yourcompany.sharepoint.com/sites/it-configuration-site" `
    -Description "WikiPakk configuration, where to find the current license key" `
    -Scope Tenant
# Get-PnPStorageEntity # <- use this to list all configured storage entities

Above script instructs WikiPakk to look for the license key in site https://yourcompany.sharepoint.com/sites/it-configuration-site.

6.2.1 - WikiPakk License Key Lookup and Refresh Flow

This articles shows how WikiPakk searches for and refreshes its license key.

WikiPakk license keys have a validity period. This might be a month or a year, depending on the subscription you are on.

License keys initially have a start and end date baked in and expire at their end date.

Expired license keys need to be refreshed.

When the validity period ends, WikiPakk needs to refresh the license key, usually by connecting to a licensing server. A refreshed key can also be provided manually if connecting the licensing server is not allowed.

The license key refresh flow in a nutshell looks as follows:

  1. Can WikiPakk find an up-to-date, non-expired license key somewhere in the local browser/SharePoint environment?
    • Good: use that. Done.
      Note: The license key that is stored in SharePoint can be updated at any time manually, which would be on a monthly or yearly basis. This can be automated, get in touch if you want to know details on how to automate that.
  2. Can WikiPakk find a expiring or expired license key available, at any location where a license key could be stored?
    • No problem. WikiPakk contacts the licensing server, shows the old license key, and gets a refreshed one that is valid for another period; that is, if the subscription is still active.
      Note: this does only work if there had been a license key configured before, that is now about to expire or is already expired.

Here is the detailed flow:

6.3 - WikiPakk Page Tree Quick Start

How to get started with the page tree

Add the WikiTraccs WikiPakk app to the site:

Note: your SharePoint admin has to add the app package to the tenant app catalog for the app to show up.

That’s it, the page tree now works.

And here is the page tree editor web part in action:

Use this web part to order the pages. The page tree will show the new order immediately.

6.4 - WikiPakk Features

What can you expect from WikiTraccs WikiPakk?

What does WikiPakk provide?

WikiTraccs WikiPakk add the following productivity-enhancing functions to the SharePoint modern pages experience:

  • a hierarchical page tree for SharePoint pages
  • a breadcrumb above every page providing quick context
  • a page tree editor to reorder pages

Zero configuration necessary. No content types or fields need to be added. Add the app to any site and breadcrumb and page tree will appear, ready to be used.

A horizontal bar will be added to the top of the site, showing a breadcrumb and a “Page Tree” button. When opening a SharePoint modern page, the breadcrumb will show its position in the configured page hierarchy. An SPFx application customizer is responsible for adding the top bar.

Selecting the “Page Tree” button will slide out a panel from the right, showing all modern pages. The pages are shown as tree, according to the configured page hierarchy.

The “WikiTraccs WikiPakk Page Tree Editor” web part is used to configure the page hierarchy. The web part can be added to any modern page. It shows all modern pages of the site. Those pages can be moved around by drag and drop, forming a hierarchy of pages. Breadcrumb and page tree will reflect the configured hierarchy.

The page tree is compatible with pages that were migrated by WikiTraccs. The migrated Confluence hierarchy just works with the WikiPakk page tree.

New, vanilla SharePoint pages can be added as well. All can be reordered.

6.5 - WikiPakk Topics

Topics around the WikiPakk page tree for SharePoint

6.5.1 - Inaccessible Pages

What does it mean if a tree node says ‘inaccessible page’?

You might see nodes in the tree that say inaccessible page, like here with inaccessible page 47:

Where do they come from?

There are two sources: deleted pages and pages that the current user is not allowed to see.

Deleted pages

Deleting pages can make tree nodes show the inaccessible page placeholder.

Consider the following page tree:

Note the Projects page that has two child pages: Project Bar and Project Foo.

Now we delete the Projects page (that has the SharePoint item ID 47):

The tree now cannot get information about that page anymore. However, it still knows where the page used to be in the hierarchy of pages.

To maintain the configured hierarchy of pages, the tree shows a placeholder inaccessible page 47 where the page used to be:

The child pages are still being shown at the correct position.

If we restore the Projects page from the recycle bin the tree will again show its title and link to the page:

Note that WikiPakk cannot know if a page has been deleted or if a page is not accessible due to missing permissions.

Pages with unique permissions

Consider the following page tree:

What happens if a user cannot access the Projects page? This is the case when the page has its permission hierarchy broken, unique permissions set, and the current user is not allowed to view the page.

For the current user, the tree will look like this:

For other users, the tree will look differently, depending on their access level.

Note that WikiPakk cannot know if a page is not accessible due to missing permissions or if it has been deleted.

SharePoint works differently than Confluence

If you know the page tree from Atlassian Confluence, you won’t know this issue of inaccessible pages.

In Confluence, if you are not permitted to access a page, you also cannot access its child pages.

In Confluence, if a page is deleted, the child pages won’t exist anymore.

Pages work differently in SharePoint.

In SharePoint, when deleting a page, its child pages in the Site Pages library and in the WikiPakk page tree still exist.

In SharePoint, when restricting access to a page, child pages might still be accessible for the current user.

Thus WikiPakk has to cope with a situation where in the midst of the page tree certain pages might be inaccessible.

Those pages will be represented as inaccessible page.

Handling inaccessible pages

There are some strategies to handle those pages.

Remove those pages via context menu

Note: this option is available as of WikiPakk 2.5.1. Update now.

Use the mouse to hover over the inaccessible page. Click the three dots to open the context menu. Click Remove from tree.

This removes hierarchy information for this page from the WikiPakk hierarchy table. All children of this page will be moved one level up.

The resulting tree looks like this:

Move inaccessible pages to a dedicated node

Use the WikiPakk page tree editor web part to move the inaccessible page away:

Note: the Deleted node in above image is a dummy page that has been created to serve as parent for inaccessible page nodes.

Out of sight, out of mind.

If the inaccessible page has child pages, you might want to move those to another parent node. In our sample those are the Project Bar and Project Foo pages, which have been moved to Home.

Advanced: Delete hierarchy information for inaccessible pages

You can make the inaccessible pages disappear completely by deleting their hierarchy information.

WikiTraccs stores hierarchy information for pages in a hidden list. This list exists in every site WikiPakk has been added to.

Open WikiPakk’s hidden hierarchy list by appending Lists/WikiTraccsPageTree to the SharePoint site root address, like so: https://contoso.sharepoint.com/sites/pagetreedemo/Lists/WikiTraccsPageTree.

Build this root address for your site and enter it into the browser address bar.

Locate the inaccessible page ID in the WtPId column, here 47.

Delete the list item.

The inaccessible page 47 is now gone from the tree.

Usability outlook

There are features currently being worked on that will improve handling for deleted pages:

  • ✅ done: manual option to remove inaccessible page nodes from the tree via their context menu
  • detection of deleted pages by looking in the recycle bin - this would allow removing some of the inaccessible page nodes automatically

6.6 - WikiPakk FAQ

Frequently Asked Questions (FAQ) about the WikiPakk Page Tree for SharePoint

This FAQ covers questions folks have while evaluating and using WikiPakk.

Note that this covers questions solely related to WikiPakk, but also questions related to WikiPakk in the context of a Confluence to SharePoint migration - which was the genesis of WikiPakk.

Q: Does WikiPakk work with “normal” SharePoint pages?

A: Yes. Each SharePoint site owner can decide to add the WikiPakk app to their site to allow users to organize pages.

Q: We would like to know why WikiPakk is set as a subscription model, as we will do the Confluence to SharePoint migration once.

A: WikiPakk provides value even after the migration.

Immediately after the migration, it will be useful because it picks up and displays the migrated page hierarchy. Users have an easier time finding their pages.

Over time, new SharePoint pages will be added, and the hierarchy needs to be adjusted. Since the page tree comes with an editor, users can just do that. Move pages around in the tree, change the hierarchy, organize knowledge. New SharePoint pages will be added at the right place in the hierarchy, just like in Confluence.

But WikiPakk also provides value for SharePoint users working in regular sites, that have no migrated pages in them. WikiPakk is fully compatible with out of the box SharePoint pages. SharePoint has no built-in way of organizing pages in a flexible hierarchy. The built-in SharePoint menus need to be updated manually and are limited to 2 or 3 levels of nesting. That’s where WikiPakk can help. Each site owner can decide to add it to their site. New pages will be shown in the page tree automatically, ready to be organized in just the right way.

Then there is Microsoft, constantly changing and evolving SharePoint Online, and WikiPakk has to keep up - which is a justification of the subscription model.

Given all that, many WikiTraccs users decide to add WikiPakk to the mix to at least ease the transition from Confluence to SharePoint.

Note that you can at any time cancel the subscription, I won’t hound you. Either it provides value, or it doesn’t. You decide (and hopefully give me some feedback).

Q: I was wondering if you offered a trial of the WikiPakk SPFx solution?

A: You can install WikiPakk from Microsoft AppSource and try it in trial mode. It’ll display a note that it cannot find a license but is otherwise fully functional.

Further reading:

6.7 - Troubleshooting WikiPakk

What if something doesn’t work with WikiPakk?

Which version of WikiPakk am I using?

Click the Page Tree button to open the page tree panel.

In the panel, scroll down (if necessary) until you see the question mark (?) link.

Click the question mark (?) link to open the About dialog.

The about dialog shows the version (sample: 2.7.0.0 & 2.7.0).

Diagnosing issues in the page hierarchy

The SharePoint page tree gets hierarchy information from different sources, depending on whether it is showing regular SharePoint modern pages, or pages that have been migrated from Confluence to SharePoint.

For the hierarchy to work there need to be:

  • modern SharePoint pages
  • a page ID per page
  • a parent page ID per page

The page tree might be incomplete if any of those is missing.

Checking the hierarchy for pages that have been migrated from Confluence to SharePoint

Let’s assume the parent page of a page is missing in the page tree.

First, open the “aggregated-info” progress log files for the Confluence space this page was in and check that all pages have been migrated. If there are pages yet to be migrated, migrate them and check back if the page tree looks good after doing that.

If the issue persists, continue.

To diagnose the issue we first need to find out if the parent page has been migrated yet.

Open the page, whose parent page is missing, here it is arc42:

The Confluence page ID is part of the page URL. Copy this page ID. In the screenshot this is 2293795.

We are now going to look up the parent page ID and parent page.

Open the Site Pages library. Make sure to add the columns Confluence: Id (WikiTraccs) and Confluence: Parent Id (WikiTraccs) to the current view.

Filter the column Confluence:Id (WikiTraccs) for the page ID, here 2293795:

In the screenshot above the parent page ID is zero (0), which indicates this is a root page that has no parent page. This was the root page of a Confluence space. Note that there can be multiple such root pages per space.

Everything is fine in this case.

But imagine the parent page ID being 123456. If this was the case, do the following: filter the Confluence: Id (WikiTraccs) column for the parent page ID (here: 123456), to find the parent page.

Can no such parent page be found? The page has not yet been migrated and the tree is correctly showing no parent page. In this case, migrate the missing page.

Can the parent page be found? The page tree should display it. There might be an issue with the page tree if the parent page exists, but is not shown in the page tree. In this case, copy the log (see next section on how to do this), and send the log, the page ID, the parent page ID and the progress log files for the space to [email protected] for further diagnosis.

Export the page hierarchy for further diagnosis

In the page tree panel, click the question mark to open the About dialog:

In the About dialog, click Page tree diagnostics to expand the section, then click Collect diagnostic information.

Now text should appear in the text box. Copy all this text and send it to support upon request.

How to get and copy the WikiPakk logs from the Browser console

The log can be found in the browser console.

To view and copy the log of the SharePoint page tree and breadcrumb follow these steps:

  1. open the Chrome browser
  2. open a modern SharePoint page where the page tree misbehaves
  3. open the Chrome developer tools: choose the three dot menu in the upper right corner, then More tools, then Developer tools; or simply press the F12 key
  4. the developer tools panel opens
  5. choose the Console tab
  6. enter wikipakk in the search box
  7. choose the levels drop down
  8. select all levels, including Verbose

Developert tools, showing log entries of WikiPakk

  1. reload the page, for example by pressing the F5 key

The console should now show lots of log entries from WikiPakk, like in above screenshot.

When being asked for, copy all those log entries and send them to [email protected].

6.7.1 - Troubleshooting WikiPakk License Issues

What if the “Could not find a valid license” message is shown despite having a valid license key in place?

How applying the WikiPakk license is supposed to work

After installing WikiPakk and adding it to a site it will show a red banner with the message Could not find a valid license, which is correct since there is no license, yet.

After purchasing a license for WikiPakk you’ll receive a license key.

The license key needs to be stored in a place in SharePoint where WikiPakk can find it. There are multiple options for storing the license key which are documented in this article: WikiPakk Licensing.

Click the Retry link in the red box and the red box should disappear.

Make sure to test with at least one regular user account that for them the red box also disappears to rule out permission-related issues.

Read further if the red box and note do not disappear.

What if WikiPakk cannot find the license?

If some users still see the red box with the Could not find a valid license message then for some reason WikiPakk cannot either find the license in any of the supported places, or cannot refresh the license.

WikiPakk allows to troubleshoot that.

We’ll open the browser’s developer tools to access the WikiPakk log messages. The log contains information about each step WikiPakk makes.

Here’s how to access the log via the Chrome browser’s developer tools:

Note: The Edge browser provides a similar way to access the developer tools, although the menu options you have to select differ a bit.

Above animation shows the following:

  1. in Chrome browser, have a SharePoint site open where WikiPakk is installed
  2. expand the Page Tree to view the red licensing error
  3. click the Retry link to check if WikiPakk can refresh the license; it can’t
  4. open Chrome’s developer tools via Three Dot Menu -> More tools -> Developer Tools
  5. in the Console section of the developer tools, enter wikipakk license into the search box; WikiPakk licensing-related log messages are shown
  6. the log messages are selected and can be copied and pasted, e.g. to support emails

What do those log messages mean?

You might be able to figure out what’s wrong on your own. The following sections provide information about commonly encountered log messages.

License found in memory

[LicenseProcess] Using memory-cached license info

There is a cached license available in memory. Reloading the page in the browser clears the memory cache.

Valid license found in local storage

[LicenseProcess] Found license in local storage, good (valid from Wed Jun 19 2024 09:21:15 GMT+0200 (Central European Summer Time) to Fri Jul 19 2024 09:21:15 GMT+0200 (Central European Summer Time))

WikiPakk found a valid license in the browser’s local storage. This should be a regular case.

Cooldown mode

[LicenseProcess] Got no license in local storage, need to retrieve one
[LicenseProcess] Last license check was 16.7949 minutes ago, cooldown is 120 minutes
[LicenseProcess] We are in license check cooldown mode

When no license can be found or needs to be refreshed, WikiPakk will try to find or refresh one every so often.

After each check WikiPakk goes into cooldown mode, so it might take a couple of hours for a newly stored license to be picked up automatically.

You can manually force a check at any time, though. Click the Retry link in the red box. This forces a license key lookup and ignores the cooldown mode.

No license found at all


[SharePointLicenseSource] Description field of Site Pages library is empty
[LicenseProcess] Current site has no license configured
[SharePointLicenseSource] Looking up tenant property wikipakk.licensesiteurl
[SharePointLicenseSource] Tenant property wikipakk.licensesiteurl has value: {"odata.metadata":"https://contoso.sharepoint.com/sites/it-config-site/_api/$metadata#Edm.Null","odata.null":true}
[LicenseProcess] Configured dedicated site has no license configured.
[SharePointLicenseSource] Trying to get license info from default site WikiPakkConfiguration
[SharePointLicenseSource] Determined URL of potential default site: https://contoso.sharepoint.com/sites/it-config-site
[SharePointLicenseSource] Trying to get license info from site https://contoso.sharepoint.com/sites/WikiPakkConfiguration
[SharePointLicenseSource] Trying to get license info from Site Pages library
POST https://contoso.sharepoint.com/sites/WikiPakkConfiguration/_api/contextinfo 404 (Not Found)
[SharePointLicenseSource] Got an exception when connecting to the other web at 'https://contoso.sharepoint.com/sites/WikiPakkConfiguration': Error: Error making HttpClient request in queryable [404]  ::> ; check the tenant property 'wikipakk.licensesiteurl'
[LicenseProcess] Default site has no license configured.
[LicenseProcess] Could not find a license that is either valid or not near expiration

No license can be found. This is the case initially, right after adding WikiPakk to a site.

WikiPakk tries every location where a license might be found:

  1. local site, Site Pages description field
  2. site configured via tenant property wikipakk.licensesiteurl, Site Pages description field
  3. well-known WikiPakk config site /sites/WikiPakkConfiguration (if it exists), Site Pages description field

The log shows each of those steps.

Expired license needs a refresh

The logs will show the need to refresh an expired license key and the result of this operation.

6.8 - Legacy: Confluence Page Hierarchy

This article covers how migrated page metadata from Confluence can be used to build a page tree.

The WikiTraccs Page tree shows a page tree like in Confluence.

Example of the page tree showing SharePoint pages in a hierarchical fashion.

Additional Site Pages Library Columns

SharePoint stores modern pages in the Site Pages Library.

WikiTraccs creates modern pages in the Site Pages Library as well.

Additional columns must be added to the Site Pages Library for the page tree to work.

Display NameInternal NameTypeNotesSample Value
Confluence: Id (WikiTraccs)WT_In_CfContentIdSingle line of textConfluence page ID118587460
Confluence: Title (WikiTraccs)WT_In_CfTitleSingle line of textConfluence page titleDemo Page
Confluence: Parent Id (WikiTraccs)WT_In_CfParentIdSingle line of textID of parent page (0 for the top-most pages)118587459
Confluence: Parent Id Chain (WikiTraccs)WT_In_CfParentIdChainMultiple lines of textChain of all parent IDs, starting with top-most, diving down to the right; using ;# and ;#;# as delimiters like in the sample value (None;#0 for top-most pages)Page;#118587415;#;#Page;#118587459
Confluence: Space Key (WikiTraccs)WT_In_CfSpaceKeySingle line of textSpace keyWTD
Confluence: Space Name (WikiTraccs)WT_In_CfSpaceNameSingle line of textSpace nameWikiTraccs Demo Space
Confluence: Sibling Order (WikiTraccs)WT_In_CfSiblingOrderNumberOrder in the page tree, lower numbers come first1

Create those columns via the Library settings of the Site Pages library.

When creating the columns, in the Column name input, enter the Internal name as stated in the table above. This is the only way to properly set the internal name in the browser.

The configuration of the Site Pages library now shows the added columns:

Column have been added to the Site Pages library.

In a second step, you can rename the columns.

Page Metadata

The page tree automatically picks up any metadata in the Site Pages Library.

Let’s manually enter metadata for some pages:

Page Metadata for the WikiTraccs Page Tree

Open or reload a page with metadata.

Now a breadcrumb should appear that looks like this:

WikiTraccs Page Breadcrumb

Selecting the page tree icon right of the breadcrumb opens the page tree:

WikiTraccs Page Tree

7 - Purchasing

Information about purchasing products of the Wiki Transformation Project.

How to purchase?

Purchases are initiated via checkout forms linked on the product’s web sites and from quotes.

For WikiTraccs, the Confluence to SharePoint Migration Tool, choose the Proceed to checkout option on the WikiTraccs Pricing page.

For WikiPakk, the Page Tree Experience, choose the BUY NOW option on the WikiPakk Pricing page.

If you received a quote link or PDF, use the checkout link in the quote.

Merchant, Biller

We use the e-commerce platforms FastSpring and Lemon Squeezy to handle billing, payments, taxes, and subscription management.

Those platforms are sometimes referred to as merchant of record. They’ll act as invoicing party.

The checkout forms on the web site use FastSpring.

Pricing

Prices are listed on the product’s pricing pages.

For WikiTraccs, the Confluence to SharePoint Migration Tool, see WikiTraccs Pricing.

For WikiPakk, the Page Tree Experience, see WikiPakk Pricing.

Common Questions

Can I get a quote?

Yes. Please provide your billing information (name, email, company name, address, and tax ID if applicable) via email ([email protected]).

Make sure to include the license tier (page count tier for WikiTraccs, number of licensed SharePoint users for WikiPakk) as well.

Can I get a form W-8 or form W-9?

Yes. You need the W-9 of either FastSpring or Lemon Squeezy. For FastSpring this is available here for download: W-9.

Can I create a tax-exempt order (e.g. as state entity)?

Yes. To create a tax-exempt order the following information is required:

  • a document proving the tax-exempt status, e.g. form ST-119.1
  • recipient information: email, first name, last name, billing address

Please get in touch via email to have the order created.

Can I get a refund?

No. For WikiTraccs, please use the trial version of the WikiTraccs Confluence to SharePoint migration tool to check if it suits your needs. The trial version is free and no credit card or sign-up is required for testing.

For WikiPakk the same applies. Get it from App Source and test until you are convinced.

Are educational discounts available?

No, there are currently no educational discounts to offer.

Can I get an invoice?

Yes, you can download the invoice after purchasing.

Alternatively you can get in touch via email to have a custom order created and an invoice generated.

Can I get the invoice updated?

Yes. Please get in touch via email.

What are the available purchase methods?

See above section How to purchase? and How to purchase as or via a third party?.

Which payment methods are available?

Available payment methods are depending on the e-commerce platform, the region, and the currency. FastSpring is the main e-commerce platform used by the Wiki Transformation Project.

When checking out, the following payment methods are available in most regions:

  • Credit Cards
  • PayPal Checkout
  • Wire Transfer*

Additional payment methods may be available, like PayPal, Amazon, Check, or Money Order. For FastSpring, see a complete list here: Payment Methods accepted by FastSpring.

Note that not all payment methods are available for recurring payments with automatic renewal. Please get in touch if automatic renewal is an issue.

*) Note that for wire transfers unique banking information will be created for each order.

What are your payment terms?

Payment due 14 days after invoice receipt. The license key is sent immediately after the payment has been received.

When using the online checkout form, the invoice is generated upon checkout.

How to purchase as or via a third party?

Licenses are always bound to a specific client. The purchase can be made by a third party.

As a third party, you should follow the purchasing instructions outlined in the How to purchase section.

When requesting a quote, or after purchasing a license for a client, please provide the following details via email to [email protected]:

Buyer Details - when requesting a quote, or enter on checkout:

  • Name
  • Email
  • Company Name
  • Address
  • Tax ID (if applicable)

Client Details - after the purchase:

  • Name
  • Email
  • Company Name
  • Address
  • Transaction ID / invoice #

Partnership

Before discussing partnership terms and special pricing, we recommend securing 10 sales/yr for your clients to assess the fit and demand. Once achieved, we’ll be delighted to explore a mutually beneficial partnership.

Reselling

As a reseller the section How to purchase as or via a third party? applies.

Please find answers to specific questions below.

May we purchase on behalf of PARTY-A via a reseller (PARTY-B) for PARTY-C?

Yes, see above section How to purchase as or via a third party?.

Must mandatory agreements be signed?

No, but the Terms of Service must be accepted.

Is there channel discount that will be included? Can we get a coupon code?

Yes, starting with a specific number of purchases. The same conditions as in above section Partnership apply.

What is the delivery method?

WikiTraccs is provided as software download via GitHub.

WikiPakk is distributed as software download via Microsoft App Source.

Clients can download products at any time, with or without a license. Unlicensed products act as trial version.

Does the software auto-renew?

No, for WikiTraccs, the license does not auto-renew.

Yes, for WikiPakk, the subscription auto-renews every month or year (depending on the billing cycle chosen), until canceled.

Subscription-related terms as per the Terms of Service:

6.3.3 Automatic Renewal Terms: Once Customer subscribes, E-Commerce Platform will automatically process a subscription fee in the next billing cycle. E-Commerce Platform will continue to automatically process the subscription fee according to the chosen plan’s then-current rate, until Customer cancels their Subscription.

6.3.4 Cancellation Policy for Subscription: Customer may cancel their Subscription at any time by following the cancellation procedures of E-Commerce Platform. If Customer cancels their Subscription, the cancellation will take effect for the next billing cycle. If Customer cancels their Subscription, they can re-subscribe any time.

Are there additional mandatory costs, subscriptions, over usages or charges?

No, apart from the license costs there are no additional charges.

7.1 - Invoice and Wire Transfer (using FastSpring)

This article describes how to generate an invoice from a quote and how to initiate the payment.

Accepting the quote

Starting from a quote, you click Accept & Continue “button”.

Note: The quote might be localized to your language.

After clicking Accept & Continue in, you are presented with the option to pay immediately or create an invoice.

Generating the invoice

Select the Invoice option, as we want to create an invoice:

Click Generate invoice to create both order and invoice.

This should take you to a dialog that confirms your order:

Click View Invoice to open the invoice.

Viewing the invoice

The invoice looks a bit like the quote.

You can now forward that invoice to the purchasing department. You can either send a link to the invoice, or download it using the download button in the upper right corner:

Click Pay Now to select a payment method.

Selecting a payment method

Select from available payment methods; here Wire Transfer has been selected:

Click Pay to get instructions for wire transfer. Those will include the bank details that are provided by FastSpring.

You can also choose any of the other available payment methods.

You will also receive an email:

Thank you for your purchase!