Blogs

Forcing Lowercase URLs in Optimizely CMS During Auto-Translation

Thu, 02 Apr 2026 15:15:00 GMT

Learn how to fix uppercase and punctuation issues in Optimizely CMS 12 URL segments caused by LanguageManager auto-translation using a custom IUrlSegmentGenerator and event-based tracking.

Stott Robots Handler v7 for Optimizely CMS 13

Thu, 02 Apr 2026 09:44:40 GMT

Stott Robots Handler version 7 is now available for Optimizely PaaS CMS 13. This is includes updates to support the switch from a Site based architecture to an Application based architecture.

How does the change from Sites to Applications impact the user?

The data structure of Applications is subtly different to that of Sites. In CMS 12, sites were uniquely identified using a GUID. In CMS 13, Applications are uniquely identified using a string identifier. This breaks the relationship between existing robots.txt and llms.txt content and the sites they were configured to serve.

Users will have to reconfigure their robots.txt and llms.txt content when moving from CMS 12 to CMS 13. The content for both files is stored in the Dynamic Data Store and is matched to an active application before being displayed to the CMS Administrator or being served to end users.

The Environment Robots and the API Tokens are global configurations and are not bound to a specific site or application. When upgrading to version 7 and CMS 13, these features will retain their existing configuration.

What features does Stott Robots Handler have?

🤖 Manage robots.txt content by Application and specific Host URL
📄 Manage llms.txt content by Application and specific Host URL
🔒 Override robots meta tags and response headers at an environment level to prevent indexing lower environments in search engines.
🌐 APIs to support headless solutions
🌐 APIs to support modification of robots.txt and llms.txt content directly within Optimizely Opal

What does this mean for Optimizely CMS 12?

Support for version 6 of the Stott Robots Handler is not going away. New functionality will be developed directly for version 7 and then backported to version 6 where appropriate. I can review the recent download stats on a version by version basis on nuget and I will use this as an indicator of the current market need.

I expect that it will take a few years for a significant portion of customers to move from CMS 12 to CMS 13. Therefore, I expect to maintain the CMS 12 version for the short to mid term.

Getting Started

Stott Robots Handler v7 is available for Optimizely PaaS CMS 13 on nuget.org and on api.nuget.optimizely.com. You can see the full installation instructions and package information over on the github page, including how to configure the add-on for use with Opti Id.

Getting started can be as simple as:

// Install the nuget package
dotnet add package Stott.Optimizely.RobotsHandler

// Add this to your services
services.AddRobotsHandler();

// Add this to your configure method
services.UseRobotsHandler();

// Add this to your _ViewImports.cshtml if you are running traditional
@addTagHelper *, Stott.Optimizely.RobotsHandler

I am an OMVP and the author and maintainer of Stott Security and Stott Robots Handler for Optimizely CMS 12. You can find all of my content collated on https://www.stott.pro/

Automating Block Translations in Optimizely

Wed, 01 Apr 2026 16:00:00 GMT

Stop manual block-by-block translations. Learn how to use the TranslateOrCopyContentAreaChildrenBlockForTypes config to automate Optimizely CMS content workflows.

How to Disable automatic indexing in Optimizely Search & Navigation

Wed, 01 Apr 2026 07:11:38 GMT

Learn how automatic event-based indexing works in Optimizely Search & Navigation and how you can temporarily disable it.

Fixing “Published By” After OKTA SSO in Optimizely CMS

Wed, 01 Apr 2026 04:54:06 GMT

Enabling Okta SSO significantly strengthened our authentication and security model in Optimizely CMS. However, like many real-world implementations, it also introduced an unexpected challenge in the CMS authoring experience, as the system now stores the Okta ID as the username.

Problem:

After switching to SSO, we observed a change in how user identities were stored:

The “Published By” field displayed Okta ID
Instead of names or emails, editors saw technical IDs

Impact on Editorial Exp.

This created friction for content teams:

Author attribution became unclear
Content review was harder to follow
Auditing lost its human-readable context

For non-technical users, this was a noticeable drop in usability.

Solution:

To address this, we introduced a custom transformation:

👉 PublishedByTransform

This transform maps the stored Okta identifier to a friendly display value, such as:

Author name
Email address
Or any readable identity field

Instead of exposing raw Okta IDs, the CMS now resolves and displays meaningful user information.

 [ServiceConfiguration(typeof(IModelTransform), Lifecycle = ServiceInstanceScope.Singleton)]
 public class PublishedByTransform : ContentDataStoreModelTransform
 {
     private readonly EPiServer.Logging.ILogger _logger;
     private readonly IUserService _userService;
     private readonly IPrincipalAccessor _principalAccessor;
     private readonly IContentVersionRepository _contentVersionRepository;

     public PublishedByTransform(
         IUserService userService,
         IPrincipalAccessor principalAccessor,
         IContentVersionRepository contentVersionRepository)
     {
         _userService = userService ?? throw new ArgumentNullException(nameof(userService));
         _principalAccessor = principalAccessor ?? throw new ArgumentNullException(nameof(principalAccessor));
         _contentVersionRepository = contentVersionRepository ?? throw new ArgumentNullException(nameof(contentVersionRepository));
         _logger = LogManager.GetLogger(typeof(PublishedByTransform));
     }

     public override void TransformInstance(IContent source, ContentDataStoreModel target, IModelTransformContext context)
     {
         base.TransformInstance(source, target, context);
         ContentVersion contentVersion1 = this._contentVersionRepository.Load(source.ContentLink);
         ContentVersion contentVersion2 = _contentVersionRepository.LoadPublished(source.ContentLink, source.LanguageBranch());

         if (contentVersion1 != null)
         {
             var versionCreatedBy = string.IsNullOrEmpty(contentVersion1.StatusChangedBy) ? contentVersion1.SavedBy : contentVersion1.StatusChangedBy;
             target.VersionCreatedBy = ResolvePublishedBy(versionCreatedBy);
         }

         if (contentVersion2 != null)
         {
             var publishedBy = !string.IsNullOrWhiteSpace(contentVersion2.StatusChangedBy)
                 ? contentVersion2.StatusChangedBy
                 : contentVersion2.SavedBy;

             target.PublishedBy = ResolvePublishedBy(publishedBy);
         }
     }

     private string? ResolvePublishedBy(string? publishedBy)
     {
         if (string.IsNullOrWhiteSpace(publishedBy))
             return publishedBy;

         try
         {
             var user = _userService.GetUserByName(publishedBy);
             if (user == null)
                 return publishedBy;

             var claimsPrincipal = _principalAccessor.Principal as ClaimsPrincipal;
             var currentUserEmail = claimsPrincipal?.FindFirst("email")?.Value ?? claimsPrincipal?.FindFirst(ClaimTypes.Email)?.Value;
             if (!string.IsNullOrWhiteSpace(currentUserEmail)
                 && !string.IsNullOrWhiteSpace(user.Email)
                 && string.Equals(currentUserEmail, user.Email, StringComparison.OrdinalIgnoreCase))
             {
                 return "you";
             }

             return !string.IsNullOrWhiteSpace(user.Email) ? user.Email : user.UserName;
         }
         catch (Exception ex)
         {
             _logger.Error($"PublishedByTransform failed to resolve PublishedBy for value '{publishedBy}'. Error: {ex}");
             return publishedBy;
         }
     }
 }

Result:

With this small but impactful enhancement, we achieved the best of both worlds:

Secure SSO via Okta remains fully in place
“Published By” now shows clear, readable author names

Thank you for reading the blog. Cheers!

OptiPowerTools.Hangfire: A Drop-in Hangfire Integration for Optimizely CMS 12

Tue, 31 Mar 2026 08:00:00 GMT

Back in 2024, I wrote a post on Adding Hangfire to Episerver/Optimizely CMS 12, walking through each step of integrating Hangfire into an Optimizely project — the authorization filter, the controller, the view with an iframe, the menu provider, the startup wiring. It was a fair amount of boilerplate, but it worked and people found it useful.

Upgrade Guide: Commerce 14 to Commerce 15 preview

Tue, 31 Mar 2026 03:59:41 GMT

This document provides step-by-step instructions to upgrade a Commerce site from Commerce 14/CMS 12 to Commerce 15/CMS 13 preview.

Overview

This upgrade includes:

Commerce: 14.15.3 → 15.0.0-preview1

CMS: 12.31.2 → 13.0.0-preview4

.NET: 8.0 → 10.0

Prerequisites

Visual Studio 2022 with .NET 10.0 SDK

SQL Server (LocalDB or full instance)

Basic understanding of Optimizely Commerce and CMS

Step 1: Create a new Commerce 14 empty site from template

To create a baseline Commerce 14 site from template:

Run the template command:

dotnet new epi-commerce-empty --name CoCo14 --force

Open the project, restore packages, and build it

Press F5 and create a user by accessing: https://localhost:5000/util/register

Migrate Commerce data: https://localhost:5000/episerver/commerce/migrate

Verify the CMS/Commerce Admin UI: https://localhost:5000/episerver/cms

Verification: Ensure the site is running without errors before proceeding.

Step 2: Update Project Configuration

File Modified: [CoCo14.csproj]

Target Framework

<TargetFramework>net10.0</TargetFramework>  <!-- was net8.0 -->

Package References

Before (Simple metapackage approach):

