Overview of migrating from Search & Navigation
Migrate from Optimizely Search & Navigation to Optimizely Graph using a controlled, low-risk approach. Run both systems in parallel, validate functionality, switch production traffic, and decommission Search & Navigation after the migration completes.
Optimizely published a walkthrough of automating the Search & Navigation to Optimizely Graph migration using Claude Code. See Automated Search & Navigation to Graph Migration with Claude Code on Optimizely World.
Overview of the migration to Optimizely Graph
This guide assumes that Optimizely Search & Navigation is installed and running in a production environment.
Optimizely recommends using the following incremental migration strategy:
Advantages of using Optimizely Graph
Optimizely Graph provides a modern search and content delivery platform designed for headless and API-driven architectures, with the following key advantages:
- GraphQL-based API – Query only the data you need using a strongly typed schema.
- Headless and omnichannel support – Deliver content to web, mobile, and third-party applications from a single source.
- Semantic and structured search – Combine full-text search with structured filtering and relationships.
- Modern CMS integration – Integrate with Optimizely CMS 13 natively.
- Flexible front-end architectures – Support frameworks such as React, Vue, and other JavaScript-based solutions.
- Improved scalability – Support cloud-native workloads and high-volume query scenarios.
These capabilities make Optimizely Graph suitable for teams that require API-first development, headless CMS support, or advanced search scenarios.
🚧 Important Before starting the migration, review what Graph does not provide compared to Search & Navigation:
- Admin portal UI – Optimizely Graph does not provide a web-based administration interface.
- Statistics and analytics dashboard – Optimizely Graph does not include built-in analytics or reporting.
For more information, see Feature comparison.
Use the following guidance to decide whether to proceed:
- Continue if API-based administration and CMS integration meet your requirements.
- Reconsider if a web-based admin UI or built-in analytics are critical to your workflows.
- Plan alternative solutions, such as external analytics tools or custom implementations, before proceeding.
Install and configure Optimizely Graph
Install Optimizely Graph packages, configure settings, and sync content.
- Install required NuGet packages:
dotnet add package EPiServer.ContentDeliveryApi.Cms
dotnet add package Optimizely.ContentGraph.CMS📘 Note This configuration requires Optimizely CMS 12 running on .NET 6 or later.
- Add the following configuration to appsettings.json:
{
"Optimizely": {
"ContentGraph": {
"GatewayAddress": "https://cg.optimizely.com",
"AppKey": "your-app-key",
"Secret": "your-app-secret",
"SingleKey": "your-single-key",
"PreventFieldCollision": true
}
}
}- Update Startup.cs to register the required services:
public void ConfigureServices(IServiceCollection services)
{
services.AddContentDeliveryApi();
services.AddContentGraph();
}- Run the initial sync. This syncs content, content types, relationships, and media metadata to Graph.
- Go to CMS Admin > Scheduled Jobs.
- Select Optimizely Graph Full Synchronization.
- Select Start.
- Verify the installation:
- Open the Global Menu and select Optimizely Graph.
- Run a test query, for example:
{
Content {
total
items {
Name
}
}
}Maintain parallel operation
Run Optimizely Search & Navigation and Optimizely Graph concurrently. Content automatically syncs to both systems. Optimizely Search & Navigation continues to handle production traffic while you test Optimizely Graph in non-production scenarios.
Test migrated features
Review the feature migration guides for detailed instructions:
- Basic searchBasic search
- SynonymsSynonyms
- Best bets and pinned resultsBest bets and pinned results
- AutocompleteAutocomplete
Switch to Optimizely Graph
After you validate functionality and performance, route production traffic to Optimizely Graph.
🚧 Important Keep Optimizely Search & Navigation running during this phase. Maintain indexing jobs and infrastructure so you can roll back quickly if issues occur.
Monitor and remove Optimizely Search & Navigation
Optimizely Graph now handles production traffic while Optimizely Search & Navigation continues to run as a backup. Remove Optimizely Search & Navigation when:
- No incidents have occurred for an agreed-upon monitoring period.
- Performance remains stable.
- User feedback is positive.
- Your team is confident in the migration.