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

Return to the regular view of this page.

Page Refinement - Log User Mentions

This article documents the ability of WikiTraccs to check already migrated pages for user mentions that can be refined.

    Note: Logging User Mentions is available as of WikiTraccs v1.33.28

    Getting Started Quickly

    Here’s how to enable and start the check for user mentions:

    1. 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 User Mentions action
      4. click Ok to save the settings and close the settings dialog
    2. Choose selectors in the Space Inventory list, just as you would before starting an actual migration
    3. Click Start Transformation to start

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

    Prerequisites for Logging User Mentions

    You need migrated pages. If you did not migrate pages, yet, checking user mentions doesn’t make sense.

    The log action reports on two things at once: user mentions that are already correct (validated no-change) and user mentions that would benefit from a rewrite because a mapping was added, changed, or is missing. The most typical trigger is a change to the WikiTraccs User Mappings list (in the WikiTraccs site) after the initial migration - new mapping rows make previously-unmapped mentions resolvable, and edited rows shift existing mentions to a different target. The log run surfaces both cases so you can decide whether to follow up with the fix action.

    You don’t need a fully populated mappings list for the log to be useful. If a mapping is missing, the report records the mention as MentionMappingMissing, which is itself an actionable result - it tells you which source users need a mapping row added before fixing can take effect.

    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 Mention Report

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

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

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

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

    One mention report file per day will be created. If you start the check for user mentions 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 mention report is its own file, separate from the broken-links report. Both files can exist side by side when both refinement actions are enabled.

    The file content looks like this (note: header row plus sample data rows for three mentions):

    SourcePage	ItemId	Version	OldLink	NewLink	State	VersionAfterUpdate	MentionSourceMri	MentionResolutionMode	MentionRegistryResolution	MentionMatchedMappingCount	MentionTargetUpn	MentionTargetDisplayName	MentionSourceDisplayName
