Extract And Understand

Phase 1: Extract & Understand

Extract a classic SharePoint page (wiki, web part page, or publishing page), classify each content block by intent, build a CIM (Canonical Intermediate Model), and save it.

After building and saving the CIM, immediately invoke the transform-and-create skill to proceed — unless invoked from migrate-site (which extracts all pages first, then migrates in Phase 2).

Core Rules

• Understand intent, not just tags. Classify by what the content is trying to do.
• Try your best. A creative approximation beats a bland fallback; use build_any_webpart as the escape hatch.
• Be honest about limits. JavaScript-dependent content cannot run in modern pages. Preserve it as text with alternatives.
• Never silently drop content.
• Be autonomous. Ask only when you cannot proceed:
  • the destination site URL is unknown for a publishing site migration where the Site Pages feature is not activated
  • the content is genuinely ambiguous in a way that would materially change the result
• Do not ask about layout choices, web part type, skipping empty web parts, or page naming.

Workflow

Step 0: Extract & Build CIM

1. Call extract_classic_page(siteUrl, pageName) once. The MCP tool retries a failed extraction two times (three total attempts) before returning an error.
2. Build a CIM from the extracted bundle that captures:
   • page title, type (wiki / webpart / publishing), author, and layout
   • content zones or wiki zones with their HTML
   • web parts found (type, title, resolved content) and whether any content contains scripts
   • for publishing pages: field controls from the layout ASPX, web part zones and column widths, and publishing field values such as images, byline, and dates
   • if publishingLayoutHtml is present, analyze it as hardcoded page-layout ASPX content shared by every page using that layout; identify headings, navigation tiles, link grids, images, CTAs, and similar template-level blocks
   • the proposed migration plan for each content block / field / zone (text web part, image web part, Quick Links, and so on)
   • cross-tenant asset detection: when the destination site is on a different tenant, call discover_page_assets(siteUrl, pageName, destSiteUrl) and include the crossTenantAssets count and list in the CIM. Server-relative URLs (for example, /sites/pub1/images/photo.jpg) resolve only within the same tenant.
3. Classify each content block by intent using CEWP Content Classification:
   • consult the Web Part Mapping Reference table below for the modern equivalent
   • inspect the actual HTML content to understand what the user is trying to accomplish
   • consider the page as a whole (dashboard, wiki article, landing page, and so on)
4. Present a brief CIM summary to the user (page type, section count, key decisions) as informational output, but do not wait for confirmation; proceed immediately to saving and handoff.

Step 1: Save CIM to File

1. Save to <git_repo_path>\pageunderstanding\<sitename>\<pagename>.json
   • <sitename>: derive from the site URL path and replace / with - (for example, /sites/pub1 → sites-pub1)
   • <pagename>: page name without .aspx
2. Create pageunderstanding/<sitename>/ if needed.
3. Always overwrite existing files without reading or merging them.

CIM Schema

{
  "schemaVersion": "1.0",
  "extractedAt": "<ISO 8601>",
  "source": { "siteUrl": "", "pageUrl": "", "pageName": "", "pageType": "wiki|webpart|publishing", "title": "" },
  "metadata": { "author": {}, "created": "", "modified": "", "modifiedBy": "", "contentTypeId": "", "uniqueId": "" },
  "publishingLayout": { ... },
  "content": {
    "title": "",
    "publishingFields": { ... },
    "webParts": [ ... ],
    "wikiZones": [ ... ]
  },
  "transformationHints": { ... }
}

Publishing fields in content.publishingFields use type discriminators:

Web part modernMapping: For each web part in content.webParts, consult get_webpart_mapping_hints and add a modernMapping with the correct schema properties. See the webpart-mapping-reference skill for the authoritative List web part property schema and examples.

Zone-aware hints: When PublishingPageContent or WikiField contains embedded web parts, the transformationHints note must reference the concrete modernMapping strategy, not “render as placeholder”.

HTML table layout detection: When PublishingPageContent uses an outer <table> (typically class="ms-rteTable-*" or width="100%") for multi-column layout, the CIM transformationHints must capture that structure:

{
  "transformationHints": {
    "layoutStrategy": "html-table",
    "tableLayout": {
      "columnRatio": "oneThirdLeftColumn",
      "rows": [
        { "leftContent": "hero image", "rightContent": "Getting Started through section X" },
        { "leftContent": "empty", "rightContent": "Section Y through Z" }
      ]
    }
  }
}

This ensures transform-and-create builds multi-column modern sections instead of flattening everything into oneColumn. Inspect the top-level table's <td> widths or proportions to determine the column ratio.

Image dimensions: For every image in contentBlocks or publishingFields, capture imgWidth and imgHeight from the extracted data. The classic extraction already provides naturalWidth/naturalHeight or explicit width/height attributes, and the Image web part needs these values to avoid collapsing to 0×0.

Web Part Mapping Reference

Sorted by usage. Tier: 1 = Direct, 2 = Conditional, 3 = Complex, 4 = No OOB (SPFx needed), 5 = Deprecated/Dropped.

CEWP Content Classification

ContentEditorWebPart (CEWP) contains arbitrary HTML. Classify by intent:

Scripts cannot run in modern pages.

Content Pattern → Tool Quick Reference

Troubleshooting & Tools

• extract_classic_page retries a failed extraction two times before it returns an error. Do not invoke it again manually; after all three attempts fail, verify the site URL and page name.
• Publishing sites can host modern pages only when the Site Pages feature is activated (a Site Pages library exists). If activated, migrate in the same site; otherwise the user must specify a separate destination site.
• Permission errors mean the app needs at least Sites.Read.All.
• extract_page_data (used in compare-and-refine) only works on modern pages. It returns No content container found on classic wiki/publishing pages. Always use extract_classic_page for source extraction.