Webpart Mapping Reference

Web Part Mapping Reference (Supplementary)

Companion reference for the migration pipeline skills. It contains the authoritative mapping tables, CIM schema details, and zone-aware rules used during extraction (Phase 1) and transformation (Phase 2).

For programmatic suggestions with confidence scores, always call get_webpart_mapping_hints first. Use the tables below when AI judgment or exact property details are still needed.

CIM Schema Specification

{
  "schemaVersion": "1.0",
  "extractedAt": "<ISO 8601 timestamp>",
  "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 format

Each field in content.publishingFields has a type discriminator:

Web part modernMapping

Each entry in content.webParts should include a modernMapping object:

{
  "id": "...",
  "typeName": "Microsoft.SharePoint.WebPartPages.XsltListViewWebPart",
  "title": "Pages",
  "listId": "...",
  "listUrl": "/sites/pub1/Pages",
  "modernMapping": {
    "modernType": "List",
    "webPartId": "f92bf067-bc19-489e-a556-7fe95f508720",
    "builderTool": "build_any_webpart",
    "properties": { "selectedListId": "...", "listTitle": "Pages", "selectedListUrl": "..." },
    "crossSiteNote": "For cross-site migration, resolve the destination site's equivalent library and update properties accordingly."
  }
}

Property validation at transform time is mandatory:

1. call get_modern_webpart_catalog() to get the real property schema
2. keep only schema-valid properties
3. populate every required property, using resolve_list_info for destination-site list/view GUIDs as needed
4. use the catalog dataVersion example (typically "1.0") instead of guessing

Zone-Aware Processing

Classic wiki and publishing pages can embed web parts inline with <div class="ms-rte-wpbox"> markers. extract_classic_page splits these into wikiZones.

Extract phase (Phase 1)

When building the CIM:

1. consult get_webpart_mapping_hints for each web part
2. populate modernMapping on content.webParts
3. add a transformationHints.note that names the concrete strategy, not “render as placeholder”

Transform phase (Phase 2)

When processing wikiZones:

• HTML zone (webPartIds empty): build_text_webpart(zone.html, sourceUrl)
• Web-part zone (webPartIds non-empty): match by position index, then:
  1. if resolvedHtml exists, use build_text_webpart or classify it into a richer web part such as Quick Links or Image
  2. if modernMapping exists, validate it against the catalog schema, then use modernMapping.builderTool with modernMapping.webPartId and only schema-valid properties; for cross-site list web parts, call resolve_list_info to resolve destination-site equivalents
  3. only if neither exists and the type is truly unknown, create a yellow-highlighted text fallback naming the classic type and the recommended modern alternative

Never silently skip embedded web parts.

For every explanatory fallback, wrap the entire notice in <span class="ms-rtebackcolor-3">...</span>. build_text_webpart converts this to SharePoint's native yellow highlightColorYellow. Do not highlight ordinary migrated content.

Classic-to-Modern Type Mapping

CEWP Content Classification

CTA buttons: Prefer styled <a> tags inside a text web part. The Button and CallToAction web parts are unreliable (inconsistent rendering, style loss, occasional silent drops on save), so a styled anchor inside build_text_webpart is the most predictable reproduction.

Quick Links Layout Guide

Important caveat: layoutId is persisted to the page JSON, but SPFx currently renders CompactCard regardless. Plan the visual design around CompactCard. If you need a true Button / FilmStrip / Grid look, fall back to a text web part with hand-built HTML.

JavaScript Alternatives

PnP Selector Functions

Community Script Editor (CSE)

ControlId: 3a328f0a-99c4-4b28-95ab-fe0847f657a3

To enable: Deploy PnP react-script-editor to the tenant app catalog, then set pti.MappingProperties["UseCommunityScriptEditor"] = "true". Without this, all script-dependent web parts are dropped.

BaseWebPart Fallback

If a web part type has no specific PnP mapping, the BaseWebPart default is ***Web part {Title} was not transformed***. This is distinct from:

• empty mappings — silently dropped (for example, TitleBar / GettingStarted)
• error text — specific error text (for example, XmlWebPart / DataForm)
• unmapped — properties catalogued but no mapping node, so the web part falls to BaseWebPart (for example, RSSAggregator)

Reference Files

Source data: PnP webpartmapping.xml v1.0.2111.0.