Upgrading from Optimizely CMS 12 to CMS 13 takes more than an updated NuGet package. Here's what to check before you start.
Optimizely CMS 13 is out, which means if you're still running a site on CMS 12 site, you're going to get the question: "Should we upgrade?"
Short answer: Yes. You should upgrade.
The longer answer, though, depends on how much you know before you start.
CMS 13 isn't just a version bump. It makes Opti ID a required feature, replaces Search & Navigation with ContentGraph, and brings Visual Builder to PaaS for the first time. It's also the foundation Opal needs to deliver on its full promise — if you want to really dive in on Opal's AI workflow features, you're going to need to be on CMS 13.
So while each of those pieces is manageable on their own, managing all of these changes at once means your team has some decisions to make before touching a single package. So let's get into some of those decisions.
Before You Start
Before touching a single NuGet package, a little due diligence goes a long way.
- Check your add-ons and third-party packages first. Most popular ones are either already upgraded for CMS 13 or in progress, but if you're depending on something that isn't, you'll want to know that before you're halfway through an upgrade.
- CMS 13 targets .NET 10. Most sites hosted on DXP will handle this seamlessly, but any self-hosted setups should verify they can run .NET 10 and make updates as necessary.
- Do a quick audit of any APIs marked deprecated in CMS 12. CMS 13 cleans a number of these up, and having a plan for migration can ease the upgrade process.
- While you're auditing, it's worth taking a pass at general code hygiene — content types, scheduled jobs, services, and other artifacts that have quietly outlived their usefulness. Sites that have been around for a while have a tendency to accumulate this kind of legacy weight, and the upgrade is a natural opportunity to shed it rather than carry it forward.
Are you ready for Opti ID?
CMS 13 requires Opti ID, Optimizely's single sign-on solution that provides uniform access across all Optimizely tools. It's a good idea to prepare for this ahead of time.
- If you're currently using Optimizely's default, database-backed authentication, you'll need to migrate your users over to Opti ID.
- If you're already using another SSO provider, you'll need to integrate it with Opti ID. The good news is that Opti ID supports bringing your own Identity Provider. You still manage your users there, and Opti ID connects everything together.
Are you ready for ContentGraph?
CMS 13 requires ContentGraph and drops support for Search & Navigation. This is a required upgrade, but it's worth approaching as an opportunity rather than just a migration task — ContentGraph brings a more robust search model, semantic search, and a content-delivery layer that Search & Navigation never offered.
That said, the feature sets don't match one-to-one, so it's worth taking a careful look at the differences before you start rewriting queries. On the querying side, you have two paths forward:
- Rewrite your queries from Search & Navigation syntax to GraphQL queries directly.
- Use Optimizely's ContentGraph Client SDK, which provides a Search-and-Nav-like interface to ContentGraph.
The SDK is the lowest-friction path, but it may not support the full breadth of querying features ContentGraph offers. For queries that need to traverse the graph, bespoke GraphQL queries are often more efficient. Ultimately, it's an exercise in trade-offs — find the right fit for what your site actually does.
Are you ready for Visual Builder?
CMS 13 finally brings Visual Builder to PaaS. It's a highly interactive editorial interface that lets editors design and lay out content quickly, with far fewer restrictions than traditional content areas. Taking full advantage of it requires some groundwork:
- A flexible design system capable of handling the more free-form content entry Visual Builder allows.
Potential reworking of existing blocks and content areas to support the new content models and rendering approach. - A migration path for any existing content you want to move into a Visual Builder experience.
That said, the old content area and block system still works and remains available. You don't have to use Visual Builder at all, but you'd be leaving a powerful new feature on the table. A reasonable approach is to upgrade first without Visual Builder, then add new experiences and gradually migrate old ones over time.
Are you ready for Opal?
One of the headline benefits of CMS 13 is out-of-the-box Opal integration, which brings a suite of tools for creating, managing, and optimizing content — for both human users and AI-driven experiences. The technical lift here is minimal, but don't underestimate the organizational side. You may need some training and updated governance policies and editorial workflows to use it effectively.
Opal is only as useful as the workflows and governance around it. Without those in place, it's a capable tool that nobody quite knows how to use consistently. Before you get too far into the upgrade, it's worth asking: do your editors know what Opal can do? Do you have policies around AI-assisted content? Does your approval process account for it?
None of that has to be solved before you upgrade — but teams that treat Opal as a "we'll figure it out after launch" item tend to underuse it, so a little preparation goes a long way.
How much effort are you looking at?
That depends on where you're starting from. In rough terms:
- High effort — If you're on standard database-backed authentication and still using Search & Navigation, you're doing the full migration: Opti ID, ContentGraph, and everything that comes with both.
- Medium-high effort — If you've already moved to Opti ID but haven't adopted ContentGraph yet, you're through the hardest part of the identity work. The Search & Navigation migration is still ahead of you.
- Low effort — If you have both Opti ID and ContentGraph in place, the core upgrade path is significantly shorter.
