| name | webpart-mapping-reference |
| description | Supplementary reference for PnP selector functions, Community Script Editor, Quick Links layouts, and JavaScript alternatives. Read on-demand for deeper migration details. |
| model | sonnet |
Web Part Mapping Reference (Supplementary)
Companion reference for the migration pipeline skills. Contains the authoritative mapping tables, CIM schema specification, and zone-aware processing details used during extraction (Phase 1) and transformation (Phase 2).
For programmatic suggestions with confidence scores, always call get_webpart_mapping_hints first. The reference tables below supplement the tool for cases requiring AI judgment.
CIM Schema Specification
Top-Level Structure
{
"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:
| Field Type | Properties | Transform Action |
|---|
image | html, imageUrl, altText | build_text_webpart(html) without sourceUrl (cross-site) |
richHtml | html, plainText | build_text_webpart(html, sourceUrl) |
text | value | build_text_webpart(<p>{value}</p>) |
dateTime | value, isoDate | build_text_webpart(<p>{value}</p>) |
Web Part modernMapping
Each web part in content.webParts should include a modernMapping object with the recommended modern equivalent:
{
"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."
}
}
IMPORTANT — Property validation at transform time: The modernMapping.properties stored in the CIM are extraction-time hints and may be incomplete or contain non-schema properties. Before calling build_any_webpart, the transform phase MUST:
- Call
get_modern_webpart_catalog() to retrieve the actual property schema for the target web part type
- Include only properties that exist in the catalog schema — drop any non-schema properties
- Ensure all required properties from the schema are populated (use
resolve_list_info for list/view GUIDs on the destination site)
- Use the
dataVersion from the catalog example (typically "1.0") — do not guess or use arbitrary versions
Zone-Aware Processing
Classic wiki and publishing pages embed web parts inline within HTML content using <div class="ms-rte-wpbox"> markers. The extract_classic_page tool returns a wikiZones array that splits content around these markers.
Extract Phase (Phase 1)
When building the CIM for pages with embedded web parts:
- Consult
get_webpart_mapping_hints for each web part
- Populate
modernMapping on each web part in content.webParts
- In
transformationHints, add a note referencing the concrete strategy (not "render as placeholder")
Transform Phase (Phase 2)
When processing wikiZones during transformation:
- HTML zone (empty
webPartIds): build_text_webpart with zone.html and sourceUrl
- Web part zone (non-empty
webPartIds): find the matching web part in content.webParts by position index, then:
- If
resolvedHtml exists (e.g., CEWP with fetched content): use build_text_webpart with the resolved HTML, or classify the content and use a richer web part (Quick Links, Image, etc.)
- If
modernMapping exists: validate properties against the catalog schema before building (see Property validation at transform time above). Use the modernMapping.builderTool with modernMapping.webPartId and only schema-valid properties. For cross-site migrations where crossSiteNote warns about constraints, call resolve_list_info to resolve destination-site equivalents (list GUIDs, view GUIDs, URLs).
- Last resort only: if neither
resolvedHtml nor modernMapping is available AND the web part type is truly unknown, build a text web part noting the classic web part type and suggesting modern alternatives.
Never silently skip embedded web parts — the user should see what was there and what to do about it.
Classic-to-Modern Type Mapping
| Classic Web Part | Primary Modern Equivalent | Builder Tool | Fallback | Notes |
|---|
| ContentEditorWebPart | Varies by content | See CEWP Classification below | build_text_webpart | AI adds the most value here |
| ImageWebPart | Image | build_image_webpart | — | Direct 1:1 mapping |
| XsltListViewWebPart | List | build_any_webpart | build_text_webpart (link to list) | May need beta API |
| ListViewWebPart | List | build_any_webpart | build_text_webpart (link to list) | Same as XsltListView |
| PageViewerWebPart | DocumentEmbed or Embed | build_any_webpart / build_embed_webpart | — | DocumentEmbed for docs, Embed for URLs |
| ScriptEditorWebPart | Embed (no scripts) or Text (with scripts) | build_embed_webpart / build_text_webpart | — | Scripts cannot run in modern pages |
| SummaryLinkWebPart | Quick Links | build_quick_links_webpart | — | Natural mapping |
| ContentByQueryWebPart | Highlighted Content | build_any_webpart | build_text_webpart | Complex queries may need manual config |
| TitleBarWebPart | Text | build_text_webpart | — | Simple heading/caption |
| Unknown types | Text + Any | build_text_webpart / build_any_webpart | — | AI should analyze content directly |
CEWP Content Classification
ContentEditorWebPart (CEWP) is where AI adds the most value. These contain arbitrary HTML that existing migration tools just dump as-is. Classify by intent:
Navigation / Link Lists
Signals: <ul> or <ol> where most <li> contain <a> tags
Action: build_quick_links_webpart — extract link text and URLs
Layout hint: See Quick Links Layout Guide below
Embedded Content
Signals: <iframe>, <embed>, <object> tags
Action: build_embed_webpart with the src URL
Special: YouTube URLs auto-route to the YouTube web part
Image Galleries / Hero Images
Signals: Multiple <img> tags, or a single large image with overlay text
Action:
- Single image →
build_image_webpart
- Multiple images → consider
build_any_webpart with the Image Gallery web part type
- Image with text overlay → consider Hero web part via
build_any_webpart
Data Tables
Signals: <table> with <thead> and <tbody>, structured data rows
Action: build_text_webpart — modern text web parts render tables well
Styled Banners / Announcements
Signals: Large text, colored backgrounds, call-to-action buttons
Action: Consider Hero or Call to Action web parts via build_any_webpart, or build_text_webpart with the formatted HTML.
CTA buttons — prefer styled <a> tags inside a text web part. The Button and CallToAction web parts are unreliable (inconsistent rendering, lost styles, occasional silent drops on save). A styled anchor (<a href="..." style="display:inline-block;padding:8px 16px;background:#0078d4;color:#fff;border-radius:2px;text-decoration:none">…</a>) inside build_text_webpart is the most predictable way to reproduce a classic CTA.
JavaScript-Dependent Content
Signals: <script> tags, onclick handlers, jQuery references, SP.js calls
Action: build_text_webpart with an explanatory note. Cannot run scripts in modern pages.
Common alternatives: See JavaScript Alternatives table below
f
Quick Links Layout Guide
| Layout | Use When |
|---|
CompactCard | Compact navigation tiles |
List | Detailed lists with descriptions |
Button | Call-to-action buttons |
FilmStrip | Horizontal scrollable links with thumbnails |
Grid | Icon grid navigation |
Waffle | Dense icon grid |
Important caveat: layoutId is persisted to the page JSON but SPFx currently renders CompactCard regardless of the value. 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
| Classic Pattern | Modern Alternative |
|---|
| jQuery KPI dashboards | Power BI embed |
| SP REST API data fetchers | List web part or SPFx |
| Custom form handlers | Power Apps embed |
| Custom script web parts | SPFx web parts |
PnP Selector Functions
| Function | Used By | Returns |
|---|
ListSelectorListLibrary({ListId},{XmlDefinition/ListViewXml}) | XsltListViewWP, ListViewWP | List, Library, Calendar, Issue, TaskList, DiscussionBoard, Survey, Undefined |
ContentEmbedSelectorContentLink({ContentLink},{Content},{FileContents},{UseCommunityScriptEditor}) | ContentEditorWP | Link, NonASPXLinkNoScript, NonASPXLink, ContentNoScript, Content, NonASPXUseCSE, ContentUseCSE |
ScriptEditorSelector({UseCommunityScriptEditor}) | ScriptEditorWP, SimpleFormWP | UseCommunityScriptEditor, NoScriptEditor |
ContentEmbedSelectorSourceType({SourceType}) | PageViewerWP | WebPage, ServerFolderOrFile |
ContentByQuerySelector({ListGuid},{ListName}) | ContentByQueryWP | Default, NoTransformation |
SummaryLinkSelector({SummaryLinksToQuickLinks}) | SummaryLinkWP | UseText, UseQuickLinks |
UserExistsSelector({PersonEmail}) | ContactFieldControl | ValidUser, InvalidUser |
Community Script Editor (CSE)
ControlId: 3a328f0a-99c4-4b28-95ab-fe0847f657a3
| Web Part | CSE Branch | Content Source |
|---|
| ScriptEditorWebPart | UseCommunityScriptEditor | Inline {Script} |
| ContentEditorWebPart | NonASPXUseCommunityScriptEditor | Linked file {FileContentsEncoded} |
| ContentEditorWebPart | ContentUseCommunityScriptEditor | Inline {Script} |
| SimpleFormWebPart | UseCommunityScriptEditor | Form {Script} |
To enable: Deploy PnP react-script-editor to 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 mapping in PnP, the BaseWebPart default applies: ***Web part {Title} was not transformed***. This is distinct from empty mappings (silently dropped, e.g., TitleBar/GettingStarted), error text (specific error, e.g., XmlWebPart/DataForm), and unmapped (properties catalogued but no mapping node, falls to BaseWebPart, e.g., RSSAggregator).
Reference Files
| File | Contents | When to Read |
|---|
reference/pnp-transformations.md | Per-webpart PnP details: selectors, branch tables, properties, migration %, corrections | Need exact PnP branch logic, property names, or migration specifics |
Source data: PnP webpartmapping.xml v1.0.2111.0.
