Sample Configurations

This article contains sample configurations for different purposes.
Tags:

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

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

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

Sample: Migrate contents of one space

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

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

Snippet: Prevent WikiTraccs from downloading external images

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

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

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

Snippet: Prevent WikiTraccs from reaching out to Jira

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

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

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

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

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

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

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

Snippet: Change temporary storage folder pathes

Use those settings to control where WikiTraccs stores temporary files:

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

Explanation:

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

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

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

WikiTraccs normally promotes migrated Confluence blogposts to SharePoint news.

Prevent that with the following configuration:

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

Snippet: Configuring multi-pass migrations

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

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

Config File Templates for Debugging Purposes

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

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

Snippet: Generic Debug Configuration Template

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

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

Snippet: “Clear Cache” Settings Template

This setting clears the cache on every start:

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

Snippet: Don’t mark formerly merged table cells

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

{
    "CustomSettings": {
      "Features": {
        "TableCellSpanLayoutMode": "UnmarkedAdditionalSlots"
      }
    }
}
Last modified March 19, 2024