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

Return to the regular view of this page.

WikiTraccs Reference

A reference of topics around WikiTraccs.

1 - How does WikiTraccs work?

This article describes the basics of WikiTraccs.

Overview

WikiTraccs migrates content from Atlassian Confluence to SharePoint Online.

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

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

How does it work?

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

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

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

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

How to get started?

Read here to learn how to get started: Getting started

2 - WikiTraccs FAQ

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

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

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

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

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

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

Further reading:

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

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

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

Further reading:

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

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

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

Further reading:

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

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

Since release 1.6.4 WikiTraccs has basic hard link support. WikiTraccs looks for hard links and tries to figure out the target page. If that is successful the hard link is transformed to a proper page link in SharePoint. But this might not always succeed. And this does not work for hard links to attachments.

Further reading:

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

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

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

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

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

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

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

Further reading:

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

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

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

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

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

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

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

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

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

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

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

Further reading:

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

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

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

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

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

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

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

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

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

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

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

Further reading:

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

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

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

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

Further reading:

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

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

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

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

You enter the target SharePoint URLs into the Space Inventory.

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

Further reading:

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

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

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

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

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

Further reading:

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

Q: How much time does it take to migrate?

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

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

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

Further reading:

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

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

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

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

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

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

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

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

Further reading:

Q: Do you provide consulting services?

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

Q: Are there maintenance fees?

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

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

Read more about your options here: Support Options

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

Further reading:

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

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

Q: What do the success stories have in common?

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

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

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

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

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

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

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

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

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

Further reading:

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

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

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

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

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

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

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

Further reading:

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

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

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

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

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

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

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

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

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

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

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

Further reading:

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

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

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

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

Further reading:

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

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

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

Each space can go to its own target SharePoint site.

Multiple spaces can go to one target SharePoint site.

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

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

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

Further reading:

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

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

Have a look at the Pricing page for details.

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

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

The following four tiers are available:

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

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

Here are examples for illustration:

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

Further reading:

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

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

Further reading:

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

A: That depends on the duration of your project.

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

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

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

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

Further reading:

3 - Installation and Update

This article shows how to install and update WikiTraccs.

Downloading and running WikiTraccs for the first time

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

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

Updating WikiTraccs

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

Updating WikiTraccs works as follows:

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

You are now running the new version of WikiTraccs.

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

As long as the temporary folder is not cleared the file is there. You can also back up and restore this file as needed.

4 - Settings & Configuration

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

How to configure WikiTraccs

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

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

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

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

Both approaches are described in the following sections.

The visual and convenient configuration via WikiTraccs.GUI

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

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

This is everything needed to get a migration going.

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

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

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

The following resources have more information:

  • The quick start guide covers configuring migration source, migration target, and authentication for Confluence and SharePoint: Getting Started
  • 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

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.1 - Confluence Space Inventory

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

Facts about the Confluence Space Inventory

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

  1. show each Confluence space for you to select for migration
  2. allow adding additional selectors for Confluence pages to migrate, mainly CQL queries
  3. serve as the lookup table when resolving cross-page and cross-space links

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

You use the Space Inventory to select source pages 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)
    • WT_In_CfSpaceKey - the 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 all pages from all source selectors that have been chosen for migration, and schedule them for migration; this queue is processed one page 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

To learn how to migrate whole Confluence spaces to SharePoint refer to How to map Confluence Spaces to SharePoint Sites.

To learn about using CQL query selectors to choose Confluence pages to migrate to SharePoint refer to How to migrate Confluence Pages using CQL Query Selectors.

Here are other resources showing how the Space Inventory is used:

4.1.1 - How to map Confluence Spaces to SharePoint Sites

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

WikiTraccs allows to define a target site collection for every space it migrates.

Migrate to one target site by default

WikiTraccs by default migrates everything to the 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 all Confluence pages to this SharePoint site.

Configure a different target site for spaces

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

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

Target Site Root URL Column

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

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

The target site mapping is important to properly resolve cross-space links.

When migrating a Confluence page that points to a page in a different Confluence space, WikiTraccs looks up the target site URL for that space the page links to. It then uses this target site URL to create the proper link in SharePoint.

The links WikiTraccs creates in SharePoint follow a specific 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 a Confluence space where pages link to other pages or spaces that have not yet been migrated, while still creating valid links.

