XM Cloud Migration and API Patterns — Real Challenges We Faced and How We Fixed Them

Hello Sitecorian Community,

If you’ve been involved in an XM Cloud migration, you’ve probably come across something like this:

“We are three weeks into the migration sprint. Architecture is signed off. Then we discover that most of the existing MVC components won’t work in headless SXA. The estimate needs to change significantly.”

This happens on projects regularly — not because teams are careless, but because most migration guides cover what to do at a high level without going into the specific things that cause problems mid-sprint.

⚠️ Deprecation Timeline — Act on These Now

Before we get into migration challenges, here are the live deadlines affecting every SitecoreAI project right now:

The Real Problem With XM Cloud Migrations

Migrating from Sitecore 10 MVC to XM Cloud is not an upgrade. It is a full re-platforming to a headless, SaaS-based architecture.

Challenge 1 — Every MVC Rendering Needs to Be Rebuilt

This is consistently the largest effort in any XM Cloud migration. There is no conversion path from MVC to Content SDK. Every rendering needs to become a component, and all layouts need to be rebuilt inside the Headless SXA information architecture:

• Tenant → Site → Pages
• Page Designs and Partial Designs replace the old layout system
• All rendering logic moves to the frontend (Content SDK 2.x)
• Custom placeholder nesting does not map cleanly — redesign component by component

⚠️ If your existing solution is not SXA-based: adopting Headless SXA is an additional workload on top of the component rebuild. Budget and scope it separately — it is the most commonly missed item in early estimates. Source: Sitecore Accelerate Cookbook.

Challenge 2 — Personalization Must Be Redesigned, Not Migrated

❌ What doesn’t work

• Porting XP rules to XM Cloud directly
• Expecting xDB segments to carry over
• Treating personalization as a later sprint

✅ What we do instead

• Audit every existing personalization rule
• Identify the business intent behind each rule
• XM Cloud built-in rules for geo, auth, device
• Sitecore Personalize for behavioral targeting

This conversation needs to happen in discovery — not once the migration sprint has started.

Challenge 3 — Bad Content Migrates Perfectly

The tooling handles the mechanical side. What it cannot fix is content that was already messy. Common issues we find after migration:

• Items losing workflow state or associations
• Media references breaking because folder casing changed
• Personalize dependencies embedded in content items that need decoupling first
• Old placeholder configurations no longer matching any component definition
• Inconsistent templates multiplying into template sprawl

✅ What helped us: Run a content audit before any migration script runs. Agree a content freeze window — no new content authored during the audit and initial pass. It sounds disruptive but saves weeks of cleanup.

Challenge 4 — The JSS → Content SDK Migration (Critical)

If you are starting any new XM Cloud or SitecoreAI project today, use Content SDK 2.x. If you have existing JSS implementations, the migration path is documented and there is now a direct JSS 22.0 → Content SDK 2.1 upgrade guide that eliminates the need to step through intermediate versions.

Content SDK 2.x — create a new project (official command)

# Option 1: Content SDK CLI (minimal scaffold)
# Source: doc.sitecore.com/sai/en/developers/content-sdk/20/create-a-content-sdk-app-locally.html
npx create-content-sdk-app@latest nextjs
# Option 2: Official XM Cloud starter repository (recommended for real projects)
git clone https://github.com/Sitecore/xmcloud-starter-js.git
# Use basic-nextjs for a clean start:
cd xmcloud-starter-js/examples/basic-nextjs
npm install
# Or use the skate-park example to see components out of the box:
cd xmcloud-starter-js/examples/kit-nextjs-skate-park
npm install

✅ Key benefit: Content SDK 2.0 delivers up to 49% lighter client-side bundles and an 89% smaller application footprint vs the JSS starter kit. Pages load faster and Core Web Vitals improve directly. Source: sitecore.com/solutions/topics/content-management/from-jss-to-content-sdk

About SitecoreAI Pathway

Pathway is Sitecore’s AI-assisted migration tool. Verified facts as of September 2026:

• Content and schema migration only — not code. Rendering rebuild is a separate effort
• Up to 70% reduction in migration effort — covers both time savings and steps Pathway can automate. Around 100,000 pages migrated in beta
• Included in Sitecore 360 subscriptions at no extra cost
• Pathway v1.3 (April 28, 2026): “Any website” migration available in beta — migrate public HTML sites (non-Sitecore sources) through the same flow as Sitecore XM. Scope, language, media, and discovery behaviour limited in this beta. Source: Sitecore Developer Portal changelog, April 28, 2026
• Pathway v1.4 (July 2, 2026): image migration added for “any website” sources, multi-language migration for XM/XP sources, automatic export structure creation, improved crawl reliability. Source: Sitecore Developer Portal changelog, July 2, 2026
• Named platform support (Adobe AEM, Optimizely, Contentful): announced as roadmap intent at Symposium 2025. As of v1.4, the “any website” capability covers public HTML sources — not deep platform-specific integrations. Watch the official Sitecore Developer Portal changelog for named platform support announcements.
• AI + human-in-the-loop — Pathway flags items needing review, keeps a full audit trail, lets you test with sample data before going live

⚠️ Known limitations (verified from official Pathway docs): No support for complex controls or data sources with child items. One site at a time — repeat per site and language. Target site structure and templates must exist in SitecoreAI before Pathway runs. Workflow states, personalization rules, analytics data, and custom modules are NOT migrated. Source: sitecore.com/resources/insights/artificial-intelligence/move-to-sitecoreai-with-pathway

API Integration — Patterns That Break in Production

“The integration worked perfectly in dev. It worked in UAT. On go-live day, under real traffic, it started timing out. Logs pointed to Experience Edge being hammered.”

API failures on Sitecore projects are rarely about writing the wrong code. They are almost always about misunderstanding how Experience Edge delivers content.

How Experience Edge Actually Works

Critical: Experience Edge serves a static snapshot of Layout Service output produced at publish time. Custom Content Resolvers do NOT execute at request time — they run at publish. If your resolver needs runtime context (visitor session, query string, live API data) — redesign it. That logic belongs in the frontend or a separate API call.

Content not appearing on the live site? Debug the publish-to-Edge pipeline first. Set up infra-level alerting on Edge publish failures — a silent failure during a busy editorial period is one of the most common causes of stale content on a live site.

Caching Strategy by Data Source

The Webhook Write-Back Silent Failure

Common pattern: webhook fires → Azure Function calls AI → result writes back via the Management API. Works in testing. Fails silently in production when the item is in an approved or published workflow state and the API token lacks override permissions.

Webhook write-back — test matrix (must cover all states)

# Validate write-back against EVERY workflow state
#
# Draft                → write allowed ✅
# Awaiting review      → depends on token permissions ⚠️
# Approved             → fails silently without override ⚠️
# Published            → fails silently without override ⚠️
# Fix: ensure your API token has WorkflowState override
# Test this in your integration test suite - not just happy-path Draft

Agent API — Migrate to v2.0 Now

If your implementation uses the Agent REST API directly, v1.0 personalization endpoints were deprecated on August 4, 2026. The brief generation endpoint was deprecated on September 20, 2026. Migrate to v2.0 endpoints. Source: Sitecore Developer Portal, May 18 2026 changelog.

Agent API — v1.0 → v2.0 migration

# DEPRECATED — remove before Aug 4 deadline
GET  /api/v1/personalization/by-page/{pageId}
POST /api/v1/personalization/{pageId}/versions
# USE INSTEAD
POST /api/v2/personalization/{pageId}/versions   # create variant
GET  /api/v2/personalization/{pageId}/versions   # list variants
# DEPRECATED - brief generation (removed Sep 20 2026)
POST /api/v1/briefs/generate
# USE INSTEAD - check Sitecore Developer Portal for new endpoint

Why This Helped Our Team

Before

• Debugging in the wrong place on go-live day
• Multi-source pages unreliable under load
• Webhook write-backs failing silently
• Building custom integrations Connect could handle

After

• Infra-level Edge publish alerts in place
• Each data source has a matching cache strategy
• All workflow states covered in integration tests
• Connect checked first before any custom code

Final Thoughts

Two things that tell you more about migration scope than any architecture review: run a full rendering inventory, and run a content quality audit before sprint one. If your team or client is still on JSS for SitecoreAI — that is now EOL. Content SDK 2.x is the only supported path. If anyone is still on Explorer — it is already gone. And Experience Editor has a hard deadline of January 1, 2027.

Stay tuned for more Sitecore-related articles, tips, and tricks to enhance your Sitecore experience.
Till then, happy Sitecoring! 😊