https://contoso.sharepoint.com/sites/WikiTraccsMigrationTool/SitePages/WIKITRACCS-Welcome-35848209.aspx	12	1.0	/_layouts/15/sharepoint.aspx?q=heu%40old.com&v=%2Fsearch%2Fpeople&wtmri=user:name:atlassian:|onprem|heu&wtmdn=Heinrich&wtmsn=Heinrich Ulbricht	/_layouts/15/sharepoint.aspx?q=henry%40contoso.com&v=%2Fsearch%2Fpeople&wtmri=user:name:atlassian:|onprem|heu&wtmdn=Henry U&wtmsn=Heinrich Ulbricht	MentionUrlUpdated,MentionTextUpdated			user:name:atlassian:|onprem|heu	Tier1Real	CacheHitRich	1	[email protected]	Henry U	Heinrich Ulbricht
https://contoso.sharepoint.com/sites/WikiTraccsMigrationTool/SitePages/WIKITRACCS-Welcome-35848209.aspx	12	1.0	/_layouts/15/sharepoint.aspx?q=unknown%40old.com&v=%2Fsearch%2Fpeople&wtmri=user:name:atlassian:|onprem|unknown	?	MentionMappingMissing			user:name:atlassian:|onprem|unknown	Tier1Real	CacheMissDummyFallback	0			
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

    Each line contains multiple values separated by the tab character. The first line is a header row documenting the columns; data rows follow the same column layout. The columns are:

    • SourcePage - the SharePoint page that WikiTraccs checked
      • example: https://contoso.sharepoint.com/sites/WikiTraccsMigrationTool/SitePages/WIKITRACCS-Welcome-35848209.aspx
    • ItemId - the SharePoint list item ID in the Site Pages library
      • example: 12
    • Version - the page version
      • example: 1.0
    • OldLink - the mention link as it currently appears in the page
      • example: /_layouts/15/sharepoint.aspx?q=heu%40old.com&v=%2Fsearch%2Fpeople&wtmri=user:name:atlassian:|onprem|heu&wtmdn=Heinrich
    • NewLink - the mention link WikiTraccs would write (or ? if no target could be resolved)
      • example: /_layouts/15/sharepoint.aspx?q=henry%40contoso.com&v=%2Fsearch%2Fpeople&wtmri=user:name:atlassian:|onprem|heu&wtmdn=Henry U&wtmsn=Heinrich Ulbricht
    • State - the classification result, indicating what WikiTraccs decided to do
      • example: MentionUrlUpdated,MentionTextUpdated
      • example: MentionMappingMissing
      • example: MentionValidatedNoChange
    • VersionAfterUpdate - the SharePoint page version after the refinement run wrote changes (empty for log-only runs)
    • MentionSourceMri - the source Confluence user’s identifier that WikiTraccs extracted from the anchor (the wtmri URL parameter added during migration)
      • example: user:name:atlassian:|onprem|heu
    • MentionResolutionMode - which recognition path WikiTraccs used
      • Tier1Real - the anchor carries a real source-user identifier (the normal case)
      • Tier1Placeholder - the anchor carries a null-placeholder identifier (historical anchor from before user info was captured)
      • Tier1Legacy - the anchor has the source-user identifier but no display-name breadcrumb (from before display names were captured in the URL)
      • Tier2Promoted - the anchor pre-dates the MRI breadcrumb entirely; WikiTraccs recovered the source user via the email heuristic
      • Tier2Ambiguous - same as above, but more than one mapping row matched the email
      • Tier2NoMatch - tier-2 candidate, but the email heuristic yielded no mapping row
    • MentionRegistryResolution - how WikiTraccs looked up the source user in its local cache
      • CacheHitRich - user found with full breadcrumbs (best case)
      • CacheHitBare - user found but only with mapping-derived data
      • CacheMissDummyFallback - user not in the cache; WikiTraccs used a minimal fallback
      • NotAttempted - placeholder anchors and tier-2 paths don’t hit the cache
    • MentionMatchedMappingCount - how many rows in the WikiTraccs User Mappings list matched the source user
      • 0 - no match (reported as MentionMappingMissing)
      • 1 - unique match (the rewrite uses this row)
      • >=2 - ambiguous match (reported as MentionMappingAmbiguous; no rewrite)
    • MentionTargetUpn - the mapped SharePoint user’s UPN (empty when no mapping was found; a comma-separated list for ambiguous matches)
    • MentionTargetDisplayName - the display name used for the anchor text (falls back to the UPN when the mapping has no title)
      • example: Henry U
    • MentionSourceDisplayName - the source Confluence user’s display name (audit breadcrumb; the wtmsn URL parameter)
      • example: Heinrich Ulbricht

    Lines with the keyword wt-checkpoint are checkpoints set by WikiTraccs so it knows where to continue, should a refinement run be interrupted and restarted. Checkpoint rows are padded with empty columns to keep the TSV rectangular so external tools (Excel, pandas, Import-Csv) can read the whole file as a uniform table.

    How does WikiTraccs Identify User Mentions?

    WikiTraccs looks for anchors that point to the SharePoint people search endpoint (/_layouts/15/sharepoint.aspx?v=/search/people). Those anchors are the shape WikiTraccs itself produces for user mentions during migration.

    During migration, WikiTraccs adds breadcrumbs to the anchor’s URL so it can later recognize which Confluence user the mention originally pointed to:

    • wtmri - the source Confluence user’s identifier (present for pages migrated with recent WikiTraccs versions)
    • wtmdn - the display name that ended up in the anchor text
    • wtmsn - the source Confluence display name (for auditing purposes)

    Having the wtmri, WikiTraccs reconstructs the source Confluence user and looks up the matching row in the WikiTraccs User Mappings list. That’s the same list you maintain for user-metadata mapping during migration. The mapping row’s WT_Setting_MapForDataAndMentions column provides the mapped SharePoint user.

    For pages migrated before the wtmri breadcrumb was added, WikiTraccs falls back to a tier-2 heuristic: it compares the anchor’s q parameter (usually the source user’s email) against the WT_In_EmailAddress column of the mapping list. If exactly one row matches, WikiTraccs promotes it to a tier-1-style mention for rewriting.

    When WikiTraccs finds a unique mapping row, it builds the “authoritative” mention URL from the mapped target user and compares it with the link in the page. If the authoritative URL and the link in the page differ, or the mapping couldn’t be resolved at all, then this will be added to the mention report file.

    Limitations

    The following limitations apply:

    • user mentions only (no group mentions)
    • mention fixing requires the source Confluence user to be present in the WikiTraccs User Mappings list; unmapped users are reported as MentionMappingMissing
    • mentions in text web parts are checked; mentions in other web parts are not handled
    • WikiTraccs only recognizes mention anchors that follow its own shape (those it produced during migration)