4.1.2 - How to migrate Confluence Pages using CQL Query Selectors

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

WikiTraccs allows selecting source pages for migration using CQL queries.

Migrating spaces vs. migrating via CQL query

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

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

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

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

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

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

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

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

There are some consequences though, when using CQL queries.

The consequences of using CQL queries source selectors

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

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

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

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

Why is that?

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

Example:

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

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

Duplicate pages can be created

You can write CQL queries might include overlapping results.

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

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

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

The consequences are:

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

4.2 - Configuration via Configuration File

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

Configuring via configuration file

Use WikiTraccs.Console when working with a configuration file.

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

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

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

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

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

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.2.1 - Sample Configurations

This article contains sample configurations for different purposes.

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

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

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

Sample: Migrate contents of one space

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

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

Snippet: Prevent WikiTraccs from downloading external images

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

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

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

Snippet: Prevent WikiTraccs from reaching out to Jira

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

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

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

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

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

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

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

Snippet: Change temporary storage folder pathes

Use those settings to control where WikiTraccs stores temporary files:

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

Explanation:

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

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

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

WikiTraccs normally promotes migrated Confluence blogposts to SharePoint news.

Prevent that with the following configuration:

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

Snippet: Configuring multi-pass migrations

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

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

Config File Templates for Debugging Purposes

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

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

Snippet: Generic Debug Configuration Template

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

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

Snippet: “Clear Cache” Settings Template

This setting clears the cache on every start:

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

Snippet: Don’t mark formerly merged table cells

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

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

5 - Migration Samples

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

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

Formatting

Confluence Text Formatting

SharePoint Text Formatting

Confluence Headings and Paragraphs

SharePoint Headings and Paragraphs

Confluence Text Alignment and Indentation

SharePoint Text Alignment and Indentation

Confluence Things from the Plus Menu

SharePoint Things from the Plus Menu

Confluence Lists and Task Lists

SharePoint Lists and Task Lists

Layouts

Standard Layouts

WikiTraccs transforms the Confluence layouts to the matching SharePoint layouts.

Confluence Standard Layouts

SharePoint Standard Layouts

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

Confluence Standard Layouts in Edit Mode

SharePoint Standard Layouts in Edit Mode

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

Sections and Columns

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

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

Confluence Sections and Columns

SharePoint Sections and Columns

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

Macros

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

Confluence Info Warning Tip Note

SharePoint Info Warning Tip Note

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

Confluence Code Macro

SharePoint Code Macro

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

Confluence Panels

SharePoint Panels

Note: The formatting capabilities in SharePoint are very limited.

Confluence Status Macro

SharePoint Status Macro

Confluence Images

SharePoint Images

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

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

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

Links to Content outside a Page

Confluence Links to Pages and other Content

SharePoint Links to Pages and other Content

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

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

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

Page Attachments

Confluence Page Attachments

SharePoint Page Attachments

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

Users and Groups

Confluence Mentions and Profiles

SharePoint Mentions and Profiles

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

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

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

Tables

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

Confluence Simple Tables

SharePoint Simple Tables

Confluence Table Widths

SharePoint Table Widths

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

Confluence Advanced Tables

SharePoint Advanced Tables

Confluence Larger Tables

SharePoint Larger Tables

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

6 - Prerequisites

This article describes the prerequisites for running WikiTraccs.

Prerequisites

System requirements

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

Software requirements

  • a recent version of the Chrome browser (for authenticating with Confluence, refer to the authentication article for details on authentication)

Endpoint requirements

Refer to the endpoints article on required endpoints.

7 - Known Confluence Macros

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

How WikiTraccs handles Confluence macros

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

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

List of known macros

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

