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

Return to the regular view of this page.

Page Refinement - Fix Web Part Drift

This article documents the ability of WikiTraccs to detect and rewrite web part properties on already migrated pages that have drifted from the current SharePoint page format.

    Note: Web Part Drift handling is available as of WikiTraccs v1.34.11

    Some migrated pages carry Image or Code Snippet web part properties that can collide with the current SharePoint page editor behavior — rarely visible, but able to cause a web part reset on first edit. This Page Refinement mode finds those pages and, in fix mode, rewrites the property in place.

    Why Web Part Drift Happens on Migrated Pages

    Migrated pages themselves are frozen - WikiTraccs writes them once and they sit untouched on SharePoint until somebody edits them.

    Microsoft’s SharePoint page format, on the other hand, keeps evolving. Over time, SharePoint refines how it interprets certain web part properties, and WikiTraccs itself refines how it sets them during migration. A page that was a perfect fit for the format at migration time may, later on, benefit from an adjustment to align with the current format.

    As long as nobody edits a page, the alignment doesn’t matter and the page just works. The difference becomes visible the moment a user opens the page in edit mode, where SharePoint re-evaluates the property values.

    Re-migrating just to close that gap is rarely an option. By the time a refinement like this becomes relevant, Confluence has often already been replaced by SharePoint and the source content isn’t available to re-migrate from. What’s needed is a way to change a single web part property in place, on the pages that need it, without re-running migration.

    That’s what this refinement mode does. WikiTraccs scans already migrated pages, identifies web parts whose properties match a known drift signature, and either logs them (so you can see what’s affected) or rewrites them (so the page behaves correctly going forward).

    What gets Corrected

    There is currently one drift correction:

    • Editor pop-ups on already-configured Image and Code Snippet web parts (report Kind: AddedFromPersistedData)

      This only matters when a user opens a migrated page in edit mode. Reading or viewing a migrated page is never affected - the page renders correctly to viewers, and the flag has no influence on what they see. The whole behavior described below happens inside the SharePoint page editor only; if nobody edits the affected pages, the refinement is not needed.

      Each Image and Code Snippet web part carries a flag whose role is to tell the page editor “show the setup helper when it’s needed” - the file picker for an image, the empty editor surface for a code snippet. On a migrated page the image has already been chosen and the code snippet has already been filled in, so the helper is not needed.

      In practice, the editor usually stays out of the way. But under certain conditions it decides to show the helper anyway, and that can come with a web part reset as a side effect - the chosen image is not displayed anymore, the code snippet content is empty. This has been observed under tight memory conditions and when pages are opened in a specific way (for example scrolling very fast, or jumping straight to the end of the page, while the editor loads). The exact mechanism isn’t fully pinned down, but it looks like a timing-sensitive interaction between a one-shot update script that Microsoft runs over the page on first edit and the editor’s own initialization logic.

      If a such a reset has happened on a page, two mitigations are available without needing this refinement at all: Ctrl+Z in the editor undoes the change (the image reappears on Image web parts), and the SharePoint page version history lets you roll the page back to the version before the edit. The refinement here is about preventing the trip in the first place.

      This refinement sets the flag to the value that says “this web part doesn’t need the first-run editor, I’m sure”. With the flag set this way, neither the Microsoft update script nor the editor has a reason to act on the web part, regardless of which side of the timing race lands first, and the existing image and code snippet content are left alone. Pages migrated with WikiTraccs v1.33.17 or newer already carry that value and don’t need the refinement.

    Two Modes: Log and Fix

    This refinement supports the same two modes as the link and mention refinements:

    • Log Web Part Drift - scan pages, detect drift, write a report; no page changes
    • Fix Web Part Drift - same scan, plus rewrite the affected property and save the page; “Fix” implies “Log”, so the report is always written

    Use the log mode first to get a feel for how many pages and web parts would be touched. Switch to fix mode when you are ready to apply the change.

    How to Enable Web Part Drift Refinement

    Here’s how to enable and start the check:

    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 either Log Web Part Drift (log only) or Fix Web Part Drift (log + rewrite)
      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

    WikiTraccs highlights the chosen mode in the GUI: Refine - Log WP Drift or Refine - Fix WP Drift (since “Fix” implies logging, the label omits “Log WP Drift”).

    Prerequisites

    You need migrated pages. If you did not migrate pages, yet, checking for web part drift doesn’t make sense.

    Which Migrated Pages Get Checked

    WikiTraccs checks SharePoint sites. Within each site, only the pages that WikiTraccs migrated from the currently configured source Confluence are checked - that is, pages whose source-tenant marker matches the Confluence base URL set in your WikiTraccs source configuration. Pages from a different source (migrated from another Confluence instance, or pages that WikiTraccs didn’t migrate at all) are skipped.

    Within that scope, the configured migration wave name and include/exclude filters gate refinement the same way they gate migration.

    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 Web Part Drift Report

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

    You can use the Open Log Folder button in the GUI to open the folder.

    The drift report file name looks like:

    • 2025-06-20-123335 localhost:8090___wt-webpart-property-drift-report-v1-[log].txt (log mode)
    • 2025-06-20-123335 localhost:8090___wt-webpart-property-drift-report-v1-[fix].txt (fix mode)

    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 drift report file per day and per mode will be created. If you start the check multiple times per day in the same mode, 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 drift report is its own file, separate from the link and mention reports. All three files can exist side by side when more than one refinement action is enabled.

    The file content looks like this (note: sample for two image web parts being adjusted on different pages):

    https://contoso.sharepoint.com/sites/WikiTraccsMigrationTool/SitePages/WIKITRACCS-Welcome-35848209.aspx	12	1.0	Image	abc123-...	AddedFromPersistedData	Set addedFromPersistedData=true on Image web part	data-sp-controldata.addedFromPersistedData	false	true	ResultSuccessReplacedSomething	2.0