<PackageReference Include="EPiServer.CMS" Version="12.31.2" /> 
<PackageReference Include="EPiServer.Commerce" Version="14.15.3" />

After (Explicit package references):

Commerce packages:

<PackageReference Include="EPiServer.Commerce" Version="15.0.0-preview1" />

CMS packages (all version 13.0.0-preview4):

<PackageReference Include="EPiServer.OptimizelyIdentity" Version="13.0.0-preview4" /> 
<PackageReference Include="EPiServer.CMS.UI.AspNetIdentity" Version="13.0.0-preview4" /> 
<PackageReference Include="Optimizely.Graph.Cms" Version="13.0.0-preview4" /> 
<PackageReference Include="EPiServer.Cms.UI.ContentManager" Version="13.0.0-preview4" /> 
<PackageReference Include="EPiServer.Hosting" Version="13.0.0-preview4" /> 
<PackageReference Include="EPiServer.Cms.UI.VisitorGroups" Version="13.0.0-preview4" /> 
<PackageReference Include="EPiServer.CMS.Shell.UI" Version="13.0.0-preview4" /> 
<PackageReference Include="EPiServer.CMS.UI" Version="13.0.0-preview4" /> 
<PackageReference Include="EPiServer.ImageLibrary.ImageSharp" Version="13.0.0-preview4" /> 
<PackageReference Include="EPiServer.Events.ChangeNotification" Version="13.0.0-preview4" /> 
<PackageReference Include="EPiServer.Cms.AspNetCore.TagHelpers" Version="13.0.0-preview4" /> 
<PackageReference Include="EPiServer.Cms.AspNetCore.HtmlHelpers" Version="13.0.0-preview4" /> 
<PackageReference Include="EPiServer.Cms.TinyMce" Version="13.0.0-preview4" />

Step 3: Update Startup Configuration

File Modified: [Startup.cs]

Update Service Registration

Before (Commerce 14 - Simple metapackage registration):

services 
    .AddCmsAspNetIdentity<ApplicationUser>() 
    .AddCommerce() 
    .AddAdminUserRegistration() 
    .AddEmbeddedLocalization<Startup>();

After (Commerce 15 - Explicit service registration):

services 
    .AddCmsHost() 
    .AddCmsCore() 
    .AddCmsAspNetIdentity<ApplicationUser>() 
    .AddCmsHtmlHelpers() 
    .AddCmsTagHelpers() 
    .AddCmsUI() 
    .AddAdmin() 
    .AddCmsImageSharpImageLibrary() 
    .AddTinyMce() 
    .AddContentGraph() 
    .AddContentManager() 
    .AddCommerce() 
    .AddVisitorGroupsMvc() 
    .AddVisitorGroupsUI() 
    .AddAdminUserRegistration() 
    .AddEmbeddedLocalization<Startup>(); 
 
services.Configure<DataAccessOptions>(options => 
{ 
    options.UpdateDatabaseCompatibilityLevel = true; 
});

Step 4: Update Application Settings

File Modified: [appsettings.json]

Add the following Optimizely configuration section for Content Graph

"Optimizely": { 
  "ContentGraph": { 
    "GatewayAddress": "https://cg.optimizely.com", 
    "AppKey": "<app-key>", 
    "Secret": "<secret>", 
    "SingleKey": "<single-key>", 
    "AllowSendingLog": "true" 
  } 
}

Important: Replace the placeholder values (<app-key>, <secret>, <single-key>, <instance-id>) with your actual credentials from the Optimizely portal.

Step 5: Restore, Build, and Run Migration

After making all the changes:

Restore packages:

dotnet restore

Build the project:

dotnet build

Run the application:

- Press F5 in Visual Studio, or

- Run dotnet run from the command line

Run Commerce migration:

- Navigate to: https://localhost:5000/Optimizely/commerce/migrate

- This will update the database schema and migrate data to Commerce 15 format

Step 6: Verify the Upgrade

Access the Commerce Admin UI: Navigate to https://localhost:5000/Optimizely/Commerce/

Important Notes

Code Compatibility

Depending on your Commerce solution, you may need to update source code due to API changes in CMS 13 and Commerce 15. See the CMS 13 Pre-Release overview for details.

Commerce 15-compatible versions for popular Commerce add-ons will be released later

Preview Versions

Commerce 15.0.0-preview1 and CMS 13.0.0-preview4 are pre-release versions

Not recommended for production use

Use for evaluation and testing purposes only

Additional Resources

How to create an empty commerce project from which you can build your Optimizely Commerce Connect website

Official upgrade guide: CMS 12 to CMS 13

Overview of Commerce 15 pre-release

Prove what your experimentation program is worth with Holdouts

Mon, 30 Mar 2026 16:15:32 GMT

Running experiments is one thing. Knowing whether your experimentation program is moving the business forward? That's the harder question.

Most teams can point to individual test wins. A headline change that lifted click-through. A checkout flow that cut abandonment. But when leadership asks "what is all this experimentation worth?" the answer gets complicated fast.

Today, that question gets a lot easier to answer. Holdouts is now available in Optimizely Feature Experimentation.

What Holdouts do

Holdouts reserves a fixed percentage of your users from all running experiments. That group sees no test variants, no changes, nothing different. They're your global control.

At the end of a measurement period, you compare what happened to the holdout group against everyone else. The difference is the net lift of your entire experimentation program. Not one test. All of them.

It's the cleanest answer to the question every experimentation leader eventually faces: "What would have happened if we hadn't run any experiments at all?"

Why it matters for mature programs

If you're running multiple experiments concurrently, individual test results only tell part of the story. Experiments interact. Variants overlap. And without a clean baseline, you're measuring performance against a constantly shifting target.

Holdouts fix that. It gives you an unbiased comparison point that sits outside your test traffic. The result is a measurement you can take to leadership with confidence.

Not a collection of test summaries. A defensible number that answers the question your CFO is asking.

Built for the programs that need it most

This feature is designed for teams running at scale. If you're running a handful of experiments a year, individual test metrics serve you well. But if your program spans multiple teams, products, and concurrent tests, Holdout Groups gives you the program-level view you've been missing.

And it works alongside your existing setup. No changes to individual experiments. No disruption to running tests. Just an additional layer of measurement that sits above everything you're already doing.

What you can do now

Create a Holdout group in your Flags > Holdouts tab. Set your holdout percentage, select what metrics to measure like Overall Revenue, what Audience, and this holdout will get added to your next experimentation based on the criteria. (I typically recomennd holding back between 1-5% of your traffic). Your next leadership review can include a number that answers the question that matters: what is our experimentation program delivering?

For a full explanation of how holdouts work, see the Holdouts Glossary Page.

Ready to get started? Log in to Optimizely Feature Experimentation.

Supercharging Optimizely Forms: Introducing Dynamic Email Routing & Conditional Submissions

Mon, 30 Mar 2026 15:46:11 GMT

Supercharging Optimizely Forms: Introducing Dynamic Email Routing & Conditional Submissions

Optimizely Forms is a powerhouse for gathering user data, but as implementations grow in complexity, we often run into a common limitation with the built-in "Send email after form submission" actor: it's a bit static.

In a typical enterprise scenario, you don't just want one email going to one place. You might need to route a lead to the "Sales" team if they select a specific department, or perhaps you only want an email sent if the user ticks a "Request Callback" box.

To solve this, I’ve released an open-source package: ScottReed.Optimizely.Forms.DynamicEmailRouting. It’s a custom post-submission actor for CMS 12 that brings dynamic routing and complex conditional logic directly into the Forms UI.

The Problem: The "One-Size-Fits-All" Email

The default email actor is great for simple notifications. However, once you need logic like "If Department is 'Support', send to support@company.com" or "Only send this internal alert if 'Priority' is 'Critical'", you're usually forced to write custom code for every specific form or clutter the CMS with multiple overlapping actors.

The Solution: Dynamic Email Routing

This package extends the core functionality of the built-in email actor but adds two powerful layers: Email Routing and Conditional Logic.

1. Dynamic Email Routing

Instead of a single hardcoded "To" address, you can now define a mapping table. You select a form field, define a value to match, and specify the recipient. If no match is found, it gracefully falls back to the primary "To" address.

2. Conditional Logic (AND/OR)

Sometimes you don't want an email sent at all unless specific criteria are met. The actor allows you to add multiple conditions using "is" and "is not" operators. You can toggle between "Match ALL" (AND) or "Match ANY" (OR) logic.

Technical Implementation: Under the Hood

For the developers curious about how this is built, the package leverages several Optimizely extension points to ensure a "native" feel.

The Actor & Model

The core logic resides in DynamicEmailRoutingActor, which inherits from SendEmailAfterSubmissionActor. This is crucial because it allows us to reuse the existing EmailTemplateActorModel features—like the rich text editor, the "Insert Placeholder" dropdown, and the standard From/Subject fields—without reinventing the wheel.

The UI (Dojo & Protected Modules)

To provide a seamless editor experience, the package uses the Protected Module pattern. On build, the client-side resources (Dojo editors and language files) are zipped into a protected module folder.

I’ve implemented three custom Dojo editors:

EmailRoutingEditor.js: Handles the dynamic table for routing.
ConditionMatchEditor.js: A simple dropdown for logic selection.
ConditionsEditor.js: Manages the conditional rules.

Localization

All labels and the actor name are localized via XML files embedded within the module, ensuring it fits perfectly into the Optimizely UI language settings.