MacroSupport LevelMacro Transformation Details
Status💚The macro will be transformed to text with a color that tries to match the original (not so many choices here in SharePoint…).
Noformat💚The “no formatting” content formatting will be mirrored in the SharePoint page.
Code Block💚/🟡Code macros are transformed to SharePoint code web parts which provide comparable functionality. But if the code macro in Confluence is part of a table or any other nested structure then there is no 1:1 representation in SharePoint. The web part in this case will be replaced by a placeholder and the web part inserted at a top level place in the SharePoint page.
SharePoint Online Document (by Communardo)🟡The macro will be replaced by a link to the SharePoint document.
SharePoint Online List (by Communardo)🟡The macro will be replaced by a link to the SharePoint site containing the list; the link text contains the SharePoint list ID.
Profile Picture🟡The profile picture will be transformed like user @-mentions in the page (see section below for details).
User Profile🟡The user profile card will be transformed like user @-mentions in the page (see section below for details).
Enhanced Profile (by Communardo)🟡The user profile card will be transformed like user @-mentions in the page (see section below for details).
Jira Issue Link🟡The Jira macro will be replaced by a link to the Jira issue.
Jira Issue List🟡The Jira issue list will be converted to a static table showing links to Jira issues. If the table had multiple pages, a snapshot of only the first page is migrated to SharePoint. So, for a query that covers 1000 issues only the first 20 or so will be shown. A link to Jira is added to the SharePoint page so you can jump to Jira to see the live issue list.
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.
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🔻
Table of Contents🔻
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.

8 - Security

This section covers security-related topics.

Architectural Overview of WikiTraccs

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

The building block explained:

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

Other services

Google Chrome WebDriver Download

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

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

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

Further Information

8.1 - Data Storage and Transmission

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

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

WikiTraccs handles data securely.

Big Picture

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

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

Where does WikiTracc run? Is it a cloud service?

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

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

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

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

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

This locally stored data includes:

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

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

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

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.

8.2 - Endpoint reference

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

Required endpoints

The following table lists the required endpoints for using WikiTraccs.

Microsoft 365

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

Atlassian Confluence REST

WikiTraccs uses the REST endpoints of Confluence. The REST endpoints are expected under the following URL:

  • <confluencebaseurl>/rest/api/

Automatic Chrome WebDriver download

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

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

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

Optional endpoints

Atlassian Confluence XML-RPC

WikiTraccs uses the REST endpoints of Confluence with one exception.

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

  • <confluencebaseurl>/rpc/xmlrpc/

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

9 - Using WikiTraccs.GUI

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

9.1 - Source Configuration

Configuring the Confluence source of the migration.

Confluence Base Address

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

Source configuration

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

How to manually check that the base URL is correct?

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

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

Confluence Authentication Type

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

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

Advanced Settings

Choose the Advanced button to open the advanced settings dialog.

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

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

10 - Known Issues

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

Limitations

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

When migrating page restrictions, WikiTraccs will only migrate up to 200 user and group restrictions per page.

Overly long page titles break page creation in SharePoint. This is tracked in issue #3.

Changes to a Confluence page’s attachments are not counted as “page change”. The page is detected as unchanged, event 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.

Current limitations of WikiTraccs.Console

WikiTraccs.Console does not close itself when it has finished migrating all scheduled pages from Confluence to SharePoint. Press Ctrl+C into the console window of WikiTraccs.Console to shut down the application, then close the window; afterwards you can start another migration. This is tracked in issue #61.

11 - Authentication

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

11.1 - Authenticating with Confluence

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

The following authentication methods are currently supported:

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

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

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

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

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

Experimental alternative to obtain cookies (compatible with Kerberos)

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

This changes the flow like this:

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

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

Personal Access Token

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

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

Required permissions in Confluence

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

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

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

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

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

11.2 - Authenticating with SharePoint Online

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

The following authentication methods are currently supported by WikiTraccs:

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

Each of those authentication methods requires an Entra ID application to exist. WikiTraccs has to know the ID of this application.

Prerequisites

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

If you are lucky then there is already an Entra ID application registered that you can use. One example for an existing application is the Entra ID application that is registered when using PnP PowerShell. The registration of this application is documented here: Setting up access. The cmdlet to use is Register-PnPManagementShellAccess.

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

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

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

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

The following permissions will allow migrations as well:

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

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

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

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

Interactive authentication

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

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

Choose Interactive as Target: Authentication type.

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

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

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

Device code authentication

This authentication mode is currently not supported in WikiTraccs.GUI and only available in WikiTraccs.Console.

Documentation is tbd.

Client credentials authentication

Documentation is tbd.

12 - Confluence Inventory

How to get information about your source Confluence environment.

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

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

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

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

Have a look at the child pages for more information.

12.1 - Getting the Confluence page count

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

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

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

Getting the page count from the database via SQL

Pro:

  • returns a guaranteed accurate page count

Contra:

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

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

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

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

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

Getting the page count 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 not recommended.

Getting the page count via Analytics (Confluence Cloud)

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

Third-party solutions

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

