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

Return to the regular view of this page.

Configuration via Configuration File

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

Configuring via configuration file

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

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

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

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

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

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

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

1 - Sample Configurations

This article contains sample configurations for different purposes.

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

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

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

Sample: Migrate contents of one space

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

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

Snippet: Prevent WikiTraccs from downloading external images

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

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

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

Snippet: Prevent WikiTraccs from reaching out to Jira

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

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

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

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

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

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

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

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

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

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

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

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

Snippet: Change temporary storage folder pathes

Use those settings to control where WikiTraccs stores temporary files:

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

Explanation:

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

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

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

WikiTraccs normally promotes migrated Confluence blogposts to SharePoint news.

Prevent that with the following configuration:

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

Snippet: Configuring multi-pass migrations

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

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

Config File Templates for Debugging Purposes

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

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

Snippet: Generic Debug Configuration Template

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

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

Snippet: “Clear Cache” Settings Template

This setting clears the cache on every start:

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

Snippet: Don’t mark formerly merged table cells

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

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