Source: This post is a re-published and reformatted version of Accelerating Optimizely CMS and Commerce upgrades with agentic AI (Part 2 of 2) by Hung Le Hoang, published on Optimizely World on May 18, 2026. Hung Le Hoang is a certified Optimizely developer and member of Niteco Engineering. All credit for the original content goes to the author.
- Part 1: CMS 11 + Commerce 13 β CMS 12 + Commerce 14 β the Upgrade Machine and how a run works
- Part 2 (this post): CMS 12 + Commerce 14 β CMS 13 + Commerce 15, and the adoption work that creates actual business value
TL;DR
By 2026 standards, the technical upgrade from CMS 12 β 13 and Commerce 14 β 15 is a solvable engineering exercise. Breaking changes are catalogued, patterns are known, and the upgrade workflow has been encoded into Agent Skills that perform automated codebase analysis and large-scale modernization at speed.
The harder problem is not the upgrade β it is alignment. Getting to CMS 13 running is table stakes. Getting to CMS 13 delivering value means evolving the content model from PageData/BlockData to ExperienceData/Experience Pages, embracing Visual Builder, Optimizely Graph, Content Manager, the enhanced DAM, and Opal AI, and laying foundations that let workloads move between PaaS and SaaS without a frontend rewrite.
1. Two tracks, one destination
Most enterprises arrive at CMS 13 with two parallel streams: the CMS track (β CMS 13, .NET 10, Graph-first, Visual Builder, Content Manager, enhanced DAM, Opal) and the Commerce track (β Commerce 15, aligned to the same CMS 13/.NET 10 baseline, with renewed catalog and order APIs). Both converge on the same architectural philosophy: SaaS-grade authoring experience on PaaS, content through Graph, AI-assisted editorial layer, and a clean split between editor-owned layout and developer-owned components.
The failure mode is treating both as separate technical tasks. You end up on the latest platform versions with legacy CMS 12 design patterns still running underneath. Technology upgraded; business value unchanged. The ROI comes when both streams land on a shared future-state architecture.
2. The technical upgrade: what Agent Skills automate
A CMS 12 β 13 / Commerce 14 β 15 upgrade is a sequence of well-defined transformations. Agent Skills walk the entire solution, produce a pre-upgrade report, apply safe changes automatically, insert // TODO: [CMS13-MIGRATION] markers where human judgement is needed, drive dotnet restore / dotnet build to a clean state, and emit a structured migration report. What was historically a 4β6 week engineer-led effort collapses to hours of supervised automation.
In concrete terms, here is what each Skill covers:
Pre-upgrade analysis β inventory of every .csproj, package reference, deprecated API call, and add-on compatibility status. This phase catches NU1608 (add-on ships CMS 12 binaries) and SysRoot Availability.Specific before they become go-live surprises.
Dependency and project file upgrade β retarget to .NET 10, align all CMS packages to the 13.0.2 baseline, remove EPiServer.Find.*.
API migration β the most voluminous mechanical work, fully automated:
- PageReference siteRoot = ContentReference.StartPage;
+ ContentReference siteRoot = ContentReference.StartPage;
- var helper = ServiceLocator.Current.GetInstance<IPageRouteHelper>();
+ // Injected: private readonly IContentRouteHelper _routeHelper;
- [ScheduledPlugIn(DisplayName = "My Job", SortIndex = 100)]
+ [ScheduledJob(DisplayName = "My Job")]
public class MyJob : ScheduledJobBase { }
- [ContentProperty(DisplayName = "My Heading")]
+ [Display(Name = "My Heading")]
public virtual string Heading { get; set; }
Forms upgrade β EPiServer.Forms 5.10.x β 6.0.0. A version bump with breaking internal API changes that the Skill handles mechanically.
DI / startup alignment β registration order matters in CMS 13. The Skill enforces AddCms().AddContentGraph().AddContentManager() in the correct sequence and flags any startup extension that conflicts.
The honest framing for leadership: the technical upgrade is no longer the constraint. Speed, risk, and cost are now bounded by the things automation cannot do β content-model transformation, editorial change management, and the third-party long tail.
3. The fundamental shift: PageData β ExperienceData
The single biggest conceptual change in CMS 13 is not a breaking API β it is a redistribution of authority. In CMS 12, layout was implicitly owned by developers: every BlockData was a monolithic component, every ContentArea was free-form, and every display-option change required a developer ticket. In CMS 13, that model is inverted.
Editors add, reorder, and style Sections, Rows, and Columns in Visual Builder without opening a developer ticket. Developers define Elements, their fields, and their available Styles β and that boundary is enforced by the platform. Display options disappear as a developer concern. Blueprints replace duplicated page templates.
This is why content-model transformation is the hard part. Every block in an existing CMS 12 site encodes an implicit decision about who owns layout. Most of those decisions need to be consciously re-made, not just technically migrated.
4. The five capabilities that justify the migration
CMS 13 ships five interlocking capabilities. They are not optional add-ons β treat them as the target state the migration is building toward.
Visual Builder is the new default editing surface: live preview, Outline-driven composition, Section/Row/Column layout that editors control directly. It replaces On-Page Editing. If your program delivers CMS 13 without Visual Builder adoption, editors are using a more complex platform with no better experience than CMS 12.
Optimizely Graph is now part of the CMS bootstrap β AddContentGraph() is not optional. It is the primary content-delivery and indexing fabric, and it replaces EPiServer.Find entirely. Every other capability depends on it: Visual Builder needs it for preview, Content Manager needs it for search, Opal needs it for grounded suggestions.
Content Manager is Graph-powered editorial search. The experience shift is concrete: instead of navigating a page tree to find where a piece of content was used, editors run a semantic query. "Where did we say that our return window is 30 days?" β one query, one result, immediate edit.
Enhanced DAM replaces the old Welcome integration with an embedded asset management layer: AI-powered tagging, automatic renditions, direct upload from within the CMS editorial interface.
Opal AI is AI agent orchestration across all of the above β SEO assist, content drafting, alt-text generation, editorial QA, merchandising support β grounded against your own content through Graph and Content Manager.
These five are interdependent. Adopting Visual Builder without Graph means no live preview. Adopting Content Manager without Graph means no semantic search. Adopting Opal without Content Manager and DAM means ungrounded, hallucination-prone suggestions. The value compounds only when all five are in place.
5. The five-phase Visual Builder adoption framework
This framework has been pressure-tested on a live CMS 12 β 13 program. Each phase has a clear goal, measurable outputs, and a defined handover point to the next.
Phase 1 β Foundation and Pilot. Get Visual Builder live in production with one reference Experience Page. The objective is not coverage β it is locking the cross-cutting decisions that everything else depends on: hybrid policy (which page types stay as PageData, which migrate), cutover model (how URLs transfer ownership), redirect strategy, and the AvailableContentTypes configuration pattern. One well-built reference page is worth more than a dozen rushed ones.
Phase 2 β Discovery and Transformation. Produce the Decomposition Spec: a five-section document that becomes the single source of truth for Phases 3 and 4. Sections cover page-type strategy (PageData vs ExperienceData per type), block decomposition (how each CMS 12 block maps to Elements and Sections), display option mapping (old display options β Styles), personalization audit (which ContentArea personalizations move to which Elements), and Graph consumer inventory (every Find query that needs a Graph equivalent).
Phase 3 β Content modeling and Parity layer. Build the Visual Builder content model to production parity. This means the full Element library, complete SEO/OG/hreflang/canonical parity with the existing PageData layer, and AvailableContentTypes locked at every level of the hierarchy. Editors should not be able to assemble an invalid page.
Phase 4 β Content migration. Move production content from PageData + ContentArea into Experience Pages at business pace, not engineering pace. The AI Migration Accelerator runs per-batch: dry-run, spot-check, snapshot, run, validate, editorial sign-off, promote. Each batch is reversible until sign-off. The batch model keeps migration risk bounded β a bad batch affects that batch, not the entire site.
Phase 5 β Cutover and Decommission. Mark legacy types [Obsolete], finalize sitemap/hreflang/robots.txt, verify 301 coverage for every migrated URL, deliver editorial training, and remove the legacy content model from the codebase.
6. Find β Graph: the largest source of unscoped effort
EPiServer.Find is gone in CMS 13. There is no compatibility shim and no drop-in replacement β Graph is the strategic destination, and the migration is architectural, not mechanical. Done by hand, this is consistently the largest source of unscoped effort in any CMS 13 program.
The Find β Graph Agent Skills automate the mechanical 80β90%. The Skill inventories every Find usage β IClient, SearchClient.Instance, Find() DSL, For<T>() projections, custom conventions, indexing pipelines, boost profiles, synonyms. It maps indexed content models to Graph schemas, surfacing fields that need new indexers or computed properties. It translates query patterns to Graph equivalents β OR/AND filter trees, faceted aggregations, _Fulltext searches. It rewrites search controllers, autosuggest endpoints, and content listing components.
What it does not automate: custom relevance tuning, multi-index queries with no clean Graph equivalent, and anything where business logic is embedded in a boost profile. Those get a // TODO: [CMS13-MIGRATION] marker and land on the remaining decisions list for the delivery team.
7. Personalization and A/B testing: native, not bolted on
On CMS 12, personalization and A/B testing were bolted onto the platform β ContentArea-level swaps, external experimentation tools wired in, custom data layer plumbing. On CMS 13, they are native.
Personalization scope moves from ContentArea items (page-level, coarse) to Elements and Sections (component-level, visible in the Visual Builder Outline). A/B testing surfaces move from page-template swaps to Section-level variants, Element-level content swaps, and Style toggles. The data layer is Graph β queryable through one API rather than custom middleware. Web Experimentation runs natively against Experience Pages. Opal proposes audience segments, suggests variant content, and analyses experiment outcomes.
The migration plan should surface this as a primary business case β not a Phase 6 afterthought. Marketing teams ask about personalization and experimentation immediately after launch. If those capabilities are not ready at go-live, the value story for the upgrade is incomplete.
8. PaaS Foundation: design for the SaaS transition before you need it
The highest-leverage investment in any CMS 13 PaaS program is a Foundation that supports four delivery modes from a single codebase: headless hosting (Graph-driven delivery to an external frontend), in-process rendering (ASP.NET Core MVC + Razor, with _RootExperience.cshtml and Display Templates for every Element), SaaS compatibility (content models and queries valid on both PaaS and SaaS), and a shared frontend architecture (one component library, one design-token system, one Tailwind theme contract used by both Razor templates and the headless frontend).
The insight that makes this worth the investment: when PaaS runs in headless mode, content is delivered through Graph β exactly the same mechanism SaaS uses. The frontend cannot tell the difference. A future SaaS migration collapses from a replatform project to a DNS cutover and a content sync.
9. Third-party add-ons: the silent blockers
Most enterprise CMS 12 estates carry a long tail of community and vendor add-ons. CMS 13 breaks many of them, and some failures are silent until go-live.
The two to flag explicitly: NU1608 is not a warning β it is a release blocker. An add-on with an upper-bound dependency below 13.0.0 on any Optimizely.* package ships CMS 12 binaries that throw MissingMethodException at runtime. Hard-fail the build on NU1608; do not let it reach a deployment window. SysRoot at Availability.Specific blocks BlueprintInitialization on first boot β a one-time SQL fix that must be flagged before the deployment window, not discovered during it.
Other patterns to handle before go-live: EPiServer.Forms 5.10.x β 6.0.0 (breaking internal APIs, handled by Skill), EPiServer.Cms.WelcomeIntegration.UI β EPiServer.Cms.DamIntegration.UI (deprecated), EPiServer.Find.* β Graph (see Β§6), and packages with no CMS 13 build yet (SiteImprove, several Geta packages, Advanced.CMS.AdvancedReviews) β remove now, re-add when the CMS 13 build ships.
The upgrade Agent Skill scans for both NU1608 and SysRoot availability in Phase 1, turning go-live surprises into planning inputs.
10. What success looks like
A CMS 13 program executed against this framework lands with editors composing, previewing, and publishing in Visual Builder without developer tickets β personalization and A/B testing in the same surface as authoring. The Graph-driven content layer is the single source of truth for delivery, search, and federation. Opal's suggestions are grounded against the organization's own content. One component library and one design-token system serve both the in-process Razor renderer and the headless frontend. Upgrades are automated by Agent Skills with a hard-fail NU1608 gate in CI. Every migrated URL has a 301. The codebase is ready to move workloads to SaaS without a frontend rewrite β when and only when the business case is right.
Treat CMS 12 β 13 as two programs running in parallel: platform uplift and capability adoption. The first is now largely automatable. The second is where the value is. Conflating them is the root cause of most underwhelming CMS 13 launches. Separating them is the root cause of most successful ones.
Originally published by Hung Le Hoang on Optimizely World, May 18, 2026. Niteco Engineering.