13 - File Storage

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

Storage Locations

WikiTraccs stores data on the workstation it is running on.

Attachment Registry

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

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

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

  • Storage location for all downloaded 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 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

  • Temporary storage location for 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

Temporary Files

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

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

Here’s what WikiTraccs stores at the temporary location:

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

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

Attachment Registry

  • Temporary storage location for attachment downloads

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

  • Storage of intermediary transformation files (XML)

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

User Profile Application Data

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

14 - Glossary

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

15 - License Activation

This article describes how to activate a purchased WikiTraccs license.

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

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

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

Start WikiTraccs. It should now recognize the license file.

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

License Information

Troubleshooting

WikiTraccs logs information about any license files it finds, including locations it expects such a file to be. Check the log file that the license file is at an expected location. Or get in touch if you need help.

16 - Monitoring Confluence to SharePoint Migration Progress

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

Viewing progress via the Site Pages library

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.

You can correlate the contents of the Site Pages library with the content of the source Confluence spaces. But this can be tedious.

What if pages are missing? How to quickly determine which ones? Let’s look at progress log files.

Using progress log files to get insights

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

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

The information you can gather from these files is:

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

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

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

Progress log file documentation

xxx__10-not-yet-migrated-pages.txt

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

Sample content:

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

The tab-separated columns in this file are:

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

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

Sample content:

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

The tab-separated columns in this file are:

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

This file contains information about the freshness of migrated pages.

Sample content:

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

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

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

The tab-separated columns are:

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

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

xxx__30-aggregated-info

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

Sample content:

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

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

Progress log file cadence

WikiTraccs creates progress log files at specific times:

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

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

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

17 - Multilingual Pages

Resources that cover migrating multilingual Confluence pages to SharePoint.

How does the translation work in Confluence?

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

How does the translation work in SharePoint?

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

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

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

Refer to the following pages for more information

17.1 - Info about Scroll Translations

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

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

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

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

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

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

17.2 - Migrating all Languages to one SharePoint Page

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

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

17.3 - Migrating to Multilingual Pages in SharePoint Online

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

A brief introduction to multilingual SharePoint

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

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

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

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

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

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

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

How do multilingual pages work in SharePoint?

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

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

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

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

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

18 - Setting up .NET

This article describes alternative ways to installing Microsoft .NET

WikiTraccs requires .NET 6 to run.

But you don’t have to care if you download the self-contained version which comes with .NET 6 bundled.

The following secions each present a complete solution to setting up .NET 6 for WikiTraccs, from easiest to hardest. Choose one.

Self-contained WikiTraccs

This is the headache-free all-inclusive option. Get the release zip file with “selfcontained” in the name. Extract and run, it should work without further setup.

Standard .NET installation

Open a browser and go to the Microsoft Dotnet download page, e.g. https://dotnet.microsoft.com/en-us/download. Follow the instructions on how to install the .NET 6 Runtime for your platform (Windows, …).

You should now be able to run WikiTraccs.

Setting up portable .NET on a system with restricted permissions

.NET can be set up without adminstrative rights even in restricted environments.

  1. Open a browser and go to the Microsoft Dotnet download page, e.g. https://dotnet.microsoft.com/en-us/download/dotnet/6.0.
  2. This time choose one of the binaries that match your platform:

    Download .NET SDK binaries

  3. Unzip the file to %USERPROFILE%\dotnet and update or create the following environment variables:
DOTNET_ROOT = %USERPROFILE%\dotnet
PATH = %USERPROFILE%\dotnet;%PATH%
DOTNET_MULTILEVEL_LOOKUP = 0

You should now be able to run WikiTraccs. Try rebooting if it doesn’t work immediately.

19 - Updating previously migrated pages

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

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

Why update older migrated pages?

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

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

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

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

You simply start a migration to learn about the update state of already migrated pages.

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

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

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

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

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

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

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

How to tell WikiTraccs to update outdated pages?

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

Here are the steps:

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

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

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 pages, but not attachments. 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 (yet)
  • 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.

Changes of SharePoint pages

Changed SharePoint pages 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.

20 - WikiTraccs GUI vs. WikiTraccs Console

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

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

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

WikiTraccs.GUI

A graphical user interface for WikiTraccs.

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

Empty sign-in experience

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

Console window settings

Select OK to confirm the settings.

WikiTraccs.Console

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