Settings & Configuration

• 1: Configuration via WikiTraccs.GUI (blue window)
• 2: Confluence Space Inventory
• 2.1: How to map Confluence Source Selectors to SharePoint Sites
• 2.2: How to migrate Confluence Content using Space Selectors
• 2.3: How to migrate Confluence Content using CQL Query Selectors
• 2.4: How to migrate Confluence Content using Content ID Selectors
• 3: Configuration via Configuration File
• 3.1: Sample Configurations

1 - Configuration via WikiTraccs.GUI (blue window)

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

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

The following sections describe settings in detail.

Tab “Migration”

Migration Mode

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

Mode “Migrate Content”

This mode selects content migration.

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

You’ll always use this mode first.

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

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

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

Background

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

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

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

What does the update mode do?

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

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

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

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

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

Mode “Update Permissions (of already migrated content)”

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

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

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

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

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

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

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

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

Migrate blog posts

Choose whether to migrate blog posts or not.

Migrate footer comments

Choose whether to migrate footer comments or not.

Download external images

Choose whether to download external images or not.

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

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

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

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

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

2 - Confluence Space Inventory

Facts about the Confluence Space Inventory

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

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

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

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

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

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

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

Accessing the Space Inventory

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

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

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

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

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

How does it work exactly?

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

This image summarized:

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

Using the Confluence Space Inventory

Here are other resources involving the Space Inventory:

• Which spaces to migrate is covered in the quick start guide: Getting Started
• Why mapping to target sites is important for resolving migrated links: Cross-space links and target sites
• Migration Waves
• How to run parallel WikiTraccs migrations

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

2.1 - How to map Confluence Source Selectors to SharePoint Sites

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

Content to migrate is chosen by source content selectors.

Selectors

A selector tells WikiTraccs which Confluence content to migrate.

The following selectors are supported:

• Space selector - to select all pages of a space
• CQL query selector - to select pages via CQL search query
• Content ID selector - to select pages by ID

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

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

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

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

Migrate to one target site by default

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

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

Default Target Site Configuration in WikiTraccs.GUI

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

Configure a different target site for selectors

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

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

Target Site Root URL Column

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

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 transform links between Confluence pages to links between SharePoint pages.

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

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

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

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

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

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

2.2 - How to migrate Confluence Content using Space Selectors

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

Why use a space selector?

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

Usual scenarios are:

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

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

Where to configure space selectors?

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

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

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

Note: Other columns have been omitted for brevity.

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

Link Transformation

Space selectors are relevant for link transformation.

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

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

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

2.3 - How to migrate Confluence Content 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:

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

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

Link Transformation

CQL query selectors are relevant for link transformation.

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

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

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

2.4 - How to migrate Confluence Content using Content ID Selectors

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

Why use a content ID selector?

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

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

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

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

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

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

WikiTraccs’ Content ID Format

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

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

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

Where to configure content ID selectors?

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

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

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

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

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

Migrating via CQL query vs. migrating via content IDs

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

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

A WikiTraccs content ID selector does not have this restriction.

Why is that?

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

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

The consequences of using content ID source selectors

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

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

SQL Snippets

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

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

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

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

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

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

	SELECT contentid, LOWER(contenttype) AS contenttype
	FROM content LEFT JOIN spaces ON content.spaceid = spaces.spaceid
	WHERE (contenttype='PAGE' OR contenttype='BLOGPOST') 
		AND prevver IS NULL 
		AND content_status='current' 
		AND spacekey='MYSPACEKEY'
    ORDER BY contenttype, contentId
) subquery;

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

Link Transformation

Content ID selectors are relevant for link transformation.

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

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

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

3 - Configuration via Configuration File

Configuring via configuration file

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

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

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

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

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

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

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

3.1 - Sample Configurations

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

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

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

Sample: Migrate contents of one space

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

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

Snippet: Prevent WikiTraccs from downloading external images

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

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

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

Snippet: Prevent WikiTraccs from reaching out to Jira

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

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

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

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

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

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

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

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

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

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

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

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

Snippet: Change temporary storage folder pathes

Use those settings to control where WikiTraccs stores temporary files:

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

Explanation:

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

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

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

WikiTraccs normally promotes migrated Confluence blogposts to SharePoint news.

Prevent that with the following configuration:

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

Snippet: Configuring multi-pass migrations

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

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

Config File Templates for Debugging Purposes

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

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

Snippet: Generic Debug Configuration Template

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

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

Snippet: “Clear Cache” Settings Template

This setting clears the cache on every start:

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

Snippet: Don’t mark formerly merged table cells

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

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