WikiTraccs Reference

• 1: How does WikiTraccs work?
• 2: WikiTraccs FAQ
• 3: Installation and Update
• 4: Settings & Configuration
• 4.1: Confluence Space Inventory
• 4.1.1: How to map Confluence Spaces to SharePoint Sites
• 4.1.2: How to migrate Confluence Pages using CQL Query Selectors
• 4.2: Configuration via Configuration File
• 4.2.1: Sample Configurations
• 5: Migration Samples
• 6: Prerequisites
• 7: Known Confluence Macros
• 8: Security
• 8.1: Endpoint reference
• 9: Using WikiTraccs.GUI
• 9.1: Source Configuration
• 10: Known Issues
• 11: Glossary
• 12: Authentication
• 12.1: Authenticating with SharePoint Online
• 12.2: Authenticating with Confluence
• 13: Data storage
• 14: Confluence Inventory
• 14.1: Getting the Confluence page count
• 15: License Activation
• 16: Monitoring Confluence to SharePoint Migration Progress
• 17: Multilingual Pages
• 17.1: Info about Scroll Translations
• 17.2: Migrating all Languages to one SharePoint Page
• 17.3: Migrating to Multilingual Pages in SharePoint Online
• 18: Setting up .NET
• 19: Updating previously migrated pages
• 20: WikiTraccs GUI vs. WikiTraccs Console

1 - How does WikiTraccs work?

Overview

WikiTraccs migrates content from Atlassian Confluence to SharePoint Online.

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

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

How does it work?

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

