Page Refinement - Log Broken Links

This article documents the ability of WikiTraccs to check already migrated pages for broken links.

Tags:

Note: Page Refinement is available as of WikiTraccs v1.28.0

Getting Started Quickly

Here’s how to enable and start the check for broken links:

Enable Page Refinement mode:
1. in the menu bar of WikiTraccs.GUI, click Settings -> Configure Transformation to open the settings dialog
2. as Mode select Refine Migrated Pages
3. check only the Log Broken Links action
4. click Ok to save the settings and close the settings dialog
Choose selectors in the Space Inventory list, just as you would before starting an actual migration
Click Start Transformation to start

Note that WikiTraccs highlights the chosen mode (so you can be sure it’s the right one), here Refine Pages - Log Links:

Prerequisites for Logging Broken Links

You need migrated pages. If you did not migrate pages, yet, searching for broken links doesn’t make sense.

Granularity of the Check

WikiTraccs checks SharePoint sites. All pages of a site will be checked.

There is no way of selecting just some pages of a site.

How to Select Sites to Check

Just as when migrating content, you’ll use the Space Inventory list to tell WikiTraccs which sites to check.

In the Space Inventory, WikiTraccs looks for selectors that are marked for transformation (those have a check mark set in the WT_Setting_RequestTransformation column).

For all selectors marked for transformation, WikiTraccs collects the target sites. That’s the value you entered in the WT_Setting_TargetSiteRootUrl column (hopefully before migrating content).

Those are the sites that WikiTraccs will check.

Where to Find the Link Report

WikiTraccs stores the link report in its WikiTraccs.GUI\logs folder.

You can use the Open Log Folder button to open the folder:

The link report file name looks like 2025-06-20-123335 localhost:8090___wt-link-report-v1-[log].txt:

The file name will look different for you, as the date and time of the migration run, as well as the Confluence base address are part of it.

One link report file per day will be created. If you start the check for broken links multiple times per day, WikiTraccs will continue to add to this file. Already checked pages won’t be checked again.

You can delete this file to start over.

The file content looks like this (note: sample for three broken links and no fix possible):

https://contoso.sharepoint.com/sites/WikiTraccsMigrationTool/SitePages/WIKITRACCS-WikiTraccs---Confluence-to-SharePoint-Migration-Tool-35848209.aspx	12	1.0	/sites/Default/SitePages/TREE-WikiPakk---SharePoint-Page-Tree-35848215.aspx	?	ContentSnapshotNotFound,SharePointSearchNoHit
https://contoso.sharepoint.com/sites/WikiTraccsMigrationTool/SitePages/WIKITRACCS-Metadata-for-the-WikiPakk-Page-Tree-35848235.aspx	14	1.0	/sites/Default/SitePages/TREE-WikiPakk---SharePoint-Page-Tree-35848215.aspx	?	ContentSnapshotNotFound,SharePointSearchNoHit
https://contoso.sharepoint.com/sites/WikiTraccsMigrationTool/SitePages/WIKITRACCS-Metadata-for-the-WikiPakk-Page-Tree-35848235.aspx	14	1.0	/sites/Default/SitePages/TREE-Scripting-the-Page-Hierarchy-35848233.aspx	?	ContentSnapshotNotFound,SharePointSearchNoHit
https://contoso.sharepoint.com/sites/WikiTraccsMigrationTool	14	Site Processing Checkpoint (UTC 2025-06-20 12:33:50, 4 pages checked in this run)	wt-checkpoint	638860196303631858

The file content could also look like this (note: sample for three broken links and three fix candidates found):