Getting Started

Installation is a standard NuGet affair. Because it uses an IConfigurableModule for auto-registration, there's zero configuration required in your Startup.cs.

Install via NuGet:

https://nuget.optimizely.com/packages/scottreed.optimizely.forms.dynamicemailrouting/

dotnet add package ScottReed.Optimizely.Forms.DynamicEmailRouting

Configuration:

Ensure your SMTP is configured in appsettings.json (the actor uses the standard Optimizely SMTP client).
In the CMS, add the Dynamic email routing actor to your Form Container.
Define your routes and conditions.

[Image Placeholder: Selecting the Dynamic Email Routing actor in the Form Settings tab]

Extensibility

The project is built with extensibility in mind. If you need more complex operators (like "contains" or "starts with"), you can easily extend the EvaluateConditions logic in the actor or contribute to the repository!

Wrap Up

By moving this logic into the CMS UI, we empower editors to manage complex workflows themselves without needing a deployment for every routing change.

You can find the full source code, documentation, and a test Alloy site on GitHub: 👉 scottreed/Optimizely-Dynamic-Form-Submission

I’d love to hear your feedback or see your PRs!

How CMS Implementations Need to Change for GEO and AEO

Fri, 27 Mar 2026 15:30:20 GMT

Search is changing. AI systems are increasingly the first point of contact between your content and your audience, and they don't behave like traditional search crawlers. If your CMS implementation was built purely with SEO in mind, it probably isn't ready for what's coming.

VirtualText 2.0.0 beta for Optimizely CMS 13 previews

Fri, 27 Mar 2026 02:39:59 GMT

DavidHome.Optimizely.VirtualText 2.0.0 has been released as beta for Optimizely CMS 13 previews.

This is a major technical release. The focus is compatibility with CMS 13 previews, updated routing behavior, and alignment with Optimizely's newer application and shell APIs.

What changed

VirtualText now relies more on Optimizely's application model and less on older site-definition-based assumptions. Internally, that means updated routing, start page resolution, and site context handling through APIs such as IApplicationRepository, IApplicationResolver, and IRoutableApplication.

I also added ApplicationEventsSubscriber so partial routers are registered from application lifecycle events, and refactored several code paths from PageReference to ContentReference.

On the UI side, the plugin and RobotsTxt extension layouts were updated to use the newer Optimizely shell resources and components.

Breaking changes

2.0.0 beta is for CMS 13 previews only. If your solution is on CMS 12, stay on the previous VirtualText line.

If you have custom code around SiteDefinition.Current, ISiteDefinitionRepository, site-based routing assumptions, or overridden plugin views, review that code before upgrading.

If you run a multi-site solution, validate routing behavior explicitly after the upgrade. Router registration now follows the application lifecycle.

You should also expect small adjustments if your own code mirrors older PageReference-based assumptions.

Who should upgrade

This beta is for teams already working with Optimizely CMS 13 previews and willing to validate a major-version upgrade.

If that is your target, this is the version to evaluate. If not, stay on the current stable line.

Happy coding!

Technical Q&A for CMS 13

Thu, 26 Mar 2026 19:19:46 GMT

This blog post explains what to expect when planning to upgrade to Optimizely CMS 13. It answers common technical questions about what’s involved in moving to CMS 13, what changes to expect, and where Optimizely is headed next.

Custom Property Editors in Optimizely CMS 13

Thu, 26 Mar 2026 13:35:08 GMT

When the world first saw how to create custom editors for Optimizely CMS back in 2012, it was a game-changer for Javascript developers. For the first time, we could build custom property editors that made content editors' lives easier and more productive.

However, there was a catch: you needed to master the Dojo framework. Understanding define, declare, mixins and dependecies wasn't exactly straightforward—you had to become a Dojo master to create even simple custom editors.

Fast forward to today, and Optimizely CMS 13 (now available as preview) still supports the Dojo approach (for those who enjoy the classics), but it also introduces a modern, streamlined way to register editors as ES6 modules.

This article will guide you through the new ES6 module approach.

Your First ES6 Module Editor

An editor in CMS 13 is simply a JavaScript function with the following signature:

export default function editorWithAllSettings(editorContainer, initialValue, onEditorValueChange, widgetSettings, readOnly)

Parameters

editorContainer: The HTML element where your editor should be rendered
initialValue: The initial value of the property
onEditorValueChange: A callback function to notify the CMS when the value changes (triggers save to server)
widgetSettings: Configuration passed from the server (optional)
readonly: Boolean indicating whether the editor should be read-only

The function can either:

Return nothing (render directly into editorContainer)
Return an object with lifecycle methods (render, updateValue, destroy)

Registering the Editor on the Server

After creating client editor JavaScript file, we need to register it on the server side. This part is similar to how you would register any custom editor, with one important addition: you need to set IsJavascriptModule = true to enable the new ES6 module registration.

[ContentType]
public class TestPage : PageData
{
    [ClientEditor(ClientEditingClass = "ClientResources/Scripts/Editors/minimal-editor.js", IsJavascriptModule = true)]
    public virtual string SimpleProperty { get; set; }
}

Now we can look closer at how to implement the editor.

The Simplest Editor: Direct Rendering

Let's start with the most basic example—a function that renders a simple text input directly:

export default function customEditor(editorContainer, initialValue, onEditorValueChange) {
    const input = document.createElement("input");
    input.type = "text";
    input.value = initialValue || "";
    input.onchange = (event) => onEditorValueChange(event.target.value);
    editorContainer.appendChild(input);
}

There are few key points to note about this approach is that no framework dependencies are required. The only requirement is following the function signature convention.

This approach works well for very simple scenarios, such as:

Read-only displays (e.g., links to external systems)
Simple labels or informational fields
Lightweight custom inputs

For scenarios requiring more interaction with the CMS (like handling undo/redo), it's recommended to return an object with lifecycle methods.

Returning an Object with Lifecycle Methods

Instead of rendering directly, your function can return an object with predefined methods.

The required is the "render" method, which is called to render the editor.

export default function customEditor(editorContainer, initialValue, onEditorValueChange) {
    return {
        render: function () {
            const input = document.createElement("input");
            input.type = "text";
            input.value = initialValue || "";
            input.onchange = (event) => onEditorValueChange(event.target.value);
            editorContainer.appendChild(input);
            this._input = input;
        },
    };
}

The above example is functionally equivalent to the direct rendering approach. However, by returning an object, you can also implement additional lifecycle methods for better integration with the CMS.

Additional methods include "updateValue" and "destroy":

export default function editorWithAllSettings(editorContainer, initialValue, onEditorValueChange, widgetSettings, readOnly) {
    return {
        render: function () {
            console.log("rendering custom widget");

            const input = document.createElement("input");
            input.type = "text";
            if (readOnly) {
                input.disabled = true;
            }
            input.value = initialValue || "";
            input.onchange = (event) => onEditorValueChange(event.target.value);
            editorContainer.appendChild(input);
            this._input = input;
        },
        updateValue: function (value) {
            console.log("updating custom widget value");
            this._input.value = value;
        },
        destroy: function () {
            console.log("removing custom widget");
        },
    };
}

Method purposes:

render(): Called to initially render the editor
updateValue(): Called when the value needs to be updated (e.g., when using Undo/Redo functionality)
destroy() :Called when the editor should be cleaned up (e.g., when navigating to a different page). Use this to remove event listeners and prevent memory leaks.

Example: Text Area with Statistics

Now we can look closer at a more complex example that demonstrates the power of this approach. Building on a classic blog post by Ben McKernan, let's create a more sophisticated editor that displays live statistics, like character count, word count, and paragraph count about the text being entered:

const count = (value) => {
    const original = typeof value === "string" ? value : "";
    const trimmed = original.trim();
    return {
        paragraphs: trimmed ? (trimmed.match(/\n+/g) || []).length + 1 : 0,
        words: trimmed ? (trimmed.replace(/['";:,.?¿\-!¡]+/g, "").match(/\S+/g) || []).length : 0,
        characters: trimmed ? trimmed.replace(/\s/g, "").length : 0,
    };
};

export default function editorWithAllSettings(
    editorContainer,
    initialValue,
    onEditorValueChange,
    widgetSettings,
    readOnly
) {
    return {
        render: function () {
            const wrapper = document.createElement("div");
            wrapper.className = "text-area-with-statistics";

            const textarea = document.createElement("textarea");
            if (readOnly) {
                textarea.disabled = true;
            }
            textarea.value = initialValue || "";

            const stats = document.createElement("div");
            const updateStats = (value) => {
                const { characters, words, paragraphs } = count(value);
                stats.textContent = `Characters: ${characters}\nWords: ${words}\nParagraphs: ${paragraphs}`;
            };
            stats.style.whiteSpace = "pre";

            updateStats(textarea.value);

            textarea.oninput = (event) => {
                onEditorValueChange(event.target.value);
                updateStats(event.target.value);
            };

            wrapper.appendChild(textarea);
            wrapper.appendChild(stats);
            editorContainer.appendChild(wrapper);

            this._textarea = textarea;
            this._stats = stats;
        },
        updateValue: function (value) {
            this._textarea.value = value;
            const { characters, words, paragraphs } = count(value);
            this._stats.textContent = `Characters: ${characters}\nWords: ${words}\nParagraphs: ${paragraphs}`;
        }
    };
}

This editor is around 50 lines of code, with no dependencies on any framework. It demonstrates how you can create a rich editing experience with live feedback using just vanilla JavaScript. The "updateValue" method ensures that the statistics are always in sync with the current value, even when changes come from outside the editor (e.g., Undo/Redo).

Passing Configuration from the Server

In many scenarios, we might want to pass custom settings from the server to your editor. For example we have dropdown editor and want to populate the options from the server, or we want to pass some initial text or configuration values. The best way to do this is by implementing a custom "EditorDescriptor".

[EditorDescriptorRegistration(TargetType = typeof(string), UIHint = "CustomModuleEditor")]
public class CustomEditorDescriptor : EditorDescriptor
{
    public CustomEditorDescriptor()
    {
        ClientEditingClass = "ClientResources/Scripts/Editors/editor-with-custom-settings.js";
    }

    public override void ModifyMetadata(ExtendedMetadata metadata, IEnumerable<Attribute> attributes)
    {
        base.ModifyMetadata(metadata, attributes);

        metadata.EditorConfiguration["isJavascriptModule"] = true;
        metadata.EditorConfiguration["initialTextFromServer"] = "Here is sample initial text from the server";
    }
}

Important: Don't forget to set metadata.EditorConfiguration["isJavascriptModule"] = true to enable ES6 module mode.

Then we can use this editor descriptor in our content type by specifying the "CustomModuleEditor" UIHint.

[ContentType]
public class TestPage : PageData
{
    [UIHint("CustomModuleEditor")]
    public virtual string EditorWithCustomSettings { get; set; }
}

The server configuration is simply available through the widgetSettings object as field parameter:

export default function editorWithAllSettings(editorContainer, initialValue, onEditorValueChange, widgetSettings, readOnly) {
    return {
        render: function () {
            const wrapper = document.createElement("div");

            const input = document.createElement("input");
            input.type = "text";
            if (readOnly) {
                input.disabled = true;
            }
            input.value = initialValue || "";
            input.onchange = (event) => onEditorValueChange(event.target.value);
            this._input = input;

            const descriptionEl = document.createElement("div");
            descriptionEl.textContent = widgetSettings.initialTextFromServer;

            wrapper.appendChild(input);
            wrapper.appendChild(descriptionEl);
            editorContainer.appendChild(wrapper);
        },
        updateValue: function (value) {
            this._input.value = value;
        }
    };
}

Advanced Scenarios: Modern Tooling and Frameworks

The real power of ES6 module registration goes beyond just simpler code. You can now build custom editors using modern JavaScript tooling and development practices.

The editor can be implemented outside of the CMS project, with its own dependencies, build process, and development environment. You can use React, Vue, Angular, or any framework you prefer, and bundle it with tools like Webpack or Vite.

For example:

TypeScript for type safety
React for component composition
Vite for fast builds
Optimizely Axiom for consistent UI components. Which give you same design system as Optimizely's own products, ensuring a polished, professional look and feel.
Storybook for component development and documentation
Vitest for unit testing

Example Project Structure for textarea with statistics editor

CustomEditorSample/
├── src/
│   ├── TextAreaWithStats.tsx          # React component
│   ├── TextAreaWithStats.stories.tsx  # Storybook stories
│   ├── count-statistics.ts            # Business logic
│   ├── count-statistics.test.ts       # Unit tests
│   └── index.ts                       # ES6 module wrapper
├── vite.config.js                      # Build configuration
└── package.json

The React Component

import React, { useState, useEffect } from 'react';
import { AxiomProvider, Textarea, Box, Group, Text } from '@optiaxiom/react';

export const TextAreaWithStats: React.FC<TextAreaWithStatsProps> = ({
    initialValue = '',
    onValueChange,
    readOnly = false,
}) => {
    const [value, setValue] = useState<string>(initialValue);
    const [stats, setStats] = useState<TextStats>({ characters: 0, words: 0, paragraphs: 0 });

    useEffect(() => {
        setStats(countStatistics(value));
    }, [value]);

    const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
        const newValue = e.target.value;
        setValue(newValue);
        if (onValueChange) {
            onValueChange(newValue);
        }
    };

    return (
        <AxiomProvider>
            <Box>
                <Textarea
                    value={value}
                    onChange={handleChange}
                    disabled={readOnly}
                    placeholder="Enter text..."
                />
                <Group mt="4" flexDirection="column" gap="2">
                    <Text fontSize="md" color="fg.secondary">
                        Characters: {stats.characters}
                    </Text>
                    <Text fontSize="md" color="fg.secondary">
                        Words: {stats.words}
                    </Text>
                    <Text fontSize="md" color="fg.secondary">
                        Paragraphs: {stats.paragraphs}
                    </Text>
                </Group>
            </Box>
        </AxiomProvider>
    );
};

The "index.ts" file exports the editor function that the CMS expects, while using React internally:

import React from 'react';
import { createRoot, Root } from 'react-dom/client';
import { TextAreaWithStats } from './TextAreaWithStats';

export default function editorWithAllSettings(
    editorContainer: HTMLElement,
    initialValue: string,
    onEditorValueChange: (value: string) => void,
    widgetSettings?: Record<string, unknown>,
    readOnly?: boolean
) {
    let root: Root | null = null;

    return {
        render: function () {
            const container = document.createElement('div');
            editorContainer.appendChild(container);

            root = createRoot(container);
            root.render(
                React.createElement(TextAreaWithStats, {
                    initialValue,
                    onValueChange: onEditorValueChange,
                    readOnly,
                    widgetSettings,
                })
            );
        },
        updateValue: function (value: string) {
            if (root) {
                root.render(
                    React.createElement(TextAreaWithStats, {
                        initialValue: value,
                        onValueChange: onEditorValueChange,
                        readOnly,
                        widgetSettings,
                    })
                );
            }
        },
        destroy: function () {
            if (root) {
                root.unmount();
                root = null;
            }
        },
    };
}

Development with Storybook

Storybook allows you to develop and test your editor in isolation, without needing to run the full CMS.

Unit Testing

Write tests for your business logic using Vitest:

import { describe, expect, it } from "vitest";
import { countStatistics } from "./count-statistics";

describe("countStatistics", () => {
    it("counts a single paragraph and strips punctuation from words", () => {
        expect(countStatistics("  Hello, world!  ")).toEqual({
            paragraphs: 1,
            words: 2,
            characters: 12,
        });
    });

    it("counts paragraph groups separated by newlines", () => {
        expect(countStatistics("First line\nSecond line\n\nThird line")).toEqual({
            paragraphs: 3,
            words: 6,
            characters: 28,
        });
    });
});

The ES6 module approach gives you complete freedom to use vanilla JavaScript, React, Vue, or any framework you prefer, while taking advantage of modern development practices like TypeScript, ESLint, and Prettier. You can write unit tests, use Storybook for component development, and benefit from hot module replacement and fast builds with Vite. The code is cleaner, more maintainable than Dojo-based editors, and easily reusable across projects.

The module approach in Optimizely CMS 13 is a step forward in custom editor development. While the Dojo framework served us well for over a decade, the new approach embraces modern JavaScript standards and development practices.

Whether you're building a simple text input or a sophisticated React component with real-time validation, the ES6 module registration makes it easier, more maintainable, and more enjoyable to create custom property editors.

The best part? You can adopt this gradually—your existing Dojo editors will continue to work, so you can migrate at your own pace.

Happy coding!

Introducing the Optimizely CMS 13 Graph SDK

Wed, 25 Mar 2026 02:51:18 GMT

Query Optimizely Graph Without Writing GraphQL. A C# fluent API that lets you migrate from Search & Navigation with familiar patterns.

CMS 13 Optimizely Graph Migration SDK Search & Navigation

TL;DR

Search & Navigation is gone in CMS 13. Optimizely Graph is the replacement, and the Optimizely.Graph.Cms.Query SDK lets you query it with familiar C# fluent patterns instead of raw GraphQL.
The API mirrors what you know: Where() replaces Filter(), SearchFor() replaces For(), Limit() replaces Take(). Your muscle memory transfers.
Three entry points: QueryContent<T>() for CMS content, Query<T>() for any type, Query("TypeName") for dynamic scenarios.
New capabilities included: Boolean facets, IAsyncEnumerable streaming, decay/factor scoring, pinned results, named queries, and cursor-based pagination.
.ToGraphQL() is your best friend. Call it on any query to inspect the generated GraphQL. This will be invaluable during migration.
A complete migration reference table (Section 12) maps every Search & Navigation API to its Graph SDK equivalent.

1. Why This SDK Exists

With CMS 13, Optimizely is replacing Search & Navigation (formerly Episerver Find) with Optimizely Graph as the platform's content query engine. This is not an optional migration, Search & Navigation will not be available in CMS 13.

For many partner developers, this triggers understandable anxiety. Search & Navigation's fluent API has been the go-to for content querying for years. Teams have accumulated deep expertise in its fluent Search<T>().For().Filter() patterns, and the prospect of learning GraphQL from scratch feels like a significant lift on top of everything else in a CMS 13 migration.

That's exactly why the Graph SDK exists.

The Optimizely.Graph.Cms.Query package provides a C# fluent API that compiles your familiar expressions into GraphQL queries behind the scenes. You write C#. The SDK writes GraphQL. Optimizely Graph executes it.

You do not need to learn GraphQL to use Optimizely Graph.

The SDK translates your C# lambda expressions into optimized GraphQL queries automatically. If you've used Search & Navigation, you already know 90% of what you need.

The API intentionally mirrors Search & Navigation patterns where possible: Where() replaces Filter(), SearchFor() replaces For(), Limit() replaces Take(). The muscle memory transfers.

2. Getting Started

DI Registration

// Program.cs or Startup.cs
services.AddGraphContentClient();

Inject the Client

Inject IGraphContentClient into your controllers, services, or view components:

public class SearchController : Controller
{
    private readonly IGraphContentClient _graphClient;

    public SearchController(IGraphContentClient graphClient)
    {
        _graphClient = graphClient;
    }
}

Three Entry Points

The SDK provides three ways to start a query, depending on your needs:

Method	Use Case	Type Constraint	Returns
QueryContent<T>()	Strongly-typed CMS content queries	T : class, IContentData	ISearchableContentQuery<T>
Query<T>()	Strongly-typed queries for any class	T : class	ISearchableQuery<T>
Query("TypeName")	Untyped queries by content type name	None	ISearchableQuery

QueryContent<T>() is the most common choice for CMS content. It constrains T to IContentData, giving you access to CMS-specific features like content resolution via GetAsContentAsync().

Query<T>() works with any class, not just CMS content types. Use this when querying custom types indexed in Graph that don't implement IContentData.

Query("TypeName") creates an untyped query using a string type name. Useful for dynamic scenarios where the content type isn't known at compile time.

3. Your First Query

Let's see the same query expressed three ways. Goal: Find all recipes in the "Dessert" category, returning only Name and Description.

Before - Search & Navigation

var result = searchClient.Search<Recipe>()
    .Filter(x => x.Category.Match("Dessert"))
    .Select(x => new { x.Name, x.Description })
    .GetResult();

After - Graph SDK

var result = await _graphClient
    .Query<Recipe>()
    .Where(x => x.Category, "Dessert")
    .Fields<Recipe>(nameof(Recipe.Name), nameof(Recipe.Description))
    .GetAsync();

The parallels are clear: Filter() becomes Where(), Select() becomes Fields<T>(), and GetResult() becomes GetAsync(). The Graph SDK is async-first, returning Task<IContentResult<T>>.

GetAsContentAsync() - CMS Content Resolution

When querying CMS content types, use GetAsContentAsync() to resolve results directly as IContent items. This returns the same fully-resolved content objects that Search & Navigation's GetResult() provided.

var result = await _graphClient
    .QueryContent<Recipe>()
    .Where(x => x.Category, "Dessert")
    .GetAsContentAsync();

// result implements IEnumerable<IContent>
foreach (var content in result)
{
    // content is IContent, fully resolved from CMS
}

Do not use .Fields() with GetAsContentAsync()

The SDK generates a minimal query fetching only content identifiers (_id, _metadata), then resolves full IContent objects through the CMS content loader. Calling .Fields() with an IContentData projection type will throw InvalidOperationException.

Generated GraphQL

For the GetAsync() query above (with Fields), the SDK generates:

{
  Recipe(where: { category: { eq: "Dessert" } }) {
    items {
      Name
      Description
    }
  }
}

Tip: Use .ToGraphQL()

Call .ToGraphQL() on any query to see the generated GraphQL without executing it. This is invaluable for debugging and learning how your C# maps to GraphQL.

string graphql = _graphClient
    .Query<Recipe>()
    .Where(x => x.Category, "Dessert")
    .ToGraphQL();

Console.WriteLine(graphql);

GetAsync() returns raw Graph results as IContentResult<T>. Use with .Fields<TProjection>() to specify which fields to return.
GetAsContentAsync() resolves results through the CMS content loader, returning IGetAsContentResult<IContent>. Do not use .Fields() with this method.
GetAsContentAsync() is only available on QueryContent<T>() queries.

4. Filtering

Filtering is where you'll spend most of your time. The SDK provides multiple approaches, from simple lambda expressions to a dynamic FilterBuilder API.

Lambda Expressions

The most natural way to filter, standard C# comparison operators inside a Where() lambda:

// Equality
.Where(x => x.Category == "Dessert")

// Not equal
.Where(x => x.Category != "Archived")

// Numeric comparisons
.Where(x => x.Rating > 4)
.Where(x => x.CookingTime < 30)

// Boolean
.Where(x => x.IsPublished)
.Where(x => !x.IsArchived)

// Compound conditions with && and ||
.Where(x => x.Category == "Dessert" && x.Rating > 4 && x.IsPublished)
.Where(x => x.Category == "Appetizer" || x.Category == "Dessert")

Full example with compound conditions:

var result = await _graphClient
    .Query<Recipe>()
    .SearchFor("Cookies")
    .Where(x => x.Category == "Dessert" && x.Rating > 4 && x.IsPublished)
    .Fields<RecipeResult>(x => x.Name, x => x.Description)
    .GetAsync();

Generated GraphQL:

{
  Recipe(
    where: {
      _and: [
        { category: { eq: "Dessert" } }
        { rating: { gt: 4 } }
        { isPublished: { eq: true } }
      ]
      _fulltext: { match: "Cookies" }
    }
  ) {
    items { Name  Description }
  }
}

Multiple .Where() calls

You can chain multiple .Where() calls on the same query. Each call adds an AND condition.

String Filters

Extension methods for string operations that go beyond what lambda expressions can express:

// Exact match
.Where(x => x.Author.Match("Jane Doe"))

// Like -- SQL-style wildcards (% = 0+ chars, _ = single char)
.Where(x => x.Title.Like("%chocolate%"))

// Contains -- substring search
.Where(x => x.Title.Contains("chocolate"))

// StartsWith
.Where(x => x.Title.StartsWith("How to"))

// In -- matches any value in a collection
.Where(x => x.Category.In(new[] { "Dessert", "Appetizer", "Main Course" }))

// Exists -- check if field has/lacks a value
.Where(x => x.Author.Exists())       // has a value
.Where(x => x.Author.Exists(false))  // is null

Collection and Range Filters

Numeric and DateTime properties support range-based filtering:

// Numeric range (inclusive)
.Where(x => x.CookingTime.InRange(15, 45))

// Greater than / Less than
.Where(x => x.Rating.GreaterThan(3))
.Where(x => x.CookingTime.LessThanOrEqual(60))

// DateTime range
.Where(x => x.PublishDate.InRange(startDate, endDate))

// DateTime comparisons
.Where(x => x.PublishDate.GreaterThan(DateTime.UtcNow.AddDays(-30)))

Dynamic FilterBuilder API

For scenarios where filters must be built at runtime. Based on user input, iterating over collections, or applying conditional logic:

var filter = _graphClient.BuildFilter<Recipe>();

if (!string.IsNullOrEmpty(selectedCategory))
{
    filter = filter.And(x => x.Category.Match(selectedCategory));
}

if (minRating.HasValue)
{
    filter = filter.And(x => x.Rating.GreaterThanOrEqual(minRating.Value));
}

var result = await _graphClient
    .QueryContent<Recipe>()
    .Filter(filter)
    .Fields<RecipeResult>(x => x.Name, x => x.Description)
    .GetAsync();

Combining with OR logic:

var filter = _graphClient.BuildFilter<Recipe>()
    .Or(x => x.Category.Match("Dessert"))
    .Or(x => x.Category.Match("Appetizer"))
    .Or(x => x.Category.Match("Snack"));

Key FilterBuilder Details

BuildFilter<T>() is an extension method on IGraphContentClient. Each .And() / .Or() call returns a new FilterBuilder<T> instance (immutable). FilterBuilder<T> has an implicit conversion to GraphFilter, so it can also be passed to .Where(GraphFilter).

Combining Where() and Filter()

var dynamicFilter = _graphClient.BuildFilter<Recipe>()
    .And(x => x.IsPublished.Match(true))
    .And(x => x.Rating.GreaterThan(3));

var result = await _graphClient
    .QueryContent<Recipe>()
    .Where(x => x.Category == "Dessert")  // Lambda expression
    .Filter(dynamicFilter)                  // FilterBuilder
    .Fields<RecipeResult>(x => x.Name, x => x.Description)
    .GetAsync();

Where() vs Filter()

Where() adds filter conditions directly. Filter() accepts a FilterBuilder<T>? specifically, which is designed for the dynamic filter-building pattern. Both can be combined in the same query.

See the complete migration reference (Section 12) for S&N filter equivalents.

5. Full-Text Search

Full-text search follows a chain pattern: SearchFor() opens the search context, then UsingFullText() and UsingField() configure how the search is applied.

Basic Full-Text Search

var result = await _graphClient
    .QueryContent<ArticlePage>()
    .SearchFor("chocolate cake recipe")
    .Fields<ArticleResult>(x => x.Title, x => x.Summary)
    .GetAsync();

SearchFor() returns ISearchFieldContentQuery<T>, which adds three search-specific methods: UsingFullText(), UsingField(), and Track().

UsingFullText

Apply the search term across all searchable fields with optional highlighting and boost:

var result = await _graphClient
    .QueryContent<ArticlePage>()
    .SearchFor("chocolate cake")
    .UsingFullText(highlightTag: "<mark>", boost: 2)
    .Fields<ArticleResult>(x => x.Title, x => x.Summary)
    .GetAsync();

UsingField - Targeted Search with Boost

Target the search to specific fields with per-field boost values:

var result = await _graphClient
    .QueryContent<ArticlePage>()
    .SearchFor("chocolate cake")
    .UsingField(x => x.Title, boost: 3, highlightTag: "<strong>")
    .UsingField(x => x.Summary, boost: 2)
    .UsingField(x => x.Body, boost: 1)
    .Fields<ArticleResult>(x => x.Title, x => x.Summary)
    .GetAsync();

See the complete migration reference (Section 12) for S&N search equivalents.

6. Faceted Search

Facets aggregate your results into buckets (categories, date ranges, numeric ranges, or boolean groups). The SDK provides separate Facet() overloads for each data type.

String Facets

var result = await _graphClient
    .QueryContent<ArticlePage>()
    .Facet(x => x.Category)
    .Fields<ArticleResult>(x => x.Title, x => x.Category)
    .GetAsync();

// With ordering and limits
.Facet(x => x.Category,
       limit: 10,
       orderType: OrderType.COUNT,
       direction: OrderDirection.Descending)

Range Facets (int)

var result = await _graphClient
    .QueryContent<Recipe>()
    .Facet(x => x.CookingTime, ranges: new[]
    {
        new RangeFacetInput<int> { From = 0, To = 15 },
        new RangeFacetInput<int> { From = 15, To = 30 },
        new RangeFacetInput<int> { From = 30, To = 60 },
        new RangeFacetInput<int> { From = 60, To = 120 }
    })
    .Fields<RecipeResult>(x => x.Name, x => x.CookingTime)
    .GetAsync();

Boolean Facets New

Boolean facets are new in the Graph SDK (Search & Navigation did not support them):

var result = await _graphClient
    .QueryContent<ArticlePage>()
    .Facet(x => x.IsFeatured)
    .Fields<ArticleResult>(x => x.Title, x => x.IsFeatured)
    .GetAsync();

Facet Filtering: OR Within, AND Between

The Graph SDK applies facet filters with intuitive boolean logic:

Within a single facet: values are combined with OR. Selecting "Dessert" and "Appetizer" in Category returns items in Dessert or Appetizer.
Between different facets: filters are combined with AND. Selecting "Dessert" in Category and "Jane Doe" in Author returns items matching both.

var result = await _graphClient
    .QueryContent<Recipe>()
    .Facet(x => x.Category, filters: new[] { "Dessert", "Appetizer" })  // OR
    .Facet(x => x.Author, filters: new[] { "Jane Doe" })              // AND with above
    .GetAsContentAsync();

// Returns: (Category is Dessert OR Appetizer) AND (Author is Jane Doe)

Improvement over S&N

In Search & Navigation, achieving OR-within / AND-between facets required executing multiple search queries and merging results. With the Graph SDK, a single query handles it natively.

Reading Facet Results

var result = await _graphClient
    .QueryContent<ArticlePage>()
    .Facet(x => x.Author)
    .Facet(x => x.Category)
    .Fields<ArticleResult>(x => x.Title, x => x.Author, x => x.Category)
    .GetAsync();

// Read facet values (type-safe)
var authorFacets = result.Facets.GetFacet(x => x.Author);

foreach (var facet in authorFacets)
{
    string name = facet.Name;   // e.g., "Jane Doe"
    int count = facet.Count;    // e.g., 15
}

// Other helpers
bool hasFacet = result.Facets.HasFacet("Author");
var fieldNames = result.Facets.FieldNames; // ["Author", "Category"]

See the complete migration reference (Section 12) for S&N facet equivalents.

7. Sorting, Pagination & Streaming

Sorting

// Sort by property (descending)
var result = await _graphClient
    .QueryContent<ArticlePage>()
    .OrderBy(x => x.PublishDate, OrderDirection.Descending)
    .Fields<ArticleResult>(x => x.Title, x => x.PublishDate)
    .GetAsync();

OrderBy() returns IOrderedContentQuery<T>, which allows chaining additional sort criteria with ThenBy():

// Primary sort by date, secondary sort by title
.OrderBy(x => x.PublishDate, OrderDirection.Descending)
.ThenBy(x => x.Title, OrderDirection.Ascending)

Ranking New

When using full-text search, sort by relevance score using the _ranking pseudo-field with a RankingMode:

var result = await _graphClient
    .QueryContent<ArticlePage>()
    .SearchFor("chocolate")
    .UsingFullText()
    .UsingField(x => x.Title, boost: 10)
    .OrderBy("_ranking", RankingMode.Relevance)
    .ThenBy(x => x.PublishDate, OrderDirection.Descending)
    .Limit(15)
    .GetAsContentAsync();

Pagination

// Skip and Limit
var result = await _graphClient
    .QueryContent<ArticlePage>()
    .OrderBy(x => x.PublishDate, OrderDirection.Descending)
    .Skip(20)
    .Limit(10)
    .IncludeTotal()
    .Fields<ArticleResult>(x => x.Title, x => x.PublishDate)
    .GetAsync();

int totalCount = result.Total; // populated when IncludeTotal() is used

IAsyncEnumerable Streaming New

For large result sets, stream results page-by-page without loading everything into memory:

await foreach (var page in _graphClient
    .QueryContent<ArticlePage>()
    .OrderBy(x => x.PublishDate, OrderDirection.Descending)
    .GetAsyncEnumerable<ArticlePage>(pageSize: 50))
{
    foreach (var item in page.Items)
    {
        // Process each item
    }
}

See the complete migration reference (Section 12) for S&N sorting/pagination equivalents.

8. Projections, Autocomplete & Locale

Field Projection

Control which fields are returned to reduce payload size and improve performance:

// Lambda-based (type-safe)
var result = await _graphClient
    .Query<Recipe>()
    .Fields<RecipeResult>(x => x.Name, x => x.Description)
    .GetAsync();

You can project to any class that has matching properties, as long as it does not implement IContentData:

public class RecipeResult
{
    public string Name { get; set; }
    public string Description { get; set; }
}

Autocomplete

Provide type-ahead suggestions based on indexed field values:

var result = await _graphClient
    .QueryContent<ArticlePage>()
    .Autocomplete(x => x.Title, "choc", limit: 5)
    .Fields<ArticleResult>(x => x.Title)
    .GetAsync();

Locale and Multi-Language

Control which language versions of content are returned:

// Single locale
.SetLocale("en")

// Multiple locales
.SetLocale("en", "sv")

// All locales
.SetLocale(QueryLocale.All)

If SetLocale() is not called, the SDK uses the default locale for the current thread.

var result = await _graphClient
    .QueryContent<ArticlePage>()
    .SetLocale("en", "sv")
    .SearchFor("chocolate")
    .Fields<ArticleResult>(x => x.Title, x => x.Summary)
    .GetAsync();

9. Content Variations, Auth & Caching

Content Variations New

Content Variations are a new concept in Optimizely Graph. Content Variations support scenarios like A/B testing and personalization where the same content exists in multiple variations.

// Include a specific variation plus the original content
.SetVariation(includeOriginal: true, "WinterCampaign")

// Include only the specific variation (exclude original)
.SetVariation(includeOriginal: false, "WinterCampaign")

// Include all variations via options builder
.SetVariation(options =>
{
    options.Include = VariationScope.All;
    options.IncludeOriginal = true;
})

WithDisplayFilters() - Context-Aware Access (Recommended)

WithDisplayFilters() is the recommended approach for page rendering scenarios. It automatically detects the current user from Thread.CurrentPrincipal and adjusts authentication accordingly:

No authenticated user: Uses SingleKey mode (public content only)
Authenticated user detected: Switches to BasicAuth with AsUser(), making user-restricted content visible
Always: Filters to published content only

// Recommended for page rendering
var result = await _graphClient
    .QueryContent<ArticlePage>()
    .WithDisplayFilters()
    .Where(x => x.Category == "News")
    .GetAsContentAsync();

Authentication Quick Reference

Method	Auth Mode	Restricted Content	Deleted/Expired	Best For
(default)	SingleKey	No	No	Public-facing pages
WithDisplayFilters()	Auto-detected	Yes (if user detected)	No (published only)	Page rendering
AsUser(principal)	SingleKey	Yes (for that user)	No	User-specific access
WithAuth(options)	Configurable	Yes (with BasicAuth)	Configurable	Full control

Caching

The SDK caches Graph responses by default (5-minute absolute expiration). You can disable caching or configure custom options per query:

// Disable caching
.WithoutCache()

// Custom cache options
.WithCacheOptions(options =>
{
    // Configure cache duration, etc.
})

10. Advanced Features

Decay Functions - Time-Based Relevance New

Decay functions adjust document scores based on how far a DateTime field is from an origin value. Documents closer to the origin score higher, which can be useful for boosting recent content.

using static Optimizely.Graph.Cms.Query.Linq.Request.GraphQueryFilter;

var result = await _graphClient
    .QueryContent<ArticlePage>()
    .Where(x => Decay(x.PublishDate, new DecayOptions
    {
        Origin = DateTime.UtcNow,
        Scale = 30,
        Rate = 0.5f
    }))
    .Fields<ArticleResult>(x => x.Title, x => x.PublishDate)
    .GetAsync();

Factor - Numeric Field Scoring New

Factor() uses a numeric field's value to influence relevance scores. Useful for boosting documents with higher popularity, stock, or rating:

using static Optimizely.Graph.Cms.Query.Linq.Request.GraphQueryFilter;

var factorOptions = new FactorOptions(2.0f, FactorModifier.Sqrt);
.Where(x => Factor(x.StockQuantity, factorOptions))

// Combine with other conditions
.Where(x => Factor(x.StockQuantity, factorOptions) && x.InStock)

Pinned Results New

Promote specific content items when search queries match configured phrases (similar to Search & Navigation's "Best Bets"):

var result = await _graphClient
    .QueryContent<ArticlePage>()
    .SearchFor("getting started")
    .WithPinned()
    .Fields<ArticleResult>(x => x.Title, x => x.Summary)
    .GetAsync();

// With explicit phrase and collection
.WithPinned(phrase: "getting started", collectionId: myCollectionId)

Named Queries New

Assign a name to your query for logging, tracing, and Graph analytics:

var result = await _graphClient
    .QueryContent<ArticlePage>()
    .SearchFor("chocolate")
    .WithName("SearchPage_MainQuery")
    .Fields<ArticleResult>(x => x.Title, x => x.Summary)
    .GetAsync();

Inspecting Generated GraphQL

Use .ToGraphQL() at any point in the chain to see the GraphQL that would be sent:

string graphql = _graphClient
    .QueryContent<ArticlePage>()
    .SearchFor("chocolate")
    .Where(x => x.Category == "Dessert")
    .OrderBy(x => x.PublishDate, OrderDirection.Descending)
    .Limit(10)
    .ToGraphQL();

_logger.LogDebug("Generated GraphQL: {Query}", graphql);

Tip

.ToGraphQL() is invaluable during development and debugging. Use it to verify your C# expressions produce the expected GraphQL, especially when building complex filter combinations.

11. Working with Results & Untyped Queries

IContentResult<T>

All queries return IContentResult<T>, which contains:

Property	Type	Description
Items	IEnumerable<T>	The result items
Total	int	Total matching items (when IncludeTotal() is used)
Cursor	string	Cursor for cursor-based pagination
Facets	Facet data	Aggregation results from Facet() calls
TrackUrls	Track URL data	URLs for search tracking
CorrelationId	string	Correlation ID for diagnostics

GetAsync() Variants

// Standard execution with projected fields
IContentResult<ArticleResult> result = await _graphClient
    .QueryContent<ArticlePage>()
    .Fields<ArticleResult>(x => x.Title, x => x.Author)
    .GetAsync();

// Project to a different type at execution time
IContentResult<JsonElement> result = await _graphClient
    .Query("Recipe")
    .Fields("Name", "Description")
    .GetAsync<JsonElement>();

Streaming with GetAsContentAsyncEnumerable New

For CMS content queries, stream results as fully resolved IContent objects:

await foreach (var content in _graphClient
    .QueryContent<ArticlePage>()
    .GetAsContentAsyncEnumerable<ArticlePage>())
{
    // content is IContent, fully resolved through the CMS content loader
}

Untyped / Dynamic Queries

When the content type isn't known at compile time, use the Query(string) entry point:

var result = await _graphClient
    .Query("Recipe")
    .SearchFor("Chocolate Cake")
    .Where("CookingTime", ComparisonOperator.LessThan, 30)
    .Fields("Name", "Description")
    .GetAsync<JsonElement>();

Generated GraphQL:

{
  Recipe(
    where: {
      cookingTime: { lt: 30 }
      _fulltext: { match: "Chocolate Cake" }
    }
  ) {
    items { Name  Description }
  }
}

12. Complete Migration Reference

This table maps every Search & Navigation API to its Graph SDK equivalent. Use it as a quick reference during migration.

Feature	Search & Navigation API	Graph SDK API	Notes
Entry point	client.Search<T>()	_graphClient.QueryContent<T>()	Graph SDK is injected via DI
Full-text search	.For("query")	.SearchFor("query")
All fields search	.InAllField()	.UsingFullText()
Field-targeted search	.InField(x => x.Title, 2.0)	.UsingField(x => x.Title, boost: 2)
Highlight	.WithHighlight(spec)	.UsingFullText(highlightTag: "<mark>")
Filter (equality)	.Filter(x => x.Category.Match("News"))	.Where(x => x.Category == "News")
Filter (comparison)	.Filter(x => x.Rating.GreaterThan(3))	.Where(x => x.Rating > 3)
Filter (range)	.Filter(x => x.Price.InRange(10, 50))	.Where(x => x.Price.InRange(10, 50))
Filter (contains)	.Filter(x => x.Title.Contains("text"))	.Where(x => x.Title.Contains("text"))
Filter (starts with)	.Filter(x => x.Title.Prefix("How"))	.Where(x => x.Title.StartsWith("How"))
Filter (ends with)	Not directly supported	.Where(x => x.Title.EndsWith("Guide"))
Filter (in collection)	.Filter(x => x.Tag.In(values))	.Where(x => x.Tag.In(values))
Filter (exists)	.Filter(x => x.Title.Exists())	.Where(x => x.Title.Exists())
Filter (wildcard)	*.Filter(x => x.Title.MatchWildcard("app"))**	.Where(x => x.Title.Like("app%"))	Different wildcard syntax
Compound filter (AND)	.Filter(x => ...).Filter(x => ...)	.Where(x => x.A == "a" && x.B == "b")
Compound filter (OR)	.Filter(x => x.A.Match("a") \| ...)	.Where(x => x.A == "a" \|\| x.B == "b")
Dynamic filters	Combine Filter objects manually	.BuildFilter<T>().And(...).Or(...)
Synonyms	.UsingSynonyms()	.Match("value", SynonymSlot.One)	Per-filter synonym support
String facets	.TermsFacetFor(x => x.Category)	.Facet(x => x.Category)
Date facets	.DateHistogramFacetFor(x => x.Date, interval)	.Facet(x => x.Date, unit: FacetDateTimeUnit.DAY)
Numeric range facets	.RangeFacetFor(x => x.Price, ranges)	.Facet(x => x.Price, ranges: buckets)
Boolean facets	Not available	.Facet(x => x.IsFeatured)	New in Graph SDK
Sort ascending	.OrderBy(x => x.Date)	.OrderBy(x => x.Date, OrderDirection.Ascending)
Sort descending	.OrderByDescending(x => x.Date)	.OrderBy(x => x.Date, OrderDirection.Descending)
Secondary sort	.ThenBy(x => x.Title)	.ThenBy(x => x.Title, OrderDirection.Ascending)
Sort by relevance	Not available	.OrderBy("_ranking", RankingMode.Relevance)	New in Graph SDK
Pagination (skip)	.Skip(20)	.Skip(20)
Pagination (take)	.Take(10)	.Limit(10)
Total count	Included by default	.IncludeTotal()	Opt-in for performance
Field projection	.Select(x => new { x.Title })	.Fields<T>(x => x.Title)
Autocomplete	Via Statistics API	.Autocomplete(x => x.Title, "prefix")	Built into query API
Best bets	Via Best Bets UI	.WithPinned()	Simplified API
Track search	.Track()	.Track()
Locale	.Language(lang)	.SetLocale("en")
Execute (sync)	.GetResult()	N/A	Graph SDK is async-only
Execute (async)	.GetResultAsync()	.GetAsync()
Streaming	Not available	.GetAsyncEnumerable<T>(pageSize)	New in Graph SDK
Single result	Not available	.GetSingleAsync()	New in Graph SDK
Auth (display filters)	Via display modes	.WithDisplayFilters()	Auto-detects user context

What's New (Graph SDK Only)

These features are available in the Graph SDK but did not exist in Search & Navigation:

Feature	API	Description
Content Variations	SetVariation()	Query A/B test and personalization variants
GraphQL Inspection	ToGraphQL()	View the generated GraphQL query string
Cursor-Based Pagination	Cursor in IContentResult<T>	Efficient deep pagination beyond skip/limit
IAsyncEnumerable Streaming	GetAsyncEnumerable<T>(pageSize)	Stream pages without loading all into memory
Like Filter	.Like("app%")	SQL-style wildcard patterns with % and _
Boolean Facets	.Facet(x => x.IsFeatured)	Aggregate results by true/false values
Named Queries	.WithName("name")	Tag queries for logging and Graph analytics
Cache Control	.WithoutCache()	Per-query cache configuration
Cross-Type FilterBuilder	.And<TSource, TOther>(expr)	Combine filters across different content types
Direct IContent Resolution	GetAsContentAsyncEnumerable<T>()	Resolve Graph results directly to IContent
Decay Functions	Where(x => Decay(field, options))	Time-based relevance scoring
Factor	Where(x => Factor(field, options))	Numeric field relevance scoring
Pinned Results	WithPinned(phrase, collectionId)	Promote content for specific search phrases
Opt-In Total Count	IncludeTotal()	Only calculate total when needed (perf opt)
GetSingleAsync	GetSingleAsync()	Return exactly one result or throw
ThenBy	.ThenBy(x => x.Field, direction)	Secondary sort criteria after OrderBy()
Ranking Mode	.OrderBy("_ranking", RankingMode.Relevance)	Sort by relevance, boost, or index order
WithDisplayFilters	.WithDisplayFilters()	Context-aware auth that auto-detects user

Looking Ahead

The Graph SDK already covers the vast majority of Search & Navigation query patterns. For most CMS content query scenarios (filtering, full-text search, faceting, sorting, pagination, autocomplete, and search tracking) you can migrate your existing code with straightforward API mapping.

Additional capabilities are being added with each release. The SDK is actively evolving based on partner feedback and real-world migration experiences. If you encounter a pattern from Search & Navigation that doesn't have a direct equivalent yet, the Optimizely team wants to hear about it.

Next Steps

Add the Optimizely.Graph.Cms.Query package to your CMS 13 project.
Register with services.AddGraphContentClient() in your startup.
Inject IGraphContentClient and start querying.
Use .ToGraphQL() to inspect generated queries as you learn.

Resources:

Key tip for your migration

Start with .ToGraphQL(). Write your Graph SDK queries, inspect the generated GraphQL, and compare it to what you expect. This feedback loop will build your confidence quickly and help you verify that your migrated queries produce the correct results.

This guide is based on the Optimizely.Graph.Cms.Query SDK for Optimizely CMS 13. API details reflect the current SDK version and may evolve in future releases.

AEO/GEO in a Legacy Optimizely CMS Project: A Practical Pattern for Google, ChatGPT, and Claude

Mon, 23 Mar 2026 00:00:00 GMT

A practical Optimizely CMS pattern for AEO/GEO on legacy sites: shared page metadata, Razor-rendered JSON-LD, crawler-aware robots.txt, and Scheduled Jobs for gradual enrichment.

Schema.org as Native CMS Properties

Fri, 20 Mar 2026 14:55:00 GMT

Learn how to implement Schema.org structured data as native Optimizely CMS properties. Move SEO from hardcoded templates to a validated, content-managed model

Integrating Searchspring with Optimizely – Part 1: Architecture & Setup

Fri, 20 Mar 2026 12:38:23 GMT

Integrating Searchspring with Optimizely – Part 1: Architecture & Setup

CMS 13 Preview 4 — Upgrading from Preview 3

Fri, 20 Mar 2026 12:08:15 GMT

This is the third post in a series where I use the Alloy template as a reference to walk through each CMS 13 preview. The first post covered upgrading from CMS 12 to Preview 2, and the second looked at the key changes in Preview 3. If you're following along, pick up where we left off.

Preview 4 is out. The package bump is easy enough, but there's an API change around how you resolve the start page that'll ripple through your code. Here's what to change and what's worth knowing about.

Step 1: Update Packages

Bump your package references from preview3 to preview4:

<PackageReference Include="EPiServer.CMS" Version="13.0.0-preview4" />
<PackageReference Include="EPiServer.CMS.UI.AspNetIdentity" Version="13.0.0-preview4" />
<PackageReference Include="Optimizely.Graph.Cms" Version="13.0.0-preview4" />

Known Issue: Database Schema Upgrade from Older CMS 12 Versions

If you're upgrading directly from an older CMS 12 version (e.g. 12.34.1 or earlier) to a CMS 13 preview and not from preview3 (which this article assumes), the database schema migration may fail with an error like:

Column names in each table must be unique. Column name 'Failed' in table 'dbo.tblNotificationMessage' is specified more than once.

This happens because certain columns were added in later CMS 12 releases, and the CMS 13 migration scripts don't check whether they already exist before trying to add them.

Workaround: First upgrade to the latest CMS 12 version so that your database schema is fully up to date, then upgrade from there to the CMS 13 preview. This ensures all intermediate schema changes are applied before the CMS 13 migration runs.

Step 2: Resolving the Start Page

In Preview 3, Alloy template resolved the start page by casting to Website and accessing RoutingEntryPoint. In Preview 4, the simplest approach is to use ContentReference.StartPage directly — no need to go through IApplicationResolver in most cases.

Before (Preview 3)

var website = _applicationResolver.GetByContext() as Website;
var startPageContentLink = website?.RoutingEntryPoint;

After (Preview 4)

var startPageContentLink = ContentReference.StartPage;

In the Alloy template this simplified things across several files by using ContentReference.StartPage
- PageViewContextFactory.cs — CreateLayoutModel
- ContentLocator.cs — GetContactPages
- PreviewController.cs — the Index action
- StartPageController.cs — the Index action
- Breadcrumbs.cshtml and Header.cshtml — same change

If you do need more control, IRoutableApplication with its EntryPoint property is still available as an alternative.

The SiteDefinition migration keeps getting refined. Issues with default application provisioning and hostname resolution between preview and view modes from earlier previews have been sorted out.

Step 3: DAM Integration (optional)

Preview 4 adds a new package for Optimizely DAM integration. Its important to call out that even though DAM is a fundamental piece of CMS 13 it is possible to run without it. CMS still can store assets in te traditional sense.

Similar to CMS 12 the DAM configuration is handled using options directly requiring an application to be created in CMP from which the credentials can be retrieved for configuration in CMS. You'll also need the SSO ID which can be found under Settings \ Organization \ General in CMP.

The DAM integration no longer talks to the CMP REST API directly. Instead it's built on External Sources, which means DAM assets need to be indexed into the Optimizely Graph instance connected to your CMS. So before wiring up the code below, make sure you have Optimizely Graph set up, then contact Optimizely Support to connect DAM to your Graph instance. The onboarding steps — selecting your DAM instance, activating asset types — follow the same process as CMS SaaS and are documented in the Onboard DAM to CMS guide. Updated documentation specific to CMS 13 will be available at release. Once that's done, Content Manager can be used to discover and pick DAM assets directly from the editing UI.

Add the package:

<PackageReference Include="EPiServer.Cms.DamIntegration.UI" Version="13.0.0-preview4" />

services.AddDamUI();

Add the DAM HTML helpers namespace to Views/_ViewImports.cshtml:

@using EPiServer.Cms.DamIntegration.UI.Helpers

This gives you access to helpers like RenderTagWithMetadata(...) for rendering DAM assets. Note that the epi-property tag helper you're already using comes from EPiServer.Cms.AspNetCore.TagHelpers, which should already be registered in your _ViewImports.cshtml via @addTagHelper.

Then configure your CMP credentials (note that these have defaults, included here for transparency) in appsettings.json:

"Optimizely": {
  "Cms": {
    "DamUI": {
      "Endpoint": "https://cmp.optimizely.com",
      "SsoId": "<your-sso-id>",
      "NavigationUrl": "https://cmp.optimizely.com/cloud/library"
    }
  },
  "Cmp": {
    "Client": {
      "TokenUrl": "https://accounts.cmp.optimizely.com/o/oauth2/v1/token",
      "ApiUrl": "https://api.cmp.optimizely.com/v3/",
      "ClientId": "<your-client-id>",
      "ClientSecret": "<your-client-secret>"
    }
  }
}

The DAM picker now also supports multi-select, which is a nice improvement for editors working with lots of media.

Migrating from CMS 12 DAM Integration

For the GA release of CMS 13, a standalone migration package will be available that converts the CMS 12-style DAM integration to the new one. This package will handle the migration of existing DAM asset references so that they work with the new EPiServer.Cms.DamIntegration.UI package.

The first version of the migration package will support:
- ContentReference properties
- IList<ContentReference> properties

Support for additional property types will be added in future releases.

Using DAM Assets in Your Content

To use DAM assets on a page, add a ContentReference property with the UIHint.Image hint:

using EPiServer.Web;
using System.ComponentModel.DataAnnotations;

public class DamExamplePage : StandardPage
{
    [Display(GroupName = Globals.GroupNames.Content)]
    [UIHint(UIHint.Image)]
    public virtual ContentReference Image { get; set; }
}

In the view, render it with the epi-property tag helper — same pattern as any other CMS property:

<img epi-property="@Model.CurrentPage.Image" />

Step 4: Audiences (optional)

Audiences are a separate package in CMS 13. If you were using services.AddVisitorGroups() in Preview 3, you'll need to add the new NuGet package and update your service registration.

Add the package:

<PackageReference Include="EPiServer.Cms.UI.VisitorGroups" Version="13.0.0-preview4" />

Then update your Startup.cs — the old AddVisitorGroups() call is replaced with two separate registrations:

using EPiServer.Cms.UI.VisitorGroups;
services.AddVisitorGroupsMvc().AddVisitorGroupsUI();

A few audience-related bugs have also been fixed: the policy-not-found error is gone, Geographic Location criteria works, and context menu positioning for personalized groups has been corrected.

What Else Is New in Preview 4

A few things worth knowing about beyond the upgrade steps:

Graph .NET SDK

There's a new .NET SDK for Optimizely Graph with a fluent API covering facets, caching, auth, tracking, and object-to-Graph field mapping. Extensibility points have also been added to ContentGraph.CMS so you can hook into the indexing pipeline.

Improved Migration from SiteDefinition

The migration from SiteDefinition to the Application Model has been improved. Creating in-process websites via the settings UI works again, and typed content types now show up correctly when picking the start page for an application.

For the full list of changes, check the official release notes.

The move to CMS 13: Upgrade Notes for Technical Teams

Fri, 20 Mar 2026 00:00:00 GMT

A technical walkthrough of CMS 13 preview3 and headless work: what is changing, where the risks are, and how an upgrade and what to expect

Customizing Product Data Sent to Optimizely Product Recommendations in Optimizely Commerce

Fri, 20 Mar 2026 00:00:00 GMT

A practical guide to customizing IEntryAttributeService in Optimizely Commerce so you can override product titles, add custom feed attributes, and keep safe fallbacks to the default behavior.