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

Hello Sitecorian Community,

If you’ve worked on a Sitecore XM Cloud migration project, you’ve probably faced something like this:

“The architecture is signed off. The team starts building. Three weeks in, we discover 80% of the existing MVC components won’t work. The estimate needs to triple.”

This is not a rare situation. It happens regularly because most migration guides focus on what to do at a high level — not the specific things that will actually bite you mid-sprint.

In this post, I want to share the real challenges we’ve encountered on XM Cloud migration projects, and the API integration patterns that break in production even when they work fine in dev.

The Real Problem With XM Cloud Migrations

The first thing to be clear about:

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

Here is what changes at the architecture level:

Traditional Sitecore MVCXM Cloud (Headless)Controller renderings + Razor viewsJSS components in Next.js / ReactServer-side rendering and logicFrontend-driven renderingCD server for content deliveryExperience Edge CDN — no CD serverxDB-driven personalizationRule-based only, or Sitecore PersonalizeTight coupling with .NETAPI-first, decoupled architecture

Challenge 1: Every MVC Rendering Needs to Be Rebuilt

This is consistently the largest effort in any migration.

Controller renderings, Razor views, rendering parameters, server-side visibility logic — all of it needs to become a JSS component. There is no conversion path. You rebuild using the Headless SXA information architecture:

• Tenant → Site → Pages
• Page Designs and Partial Designs replace layouts
• All rendering logic moves to the frontend
• Custom placeholder logic needs to be redesigned — older nesting patterns don’t map cleanly

⚠️ If your existing solution is not SXA-based: adopting Headless SXA becomes an additional workload on top of the component rebuild. You need to re-map your entire solution into the SXA tenant/site/page structure. Budget for this separately.

Challenge 2: Personalization Cannot Be Migrated — It Needs to Be Redesigned

This is the one that surprises most teams.

XP personalization was powered by xDB analytics. XM Cloud does not have xDB. The personalization rules you built on XP will not work in XM Cloud. Do not try to port them — the engines are fundamentally different.

What we did instead:

• Audited every existing personalization rule
• Identified the business intent behind each rule
• Redesigned using XM Cloud built-in rules for simple cases (geo, auth, device type)
• Used Sitecore Personalize for anything requiring behavioral targeting or multi-source decisioning

This needs to be a separate scoping conversation with the client — not something discovered during sprint three.

Challenge 3: Bad Content Migrates Perfectly

The tooling (Sitecore CLI, Content Serialization) handles the mechanical migration well. What it cannot fix is content that was already messy.

Common issues we see after migration:

• Items losing workflow state or associations
• Media references breaking because folder casing changed
• Personalize dependencies still embedded in content items
• Old placeholder configurations causing component mapping errors
• Inconsistent templates creating template explosion in the new environment

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

Challenge 4: The C# Team and Next.js

Most established Sitecore teams are strong in C#. All XM Cloud documentation and official tooling assumes you are building with Next.js.

The ASP.NET Rendering SDK exists but you will be off the golden path — fewer examples, less community support, and real limitations when integrating with Sitecore Personalize.

What helped us: We ran a Next.js learning sprint before the project kicked off. Getting two or three developers comfortable with React, the JSS SDK, and the Next.js App Router before sprint one paid back immediately. Don’t skip this step.

About SitecoreAI Pathway

Sitecore announced SitecoreAI Pathway at Symposium 2025. Here is what we know from official sources:

• Handles content migration only — not code. The rendering rebuild is still a separate effort
• Up to 70% faster content migration timelines — around 100,000 pages migrated during beta
• Included in Sitecore 360 subscriptions at no extra cost
• Supports Sitecore XP migrations now, rolling out to Adobe/Optimizely/Contentful
• AI + human-in-the-loop — you validate and correct what the AI missed

If your client is on Sitecore 360, include a Pathway assessment in your discovery phase.

API Integration — The Patterns That Break in Production

Moving to API integration patterns on Sitecore projects. Here is a scenario we’ve encountered more than once:

“The integration with the CRM worked perfectly in dev and UAT. On go-live day, under real traffic, it starts timing out. Logs point to Experience Edge GraphQL being hammered.”

API failures on Sitecore projects are rarely about writing the wrong code. They are almost always about not fully understanding how Experience Edge works.

How Experience Edge Actually Delivers Content

Experience Edge is Sitecore’s globally distributed, CDN-backed GraphQL API. Your Next.js rendering host fetches content from Edge — not directly from the CM.

Two critical things that follow from this architecture:

• Custom Content Resolvers do not execute on Edge. They run at publish time only. If your resolver needs runtime context (visitor’s browser, query string, session data) — that is not supported on Edge. Redesign around it.
• Content not appearing on the live site? Check the publish-to-Edge pipeline first, not your Next.js code. A publishing job that fails silently during busy editorial periods is a common cause — set up infra-level alerting on Edge publish failures.

Caching Strategy — Don’t Treat All Data Sources the Same

The pattern that breaks most often: a page pulls from XM Cloud content, a product API, and CDP profile data — all with the same caching approach. Change frequency is completely different for each source:

Data SourceChange FrequencyCorrect StrategyXM Cloud contentHours to daysISR or full static generation (Next.js)Product / commerce dataMinutes to hoursServer-side with short revalidationCDP profile / audience dataPer sessionClient-side fetch after page load — cannot be edge-cached

The Webhook Write-Back Problem

A common integration pattern now with SitecoreAI: a webhook fires → Azure Function calls an AI service → result writes back to Sitecore via the Management API.

The silent failure we hit: the Management API respects workflow state. If the agent tries to write to an item in an approved or published workflow state, and the API token does not have override permissions — it fails silently. No error in logs. No exception thrown. Just nothing happens.

# Always test write-back against every workflow state:
# Draft state         → write allowed ✅
# Awaiting review     → depends on token permissions ⚠️
# Approved state      → fails silently without override ⚠️
# Published state     → fails silently without override ⚠️

✅ Fix: Add Management API write-back tests for every workflow state your implementation uses. Not just the happy path. This test will save you a go-live incident.

Use Sitecore Connect Before Writing Custom Code

Before writing any custom integration from scratch, check Sitecore Connect first. It ships with pre-built connectors for Salesforce, OpenAI, Gemini, and others. Connect integrations operate within SitecoreAI’s governance and audit model. A custom webhook pipeline does not. For enterprise clients with compliance requirements around data flows — this distinction matters.

Why This Helped Our Team

Before understanding these patterns:

• Go-live issues were hard to diagnose — wrong place to start debugging
• Multi-source pages had inconsistent behaviour under load
• Webhook write-backs silently failed in certain workflow states

After:

• Published pipeline alerts catch Edge failures before users report them
• Each data source has a caching strategy matched to its change frequency
• Integration test matrix covers all workflow states explicitly

Final Thoughts

XM Cloud migration and API integration both require understanding the underlying architecture deeply — not just following the official documentation. The documentation tells you what things are. Real project experience tells you where the edges are.

If you are planning an XM Cloud migration, run a full rendering inventory and content audit before committing to a timeline. Those two things will tell you more about the true scope than any architecture review.

Stay tuned for more Sitecore-related articles, tips, and tricks to enhance your Sitecore experience.

Till then, happy Sitecoring! 😊

Please leave your comments or share this article if it’s useful for you!