Upgrade to CMS 13
Why upgrade to CMS 13
Section titled “Why upgrade to CMS 13”CMS 13 is not a minor version bump — it aligns the PaaS platform with CMS SaaS capabilities while preserving the full-control development model that PaaS customers value. Key reasons to upgrade:
- Visual Builder — The drag-and-drop page composition experience, previously SaaS-only, is now available on PaaS
- Graph as primary delivery — Content delivery through GraphQL with a schema aligned to SaaS, enabling headless and multichannel architectures
- Modern frontend support — Updated JS SDK supporting React, Next.js, and other frameworks alongside traditional MVC/Razor
- Opal AI integration — AI content generation and optimization available in the PaaS editor
- Unified API surface — Management and REST APIs are now consistent between SaaS and CMS 13
Before you start
Section titled “Before you start”Assess your current implementation
Section titled “Assess your current implementation”Your upgrade effort depends on what you use today:
| Current dependency | Impact | Action required |
|---|---|---|
| Search and Navigation | 🔴 Breaking | Must migrate to Graph — Search and Navigation is not supported in CMS 13 |
| Graph (CMS 12 version) | 🟡 Schema change | Schema changed significantly — plan for Graph migration |
| Commerce 14 | 🔴 Not compatible | Must upgrade to Commerce 15 for CMS 13 compatibility |
| Custom Dojo widgets | 🟡 Deprecated | Dojo is no longer required — modern alternatives available |
| MVC controllers | 🟢 Supported | MVC remains fully supported with rendering helpers |
| Razor Pages | 🟢 Supported | Razor Pages work in CMS 13 |
| Razor Components | 🟡 Partial | Not yet fully supported — check release notes |
| Visitor Groups | 🟡 Changed | Still available for MVC rendering, but not indexed in Graph |
| Scheduled Jobs | 🟢 Unchanged | API unchanged, async support planned for future |
| Custom property types | 🟢 Supported | Continue working as before |
Critical breaking changes
Section titled “Critical breaking changes”These changes will break existing implementations if not addressed:
1. Search and Navigation → Graph migration (mandatory)
Search and Navigation is completely removed in CMS 13. Every search feature — site search, content filtering, type-ahead — must be rebuilt using Optimizely Graph.
If you are currently on CMS 12 and considering implementing Graph: wait for CMS 13. The Graph schema changed significantly between versions, and implementing on CMS 12 means migrating the schema again for CMS 13.
2. Graph schema changes
The CMS 13 Graph schema aligns with CMS SaaS. If you implemented Graph on CMS 12, your queries, schema extensions, and frontend integrations will need updates. The schema cannot be manually modified — CMS generates it automatically, with some extension points available.
3. Commerce compatibility
CMS 13 is not compatible with Commerce 14. You must upgrade to Commerce 15 at the same time or after the CMS upgrade.
Upgrade steps
Section titled “Upgrade steps”Step 1: Update NuGet packages
Section titled “Step 1: Update NuGet packages”Update to the latest CMS 13 packages from the Optimizely NuGet feed:
# Update all Optimizely packages to CMS 13
dotnet add package Optimizely.CMS.Core --version 13.*
dotnet add package Optimizely.CMS.UI --version 13.*
# If using Commerce, update to 15
dotnet add package Optimizely.Commerce --version 15.*
# Restore and build
dotnet restore
dotnet buildStep 2: Remove Search and Navigation dependencies
Section titled “Step 2: Remove Search and Navigation dependencies”If your project references EPiServer.Find or EPiServer.Search, remove them and replace with Graph:
# Remove old search packages
dotnet remove package EPiServer.Find
dotnet remove package EPiServer.Search
# Add Graph packages
dotnet add package Optimizely.ContentGraph.ClientStep 3: Migrate search functionality to Graph
Section titled “Step 3: Migrate search functionality to Graph”Replace Find queries with Graph GraphQL queries. See the Graph Query Language Reference for the full API.
Step 4: Update editor customizations
Section titled “Step 4: Update editor customizations”If you have custom Dojo widgets for editor UI, plan to migrate them. Dojo is no longer required — modern approaches are documented in the Custom Editors guide.
Step 5: Configure Opti ID (optional but recommended)
Section titled “Step 5: Configure Opti ID (optional but recommended)”Opti ID is required for DAM, OCP, and Opal features. It applies only to editor and business users — custom site authentication for your visitors is unaffected.
DAM is cloud-based and requires Opti ID. It can coexist with your existing media library — there is no automatic migration, and the old media library cannot be disabled yet.
Step 6: Test Visual Builder integration
Section titled “Step 6: Test Visual Builder integration”Visual Builder is now available on PaaS with the same content modeling rules as SaaS. Pages and Visual Builder experiences can coexist — you can adopt Visual Builder gradually without rewriting existing page types.
Step 7: Validate Visitor Group behavior
Section titled “Step 7: Validate Visitor Group behavior”Visitor Groups still work for MVC-rendered content, but they are not indexed in Graph. If you deliver personalized content through Graph to headless frontends, you will need alternative personalization approaches.
Step 8: Deploy and verify
Section titled “Step 8: Deploy and verify”Use the Deploy CMS PaaS guide for deployment steps. The Stride starter template (replacing Alloy) will be available at GA for reference implementations.
What stays the same
Section titled “What stays the same”Not everything changes. These areas work identically in CMS 13:
- Content types and properties — Same definition patterns, same attributes
- Initialization modules — Same API
- Content events — Same
IContentEventsinterface - Scheduled jobs — Same API (async support planned for future)
- MVC controllers — Fully supported with rendering helpers
- Custom property types — Continue working
- REST APIs — Consistent format and payload between SaaS and CMS 13
SaaS vs CMS 13: which to choose
Section titled “SaaS vs CMS 13: which to choose”| Factor | CMS 13 (PaaS) | CMS SaaS |
|---|---|---|
| Custom code in process | ✅ Yes — full control | ❌ No custom code in process |
| Infrastructure management | You manage | Optimizely manages |
| Automatic updates | Manual upgrades | Automatic |
| On-premises hosting | ✅ Supported | ❌ Cloud only |
| Opal AI | ✅ Via Opti ID | ✅ Built-in |
| Visual Builder | ✅ Available | ✅ Available |
| Graph delivery | ✅ Primary API | ✅ Built-in |
Choose CMS 13 PaaS if you need deep customization, on-premises hosting, or full control over the runtime. Choose SaaS if you prefer automatic updates and less infrastructure responsibility.
Timeline and support
Section titled “Timeline and support”- CMS 12 continues to receive security updates
- CMS 13 GA includes Stride starter template
- CMS 14 has no confirmed timeline
- CMS 12 certification remains relevant — CMS 13 is evolutionary
1. Your CMS 12 site uses Search and Navigation extensively for site search, content filtering, and type-ahead suggestions. You are planning a CMS 13 upgrade. What is the required approach for search?
Search and Navigation is completely removed in CMS 13. All search functionality must be rebuilt using Optimizely Graph. There is no compatibility layer or transition period.
Search and Navigation is completely removed in CMS 13. All search functionality must be rebuilt using Optimizely Graph. There is no compatibility layer or transition period.
Review this topic →2. A client running CMS 11 asks whether they should upgrade to CMS 12 first and then to CMS 13, or go directly to CMS 13. What do you recommend?
Direct upgrade from CMS 11 to CMS 13 is supported and recommended. The effort equals going through CMS 12, so skipping the intermediate version avoids upgrading twice.
Direct upgrade from CMS 11 to CMS 13 is supported and recommended. The effort equals going through CMS 12, so skipping the intermediate version avoids upgrading twice.
Review this topic →