This is the multi-page printable view of this section. Click here to print.
WikiTraccs Documentation
- 1: Getting Started
- 2: Migration Process and Use Cases
- 2.1: Migration Playbook
- 2.2: Recipes
- 3: WikiTraccs Features
- 4: WikiTraccs Reference
- 4.1: How does WikiTraccs work?
- 4.2: WikiTraccs License Activation
- 4.3: WikiTraccs FAQ
- 4.4: Prerequisites
- 4.5: Installation and Update
- 4.6: Settings & Configuration
- 4.6.1: Configuration via WikiTraccs.GUI (blue window)
- 4.6.2: Confluence Space Inventory
- 4.6.2.1: How to map Confluence Source Selectors to SharePoint Sites
- 4.6.2.2: How to migrate Confluence Content using Space Selectors
- 4.6.2.3: How to migrate Confluence Content using CQL Query Selectors
- 4.6.2.4: How to migrate Confluence Content using Content ID Selectors
- 4.6.3: Configuration via Configuration File
- 4.6.3.1: Sample Configurations
- 4.7: Migration Samples
- 4.8: Monitoring Confluence to SharePoint Migration Progress - Overview
- 4.8.1: Monitoring Per Page Progress
- 4.8.2: Monitoring Per Selector Progress
- 4.8.3: Live Progress Indicators
- 4.9: Known Confluence Macros
- 4.10: Security
- 4.10.1: Data Storage and Transmission
- 4.10.2: Endpoint reference
- 4.11: Using WikiTraccs.GUI
- 4.11.1: Source Configuration
- 4.12: Authentication
- 4.13: Confluence Inventory
- 4.14: Updating Previously Migrated Pages
- 4.15: Migration Waves
- 4.16: File Storage
- 4.17: Glossary
- 4.18: Multilingual Pages
- 4.18.1: Info about Scroll Translations
- 4.18.2: Migrating all Languages to one SharePoint Page
- 4.18.3: Migrating to Multilingual Pages in SharePoint Online
- 4.19: WikiTraccs GUI vs. WikiTraccs Console
- 4.20: Known Issues and limitations
- 5: Troubleshooting
- 5.1: Connectivity Issues
- 5.2: Authentication Issues
- 5.3: Logging
- 5.4: Troubleshooting Strategies
- 5.5: Troubleshooting FAQ
- 5.6: Support Options
- 5.7: Error Messages
- 5.8: Common Warnings and Errors in Log Files
- 6: WikiPakk Reference
- 6.1: WikiPakk Installation and Ops
- 6.1.1: Install WikiPakk
- 6.1.2: Update WikiPakk
- 6.1.3: Update WikiPakk (staged)
- 6.1.4: Rolling back an update of WikiPakk
- 6.1.5: Inventorize WikiPakk
- 6.2: WikiPakk Licensing
- 6.3: WikiPakk Page Tree Quick Start
- 6.4: WikiPakk Features
- 6.5: WikiPakk Topics
- 6.5.1: Inaccessible Pages
- 6.6: WikiPakk FAQ
- 6.7: Troubleshooting WikiPakk
- 6.8: Legacy: Confluence Page Hierarchy
- 7: Purchasing
1 - Getting Started
Only a few steps, BUT...
You need the following at hand in this guide:
- the means to authenticate with Confluence (version 6+)
- the means to authenticate with SharePoint Online
- two new SharePoint sites
- the client ID of a registered Entra ID application (How to?)
Note that all of the above is covered in the quick start video below, including an Entra ID configuration.
Quick Start Video - First Confluence Migration
Important: In the video, the PnP.Management Shell Entra ID Application is being used to authenticate with SharePoint. This is not possible anymore as Microsoft retired that application in September 2024. You have to register your own application instead.
Note: In the video, I use the wiki.hyperledger.org Confluence site for testing. They moved on to the cloud and are now on lf-hyperledger.atlassian.net/wiki. A Confluence on-prem alternative is confluence.hl7.org.
Further Reading
The Hotspots page has lots of good links to help you get up to speed with topics like what can be migrated, and how to stay up-to-date.Let’s dive in.
STEP ONE: Download WikiTraccs
Click to open the WikiTraccs download page: DOWNLOAD page.
Download the zip file.
No installation required
WikiTraccs has no installer. It is provided as portable version which means you extract a zip file and run the program.Extract the zip file - it contains two folders WikiTraccs.Console and WikiTraccs.GUI.
In the WikiTraccs.GUI folder run WikiTraccs.GUI.exe.
Unblock WikiTraccs
Windows might block WikiTraccs.GUI.exe from running, showing a blue warning message. This message shows because the file has not been signed. Unblock the file:
- Open Microsoft Windows Explorer to locate WikiTraccs.GUI.exe
- Select WikiTraccs.GUI.exe with the right mouse button and choose Properties
- Choose Unblock in the lower right corner of the resulting dialog(*)
- Select OK to close the dialog
(*) If the Unblock button or option is not present, the file is not blocked.
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.
WikiTraccs Site
WikiTraccs uses this site to store migration-related data. The site is also used to configure aspects of the migration. The site should not be used for other purposes.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.
Where to get the Entra ID Application Client ID from?
Read the blog post Registering WikiTraccs as app in Entra ID for step-by-step instructions.
Refer to Authenticating with SharePoint for more general information.
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.
Note
When chosing Personal Token as authentication type, no browser window will open. The token already combines a Confluence user identity and password, so WikiTraccs should be able to test the connection without showing a browser for login. Personal Access Tokens are available as of Confluence 7.9.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.
Something didn't work?
If something goes wrong refer to the Troubleshooting section.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.
Only one target site? No!
You can configure one default target site in the WikiTraccs.GUI user interface.
Additional target sites can be configured in the Confluence Space Inventory. The default will be used as fallback if a source selector has no target site set.
Configuring a different target site per space is possible via the WT_Setting_TargetSiteRootUrl column of the space inventory list. See How to map Confluence Spaces to SharePoint Sites for more information.
Select the Start transformation button to start the migration.
A new window opens - WikiTraccs.Console - and the migration begins.
Multiple log ins
You might have to authenticate twice because WikiTraccs.GUI first tests the connection, then hands over to WikiTraccs.Console which authenticates again.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.
Tip
To end the migration prematurely select the WikiTraccs.Console window and press Ctrl+C to shut it down. You can start it again at any time and it will resume where it left off.1.1 - WikiTraccs Hotspots
🔥 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?
- Have a look at the features page for a complete and detailled list of what can and cannot be migrated: Features.
- Get a visual insight of migration results here: Migration Samples.
- A primer on what to expect from WikiTraccs (and what not to expect) is this post: What to expect from WikiTraccs?.
- Migrating Confluence images is covered here, with great visual detail:
- Setting the right expectations regarding Confluence macros is what this blog post does: What about those Confluence Macros?
- A list of macros and how they are migrated can be found here: Known Macros.
🔥 How to migrate permissions, and metadata like page authors and dates?
- Migrating permissions is possible, although it only makes sense in some cases; more details here: Mapping principals and migrating permissions.
- Migrating page authors, editors, creation and modification dates is possible with the right permissions; this is bound to the Entra ID app registration and covered in this section: Are there alternatives to those permissions?
- How to map users and groups from Confluence to SharePoint users and groups is covered in Mapping Confluence users and groups to SharePoint.
🔥 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?
1.2 - WikiTraccs Trial 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:
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:
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:
- You purchase a license key via the Pricing page.
- 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
2.1 - Migration Playbook
Confluence to SharePoint Migration Phases - General Guidance
Note
This list is not exhaustive and shall provide inspiration for planning a migration from Confluence to SharePoint.Proof of Concept Phase
- Plan the transformation from Confluence to SharePoint
- Organize transformation workshops or whatever other format is suitable for you
- Identify workloads
- Get external help if necessary
- Focusing on SharePoint: Get to know SharePoint!
- SharePoint and Microsoft 365 can be overwhelming for technical and non-technical people alike, especially if those services are new
- Manually transform workloads from Confluence to SharePoint; involve key users to review the results in SharePoint
- When it comes to pages: play around, create SharePoint pages, use web parts, try to rebuild some Confluence pages and get to know the possibilities and limitations; WikiTraccs is also bound by those
- Test tools that integrate or migrate content
- Think about migration vs. integration for each workload
- Running a first test migration with WikiTraccs can help deciding if such migration tooling is an option
Decision
- Which workloads should be migrated from Confluence to SharePoint Online?
- Which workloads will be rebuilt manually in SharePoint? Where can a migration tool like WikiTraccs help?
Analysis Phase
- Which spaces should be migrated? (Recommendation: clean up)
- Which spaces should be migrated to which SharePoint sites?
- How many spaces are to be migrated? How many pages? How many attachments (number, size)?
- WikiTraccs does not yet have a pre-migration scan feature (feature request); insight during and after the migration is given via the migration progress log files
- those numbers can help estimating migration times, and help deciding which spaces should be migrated first - or cleaned up
- watch out for large spaces, see Migrating large Confluence spaces to SharePoint
- Do permissions need to be migrated? (Recommendation: no)
- Map Confluence use cases to SharePoint
- Define SharePoint replacements for Confluence macros (Consider how WikiTraccs handles macros)
- Define key users for spaces that check migration results in the user acceptance test phase
Test Migration Phase
- Run the test migration (see playbook below)
- User acceptance test phase (UAT)
- Let key users check the SharePoint pages that were created by WikiTraccs
- Adjust settings, mappings etc. and remigrate content from Confluence to SharePoint as needed
Production Migration Phase
- Run the production migration (same playbook as test migration)
Hypercare Phase
- Provide support to users, foster end-user adoption
Migration Playbook with Focus on WikiTraccs
The following sections focus on using WikiTraccs as migration tool.
Prepare the Confluence to SharePoint migration
Note
The following might apply to multiple environments, e.g. test and production.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
- How should Confluence pages with translations be migrated to SharePoint?
- Insert the “Page Attachments” section into SharePoint pages?
- Any macros to ignore when migrating Confluence content? See Ignoring macros when migrating pages from Confluence to SharePoint.
- …
- document the WikiTraccs settings you chose
Other
- check that key users have access to test environments
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
- Are there additional macros that need to be added to the macro ignore list? See Ignoring macros when migrating pages from Confluence to SharePoint for details.
- Check the Recent Pages (WikiTraccs) view of the Site Pages library and search for irregularities. Any pages with Failed Transformations count of 9001 need to be deleted and remigrated. See Measuring page migration success for details.
- Check that the latest migration progress log files are present for each space. Check their contents to verify that all pages have been migrated. See Monitoring Confluence to SharePoint Migration Progress for details.
- either clean up or manually migrate Confluence pages that have more than 2 MB of text content or have overly long titles, see the Known Issues page for details.
- check feedback from key users
- search the documentation and get in touch if something seems not right
Repeat as needed
Repeat the 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
2.2.1 - Find out why some pages won't migrate
Sample Situation
You have migrated a Confluence space that contains 3000 pages. Yet, when looking at the target site’s Site Pages library, you can only see 2900 pages. That’s 100 pages missing.
What’s up with those 100 missing pages? Why won’t they migrate?
What are possible root causes?
There are many reasons why pages fail to migrate. Some of them are temporary.
Here is a list of common issues:
- Connection Issues
- when downloading content from Confluence, there was a service or connection issue
- when creating a page in SharePoint Online, there was a service or connection issue and page or attachment creation failed
- Not enough Disk Space
- there is not enough disk space for WikiTraccs to download all page attachments
- “Interesting” Page Content
- a page contains content that WikiTraccs has never seen before and that it can’t handle well
WikiTraccs has mechanisms built-in to deal with some of those issues. For example, attachment upload and SharePoint page creation will be retried a couple of times to work around temporary connection issues. Missing disk space will cause the migration to be paused, until space is available again.
What to try first?
The first thing you should do is run the migration again, until the number of migrated pages stabilizes.
After the first migration run, 100 pages might be missing (for example due to unstable networking conditions). The second migration run might migrate another 50 pages. And the third migration run doesn’t change that.
Now what you are dealing with is the 50 pages that are still missing.
How to diagnose this?
The first thing we need is to look at the progress log files: Using progress log files to get insights.
Use the __30-aggregated-info progress log file to learn about the expected number of pages and the missing number of pages.
Use the __10-not-yet-migrated-pages progress log file to learn which pages are missing. This file contains page IDs that can be used to look up those pages in the common log files.
Take note that new progress log files are created with each migration run and that each space (or CQL selector) gets its own set of progress log files. So make sure to look at the most recent ones.
The ultimate tool to diagnosing why a page didn’t migrate are the common log files: Common log files.
Using the page IDs from the __10-not-yet-migrated-pages progress log file, we can look up corresponding log messages in the common log file(s) of a migration run.
Ultimately, the common log files should tell what was going on with those pages.
How to solve this?
Sometimes the common log files show something obvious, like a system being down, an authentication failing, or connection errors. This might help you inferring solutions.
But often it’s easier to send me the log files via email, for further diagnosis: [email protected].
Make sure to send the progress log files and also the common log files for a migration run.
2.2.2 - Getting a list of pages per space [on-premises]
Getting pages per space
This script returns a list of page metadata like content ID and title.
Run the following SQL script on the Confluence database. IMPORTANT: Replace MYSPACEKEY
with the key of the space you want to get the page info for:
select contentid, contenttype, title, content_status, spacekey
from content left join spaces on content.spaceid = spaces.spaceid
where (contenttype='PAGE' or contenttype='BLOGPOST') and prevver is null and content_status='current' and spacekey='MYSPACEKEY';
Note: the space key is case SeNsItIvE.
Getting the page count per space
This script returns the page count for a space.
Run the following SQL script on the Confluence database. IMPORTANT: Replace MYSPACEKEY
with the key of the space you want to get the page count for:
select count(*)
from content left join spaces on content.spaceid = spaces.spaceid
where (contenttype='PAGE' or contenttype='BLOGPOST') and prevver is null and content_status='current' and spacekey='MYSPACEKEY';
Note: the space key is case SeNsItIvE.
Getting the most recent page change per space
This script returns the timestamp of the most recently modified page or blog post for every space.
Run the following SQL script on the Confluence database.
SELECT
spaces.spacekey,
MAX(content.lastmoddate) AS most_recent_change_date
FROM
content
LEFT JOIN
spaces ON content.spaceid = spaces.spaceid
WHERE
(content.contenttype = 'PAGE' OR content.contenttype = 'BLOGPOST')
AND content.prevver IS NULL
AND content.content_status = 'current'
GROUP BY
spaces.spacekey
ORDER BY
most_recent_change_date DESC;
3 - WikiTraccs Features
WikiTraccs takes the content of each Confluence page and converts it to something SharePoint can understand.
Give it a try
This page contains a lot of theory. At the end of the day you should try it. It’s free and you can have your first test migration running in less than 30 minutes.
Or have a look at some migration samples.
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.
Links in General
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.
Links Specific to Confluence
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.
Note
Refer to this blog post for more information: Confluence Link Types Explained.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:
- correct and simplify the structure (users may create non-sensical, deeply nested behemoths)
- 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).
Jira Issue Links and Lists
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.
Note
Jira has to be up and running during the migration to get issue and issue list information. The information will be gotten in the context of the migration account for Confluence, so make sure that it has proper access.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.
Note
WikiTraccs aims to create SharePoint pages that could also be created by users in the browser. It is possible to create nested tables, merged cells and cell background colors via code - so WikiTraccs could do it. But those would be non-standard constructs (at the time of writing this).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
4.1 - How does WikiTraccs work?
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
After purchasing WikiTraccs a license key will be shown. Furthermore, an email will be sent to the email address entered into the checkout form.
Note
License key delivery time and display modalities vary between marketplaces. With the FastSpring merchant it is instant and the license key will be shown and sent via email, with Lemon Squeezy it takes up to 24 hours and the license key arrives via email.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
Tip
The license key converts an existing WikiTraccs trial version to a licensed full version. You don’t need to download a new release package.
Nevertheless, it is recommended to look for WikiTraccs updates here: WikiTraccs Releases.
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
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:
- More about Confluence permissions here: Authenticating with Confluence
- More about SharePoint permissions here: Authenticating with SharePoint Online
- Step-by-step instructions for creating Entra ID app registration: Registering WikiTraccs as app in Entra ID
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:
- More on who can create and configure Entra ID applications: Delegate app registration permissions in Entra ID
- Step-by-step instructions for registering the application in Entra ID: Registering WikiTraccs as app in Entra ID
- More about the permissions of the Entra ID application here: Authenticating with SharePoint Online
Q: Will the links between Confluence pages work properly when migrated to SharePoint?
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:
- In-depth information: Confluence Link Types Explained
- Details about hard link handling: WikiTraccs 1.6.4 Release Notes
- Feature description: Features -> Links specific to Confluence
- For cross-space links to work the space to site mapping has to be configured in the Space Inventory: Cross-space links and target sites
Q: What is a Hard Link for WikiTraccs? And why is it hard for WikiTraccs to migrate hard links?
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:
- In-depth information: Confluence Link Types Explained
- Details about hard link handling: WikiTraccs 1.6.4 Release Notes
- Feature description: Features -> Links specific to Confluence
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:
- Documentation: Confluence Space Inventory
- For cross-space links to work the space to site mapping has to be configured in the Space Inventory: Cross-space links and target sites
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:
- This overview covers what WikiTraccs can do: Feature Overview. If you think something should definitely be in there, please create a feature proposal.
- Confluence page layouts, sections, columns, and panels.
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:
- Page migration success: Measuring page migration success
- Space migration progress: Monitoring Confluence to SharePoint Migration Progress
- And for general diagnosis of issues: common log files
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:
- Documentation about the challenges of large spaces: Migrating large Confluence spaces to SharePoint
- Feature proposal to speed up migrating large Confluence spaces: #69
- Documentation about throttling by Microsoft
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:
- Documentation: Confluence Space Inventory
- How to map Confluence Spaces to SharePoint Sites
- Hints about what you should consider as part of your migration project: Migration Playbook
- More about the SharePoint breadcrumb and page tree experience: WikiPakk
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:
- Separate FAQ around pricing and licensing here: WikiTraccs Pricing
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.
It's important to note that WikiTraccs creates SharePoint modern pages as wiki pages, not classic pages. Modern pages are part of the SharePoint modern experience which is the future.
Furthermore, when creating modern pages, WikiTraccs aims to create standards compliant pages that a user could have created. This approach is different from other products.
Why is this important? Because when a user edits and saves a migrated page, it will behave like a normal SharePoint modern page, without any formatting disappearing. Besides, it will be friendly to mobile use.
Please refer to the linked pages for more information about WikiTraccs’ capabilities and visual migration samples.
Further reading:
- What can be migrated? Read here: WikiTraccs Features
- Visual migration samples: Migration Samples
- Blog post: What about those Confluence Macros?
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.
It's important to note that WikiTraccs creates SharePoint modern pages as wiki pages, not classic pages. Modern pages are part of the SharePoint modern experience which is the future.
Furthermore, when creating modern pages, WikiTraccs aims to create standards compliant pages that a user could have created. This approach is different from other products.
Why is this important? Because when a user edits and saves a migrated page, it will behave like a normal SharePoint modern page, without any formatting disappearing. Besides, it will be friendly to mobile use.
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:
- See how certain Confluence macros are handled: Known Confluence Macros
- Blog post: What about those Confluence Macros?
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:
- See how certain Confluence macros are handled: Known Confluence Macros
- Blog post: What about those Confluence Macros?
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:
- 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
- use WikiTraccs to automatically fill the Space inventory list with information about those 350 Confluence spaces
- map each space to its target site URL
- select spaces to migrate
- start the migration using WikiTraccs
Further reading:
- How to map Confluence Spaces to SharePoint Sites
- Feature proposal to allow selecting pages via CQL query, which would allow “splitting” spaces: #77
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:
- Introduction to SharePoint information architecture > Guiding principle: the world is flat
4.4 - Prerequisites
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
Note
The following are tested configurations. Others will work as well.Component | Works |
---|---|
CPU | 64-bit 2.6-GHz quad core processor |
RAM | 16 GB |
Operating system | Windows 11 client |
Component | Works |
---|---|
CPU | 64-bit 3.1-GHz quad core processor |
RAM | 24 GB |
Operating system | Windows 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.
Note
The local storage requirement is dependent on the amount of transformed content. Refer to the data storage article for details.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
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.
Tip
Activate notifications for releases on GitHub to stay up to date with new releases.Updating WikiTraccs works as follows:
- 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)
- (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)
- run WikiTraccs (GUI or Console) from the new directory
You are now running the new version of WikiTraccs.
Note
You might want to keep the old WikiTraccs directory around in case you need to switch back to the old version or have a look at old log files.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.
Note
Don’t modify this settings file, it belongs to WikiTraccs.GUI. Use appsettings.json if you must.4.6 - Settings & Configuration
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)
Tip
Use WikiTraccs.GUI to get started quickly. Use it to configure source, target, and authentication options. Use the quick start guide.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
Tip
This is the recommended approach.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:
- Confluence migration source and spaces
- SharePoint target tenant and sites
- authentication for Confluence and SharePoint
- initial Space Inventory population
- migration mode: migrate content, update date and people fields, update permissions
- re-migrate content that had errors
- add link to source page or not
- macro ignore list
- translation migration mode for pages with translations
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 quick start guide covers configuring migration source, migration target, and authentication for Confluence and SharePoint: Getting Started
- Migration settings are documented here: Configuration via WikiTraccs.GUI (blue window)
- Everything you need to know about the Space Inventory is covered here: Confluence Space Inventory
The more involved configuration via config file and WikiTraccs.Console
Note
If you are just getting started with WikiTraccs, you probably won’t have to read further. Above section about WikiTraccs.GUI should cover everything you need.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 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:
- You migrate content from Confluence to SharePoint
- During the migration, WikiTraccs adds all Confluence users it encounters to the mapping list
- You configure the user mapping
- 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.
Note
In this mode no content will be migrated from Confluence to SharePoint. This mode is just for updating the author and editor of SharePoint pages.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:
- You migrate content from Confluence to SharePoint
- 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
- You configure the user and group mapping
- 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.
Note
In this mode no content will be migrated from Confluence to SharePoint. This mode is just for updating the permissions of SharePoint pages. However, WikiTraccs will reach out to Confluence if (for whatever reason) a permission snapshot cannot be found in the Confluence Permission Snapshots library in the WikiTraccs site.Important
The permissions WikiTraccs applies to already migrated SharePoint pages is based on permission snapshots taken at page migration time. Those snapshots are stored in the Confluence Permission Snapshots library in the WikiTraccs site.
That means that any updates to page restrictions in Confluence will not be reflected in the permission update mode run.
If you want WikiTraccs to update a permission snapshot, you need to delete either the SharePoint page and migrate it again, or delete the permission snapshot from the Confluence Permission Snapshots library. WikiTraccs will then reach out to Confluence to get the latest page restrictions and recreate the permission snapshot.
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.
Migrate footer comments
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
Facts about the Confluence Space Inventory
The Confluence Space Inventory - or short Space Inventory - is a SharePoint list that serves the following purposes:
- list all Confluence spaces; those can be marked as migration source, making them a space selector
- allow configuring additional source content selectors (CQL query selectors, content ID selectors)
- serve as the lookup table when transforming Confluence links to SharePoint links
Selectors
A source content selector is either a Confluence space key, a CQL query, or a list of content IDs. When selected for migration, all pages, blogs, etc. covered by the source selector will be scheduled for migration.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:
- Which spaces to migrate is covered in the quick start guide: Getting Started
- Why mapping to target sites is important for resolving migrated links: Cross-space links and target sites
- Migration Waves
- How to run parallel WikiTraccs migrations
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
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:
- Space selector - to select all pages of a space
- CQL query selector - to select pages via CQL search query
- Content ID selector - to select pages by ID
WikiTraccs also needs to know where to create the migrated SharePoint pages. This is done by configuring a target site collection for each selector.
Note
Attachments are not covered by selectors. They are always migrated together with their parent page or blogpost.The source-to-target mapping is important for two things:
- knowing which Confluence content to get and to which SharePoint site to migrate this content
- 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.
Note
This default mode is usually not what you want. So read on.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.
Cross-space links and target sites
In general, when migrating pages, WikiTraccs translates links between Confluence pages to proper links between SharePoint pages.
Note
Everything in this section applies to attachments as well.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.
Note
WikiTraccs uses the default target site URL when there is no target site URL configured for a space.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.
Note
When you don’t migrate the pages that WikiTraccs linked to in SharePoint those links will - of cource - be broken, since the target is missing.4.6.2.2 - How to migrate Confluence Content using Space Selectors
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_CfSpaceName | WT_In_CfSpaceKey | Wt_Setting_RequestTransformation | WT_Setting_TargetSiteRootUrl | |
---|---|---|---|---|
Project Alpha | PALPHA | x | https://contoso.sharepoint.com/sites/ProjectAlpha | |
Project Beta | PBETA | x | https://contoso.sharepoint.com/sites/ProjectBeta | |
Miscellaneous | MISC | x | https://contoso.sharepoint.com/sites/Miscellaneous | |
Marketing | MRKT | https://contoso.sharepoint.com/sites/Marketing | ||
Sales | SALES | https://contoso.sharepoint.com/sites/Sales | ||
Customer Service | SERVICE | https://contoso.sharepoint.com/sites/CustomerService | ||
HR | HR | https://contoso.sharepoint.com/sites/HR | ||
Finance | FIN | https://contoso.sharepoint.com/sites/Finance | ||
IT | IT | https://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.
Link Transformation
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
Note
CQL query selectors have been introduced in WikiTraccs release 1.8.0.WikiTraccs allows selecting source pages for migration using CQL queries.
Migrating spaces vs. migrating via CQL query
Note
Refer to the Atlassian documentation about the CQL query syntax: Advanced Searching using CQL.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
Note about Page Restrictions
CQL queries will only surface restricted pages when the logged-in user is explicitly listed in the page restrictions (either directly or as member of a group). Confluence admin accounts that are allowed to access all pages (even restricted ones) are often not part of page restriction configurations and thus restricted pages will be missing in the CQL query result. This is Confluence out-of-the-box behavior.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
Tip
If you want to test a CQL query you can do so in the browser as follows:
- open a browser and log in to Confluence
- in the same browser window, enter the following in the address bar:
https://<confluencebaseurl>/rest/api/content/search?start=0&limit=200&cql=type="page"
(note: make sure to replace<confluencebaseurl>
with the base URL of your Confluence); press Return
The browser window should now show a wall of text. This is the result for the CQL query type="page"
which selects “all pages”.
Link resolution is more difficult
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 sitehttps://contoso.sharepoint.com/sites/one
, andlabel="two"
, mapped to target sitehttps://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 querylabel="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 querylabel="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
Link Transformation
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
Note
Content ID selectors have been introduced in WikiTraccs release 1.18.0.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, like123456789
;#
is a delimiter to separate the ID from the typeTYPE
is the Confluence content type likepage
andblogpost
(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.
Note
When adding new items to the Space Inventory list, SharePoint might consider Title as a required field. Just enter anything, WikiTraccs doesn’t need nor uses the Title value.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_CfSiteId | Wt_Setting_RequestTransformation | WT_Setting_TargetSiteRootUrl | WT_Setting_ContentSelectorValue | |
---|---|---|---|---|
https://contoso.com/wiki | x | https://contoso.sharepoint.com/sites/ProjectAlpha | 123456789;#page,234567891;#page,345678912;#page,4567891234;#blogpost,5678912345;#blogpost | |
https://contoso.com/wiki | x | https://contoso.sharepoint.com/sites/ProjectBeta | 101;#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
Note
Running SQL on the Confluence database is only possible in Confluence Server and Confluence Data Center, not Confluence Cloud.Using SQL you can get content IDs for your selector from the Confluence database.
Note
All statements have been tested with PostgreSQL.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.
Link Transformation
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
Configuring via configuration file
Note
You have to restart the application to apply changes to settings files.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.
Note
appsettings.json
can be used together with WikiTraccs.GUI to configure many settings not available in the GUI. Note that not all configuration options might be available. Get in touch if some setting doesn’t seem to be applied.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
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.
Note
Some settings can also be applied toWikiTraccs.GUI
, by putting the appsettings.json
in the same folder as WikiTraccs.GUI.exe. Support might instruct you to do that, for advanced configurations or when diagnosing issues.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
Note
You can configure this setting via the Settings dialog of WikiTraccs.GUI.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.
Note
Read more about content ID selectors here: Confluence Content ID Selectors.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
Tip
You can now configure those paths in the WikiTraccs settings dialog, available via the menu bar of the blue WikiTraccs window. No need to useappsettings.json
anymore.Use those settings to control where WikiTraccs stores temporary files:
{
"CustomSettings": {
"AttachmentRegistryRootPath": "D:\\FileRegistry",
"TempPath": "C:\\Users\\user\\AppData\\Local\\Temp\\",
}
}
Note
The double backslashes are there on purpose, to make this a valid JSON string. If your path looks likeC:\temp
you would instead have to enter C:\\temp
here.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)
Tip
Learn more about data that WikiTraccs stores locally in this article: File Storage.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
Note
As of WikiTraccs 0.1 you can choose which pass to run via a settings dialog in WikiTraccs.GUI.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
Real Results
All content on this page has been generated by WikiTraccs. No tweaking, no cheating. If there is something missing or off you’ll see it here and there will often be an issue link.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
Files, Images, Links
Images, External Images and Images with Links
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.
Standards Note
WikiTraccs aims to create SharePoint standard pages and content that could also have been created by a user. That’s why you won’t see certain formattings or structures being created by WikiTraccs - because there is no way to create them in the text editor web part.
Non-standard formattings also have the tendency to disappear when editing the page.
WikiTraccs could create non-standard content like nested tables or merged cells. But that is currently not a feature WikiTraccs wants to offer.
4.8 - Monitoring Confluence to SharePoint Migration Progress - Overview
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
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
Note
Selectors are used to tell WikiTraccs which content to migrate. Have a look at the selector documentation to learn more.Using progress log files to get insights
Note
Depending on whether you are running WikiTraccs.GUI or WikiTraccs.Console log files will be stored at different locations.
When using WikiTraccs.GUI, look at the WikiTraccs.GUI\logs folder. When using WikiTraccs.Console, look at the WikiTraccs.Console\logs folder.
Progress log files are stored in a sub folder that has the current date as its name, e.g. logs\2023-05-19.
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
Note
Multiple progress log files will be created with each migration run.
When starting the migration from Confluence to SharePoint WikiTraccs creates progress log files for each analyzed space. Those reflect the state before the migration of a space.
After migrating all scheduled spaces WikiTraccs creates a second batch of progress log files for each space that had pages migrated for. This will be done when going into idle mode. You may interrupt this if you don’t need those files.
When pressing Ctrl+C in WikiTraccs.Console (to cancel the running operation) it is not guaranteed that the final batch of progress log files will be generated. To get the current state just start the migration again and the files will be generated for each scheduled space.
Keep an eye on the file name and timestamp when you search for the most recent progress log files.
Note
The content of these files is subject to change as customer feedback keeps coming in, pointing to additional information that would be valuable.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.
Note
The file format changed with WikiTraccs release v1.7.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.
Tip
This file can be used to update outdated pages. See Updating previously migrated pages for details.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.
Note
WikiTraccs does not create a file if there is nothing to log. So some progress log files can be missing and that’s expected.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
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 page514-720 /h
: the estimated number of pages that will be migrated in the next hourETA 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:
Metric | Meaning |
---|---|
Median time | Median migration time per page |
Median time (IQR) | Median migration time per page, after removing outliers |
75th percentile | 75th percentile of page migration times |
75th percentile (IQR) | 75th percentile of page migration times, after removing outliers |
Items per hour | Pages migrated per hour, based on IQR Median and IQR 75th percentile |
Avg links transformed | The average number of links on those pages; links increase migration times |
Have files | The percentage of pages that have attachments or link to external images |
File count avg | The average number of files that were uploaded per page (of the pages that have any files) |
File size avg | The average file size |
Download speed | Average download speed for downloaded files |
Upload speed | Average 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 down | An indicator of downloaded file content; this is not exhaustive and accuracy will be improved in a future release |
File size sum up | An 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.
Note
Those values are supposed to make transparent where WikiTraccs spends its time. They could also hint at potential points for optimization.
If you think another metric could be valuable in above list, get in touch, I’d like to hear about your use case.
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).
Note
WikiTraccs optimizes file uploads. Files are uploaded to SharePoint Online in parallel, 2 files at a time.
You can configure more files to be uploaded in parallel, but might get throttled faster by Microsoft. Use the WiggleRoom.ParallelFileOperationsCount
configuration parameter in appsettings.json to increase the parallelism count.
4.9 - 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.
Tip
Macros so far unknown to WikiTraccs are also transformed, but in a generic way. The number of such macros is logged by WikiTraccs as “Crystal Ball Transformation Count” for each page.List of known macros
The following table shows macros that are explicitly known to WikiTraccs and how they are handled.
Macro | Support Level | Macro 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.
Static macro snapshots
Many macros could be migrated as a static snapshot. WikiTraccs currently does this for the page attachments macro. After transformation, this macro is represented as a table of attachment links in the target SharePoint page. This table is a static snapshot of how the macro looks in Confluence at migration time.
If you’d like to see additional macros migrated as static snapshot, please get in touch by opening an issue describing your use case.
4.9.1 - Macro Placeholders and 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?
Advanced Topic
This and the following sections cover macro transformation templates which are designed to change how migrated pages look in SharePoint Online.WikiTraccs allows to apply custom text placeholders in generic macro transformations, using transformation templates.
Note
Generic macro transformation means that WikiTraccs does not contain a built-in transformation rule for a macro.
An example of a non-generic macro transformation is the code snippet macro, because WikiTraccs has a transformation built-in that creates a code web part in SharePoint. Transformation templates don’t apply here.
Another example of a non-generic macro transformation is the info macro, as WikiTraccs also has special handling built-in, transforming this macro to a table that resembles the original info panel. Transformation templates don’t apply here.
Nevertheless, most third-party macros are transformed in a generic fashion and transformation templates apply.
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.
Note
Refer to the Handlebars documentation to learn how Handlebars templates work. It is out of scope for this article to cover this.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.
Note
The .hbs file extension is mandatory.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:
- 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
- create a Handlebars template that describes how the custom placeholder should look
- 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:
Variable | Data Type | Meaning |
---|---|---|
Body | n/a | the macro body (if the macro has one) |
HasBody | boolean | true, if the macro has a body; false otherwise |
HasNoBody | boolean | true, if the macro has no body; false otherwise |
Details.DisplayName | text | macro display name |
TypeAsString | text | ‘macro’ for macros, ‘ADF extension’ for ADF extensions, ‘unknown embedding’ otherwise |
IsMacro | boolean | true, if the macro is a macro |
IsAdfExtension | boolean | true, if the ‘macro’ is an ADF extension (so, not really a macro, but covered by macro transformation nevertheless) |
HasParameters | boolean | true, if the macro has parameters; false otherwise |
ParameterCount | number | the number of macro parameters |
Parameters | collection | macro 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
Architectural Overview of WikiTraccs
The following image shows which building blocks are at play when running a WikiTraccs migration.
The building block explained:
Building block | Purpose |
---|---|
Client’s computer | A 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. |
Confluence | The 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 account | The 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 Graph | The 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 account | The 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 WikiTraccs | Entra 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 files | WikiTraccs 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 team | This is your migration team. |
WikiTraccs support | Support 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 services | Other 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 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
Note
This is a potentially non-exhaustive listing.Required endpoints
The following table lists the required endpoints for using WikiTraccs.
Microsoft 365
Required Endpoint | Purpose |
---|---|
login.microsoftonline.com | Authentication with Microsoft |
aadcdn.msftauth.net | Authentication with Microsoft |
login.live.com | Authentication with Microsoft |
*.sharepoint.com | Access 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 Endpoint | Purpose | Owner info |
---|---|---|
chromedriver.chromium.org | Chrome WebDriver version detection | Whois registrant: Google LLC (CA, US) |
chromedriver.storage.googleapis.com | Chrome WebDriver download | Whois registrant: Google LLC (CA, US) |
googlechromelabs.github.io/chrome-for-testing/latest-patch-versions-per-build-with-downloads.json | Chrome WebDriver version information for Chrome starting with version 115 | Github-Repository owner: Google Chrome team |
edgedl.me.gvt1.com | Host for Chrome WebDriver downloads | Whois registrant: Google LLC (CA, US) |
storage.googleapis.com | Host for Chrome WebDriver downloads | Whois 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
4.11.1 - Source Configuration
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.
Note
Anonymous authentication can be used to migrate content like pages and attachments. What most likely won’t work is migrating permissions and gathering user and group information for user and group mappings. Choose another authentication type instead.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.
Well-known session cookies
By default WikiTraccs looks for the well-known session cookies with name JSESSIONID, and cloud.session.token. Use the advanced settings only to configure additional cookie names.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 ;.
SSO Cookies
Some SSO solutions create cookies with names like Contoso_SSO. Enter those names in the Additional cookie names input.WikiTraccs checks the presence of those cookies when testing the Confluence connection. The test fails if those cookies cannot be found.
4.12 - Authentication
4.12.1 - Authenticating with Confluence
The following authentication methods are currently supported:
- cookie-based authentication
- personal access token authentication (Confluence 7.9 and later)
Cookie-based authentication (“Interactive login”)
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.
Note
Currently only the Chrome browser is supported.Log in to Confluence like you normally would. WikiTraccs will use the cookies from the authenticted browser session to access Confluence.
Note
WikiTraccs opens and controls the browser window you use to log in. This is necessary so that WikiTraccs can access cookies. A note about this automation will be shown at the top of Chrome, which is expected.The following diagram shows how WikiTraccs uses cookies to make authenticated calls to Confluence:
Kerberos
Kerberos SSO might prevent WikiTraccs from successfully authenticating with Confluence, even when using the correct session cookies.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
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.
Note
Under the hood WikiTraccs uses the PnP Core library that is also used by PnP PowerShell. Thus concepts regarding authentication are similar. That’s why this documentation will link to PnP documentation at certain points.Tip
Use interactive authentication for starters. It’s the easiest option that gives good interactive feedback if something goes wrong.Prerequisites
Note
This section uses PnP PowerShell for Entra ID application management. Refer to Installing PnP PowerShell on how to install PnP PowerShell.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.
Note
This blog post has step-by-step instructions on how to register the app in the Azure Portal: Registering WikiTraccs as app in Entra ID.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
Note
The following assumes you are using WikiTraccs.GUI.Note
In WikiTraccs.GUI there is a Test SharePoint connection button. You can select this button at any time to test if the configuration is right and the authentication succeeds. This also checks that the permission level is sufficient.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.
Attention
The sign-in experience will be opened in a regular browser window (that might already be open) and not in a new, dedicated window. This is due to cross-platform restrictions that need to be solved. This could cause problems when already being logged in with a user account that is different from the one to be used for WikiTraccs. In this case just copy the URL from the address bar to another browser window where you sign in with the right user.Note
WikiTraccs uses the OAuth 2.0 authorization code flow.Device code authentication
Available.
Client credentials authentication
Available, but often not feasible due to MFA or CA requirements.
4.13 - Confluence Inventory
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
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
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.
Note
The update mode only covers the case where pages are updated in Confluence, outdating their SharePoint counterparts. It explicitly does not cover the case where the SharePoint pages are updated in any way, outdating the original Confluence content.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.
Note
This migration run doesn’t have to finish. Just let it work long enough to create the progress log files, then stop the migration. But you can also let it finish.Have a look at the documentation about progress log files: Monitoring Confluence to SharePoint Migration Progress > Using progress log files to get insights.
Note
Each migration will create new progress log files, once when starting and once when finishing the migration run. Look at the date and time of those files to choose the most recent ones.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:
- 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
- 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) - 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
- a line might look like this:
- 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
- save the progress log file when you are finished marking pages for update
- 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
- run WikiTraccs.GUI
- start a migration as usual, by selecting the Start transformation button in WikiTraccs.GUI
Tip: Excel might help in step 4
You can select all lines after that second+++
marker, copy them to the clipboard, and paste them into Excel. Excel should now properly display the data, allowing filtering and modifications. Set the x marker as needed. Then, in Excel, select all lines again, copy them to the clipboard, and paste them back to the file, replacing the original lines. This should even preserve the tabs that separate the values (but you should double-check that).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
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.
Tip
Migration wave configuration is optional. When using WikiTraccs.GUI, leave the Waves text box empty to tell WikiTraccs to not care about waves.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_CfSpaceName | WT_In_CfSpaceKey | Wt_Setting_RequestTransformation | WT_Setting_Waves | WT_Setting_TargetSiteRootUrl |
---|---|---|---|---|
Project Alpha | PALPHA | x | 1 | https://contoso.sharepoint.com/sites/ProjectAlpha |
Project Beta | PBETA | x | 1 | https://contoso.sharepoint.com/sites/ProjectBeta |
Miscellaneous | MISC | x | 1 | https://contoso.sharepoint.com/sites/Miscellaneous |
Marketing | MRKT | x | 2 | https://contoso.sharepoint.com/sites/Marketing |
Sales | SALES | x | 2 | https://contoso.sharepoint.com/sites/Sales |
Customer Service | SERVICE | x | 2 | https://contoso.sharepoint.com/sites/CustomerService |
HR | HR | x | 3 | https://contoso.sharepoint.com/sites/HR |
Finance | FIN | x | 3 | https://contoso.sharepoint.com/sites/Finance |
IT | IT | x | 3 | https://contoso.sharepoint.com/sites/IT |
Note: Other columns have been omitted for brevity.
With this configuration everything is prepared for a 3-wave migration.
What's a wave number?
Wave numbers are supposed to be:
- whole numbers
- equal to or larger than 1
Wave numbers don’t have to be consecutive. For example using 100, 200, and 300 (instead of 1, 2, and 3) is fine.
How to choose waves to migrate?
In WikiTraccs.GUI you can enter waves into the Waves text box right above the Start transformation button:
Note
Selecting waves is optional. Leave the Waves text box empty to migrate all selectors that have a check mark set in the Wt_Setting_RequestTransformation column of the Space Inventory.You can choose multiple waves to migrate.
Here are supported ways of selecting waves:
Wave selection example | Description |
---|---|
1 | Migrate wave 1 |
1,2,3 | Migrate waves 1, 2, and 3 |
1-3 | Migrate waves 1, 2, and 3 |
1,4-6,8 | Migrate waves 1, 4, 5, 6, and 8 |
-4 | Migrate 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 |
Tip
Above syntax is also valid in the WT_Setting_Waves column. This can be useful to include selectors in multiple migration waves.Note
For a Space Inventory entry to be considered at all for migration, the Wt_Setting_RequestTransformation field has to be checked. This is a requirement independent of any wave configuration.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
Storage Locations
WikiTraccs stores data on the workstation it is running on.
Note
This documentation is valid as of WikiTraccs v1.12.25, as some locations were consolidated in this release.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).
Tip
Delete the whole HTTPS__WIKI.CONTOSO.COM folder to be asked to log in to Confluence again when starting your next migration. WikiTraccs will recreate the folder.
So, when your configured temp folder is C:\Users\USER\AppData\Local\Temp, and your Confluence base address is https://wiki.contoso.com, you would delete the C:\Users\USER\AppData\Local\Temp\WikiTracccs\HTTPS__WIKI.CONTOSO.COM folder.
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
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
Term | Synonyms | Meaning |
---|---|---|
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, Subsite | Usually 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
Note
Multilingual pages are pages, whose content has been translated to more than one language.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:
Note
Some options will be supported in a future version of WikiTraccs and are not yet available.- migrating only one language, the translation with most content in Confluence
- migrating only one language, as chosen via configuration (not yet supported)
- migrating all translations to a single SharePoint page (default mode, supported as of WikiTraccs 1.4.2)
- 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
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
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
Note
This capability will be added in one of the next WikiTraccs releases.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.
Notes from the SharePoint documentation
Pages are not translated automatically. Each page created in your default language can have a corresponding page in a chosen target language that you, or someone you assign, manually translates. After you translate such a page and publish it, it will automatically be displayed to users who prefer that language.
Changes to the original, source page or to other translation pages are not automatically synced with all translation pages. Each translation page must be updated manually.
The language displayed to a user will depend on their personal language and region settings.
We recommend using the steps in this article for multilingual sites. However, if you are using SharePoint Server versions earlier than 2019, see Using the variations feature for multilingual sites.
The multilingual features described in this article are not available on subsites.
Multilingual features will only be available on sites that have publishing infrastructure settings disabled.
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
WikiTraccs consists of two applications: WikiTraccs.GUI and WikiTraccs.Console.
Note
When you extract the release package there are two folders: WikiTraccs.GUI and WikiTraccs.Console, containing the respective applications.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
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
5.1 - 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:
Note
User interface subject to change.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
:
- Open the Chrome browser
- Open Chrome -> (Three Dot Menu) -> Help -> About Google Chrome
- Take note of the version (e.g. 118.0.5993.118)
- 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
- 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)
- 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: - 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 - Open this URL in a new browser tab which will trigger the download of chromedriver-win32.zip
- Extract chromedriver-win32.zip and find chromedriver.exe:This is the WebDriver.
- 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
Note
These instructions were written before Google changed the ChromeDriver version matching in Chrome version 115. Those instructions would need an update to be usable for Chrome version 115 and up. Get in touch if you are in a situation were this would be valuable for you.Follow these steps to determine the right values for * ChromeDriverVersionOverride
and WebDriverDirPath
:
- Open the Chrome browser
- Open Chrome -> (Three Dot Menu) -> Help -> About Google Chrome
- Take note of the version (e.g. 86.0.4240.75)
- 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)
- 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 - 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
- Choose the headline which takes you to the download page for this ChromeDriver version:
Download ChromeDriver for your platform
- Download the right zip file for your platform (Windows, Mac or Linux); the zip contains a single file (
chromedriver.exe
orchromedriver
), which is the WebDriver - 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.
Important
Backslashes need to be escaped in yourWebDriverDirPath
since appsettings.json
is a JSON file. That means every single backslash \ becomes a double backslash \\.Now WikiTraccs skips the WebDriver version check and download. This should resolve connectivity issues to those endpoints.
Note
Restart WikiTraccs for the settings to take effect.5.2 - Authentication Issues
5.2.1 - Confluence Authentication Issues
Note
Refer to Confluence Authentication to learn about supported authentication methods.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.
Note
If no browser window opens at all then we need to go a step back. Internet connectivity issues might prevent WikiTraccs from getting everything it needs to even show the browser window. Refer to the Connectivity Issues article on how to work around those issues.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"
}
}
}
Anonymous authentication
If you are configuring this for a Confluence instance that can be accessed anonymously, and you want to migrate in anonymous mode, you must set the AjsRemoteUserKey to this exact value:
00000000000000000000000000000001
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
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
See Troubleshooting Strategies for different log files that can be used to troubleshoot issues.
5.4 - Troubleshooting Strategies
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.
How should you handle migration issues related to SharePoint pages created by WikiTraccs?
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.
Note
Please include as much of this information as possible when getting in touch. Every bit can help analyzing the situation and providing guidance.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 files | in 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 files | in 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 library | every target site for the migration contains information about migrated pages | Shows detailed information for every page migrated; see Measuring page migration success for details |
Confluence page storage format | for 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 pages | open 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 title | the log files contain any errors that hinder migration and page IDs and titles help finding the right places in the log files |
Note
Log files can contain information relating to source and target environments, as well as content.
Examples are:
- Confluence source site URL
- Sharepoint target site URLs
- image URLs
- user names, email addresses, and IDs (e.g. when user mappings fail)
- snippets of content (e.g. when macro transformations fail)
Replace any content you aren’t willing to disclose before sending those files.
Common log files
Common log files cover information about the whole Confluence to SharePoint migration.
Where can I find those logs?
InWikiTraccs.GUI\logs
or WikiTraccs.Console\logs
(depending on whether you are running WikiTraccs.GUI.exe
or WikiTraccs.Console.exe
).Why are those files useful?
Common log files are useful to troubleshoot all issues, but are essential in root cause analysis when it’s still unclear where the issue originates.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:
Note
The filename format changed slightly over time and might look different depending on the WikiTraccs release you use.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.
Note
Make sure to choose the log files where the date and time corresponds to the date and time of the migration run(s) you’d like to diagnose. In general: the more logs, the better.Progress log files
Progress log files conver the page migration state for all spaces that are part of the migration.
Why are those files useful?
Progress log files are helpful for troubleshooting issues around Confluence pages that are expected to be migrated but are not.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.
Why are screenshots useful?
Screenshots of this view can help diagnosing issues with single pages.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.
Note
Keep an eye on the file’s timestamp to read them in the right order.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.
Important note about missing macros
Many macros cannot be represented in SharePoint. So they are expected to be missing.
Here’s a primer on what to expect regarding macros: What about those Confluence Macros?
Here’s a list of macros and how they are handled by WikiTraccs: Known Confluence Macros.
Please open a support ticket with a feature request for macros you’d like to see migrated from Confluence to SharePoint. Please also include a description of your use case and a basic idea or mockup of how the migration result in SharePoint should look like.
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:
Note
Please check the affected pages. Sometimes there is one type of macro causing issues technically for many pages, but it doesn’t make a difference visually. So while it would be nice for WikiTraccs to be less error-y in its messaging the migration result is fine.
Please add information about whether you’ve got a blocking issue or whether you are just raising awareness, when getting in touch.
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
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.
Note
You can learn more about the Confluence storage format in Atlassian’s documentation: How to retrieve Confluence Storage Format.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.
Note
This option is available when the Confluence Source Editor plugin has been installed.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
Note
Below instructions assume that you did not create appsettings.json before. However, if the file is already present, the additional configuration option needs to be added at the right place. Have a look at the Settings page for documentation of the correct format.- Open the WikiTraccs.GUI folder (this is the folder where WikiTraccs.GUI.exe is stored as well)
- Create an empty file appsettings.json inside the WikiTraccs.GUI folder
- Open the appsettings.json file in a text editor and put the following text in there:
{ "CustomSettings": { "Debug": { "SaveTransformationInputToDisk": true } } }
- Save appsettings.json
- If WikiTraccs.GUI is open: close it and any other (console) windows it opened
- Open WikiTraccs.GUI and start a migration
Note
When you need to get the storage format of a page that has already been migrated before, you have to delete the already existing page in SharePoint first. Otherwise WikiTraccs won’t migrate this page again.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.
Note
The screenshot above uses the app Everything from voidtools to locate the storage format file. It provides instant search results and is perfect for finding those files and folders by page ID.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.
Note
Not using WikiTraccs.GUI? You can also configure WikiTraccs.Console to store the storage format to file. Just use the appsettings.json in the WikiTraccs.Console folder.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:
- your Confluence base address (examples: https://confluence.contoso.com, https://www.contoso.com/confluence)
- 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
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:
- your SharePoint site address (example: https://contoso.sharepoint.com/sites/it-support)
- 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)
- the title of the Site Pages library, in the site’s default language (examples: Site Pages (for English, note the space!), Websiteseiten (for German))
Note
You can figure out the page item ID by adding the ID column to any view of the Site Pages library.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.
Note about Site Pages Library title localization
Figuring out the title of the Site Pages library can be tricky when you are viewing the SharePoint site in a language that is not the default site language. The default site language is the language the site has been created in. When using the wrong title you’ll get the error List ‘…’ does not exist at site with URL. Ask the site owner for the site’s default language and use the localized title that matches this language instead.Cannot figure out the library title?
If you cannot figure out the right title of the Site Pages library, you can use its ID instead.
The address changes slightly and looks like this:
https://contoso.sharepoint.com/sites/it-support/_api/web/lists/GetById('d0dce654-b0b6-4cf6-b305-a83544aa5e10')/items(33)
The ID of the Site Page library is unique across site languages. To get the ID, open the Library Settings of the Site Pages library. Look at the browser address bar, which shows something like /_layouts/15/listedit.aspx?List=%7Bd0dce654-b0b6-4cf6-b305-a83544aa5e10%7D
. The ID is enclosed in %7B
and %7D
, or {
and }
. Here it is d0dce654-b0b6-4cf6-b305-a83544aa5e10.
5.5 - Troubleshooting FAQ
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
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:
- You raise an issue via one of the aforementioned channels (GitHub, email).
- 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.
- You test and get back to me with more information.
- <Steps 2 and 3 are repeated as necessary>
- 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
“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:
- Google Chrome is not installed
- Google Chrome is installed, but its executable could not be found at usual places
Solutions:
- Install Google Chrome
- Use the
ChromeBinaryPath
setting to manually configure the path to Chrome’s executable
5.8 - Common Warnings and Errors in Log Files
Errors
Recoverable error messages related to network connectivity
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.
Automatic recovery
WikiTraccs normally recovers automatically from all of the connection errors in this section by retrying what it was doing when hitting the error.[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
Warnings related to links
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.
Warnings related to missing images (mostly external)
'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.
Tipp
If you’ve got a lot of those external files with timeout and want to shorten the wait time - there is a configuration settting to do that. You can configure different timeouts for different domains. Have a look at theappsettings.json
sample file and the ExternalDomains
property: Configuration via Configuration File.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.
Warnings related to attachments
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.
Warnings related to Jira
[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
WikiPakk has got its own web site! Check out wikipakk.com for general product information and intro videos.
In-depth documentation is still kept here, so feel free to use the links below.
6.1 - WikiPakk Installation and Ops
Refer to the following articles for topics around installing and updating WikiPakk.
6.1.1 - 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.
Note
WikiPakk is called “WikiTraccs WikiPakk” in the app store and when installed in SharePoint, due to historical reasons. But it is commonly referred to as WikiPakk.Installation via Microsoft AppSource
The following video covers two topics:
- installing the app via Microsoft AppSource to the SharePoint tenant
- adding the WikiPakk app to a SharePoint site
Watch:
Note
The app needs to be added once to the SharePoint tenant app catalog.Required Permissions
You need to be either SharePoint administrator or have administrative rights on the tenant app catalog site to install the app right away. If you aren’t an admin, you can request the app to be installed and an administrator has to confirm this later.Note
WikiPakk is a SharePoint Framework Solution (SPFx), not a browser plugin.After adding the app
Head over to the video section on the WikiPakk website to learn more about WikiPakk.
6.1.2 - 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:
- the SharePoint tenant app catalog needs to be updated with the newest version from AppSource
- 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:
- in a browser, open the SharePoint admin center
- in the left navigation, select More features
- 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.
- the SharePoint tenant app catalog should show a previously installed version of WikiPakk:
WikiPakk, installed from AppSource, showing version 2.3.1.
- Switch to the classic experience by selecting the classic experience link:
- In the classic experience, in the list of apps, select the WikiTraccs WikiPakk app
- 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)
- 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:
- 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
Look at the changelog in AppSource
You only need to update WikiPakk in SharePoint sites if the changelog says that this is necessary.
In most cases it is not necessary to update WikiPakk in sites, although it doesn’t hurt.
This has a technical background. SharePoint client-side apps (SPFx solutions) load their resources (HTML, JavaScript, CSS) from the SharePoint tenant app catalog site. Those resources are updated with each new WikiPakk release and installing this new release to the tenant app catalog is all it takes to properly update WikiPakk.
Only when the WikiPakk manifest changes (things like app title, but also embedded resources like SharePoint lists, fields, or content types), the app needs to be updated in each site for those changes to be applied to the site.
The changelog will highlight that. It might also be worth a shot when troubleshooting update issues.
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:
- In a browser, navigate to a SharePoint site that uses WikiPakk
- In this site, navigate to Site Contents
- For the WikiTraccs WikiPakk app, choose … > Details:
- 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:
- Select Page Tree to expand the page tree panel on the right side
- Select the ? that is displayed at the bottom of the page tree; a window opens
- 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)
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:
- Create a staging site and activate the site collection app catalog
- Install the current WikiPakk app package to the staging site
- Add the WikiPakk app to the staging site
- 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
Permissions
You need an account that is site collection administrator of the tenant app catalog site and SharePoint administrator.- Create a new site that will be used for staging
- Note: in this article we’ll assume the staging site has the name wikipakk-staging and its addresss is https://contoso.sharepoint.com/sites/wikipakk-staging.
- 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"
- Here’s a sample script that uses the PnP.PowerShell module to create the site collection app catalog:
- 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.
- Open the tenant app catalog site
- Open the Apps for SharePoint library in the tenant app catalog site
- Download the current version of WikiPakk:Note: this downloads a WA200005439.cab file
Add account to site collection administrators of the tenant app catalog.
- 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
- Open the staging site
- Open the Apps for SharePoint library in the staging site
- Deploy the sppkg file to the Apps for SharePoint library:
- 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.
- As site owner, open the home page of the staging site
- Click the + New button, then click App to add an app
- 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:
- Now wait a minute and go back to the staging site’s home page
- 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.
- 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
- 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
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
There is a script for that in the library: WikiPakkInventory.ps1.
This script will check all sites for WikiPakk.
6.2 - WikiPakk Licensing
Licensing WikiPakk follows this pattern:
- purchase a subscription, immediately get a license key
- choose or create one or more SharePoint sites to store the license key in
- 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.
Note
The license key is bound to a SharePoint tenant. You enter the tenant URL in the Company field of the checkout form.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:
- in all sites WikiPakk will be added to
- in one dedicated configuration site (more on that in section “How to dedicate a specific site to store the WikiPakk license key”)
- 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).
Important
Make sure all users of WikiPakk have read access to the site you store the license key in, otherwise the license key cannot be read. This is relevant for options 2 and 3 from the list above.Note
This page has a diagram visualizing all of this: WikiPakk Licensing Flow.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
- all sites WikiPakk has been or will be added to, or
- one dedicated configuration site you choose, or
- the default configuration site /sites/WikiPakkConfiguration
As owner of such site, do the following to store the license:
- In a browser, open the SharePoint site
- Copy the license key to the clipboard (note: the license key is everything from —–BEGIN V2 LICENSE—– to —–END V2 LICENSE—–, including those delimiters)
- Open the Library Settings of the Site Pages library
- Find the place to edit the Description of the Site Pages library
- Paste the license key into the Description edit field
- Choose to Save
- Reload open pages that show the WikiPakk page tree or breadcrumb
Important
Make sure all users of WikiPakk have read access to the site, otherwise the license key cannot be read.WikiPakk should recognize first-time license keys pretty fast, and manually updated keys within 24h.
Caching
You can also clear the browser cache and local storage to make WikiPakk recognize the license key faster.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.
Note
WikiPakk will contact the licensing server at https://graph.wikitransformationproject.com. You may want to whitelist this URL. The request will be sent from the browsers of WikiPakk users.Note
WikiPakk sends the old license key to the licensing server, nothing else. This old license key is already known to the server.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
Note
Creating a site at /sites/WikiPakkConfiguration is easier, as it does not need the configuration shown below.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:
Note
Make sure to replace “yourcompany.sharepoint.com” with your SharePoint tenant host.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
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.
Note
This process is necessary to provide you with the freedom to cancel the subscription in a flexible manner.The license key refresh flow in a nutshell looks as follows:
- 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.
- Good: use that. Done.
- 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.
- 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.
Here is the detailed flow:
6.3 - WikiPakk Page Tree Quick Start
Note
More documentation follows soon. Here’s a short intro for starters.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.
Note
The page tree works with migrated pages and vanilla SharePoint pages. Migrated hierarchy from Confluence will be shown. The order can then be changed in SharePoint.6.4 - WikiPakk Features
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
6.5.1 - Inaccessible Pages
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.
Note
WikiPakk already hides inaccessible page nodes if those don’t have any children and are true tree leafs. So, after moving inaccessible notes to a dedicated parent, they might disappear, which is the expected behavior.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
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
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.
Note
WikiPakk tries its best to show a partial page tree and breadcrumb if information is missing, starting at the page that is currently open. Try selecting different pages and check if the page tree changes. This could hint at missing pages and/or metadata.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:
- open the Chrome browser
- open a modern SharePoint page where the page tree misbehaves
- 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
- the developer tools panel opens
- choose the Console tab
- enter wikipakk in the search box
- choose the levels drop down
- select all levels, including Verbose
Developert tools, showing log entries of WikiPakk
- 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
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.
Success
The red box with the note about the missing license should be gone now.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.
Note
Common causes for WikiPakk having no license are:
- not every user has access to the SharePoint site where the license is stored; grant all users read access
- the license has been stored in just one SharePoint site, but other sites don’t know about the license; using a central site will resolve this issue
- after one license period (a month, a year) expired: WikiPakk cannot contact the licensing server to refresh the license; grant access or refresh manually
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:
- in Chrome browser, have a SharePoint site open where WikiPakk is installed
- expand the Page Tree to view the red licensing error
- click the Retry link to check if WikiPakk can refresh the license; it can’t
- open Chrome’s developer tools via Three Dot Menu -> More tools -> Developer Tools
- in the Console section of the developer tools, enter wikipakk license into the search box; WikiPakk licensing-related log messages are shown
- the log messages are selected and can be copied and pasted, e.g. to support emails
Note
Add those log messages to your support request as it provides valuable information and allow to pinpoint issues pretty quickly.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:
- local site, Site Pages description field
- site configured via tenant property
wikipakk.licensesiteurl
, Site Pages description field - 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
Deprecated
This documentation refers to a proof of concept implementation of a page tree (wikitraccs-page-tree.sppkg). It is still relevant in that it describes how the metadata migrated by WikiTraccs can be used to implement a page treeThe 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.
Note
Did you migrate pages to a SharePoint site using WikiTraccs? Then all columns described here are already present in this site. Plus all metadata needed by the tree.Attention
Normally you won’t have to create those columns for yourself. When using WikiTraccs to migrate all necessary fields should already be present.Display Name | Internal Name | Type | Notes | Sample Value |
---|---|---|---|---|
Confluence: Id (WikiTraccs) | WT_In_CfContentId | Single line of text | Confluence page ID | 118587460 |
Confluence: Title (WikiTraccs) | WT_In_CfTitle | Single line of text | Confluence page title | Demo Page |
Confluence: Parent Id (WikiTraccs) | WT_In_CfParentId | Single line of text | ID of parent page (0 for the top-most pages) | 118587459 |
Confluence: Parent Id Chain (WikiTraccs) | WT_In_CfParentIdChain | Multiple lines of text | Chain 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_CfSpaceKey | Single line of text | Space key | WTD |
Confluence: Space Name (WikiTraccs) | WT_In_CfSpaceName | Single line of text | Space name | WikiTraccs Demo Space |
Confluence: Sibling Order (WikiTraccs) | WT_In_CfSiblingOrder | Number | Order in the page tree, lower numbers come first | 1 |
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.
Note
Only the internal name is used by the page tree. The display name doesn’t matter in this regard.Page Metadata
The page tree automatically picks up any metadata in the Site Pages Library.
Note
Did you migrate pages using WikiTraccs? Metadata for migrated pages is already present.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
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.
Learn more
Everything you need to know about the WikiTraccs trial version: WikiTraccs Trial Version.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?
Purchasing Roles
This section applies if
- You are a client unable to make a direct purchase and require a third party to facilitate the transaction.
- You are a third party authorized to make a purchase on behalf of a client.
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
- Company Name
- Address
- Tax ID (if applicable)
Client Details - after the purchase:
- Name
- Company Name
- Address
- Transaction ID / invoice #
Email Address
Once payment is received, the license key will be sent to the email address provided in the checkout form.Note for Consultancies
If you are a consultancy, note that per the Terms of Service you cannot use one license to serve multiple clients (no “consulting license”).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)
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.
Unique Bank Details
Bank details are unique for each order and can thus not be provided before initiating the payment. This is a requirement by FastSpring.You can also choose any of the other available payment methods.
You will also receive an email:
Thank you for your purchase!