graph TD
  id1[EXPORT: WikiTraccs exports data from Confluence] --> id2[TRANSFORM: WikiTraccs transforms Confluence content to SharePoint content] --> id3[IMPORT: WikiTraccs imports pages and files to SharePoint]

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

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 (e-mail 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 Azure AD app registration is required. The app needs delegated permissions, ideally FullControl, but Manage works to an extend. Refer to the linked documentation for details.

Further reading:

• More about Confluence permissions here: Authenticating with Confluence
• More about SharePoint permissions here: Authenticating with SharePoint Online
• Step-by-step instructions for creating Azure AD app registration: Registering WikiTraccs as app in Azure AD

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 Azure AD, register an Azure AD application - this can be done by an account with Application Developer role in Azure AD, but see the linked Microsoft documentation for more details; this has to be done once as prerequisite to using WikiTraccs
• only if a new migration account is to be used for SharePoint: in the Microsoft 365 administration, create a migration account - this needs the User Administrator admin role
• only for WikiPakk: in SharePoint Online, add the WikiPakk app from Microsoft AppSource to the global tenant app catalog - the user doing this needs to be Owner of the tenant app catalog site, although it more commonly is the SharePoint administrator

Further reading:

• More on who can create and configure Azure AD applications: Delegate app registration permissions in Azure AD
• Step-by-step instructions for registering the application in Azure AD: Registering WikiTraccs as app in Azure AD
• More about the permissions of the Azure AD application here: Authenticating with SharePoint Online

Q: Will the links between Confluence pages work properly when migrated to SharePoint?

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

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

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

Further reading:

• Details about hard link handling: WikiTraccs 1.6.4 Release Notes
• Feature description: Features -> Links specific to Confluence
• For cross-space links to work the space to site mapping has to be configured in the Space Inventory: Cross-space links and target sites

Q: What is a Hard Link for WikiTraccs? And why is it hard for WikiTraccs to migrate hard links?

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

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

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

Further reading:

• Details about hard link handling: WikiTraccs 1.6.4 Release Notes
• Feature description: Features -> Links specific to Confluence

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

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

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

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

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

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

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

Further reading:

• Documentation: Confluence Space Inventory
• For cross-space links to work the space to site mapping has to be configured in the Space Inventory: Cross-space links and target sites

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

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

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

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

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

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

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

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

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

Furthermore, when moving from Confluence to SharePoint Online, you need to think about groups. Are all groups from all Confluence user directories that take part in the Confluence permission scheme present in Azure AD? 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?

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.

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

Further reading:

• This overview covers what WikiTraccs can do: Feature Overview. If you think something should definitely be in there, please create a feature proposal.

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

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

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

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

Further reading:

• Page migration success: Measuring page migration success
• Space migration progress: Monitoring Confluence to SharePoint Migration Progress
• And for general diagnosis of issues: common log files

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

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

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

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

You enter the target SharePoint URLs into the Space Inventory.

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

Further reading:

• Documentation: Confluence Space Inventory
• How to map Confluence Spaces to SharePoint Sites

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:

• Documentation about the challenges of large spaces: Migrating large Confluence spaces to SharePoint
• Feature proposal to speed up migrating large Confluence spaces: #69
• Documentation about throttling by Microsoft

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

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

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

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

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

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

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

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

Further reading:

• Documentation: Confluence Space Inventory
• How to map Confluence Spaces to SharePoint Sites
• Hints about what you should consider as part of your migration project: Migration Playbook
• More about the SharePoint breadcrumb and page tree experience: WikiPakk

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

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

Q: What do the success stories have in common?

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

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

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

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

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

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

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

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

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

Further reading:

• Separate FAQ around pricing and licensing here: WikiTraccs Pricing

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

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

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

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

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

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

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

Further reading:

• What can be migrated? Read here: WikiTraccs Features
• Visual migration samples: Migration Samples
• Blog post: What about those Confluence Macros?

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

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

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?

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

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

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

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

Further reading:

• See how certain Confluence macros are handled: Known Confluence Macros
• Blog post: What about those Confluence Macros?

Q: 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:

• How to map Confluence Spaces to SharePoint Sites
• Feature proposal to allow selecting pages via CQL query, which would allow “splitting” spaces: #77

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

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: Is it per-license cost or do you provide an enterprise license model?

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:

• Pricing
• License Activation

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

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?

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

Further reading:

• Introduction to SharePoint information architecture > Guiding principle: the world is flat

3 - Installation and Update

Downloading and running WikiTraccs for the first time

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

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

Updating WikiTraccs

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

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 temporary directory, e.g. C:\Users\<user>\AppData\Local\Temp\WikiTraccsGui_config.json.

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

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:

• Confluence migration source and spaces
• SharePoint target tenant and sites
• authentication for Confluence and SharePoint
• initial Space Inventory population
• migration mode: migrate content, update date and people fields, update permissions
• re-migrate content that had errors
• add link to source page or not
• macro ignore list
• translation migration mode for pages with translations

This is everything needed to get a migration going.

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

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

• Confluence Space Inventory - for you to select what to migrate, and where
• Confluence User and Group Mapping - for you to map Confluence user accounts to Azure AD 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:

• Configuration via Configuration File

4.1 - Confluence Space Inventory

Facts about the Confluence Space Inventory

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

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:

• The quick start guide covers selecting which spaces to migrate: Getting Started
• Why mapping to target sites is important for resolving migrated links: Cross-space links and target sites

4.1.1 - How to map Confluence Spaces to SharePoint Sites

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.

Cross-space links and target sites

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

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:

• 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

Link resolution is more difficult

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

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

Why is that?

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

Example:

• page A links to page B with ID 2000
• WikiTraccs needs to find out which SharePoint site page B will be migrated to, to create the proper SharePoint link
• there are two CQL queries configured: label="one", mapped to target 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

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 Azure AD Application
                "ClientId": "76762071-f1a9-4323-a97a-ab24992032fd",
                // SharePoint tenant ID
                "Tenant": "82fb6e24-c982-4f08-a009-1916ee226643",
                // how to authenticate with Azure AD; valid options are: "interactive" (supports MFA, use this), "credentials" (no MFA support)
                "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": [
            {
                // use the Confluence URL as TenantId
                "TenantId": "https://www.contoso.com/confluence",
                // 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.
        "WebDriverDirPath": "C:\\Users\\user\\Documents\\00_Portable",
        // 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",
        // 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",
        // 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
        },
        "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)?
            "EnableDummyImageFloatResetForImages": true,
            // Add a link to the source Confluence page?
            "AddLinkToSourcePage": false,
            // Mark formerly merged table cells?
            "TableCellSpanLayoutMode": "UnmarkedAdditionalSlots" // default: "MarkedAdditionalSlots"
        }
    }
}

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

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

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

Formatting

Confluence Text Formatting

SharePoint Text Formatting

Confluence Headings and Paragraphs

SharePoint Headings and Paragraphs

Confluence Text Alignment and Indentation

SharePoint Text Alignment and Indentation

Confluence Things from the Plus Menu

SharePoint Things from the Plus Menu

Confluence Lists and Task Lists

SharePoint Lists and Task Lists

Layouts

Standard Layouts

WikiTraccs transforms the Confluence layouts to the matching SharePoint layouts.

Confluence Standard Layouts

SharePoint Standard Layouts

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

Confluence Standard Layouts in Edit Mode

SharePoint Standard Layouts in Edit Mode

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

Sections and Columns

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

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

Confluence Sections and Columns

