Migrate from Optimizely Search & Navigation to Optimizely Graph with a Low-Risk Parallel Strategy

Migrate from Optimizely Search & Navigation to Optimizely Graph using a controlled, low-risk approach. This guide explains how to run both systems in parallel, validate functionality, switch production traffic, and safely decommission Search & Navigation after the migration completes.

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:

Install and configure Optimizely Graph.
Run Graph alongside Search & Navigation.
Validate search behavior and performance.
Switch production traffic when results meet expectations.
Keep Search & Navigation available as a fallback until Graph is fully verified.

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 initial synchronization: This synchronizes content, content types, relationships, and media metadata to Graph.
1. Go to CMS Admin > Scheduled Jobs.
2. Select Optimizely Graph Full Synchronization.
3. Select Start.
Verify the installation:
1. Open the Global Menu and select Optimizely Graph.
2. Run a test query, for example:
```
{
  Content {
    total
    items {
      Name
    }
  }
}
```

Maintain parallel operation

In this step, you should run Optimizely Search & Navigation and Optimizely Graph concurrently. Content synchronizes to both systems automatically. 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:

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 a sufficient period.
Performance remains stable.
User feedback is positive.
Your team is confident in the migration.