https://contoso.sharepoint.com/sites/WikiTraccsMigrationTool/SitePages/WIKITRACCS-WikiTraccs---Confluence-to-SharePoint-Migration-Tool-35848209.aspx	12	1.0	/sites/Default/SitePages/TREE-WikiPakk---SharePoint-Page-Tree-35848215.aspx	/sites/WikiPakkPageTree/SitePages/TREE-WikiPakk---SharePoint-Page-Tree-35848215.aspx	ContentSnapshotFoundWithDifferentLink
https://contoso.sharepoint.com/sites/WikiTraccsMigrationTool/SitePages/WIKITRACCS-Metadata-for-the-WikiPakk-Page-Tree-35848235.aspx	14	1.0	/sites/Default/SitePages/TREE-WikiPakk---SharePoint-Page-Tree-35848215.aspx	/sites/WikiPakkPageTree/SitePages/TREE-WikiPakk---SharePoint-Page-Tree-35848215.aspx	ContentSnapshotFoundWithDifferentLink
https://contoso.sharepoint.com/sites/WikiTraccsMigrationTool/SitePages/WIKITRACCS-Metadata-for-the-WikiPakk-Page-Tree-35848235.aspx	14	1.0	/sites/Default/SitePages/TREE-Scripting-the-Page-Hierarchy-35848233.aspx	/sites/WikiPakkPageTree/SitePages/TREE-Scripting-the-Page-Hierarchy-35848233.aspx	ContentSnapshotFoundWithDifferentLink
https://contoso.sharepoint.com/sites/WikiTraccsMigrationTool	14	Site Processing Checkpoint (UTC 2025-06-20 12:55:40, 4 pages checked in this run)	wt-checkpoint	638860209402343386
https://contoso.sharepoint.com/sites/WikiPakkPageTree	4	Site Processing Checkpoint (UTC 2025-06-20 12:55:40, 2 pages checked in this run)	wt-checkpoint	638860209406942630

Each line contains multiple values separated by the tab character. Those values are:

Page URL - the SharePoint page that WikiTraccs checked
- example: https://contoso.sharepoint.com/sites/WikiTraccsMigrationTool/SitePages/WIKITRACCS-WikiTraccs---Confluence-to-SharePoint-Migration-Tool-35848209.aspx
Page Item ID - the SharePoint list item ID in the Site Pages library
- example: 12
Page Version - the page version
- example: 1.0
Link - link that couldn’t be verified (note: verified links are not logged)
- example: /sites/Default/SitePages/TREE-WikiPakk---SharePoint-Page-Tree-35848215.aspx
New Link - if WikiTraccs found the page in another site, this is the link; or ? if no link target could be found
- example: /sites/WikiPakkPageTree/SitePages/TREE-WikiPakk---SharePoint-Page-Tree-35848215.aspx
Result - the verification result, indicating where WikiTraccs checked and how it went
- example: ContentSnapshotNotFound,SharePointSearchNoHit
- example: ContentSnapshotFoundWithDifferentLink

Lines with the keyword wt-checkpoint are checkpoints set by WikiTraccs so it knows where to continue, should a tranformation run be interrupted and restarted.

How does WikiTraccs Identify Broken Links?

WikiTraccs extracts the space key and page ID from links. This is possible since links to migrated SharePoint pages follow the naming scheme SPACEKEY-some-title-PAGEID.aspx.

Having the space key and the page ID, WikiTraccs looks up the page in the Confluence Content Snapshots list (in the WikiTraccs site). For every page that WikiTraccs migrates, the target URL of the migrated page is stored there as well.

If WikiTraccs doesn’t find an entry in the Confluence Content Snapshots list, it will try to find the target page via SharePoint Search.

When WikiTraccs finds an “authoritative” URL using any of the methods above, it will compare this URL with the link it found in the page. WikiTraccs detects if the authoritative URL points to a different site than the link that is currently in the page.

If the authoritative URL and the link in the page differ, or the link couldn’t be verified at all, then this will be added to the link report file.

Limitations

The following limitations apply:

performance is not at its peak, yet
links in text web parts are checked; links in other web parts (for example image web part) are not handled
handling of page links only; no @-mentions (yet)
WikiTraccs only handles links to pages that follow its naming scheme: SPACEKEY-some-title-PAGEID.aspx

For details, refer to issue [WikiTraccs] [Feature] Find and fix broken links #152.

Last modified July 3, 2025