SharePoint Sections and Columns

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

Macros

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

Confluence Info Warning Tip Note

SharePoint Info Warning Tip Note

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

Confluence Code Macro

SharePoint Code Macro

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

Confluence Panels

SharePoint Panels

Note: The formatting capabilities in SharePoint are very limited.

Confluence Status Macro

SharePoint Status Macro

Files, Images, Links

Images, External Images and Images with Links

Confluence Images

SharePoint Images

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

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

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

Links to Content outside a Page

Confluence Links to Pages and other Content

SharePoint Links to Pages and other Content

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

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

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

Page Attachments

Confluence Page Attachments

SharePoint Page Attachments

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

Users and Groups

Confluence Mentions and Profiles

SharePoint Mentions and Profiles

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

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

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

Tables

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

Confluence Simple Tables

SharePoint Simple Tables

Confluence Table Widths

SharePoint Table Widths

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

Confluence Advanced Tables

SharePoint Advanced Tables

Confluence Larger Tables

SharePoint Larger Tables

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

6 - Prerequisites

Prerequisites

System requirements

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

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.

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

Architectural Overview of WikiTraccs

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

The building block explained:

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 - Endpoint reference

Required endpoints

The following table lists the required endpoints for using WikiTraccs.

Microsoft 365

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

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

9.1 - Source Configuration

Confluence Base Address

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

Source configuration

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

How to manually check that the base URL is correct?

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

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

Confluence Authentication Type

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

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

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.

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.

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

12 - Authentication

12.1 - 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 Azure AD 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 Azure AD application that must be configured to authorize the access to SharePoint Online. Such an Azure AD application has to either exist or you have to register a new one.

If you are lucky then there is already an Azure AD application registered that you can use. One example for an existing application is the Azure AD 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 Azure AD 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 Azure AD App.

The following permissions must be configured for the Azure AD 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 Azure AD 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 Azure AD 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 Azure AD 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.2 - Authenticating with Confluence

The following authentication methods are currently supported:

• cookie-based authentication

Cookie-based authentication

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.

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.

13 - Data storage

Data stored during transformation

Every page and attachment is stored locally.

Caching

WikiTraccs uses caches to store data for some time without calling the Confluence API again.

Detailed documentation is TBD.

14 - Confluence Inventory

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

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

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

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

Have a look at the child pages for more information.

14.1 - Getting the Confluence page count

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

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

Getting the page count from the database via SQL

Pro:

• returns a guaranteed accurate page count

Contra:

• needs permission to run SQL queries on the Confluence database
• does not work with 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.

Getting the page count from the REST API

Pro:

• easiest option, can be run in any browser
• works in Confluence Cloud

Contra:

• needs an account that is member of the confluence-administrators group
• yields an inaccurate page count if user has too low restrictive permission level
• does not work if Confluence search is broken or the search index is outdated

Copy the following search URL and replace confluencebaseurl with your Confluence’s base URL:

<confluencebaseurl>/rest/api/search?cql=type IN (blogpost, page)&limit=0

If you typically open Confluence at https://confluence.contoso.com the search URL would look like this:

https://confluence.contoso.com/rest/api/search?cql=type IN (blogpost, page)&limit=0

Open a browser, navigate to Confluence and log in.

Copy above search URL to the address bar of the browser you logged into Confluence with, and press the Return key to load the result.

The browser should now show text like this:

{"results":[],"start":0,"limit":0,"size":0,"totalSize":39348,"cqlQuery":"type IN (blogpost, page)","searchDuration":55,"_links":{"base":"https://confluence.contoso.com","context":""}}

The totalSize number is the page count, here: 39,348.

Third-party solutions

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

15 - License Activation

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

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.

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 file is at an expected location. Or get in touch if you need help.

16 - Monitoring Confluence to SharePoint Migration Progress

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
+++
CASIG	Page	78022313	2022-11-21 Peer Programming Call	/display/CASIG/2022-11-21+Peer+Programming+Call	2022-11-30-221728	2022-11-29-231728	needsupdate
CASIG	Page	78022335	CA2 SIG - Meeting November 15	/display/CASIG/CA2+SIG+-+Meeting+November+15	2022-11-24-065240	2022-11-24-065240	uptodate
CASIG	Page	78022347	CA2 SIG - Meeting December 13	/display/CASIG/CA2+SIG+-+Meeting+December+13	2022-12-14-014657	2022-12-14-014657	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)
• 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

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

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

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

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

17.3 - Migrating to Multilingual Pages in SharePoint Online

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

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

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

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.