https://contoso.sharepoint.com/sites/WikiTraccsMigrationTool/SitePages/WIKITRACCS-Topology-35848211.aspx	14	1.0	CodeSnippet	def456-...	AddedFromPersistedData	Set addedFromPersistedData=true on CodeSnippet web part	data-sp-controldata.addedFromPersistedData	false	true	ResultSuccessReplacedSomething	2.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 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 before the refinement run
      • example: 1.0
    • WebPartType - the human-readable web part type label
      • example: Image, CodeSnippet
    • WebPartId - the web part instance identifier on the page
      • example: abc123-...
    • Kind - the stable identifier of the drift analyzer that produced this row
      • example: AddedFromPersistedData
    • Description - a short human-readable description of the change
      • example: Set addedFromPersistedData=true on Image web part
    • Path - the property location inside the web part
      • example: data-sp-controldata.addedFromPersistedData
    • ValueBefore - the property value as found in the page
      • example: false
    • ValueAfter - the property value WikiTraccs would write (or did write, in fix mode)
      • example: true
    • State - the result classification (a comma-separated list of flags); empty for log-only rows that detected drift without attempting a write
      • example: ResultSuccessReplacedSomething - fix mode, the change was written
      • example: ResultErrorWebPartSkippedDueToUnexpectedChange - the web part changed in a way that no longer matches the drift signature; left as-is
      • example: ResultErrorSentinelMismatch - a pre-save consistency check detected that saving would have altered web part properties beyond the declared change; the save was skipped and the page left untouched
    • VersionAfterUpdate - the SharePoint page version after the refinement run wrote changes (empty for log-only runs)
      • example: 2.0

    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 WikiTraccs Identifies Web Part Drift

    For each web part on each migrated page, WikiTraccs runs a small set of drift analyzers. Each analyzer knows one specific property on one specific web part type, and decides whether the current value matches the drift signature it cares about.

    For the AddedFromPersistedData analyzer:

    • it only looks at Image and Code Snippet web parts
    • it reads the addedFromPersistedData flag from the web part’s data-sp-controldata
    • it acts only when the flag’s value is exactly false; web parts where the flag is already true, or where the value can’t be read, are skipped

    In fix mode, the page version increases when WikiTraccs saves the page.

    Limitations

    The following limitations apply:

    • only the web part properties listed under What gets Corrected are detected and rewritten
    • WikiTraccs only handles pages that follow its naming scheme (SPACEKEY-some-title-PAGEID.aspx) and that use the WikiTraccs content type (Site Page (transformed by WikiTraccs)); other pages on the site are skipped
    • in fix mode, each rewritten page gets a new page version