Configuration File: appsettings.json
Note
You have to restart the application to apply changes to settings files.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.
Note
appsettings.json can be used together with WikiTraccs.GUI to configure many settings not available in the GUI. Note that not all configuration options might be available. Get in touch if some setting doesn’t seem to be applied.Fixed site names
WikiTraccsDefaultTarget is a fixed name. Do not change it. Use this name in TargetSites and in each TransformationMappings entry that refers to the default target site. WikiTraccs is also a fixed name for the management site. Set each SiteRootUrl to your own SharePoint site URL.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"
},
{
// Fixed name for the default target site; do not change WikiTraccsDefaultTarget.
"HumanReadableId": "WikiTraccsDefaultTarget",
"SiteRootUrl": "https://contoso.sharepoint.com/sites/DefaultTarget"
}
]
}
],
"TransformationMappings": [
{
"SourceTenantHumanReadableId": "Contoso Confluence",
"TargetTenantHumanReadableId": "Contoso SharePoint",
// Use the fixed name WikiTraccsDefaultTarget to refer to the default target site.
"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",
// ChromeDriver version to download (troubleshooting setting)
"ChromeDriverVersionOverride": null,
// EdgeDriver version to download (troubleshooting setting)
"EdgeDriverVersionOverride": null,
// Directory where WikiTraccs looks for the WebDriver, and also store the downloaded WebDriver here
"WebDriverDirPath": null,
// Path to chrome.exe (troubleshooting setting)
"ChromeBinaryPath": null,
// Path to msedge.exe (troubleshooting setting)
"EdgeBinaryPath": null,
}
}
The larger sample below includes settings for migration, inventory, and troubleshooting. Connection details, Windows paths, proxy addresses, and the external domain rule are examples. Other optional settings use their current defaults. Replace the example values with your own values. Keep the fixed names WikiTraccs and WikiTraccsDefaultTarget.
A value of null leaves a setting unset. The comment explains which value or behavior WikiTraccs then uses. Empty selector lists add no source content selectors to those selected in the Confluence Space Inventory list.
Use one operation for each pass. For page refinement, set SpaceTransfer.Operations to ["refinepages"], then select the required PageRefiner settings.
For Telegram setup instructions and dummy example values, see the Telegram settings snippet.
Note: The log folder and Telegram settings are available as of WikiTraccs v1.37.
{
"CustomSettings": {
// Configure the Microsoft 365 connection and SharePoint sites.
"TargetTenants": [
{
// Name used to refer to this Microsoft 365 connection.
"HumanReadableId": "Contoso SharePoint",
// Root URL of the SharePoint tenant.
"SharePointRootUrl": "https://contoso.sharepoint.com",
// Application ID of the registered Entra ID application.
"ClientId": "76762071-f1a9-4323-a97a-ab24992032fd",
// Tenant ID of the Microsoft 365 tenant.
"Tenant": "82fb6e24-c982-4f08-a009-1916ee226643",
// Open the Microsoft 365 sign-in browser; this method supports MFA.
"AuthenticationType": "interactive",
// Include the management site and the default target site.
"TargetSites": [
{
// Required name for the site with the inventory and user mapping lists.
"HumanReadableId": "WikiTraccs",
// URL of the WikiTraccs management site.
"SiteRootUrl": "https://contoso.sharepoint.com/sites/MigrationStore"
},
{
// Fixed name for the default target site; do not change WikiTraccsDefaultTarget.
"HumanReadableId": "WikiTraccsDefaultTarget",
// Target site for source content selectors that have no target site of their own.
"SiteRootUrl": "https://contoso.sharepoint.com/sites/DefaultTarget"
}
]
}
],
// Connect each Confluence source to a SharePoint target.
"TransformationMappings": [
{
// Name of the source connection from SourceTenantIncludeList.
"SourceTenantHumanReadableId": "Contoso Confluence",
// Name of the target connection from TargetTenants.
"TargetTenantHumanReadableId": "Contoso SharePoint",
// Use the fixed name WikiTraccsDefaultTarget to refer to the default target site.
"TargetSiteHumanReadableId": "WikiTraccsDefaultTarget"
}
],
// Configure the Confluence connections and migration operations.
"SourceTenantIncludeList": [
{
// Confluence base URL; include the context path if there is one.
"TenantId": "https://www.contoso.com/confluence",
// Name used to refer to this Confluence connection.
"HumanReadableId": "Contoso Confluence",
// Use browser sign-in and copy the Confluence session cookies.
"AuthenticationType": "cookie",
// Sign-in URL; null opens the Confluence base URL.
"AuthUrl": null,
// Configure content migration for this Confluence connection.
"SpaceTransfer": {
// Enable content migration for this source.
"Enabled": true,
// Migrate content; use checkprincipals in a separate pass to update page authors after user mapping.
"Operations": ["retrievecontents"],
// Additional source content selectors; an empty list uses the selection in the Confluence Space Inventory list.
"SpaceIncludeList": []
},
// Configure permission migration for this Confluence connection.
"PermissionTransfer": {
// Enable permission migration; disable SpaceTransfer before you enable this setting.
"Enabled": false,
// Additional source content selectors for permission migration.
"SpaceIncludeList": []
}
}
],
// Page mode: add, add-and-overwrite-outdated, or add-and-overwrite-existing; add keeps existing pages.
"SharePointPageCreationBehavior": "add",
// Select waves; null leaves inventory selectors unrestricted and includes only Content Decision List rows without a wave.
"WaveSelection": null,
// Check whether a newer WikiTraccs version is available.
"CheckForUpdates": true,
// License file path; null uses the usual license file search.
"LicenseFilePath": "D:\\WikiTraccs\\license.txt",
// Example download rule for an external domain; the default is an empty list ([]).
"ExternalDomains": [
{
// Apply this rule to URLs that start with this address; replace the example address.
"UrlStartsWith": "https://images.example.com/",
// Maximum download attempts, including the first attempt.
"HttpTimeoutRetries": 3,
// Download timeout, in seconds.
"HttpTimeoutSecs": 12
}
],
// Attachment cache folder; null uses the WikiTraccs folder in the current user's local application data.
"AttachmentRegistryRootPath": "D:\\WikiTraccs\\Attachments",
// Folder for persistent migration data; null uses the WikiTraccs folder in the current user's local application data.
"DurableStorageRootPath": "D:\\WikiTraccs\\Data",
// Temporary file folder; null uses the WikiTraccs folder under the system temporary folder.
"TempPath": "D:\\Temp\\WikiTraccs",
// Minimum level of detail to write to the logs.
"LogLevel": "Debug",
// Configure paths for log files.
"Paths": {
// Log folder; the default is logs, relative to the working folder.
"LogFolderPath": "D:\\WikiTraccs\\Logs"
},
// Browser for automated tasks; use chrome or edge.
"Browser": "chrome",
// Chrome executable path; null finds the installed browser automatically.
"ChromeBinaryPath": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
// Edge executable path; null finds the installed browser automatically.
"EdgeBinaryPath": "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe",
// Browser driver folder; null uses AttachmentRegistryRootPath, and WikiTraccs downloads missing drivers there.
"WebDriverDirPath": "D:\\WikiTraccs\\WebDrivers",
// ChromeDriver version; null selects a version that matches Chrome.
"ChromeDriverVersionOverride": null,
// EdgeDriver version; null selects a version that matches Edge.
"EdgeDriverVersionOverride": null,
// Example browser proxy; omit this section to keep the default proxy configuration.
"Proxy": {
// Proxy host and port for HTTP requests; replace the example host and port.
"HttpProxy": "proxy.example.com:8080",
// Proxy host and port for HTTPS requests; replace the example host and port.
"SslProxy": "proxy.example.com:8080"
},
// Configure notifications about migration progress.
"Notifications": {
// Send notifications when this setting is true and Telegram is configured.
"Enabled": false,
// Include recent run messages in the Telegram progress display.
"IncludeIntermediaryMessages": true,
// Configure the Telegram bot and destination chat before you enable notifications.
"Telegram": {
// Bot token from BotFather; null means no bot is configured.
"BotToken": null,
// Destination chat ID; null means no chat is configured.
"ChatId": null
}
},
// Configure local inventory storage.
"Inventory": {
// Inventory report folder; null uses the current user's Documents folder.
"StorageFolderPath": "D:\\WikiTraccs\\Reports",
// Inventory database folder; null uses wikitraccs-inventory under DurableStorageRootPath.
"DatabaseFolderPath": "D:\\WikiTraccs\\Data\\wikitraccs-inventory"
},
// Configure migration of Scroll Translations content.
"Translations": {
// Put all language versions on one SharePoint page.
"TranslationMigrationModes": ["SingleWithAllLanguagesOnIt"],
// Preferred language for SingleWithStaticLanguage mode; null sets no preferred language.
"SingleModePreferredLanguageKey": null
},
// Configure optional changes to page content.
"OptionalPageTransformations": {
// Convert image groups to SharePoint image galleries.
"ImagesToGalleriesEnabled": false
},
// Rules that remove matching macros; use macro transformation templates instead.
"MacroTransformationConfigs": [],
// Configure content, layout, and migration checks.
"Features": {
// Update the Confluence Space Inventory list; the GUI also has a button for this operation.
"FillSpacesList": false,
// Ignore source content selectors from the Confluence Space Inventory list.
"IgnoreSpaceInventory": false,
// Enable Content Decision Lists for content selection and review.
"EnableContentDecisionLists": false,
// Hold back included Content Decision List rows until their review status permits migration.
"ContentDecisionApplyReviewGate": false,
// Review status that permits migration when ContentDecisionApplyReviewGate is true.
"ContentDecisionPassingReviewStatus": "Review done",
// Include archived Confluence content in migration.
"MigrateArchivedContent": true,
// Migrate Confluence blog posts to SharePoint pages.
"MigrateBlogposts": true,
// Publish migrated blog posts as SharePoint news; this can cause user notifications.
"PromoteBlogposts": true,
// Use a migrated Confluence space home page as the SharePoint site home page.
"SetHomepage": true,
// Add a link from each migrated page to its Confluence source.
"AddLinkToSourcePage": false,
// Add attachments to a section on the migrated page.
"AddAttachmentsSection": true,
// Add Confluence footer comments to the migrated page content.
"MigrateFooterComments": true,
// Convert page tree macros to a static tree of links.
"TransformPageTreeMacro": true,
// Convert roadmap macros to image placeholders; some details, such as text, are absent.
"TransformRoadmapMacro": true,
// Convert table of contents macros to links to page headings.
"TransformTableOfContentsMacro": true,
// Convert Confluence URL links to links to the migrated content where possible.
"ResolveHardLinks": true,
// Convert all supported links, including links that use the default target site.
"LinkTransformationMode": "all",
// Treat HTTP and HTTPS links to the same Confluence site as links to one source.
"TreatHttpAndHttpsAsSameForTenantInternalHardLinks": true,
// Download images from external websites and upload them to SharePoint.
"DownloadExternalImages": true,
// Adjust external download timeouts when a host fails repeatedly.
"AdaptiveExternalTimeouts": true,
// Skip attachment downloads when this setting is true.
"SkipAttachmentDownload": false,
// Continue migration when an attachment cannot be downloaded.
"IgnoreBrokenAttachments": false,
// Add missing draw.io file extensions and change .jar extensions to .jar_.
"RenameFiles": true,
// Use table conversion that preserves more of the Confluence layout.
"UseNonStandardTableTransformation": true,
// Adjust table widths to fit their content.
"OptimizeTableSize": true,
// Nested table mode; null keeps nested tables with the default table conversion.
"TableNestingMode": null,
// Move images outside lists to change their layout in SharePoint.
"MoveImagesOutOfLists": false,
// Create preview images for draw.io diagrams that have no preview.
"CreateMissingDrawIoPreviewImages": false,
// Create preview images for additional pages in draw.io diagrams.
"CreateMoreDrawIoPreviewImages": false,
// Confluence Cloud: migrate whiteboards as images.
"MigrateWhiteboards": false,
// Confluence Cloud: attach raw whiteboard data and media files to the migrated page.
"ExportRawWhiteboardData": false,
// Copy Team Calendars to SharePoint lists; calendar permissions are not copied.
"SynchronizeTeamCalendars": false,
// Confluence Cloud: copy databases to SharePoint lists with browser sign-in; permissions are not copied.
"MigrateDatabases": false,
// Confluence DC: attach a native Confluence Word export to migrated pages.
"ExportPagesAsNativeWord": false,
// Confluence DC: attach selected page versions as PDFs; requires Scroll PDF Exporter.
"ExportHistoricPageVersionsAsPdf": false,
// Configure version exports when ExportHistoricPageVersionsAsPdf is true.
"ScrollPdfExport": {
// Number of recent historical versions to export; 0 selects none.
"LastVersionsCount": 0,
// Export the current page version as a PDF too.
"IncludeCurrentVersionAsPdf": false,
// Also export versions that reached a Comala final state.
"AddHistoricPageIdsFromComalaFinalState": false,
// Maximum number of Comala final-state versions to add; 0 sets no limit.
"ComalaFinalStateMaxCount": 0,
// Historical version IDs for each source page ID; null adds no explicit versions.
"HistoricPageIdsByPageId": null,
// Scroll PDF Exporter template to use.
"TemplateId": "com.k15t.scroll.pdf.default-template-documentation",
// Export only the selected page in each PDF.
"PageSet": "current",
// Maximum number of seconds to wait for one PDF export.
"MaxWaitSeconds": 180,
// Number of retries after a failed PDF export.
"RetryAttempts": 0,
// Continue with other selected versions when one export fails.
"ContinueOnExportError": true,
// Limit PDF exports to selected waves; null adds no wave restriction.
"WaveSelection": null
},
// Configure Comala final-state detection for historical PDF exports.
"ComalaDocumentManagement": {
// Comma-separated final-state names; names are case-sensitive.
"FinalStateNames": "Approved,Done,Finished,approved,done,finished,APPROVED,DONE,FINISHED"
},
// Check page metadata after writing it to SharePoint.
"VerifyMetadataAfterProvisioning": true,
// Check attachments after writing them to SharePoint.
"VerifyAttachmentsAfterProvisioning": true,
// In refinepages mode, write a report of broken links.
"PageRefinerLogsBrokenLinks": true,
// In refinepages mode, repair broken links where possible.
"PageRefinerFixesBrokenLinks": false,
// In refinepages mode, change links to open in the same browser tab.
"PageRefinerMakesLinksOpenInSameTab": false,
// In refinepages mode, write a report of user mentions that need an update.
"PageRefinerLogsBrokenPrincipalRefs": false,
// In refinepages mode, update user mentions from the user mapping list.
"PageRefinerFixesBrokenPrincipalRefs": false,
// In refinepages mode, report web part properties that differ from the expected values.
"PageRefinerLogsWebPartPropertyDrift": false,
// In refinepages mode, repair web part properties that differ from the expected values.
"PageRefinerFixesWebPartPropertyDrift": false,
// Send Confluence requests through the signed-in browser.
"UseSeleniumProxy": false,
// Reload the Confluence sign-in tab at intervals to keep the session active.
"InteractiveAuthKeepAliveEnabled": false,
// Number of seconds between reloads when InteractiveAuthKeepAliveEnabled is true.
"InteractiveAuthReloadIntervalSeconds": 300,
// Confluence DC: wait for administrator access confirmation during browser sign-in.
"WaitForWebSudo": false
},
// Adjust request limits, waiting times, and processing sizes.
"WiggleRoom": {
// Allowed difference between source and target modification times, in seconds, before a page is considered changed.
"OutdatedPagesSeconds": 3,
// Maximum wait for Jira requests, in seconds; -1 disables these requests.
"JiraMaxWaitTimeSec": 30,
// Fixed number of simultaneous attachment uploads; null selects the number from each page's total attachment size.
"ParallelFileOperationsCount": null,
// Simultaneous uploads for pages below the attachment size threshold.
"ParallelFileOperationsLowLevel": 2,
// Simultaneous uploads for pages at or above the attachment size threshold.
"ParallelFileOperationsHighLevel": 4,
// Total attachment size per page, in bytes, at which the higher upload level applies.
"ParallelFileOperationsHighLevelPageBytes": 500000,
// Maximum number of files in one upload group.
"MaxFilesPerProvisioningChunk": 20,
// Base wait after a failed SharePoint write, in seconds; later retries wait longer.
"WaitTimePerProvisioningRetryBaseSec": 20,
// Total attempts to write a page to SharePoint, including the first attempt.
"ProvisioningRetriesCount": 4,
// Total attempts to read the content or permissions of a source content selector.
"SelectorRetriesCount": 4,
// Base wait after a failed selector read, in seconds; later retries wait longer.
"WaitTimePerSelectorRetryBaseSec": 20,
// Results per Confluence content request; null uses the limit for each API endpoint.
"PageRetrievalPageSizeOverride": null,
// Content IDs per CQL query; reduce this value if Confluence rejects large queries.
"PageRetrievalByContentIdsCqlPageSizeOverride": 200,
// Maximum number of Atlassian requests per second; null sets no explicit rate limit.
"AtlassianMaxRequestsPerSecond": null,
// Maximum wait for a SharePoint PnP request, in seconds.
"PnpRequestTimeout": 300,
// Maximum wait for an HTTP download request, in seconds.
"HttpTimeoutSecs": 300,
// Maximum wait for browser startup, in seconds.
"BrowserStartTimeoutSec": 300,
// Show the browser that measures table layout.
"BrowserVisibilityTableCalculator": true,
// Maximum total table cells per page before conversion stops and uses a file-based page export; 0 disables the limit.
"MaxTableCellsAllowedLimit": 40000,
// Maximum tables per page before conversion stops and uses a file-based page export; 0 disables the limit.
"MaxTablesAllowedLimit": 300,
// Maximum non-empty code lines to keep in a text web part instead of a code snippet web part.
"CodeMacroPreElementMaxLines": 4,
// Number of pages to read at a time during page refinement.
"PageRefinementBatchSize": 5,
// Number of seconds between saved page refinement checkpoints.
"PageRefinementCheckpointIntervalSec": 60,
// Maximum age of messages in the GUI log display, in seconds.
"GuiLogMaximumLineAgeSec": 120,
// Maximum number of messages kept in the GUI log display.
"GuiLogMaximumLineCount": 1000
},
// Configure checks and saved data for troubleshooting.
"Debug": {
// Clear the local cache when WikiTraccs starts.
"ClearLocalCacheOnStart": false,
// Save each page's source content to disk for troubleshooting.
"SaveTransformationInputToDisk": false,
// Skip connection checks before a GUI migration.
"SkipConnectionCheckInWikiTraccsGui": false,
// Continue despite target site preparation errors; keep false for normal migrations.
"SkipPreparationResultCheck": false,
// Read fresh API data instead of using cached responses.
"BypassCaches": false
}
}
}
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.