Blogs

Personalisation in CMS 13 when you go headless: variations in the CMS, decisions in Experimentation

Thu, 24 Sep 2026 13:48:00 GMT

Back in February I wrote about personalisation in CMS 13 using Audiences. Everything in that post still holds, with one condition I should have made louder: it only works when the CMS renders the page. The moment your front end is a separate application reading content from Optimizely Graph, Audiences stop doing anything.

This post covers why that is, and how I would approach personalisation on a headless (or hybrid) CMS 13 build instead. The content still lives in the CMS, but the decision about who sees which content moves to Optimizely's experimentation and personalisation products.

Why Audiences do not work on a headless build

Audiences (Visitor Groups, as they were) are evaluated inside the CMS process, on each request. When a content area renders, the CMS looks at the current visitor (their referrer, the pages they have viewed in this session, their geography and so on), checks each item's audience settings, and leaves out the items that do not match. The personalised HTML is the output of that render.

Audiences are evaluated when the CMS renders the content area, which is why they only apply to in-process sites.

On a headless build there is no render in the CMS. Content is published and synchronised into Optimizely Graph once, for everybody, and your Next.js (or other) front end queries Graph when a visitor arrives. Graph never sees the visitor, and the CMS is not in the request path at all, so there is nothing to evaluate the audience against.

Optimizely's own CMS 13 documentation is explicit about this:

"Audiences work only on traditional (in-process) sites, where CMS manages both content authoring and frontend rendering."
(source: Create audiences for personalization)

The CMS 13 technical Q&A adds that Visitor Groups and Audiences "are not indexed to Graph", and recommends "the new Variations support for content and Experimentation for personalization" for Graph-based delivery (source: CMS 13 technical webinar Q&A). The "View as audience" preview is also unavailable on decoupled front ends.

So if your build is headed MVC, carry on with Audiences; the February post still applies. If it is headless or hybrid, read on.

The new split: content in the CMS, the decision in Experimentation

The recommended model separates two jobs that Audiences used to do together.

The content. Editors author each version of a page in the CMS as a content variation. It gets drafted, reviewed, approved and published like any other content, and it is indexed to Graph.
The decision. An experimentation or personalisation engine decides which variation a given visitor should see, and the front end fetches that variation from Graph.

The two are joined by a single string: the variation name. If the engine says "WinterCampaign", the front end asks Graph for the "WinterCampaign" variation of the page. If that variation does not exist, it falls back to the original.

I think this is a better model than it first appears. Content stays in one place, under the CMS's workflow and version history, rather than being pasted into a testing tool's visual editor. The engine that decides is also the one that measures, so every personalised experience can be tested against the original.

Content variations in CMS 13

A content variation is a second (or third, or tenth) published version of the same content item, in the same language. Each variation has its own version history and publishing lifecycle, and only stores the properties you actually change (source: Create content variations in CMS 13).

Creating one from the editor:

Select the page in the content tree.
Choose Variations > Add variation.
Give it a name, for example WinterCampaign. It cannot start with a number or contain spaces.
Select Add variation. The variation opens in Visual Builder and appears in the Variations dropdown.
Make your changes, then Publish > Publish changes.

You can also copy a new variation from an existing one using Copy from, and if a variation wins, Copy changes to Original promotes it to become the new default.

Two things worth knowing before your editors start:

Name variations for what they are, and treat the name as a contract. The name is what the experimentation side will ask for, and it is case sensitive. Rename a variation in the CMS and the front end will quietly serve the original to everyone while the experiment keeps counting visitors.
Check which properties can vary on your version. At the time of writing, variations only vary localisable properties. Treat that as release-specific and re-check it on the version you ship.

Fetching a variation from Graph

By default, Graph queries only return original content, so existing queries are unaffected. To ask for a variation, add the variation argument and keep the original in the response as the fallback (source: Query content variations in Optimizely Graph):

query LandingPage($variation: [String!]) {
  _Content(
    where: { _metadata: { url: { default: { eq: "/winter-offers/" } } } }
    variation: { include: SOME, value: $variation, includeOriginal: true }
  ) {
    items {
      _metadata { key displayName variation }
      ... on LandingPage { Heading MainBody { html } }
    }
  }
}

const requested = items.find((i) => i._metadata?.variation === variationKey);
const original = items.find((i) => !i._metadata?.variation);
const page = requested ?? original;

That fallback is what makes the whole approach safe. If the engine is switched off, returns nothing, or asks for a variation that does not exist, the visitor gets the original page.

Route 1: Feature Experimentation (server-side, the native route)

This is the route Optimizely documents today, and the one I would reach for first on a headless build (source: Configure the Optimizely CMS (SaaS) integration; Piotr Nowak's Unlock Experimentation with Content Variations in CMS 13 walks through the same pattern for CMS 13 with both an MVC and a Next.js head).

In Feature Experimentation:

Create a flag, for example winter_landing_page.
Add variations whose keys match the CMS variation names exactly (WinterCampaign, SummerCampaign). The documented SaaS integration also adds a string variable carrying the name, which is a good idea because it lets you change the mapping without renaming the variation.
Add a rule.
- An A/B test rule splits traffic across the variations and measures them against a metric.
- A targeted delivery rule with an audience serves one variation to everyone who matches, for example visitors in the UK, logged-in members, or a segment you pass in as an attribute. This is where personalisation happens.

In the front end, decide on the server and fetch the matching variation:

import { createInstance, OptimizelyDecideOption } from '@optimizely/optimizely-sdk';

const optimizely = createInstance({
  sdkKey: process.env.OPTIMIZELY_FX_SDK_KEY!,
  datafileOptions: { autoUpdate: true, updateInterval: 60_000 },
});

export async function getVariationKey(visitorId: string, attributes: Record<string, unknown>) {
  await optimizely.onReady();
  const user = optimizely.createUserContext(visitorId, attributes);
  const decision = user?.decide('winter_landing_page', [OptimizelyDecideOption.INCLUDE_REASONS]);
  return decision?.enabled ? decision.variationKey : null;
}

A few things I would build in from the start:

A stable visitor id. Bucketing hashes on the user id, so anonymous visitors need a first-party cookie set in middleware, or they will flip between variations.
Keep the datafile fresh. Without autoUpdate, the JavaScript SDK fetches the datafile once, so rule changes in the dashboard do not reach a long-running server.
Caching. A page that varies by visitor cannot be served from one shared cache entry. Either mark decided responses as uncacheable, or cache per variation (the variation name makes a sensible cache key when the number of variations is small).
Attributes only come from you. Feature Experimentation audiences evaluate the attributes your code passes in. If you want to target on a CRM segment or a logged-in state, the front end has to supply it.

Because the decision happens on the server, there is no flicker and the personalised content is in the first HTML response.

Route 2: Web Experimentation and Personalization (client-side)

The other half of Optimizely's engine is Web Experimentation and its sibling, Optimizely Personalization. Personalization adds campaigns made of experiences, each targeted at an audience, and can use real-time segments from Optimizely Data Platform where you have it (source: Optimizely Personalization overview). Marketers own these audiences and campaigns in the Optimizely UI, which is often exactly what a marketing team wants.

The trap here is the visual editor. It makes it easy to change a heading or swap an image directly in the browser, and when you do that the personalised content lives in Web Experimentation, not in the CMS. It is unversioned by the CMS, invisible to editors, and it breaks the moment the page markup changes.

The better pattern keeps the content in the CMS and uses the campaign only to choose the variation:

Name each Web Experimentation variation or Personalization experience after the CMS variation it should show.
In the front end, read the visitor's active decisions from the snippet's state API and fetch the matching CMS variation from Graph.

function getCmsVariationName(): string | null {
  const state = (window as any).optimizely?.get?.('state');
  if (!state) return null;
  const active = state.getCampaignStates({ isActive: true });
  for (const campaign of Object.values<any>(active)) {
    const name = campaign.variation?.name;
    if (name && /^[A-Za-z][A-Za-z0-9]*$/.test(name)) return name;
  }
  return null;
}

getCampaignStates returns both experiments and personalisation campaigns (source: Get state). Check the returned shape against your own snippet version before relying on it.

This is a pattern rather than an out-of-the-box integration. Optimizely documents the Feature Experimentation route; I have not found a documented Web Experimentation equivalent, so treat this as something you build and own. The trade-offs are the usual client-side ones: the decision happens after the page loads, so either the personalised region is fetched late (reserve its space to avoid layout shift) or you hide it until the decision arrives. I would keep personalised regions out of the largest above-the-fold element for that reason.

Which route should you use?

	Feature Experimentation	Web Experimentation / Personalization
Where the decision happens	Your server or edge	The visitor's browser
Flicker and layout shift	None	Needs designing for
Who owns audiences	Developers pass attributes; audiences built in FX	Marketers, in the Optimizely UI, including ODP real-time segments
Content lives in	The CMS	The CMS, if you use the pattern above
Documented by Optimizely for CMS variations	Yes	Not yet; build it as a pattern

My default on a headless or hybrid CMS 13 build is Feature Experimentation for anything above the fold or on key journeys, with Personalization campaigns where marketers need to own and change audiences without a developer. Both can sit on the same content variations, because the only thing either needs from the CMS is the name.

What about headed sites?

Nothing changes. Audiences still work on in-process CMS 13 sites and remain the simplest option for rules-based personalisation. Content variations work there too, so a headed site can use the same Feature Experimentation pattern with the .NET SDK and IContentLoader when you want proper testing rather than show-and-hide rules.

Optimizely has said deeper integration between the CMS and Experimentation is on the roadmap, without a date. I will update this post if that changes the picture.

Optimizely Forms: 4.7.0 Too many concurrent connections

Thu, 24 Sep 2026 11:19:24 GMT

Optimizely Forms are eating your emails! How to make it stop!

Optimizely CMS 13.2: Cannot find an authentication provider for 'ActiveDirectoryManagedIdentity'

Wed, 23 Sep 2026 09:03:12 GMT

CMS 13.2 upgraded SqlClient to 7, and Managed Identity stopped working in Azure until I added one NuGet package.

Composition Over Inheritance: Why Your Content Contract Is Not a Base Class

Sat, 19 Sep 2026 08:44:58 GMT

Inside the structural conformance pattern in SaaS CMS — from server-side inheritance to pipeline governance.

A contract in Optimizely SaaS CMS is rarely what developers expect on day one.

Create a contract called Categorizable with Category and Tags properties, apply it to a content type, and open that type's property configuration. In conventional class-based inheritance, you would expect an inherited property to be an immutable field handed down from a parent class. Instead, the fields sit directly on the content type, with their own display names, help text, and local configurations.

Think of it like a job description rather than a base class. A job description specifies the qualifications a candidate must bring; it does not hand them those qualifications. The candidate arrives already qualified, and the job description simply verifies the match.

Contracts operate the same way. They do not supply properties to your content types; your content types declare their own properties, and the contract validates that they conform to the required shape.

Two quick checks confirm this:

The official documentation notes that properties must exist on the content type before applying the contract.
The content type REST payload keeps isContract, contracts, and properties as completely separate fields.

That single distinction — validator, not supplier — changes how you design your content model, how your team coordinates deployments, and what your API can deliver.

The compiler was your guardian

Historically, enterprise content modeling in server-side content management systems followed a class-based inheritance pattern:

[ContentType(DisplayName = "Article Page")]
public class ArticlePage : SitePageData
{
    public virtual string Category { get; set; }

    public virtual IList<string> Tags { get; set; }
}

This model had genuine elegance. You declared a hierarchy, and the platform did the rest. At application startup, the framework walked your class tree through reflection, synchronised it against the database, and refused to proceed if something did not line up. Change a property type where data already existed and you were told immediately — before a single editor saw a broken field.

The enforcement was automatic, unconditional, and happened before content existed. You did not have to remember to check. A compiler and a startup sync did the remembering for you.

The trade-offs of deep inheritance hierarchies are well known: fragile base classes cause parent changes to ripple unpredictably into descendants, single-inheritance limits composition across multiple domains, and deep template trees become difficult to reason about and re-index.

Yet class inheritance solved a genuine governance problem, and it solved it automatically before content existed. That is the property worth remembering as we examine what replaced it.

There was one condition attached to all of it: it worked because a single runtime owned the entire model. That condition is the thing that changed.

Two ways to satisfy GraphQL, and where each one puts the inheritance

Something shifted underneath the model, and it is worth separating two layers that often get discussed as one.

The runtime left

Optimizely SaaS CMS operates as a multi-tenant cloud architecture. Rather than executing custom server-side binaries or reflection passes during application startup, content types are declared as structured JSON schemas over a REST API. Declarative schemas replace compiled application code.

Remove the server-side runtime and you remove the mechanism that made compiled class inheritance enforceable.

GraphQL has no inheritance, and that constrains every platform equally

The GraphQL specification has no concept of class inheritance. It offers exactly two tools for polymorphism: interface and union. A GraphQL interface works structurally — every concrete type implementing an interface must itself declare every field that interface defines. The interface does not hand fields down. It describes a shape and checks that implementers match it.

This is a property of the specification, not a platform decision. Any content platform delivering through GraphQL has to project its content model into structural interfaces at the API boundary, because that is the only shape the query layer can execute.

But that constraint applies to delivery, not to authoring

Here is the part worth being precise about, because it is easy to over-generalise.

The GraphQL constraint governs what the delivery schema looks like. It says nothing about how a platform models content internally. That leaves two coherent designs, and the wider content management category contains working examples of both.

Design one: keep inheritance in the authoring model, project it at the edge. The CMS retains a template or class hierarchy. Fields are declared once on a parent and cascade to descendants. A pipeline then flattens that hierarchy into structural GraphQL interfaces when content is indexed for delivery. Authors and developers get single-point field definition and automatic propagation. The cost is a translation step between two different schema representations, and inheritance coupling in the authoring model.

Design two: model structurally from the start. Content types are flat. Each declares its own properties. Shared shapes are expressed as contracts that validate conformance rather than supply fields. The authoring schema and the delivery schema are the same shape, so nothing needs translating. The cost is that shared definitions repeat across implementers, and propagation becomes an explicit, coordinated act rather than an automatic one.

Neither is the modern one and neither is the dated one. They optimise for different things — the first for authoring convenience and single-point definition, the second for schema alignment and reach across sources.

Structural contracts in SaaS CMS

Optimizely SaaS CMS operates on this structural model. Content types declare their own properties directly, and contracts validate their conformance for Optimizely Graph.

Because the content type schema and the delivery schema share the same structural shape, there is no translation layer between CMS models and GraphQL interfaces. A direct consequence of this architectural alignment is that the exact same contract can govern content across boundaries — whether it originates natively in the CMS or is connected from an external source.

A contract is not a base class. Here is what it actually is.

A contract is a shape validator and a Graph schema generator. It does not supply properties to your content type. Your content type supplies its own, and the contract validates that they match.

Side by side, the two models look like this:

CLASS INHERITANCE (Runtime-Enforced Base Class)
Vertical hierarchy: Subclasses descend from a rigid base class

       +------------------------+
       |      SitePageData      |  <-- Base class defines Category, Tags
       +-----------+------------+
                   |  Inherits (Framework reflection at startup)
         +---------+---------+
         |                   |
         v                   v
  +--------------+    +--------------+
  | ArticlePage  |    |  EventPage   |  <-- Bound to single application runtime
  |  + Excerpt   |    |  + StartDate |      Cannot span across independent systems
  +--------------+    +--------------+


STRUCTURAL COMPOSITION (CMS SaaS / Optimizely Graph)
Horizontal conformance: Independent traits validate flat, multi-source entities

  +--------------------------------------------------------------+
  |                    Categorizable Contract                    |
  |              (Defines required shape in Graph)               |
  +---------------+-------------------------------+--------------+
                  |                               |
        Validates | Shape               Validates | Shape
                  v                               v
  +------------------------------+ +------------------------------+
  |         ArticlePage          | |         ExternalAsset        |
  |                              | |                              |
  | * Category (Editorial Topic) | | * Category (Brand Theme)     |
  | * Tags                       | | * Tags                       |
  | * Excerpt                    | | * AssetUrl                   |
  +------------------------------+ +------------------------------+
        [Native CMS Content]             [External Connected Source]

In this model, content types remain flat entities. Contracts act as shape validators rather than parents, and conformance can span across native CMS pages and external connected assets alike.

In Optimizely Graph, each contract registers as a native GraphQL interface. Implementing content types satisfy that interface by declaring the required fields on their own schema, while remaining completely independent entities.

What the structural model genuinely unlocks

It would be a shame to treat this purely as a constraint to work around. The structural model enables several things that classical inheritance could not, and a few of them are genuinely significant.

One query across many types

Because the contract becomes a real GraphQL interface, you can query across every implementing type in a single request, and reach for type-specific fields where you need them:

query {
  Categorizable(where: { Category: { eq: "Meetup" } }) {
    items {
      _itemMetadata {
        key
        displayName
      }
      Category
      Tags
      ... on ArticlePage {
        Excerpt
      }
    }
  }
}

No merging results from three separate queries. No client-side reconciliation.

Components that do not care what page they are on

A front-end component can bind to the contract rather than to any concrete type. A category pill, a tag list, a card renderer — each written once against Categorizable, working unchanged when a fourth and fifth content type start implementing it later.

Horizontal growth

New content types do not disturb existing ones. There is no parent to modify, so there is no cascade to manage. The model grows sideways rather than downwards.

Composing several traits at once

Single-inheritance models force a choice. A component that needs headline behaviour, section placement rules, and tab display options has one parent slot to work with, so teams either build a deep chain where each layer adds a concern, or pick one parent and re-declare the rest by hand.

Structural conformance removes the choice. A content type lists every contract it satisfies, and the platform validates each independently. Nothing competes for a parent slot, so there is no diamond problem to resolve and no hierarchy depth to reason about — the same component simply appears under several contracts at once.

Contracts that span sources — the part worth pausing on

This is one of the most compelling capabilities of the structural model, yet one of the least discussed.

Class inheritance cannot cross a source boundary. A base class defined within one application cannot be directly inherited by an external DAM API response or a commerce catalog item, because independent systems share no common runtime or compiler. Whatever elegance an inheritance hierarchy provides, it stops at the boundary of that specific application runtime.

Structural conformance has no such limit. Conformance only asks about shape — it is indifferent to where the data originated. Optimizely Graph registers global contracts, prefixed with an underscore, that serve as parent types across multiple sources rather than CMS content alone.

The practical consequence is compelling: an externally sourced asset and a native CMS item can align to the same contract shape, making unified polymorphic querying possible across system boundaries. For teams working with an external DAM, a PIM, or a commerce catalog alongside CMS content, that opens up a class of queries that an inheritance model could rarely express without custom translation or synchronization pipelines.

Editorial context without API fragmentation

Two teams sharing a field rarely want to label it identically. One needs Editorial Topic grouped with metadata; the other needs Event Series grouped with scheduling. In a structural model, presentation and structure are separable: editorial labels adapt to each team's context while the underlying GraphQL interface remains a single, stable contract.

What the platform locks and what it leaves to you

Because properties live directly on each content type, teams naturally ask: what is genuinely bound by the contract, and what can be customized for content authors?

When you inspect a contract-implemented property in the CMS editing interface or examine the CLI validation rules, the boundary splits cleanly into two distinct buckets:

Bucket 1: Field identity (Bound by contract)

These are the structural invariants that define what the property fundamentally is in Optimizely Graph. In the CMS editing interface, these settings appear disabled with a grey background. If you attempt to modify them on an implementing type via code or the CLI push command, the platform halts with a validation error:

Property key / name: The programmatic identifier (e.g., category, heading).
Underlying data type: The scalar or complex type definition (e.g., Choice, String, ContentReference).
Format: The technical display and storage format (e.g., Drop-down list for a choice property).
Property indexing type: How Optimizely Graph indexes the field for search and filtering (e.g., Default, Searchable).
Mandatory entry (Value must be entered): Whether the field is strictly required across all content instances.

The platform locks these down because Optimizely Graph generates a single, unified GraphQL interface for the contract. The API must guarantee that every implementing content type resolves the exact same scalar or object shape under that property name.

Bucket 2: Authoring experience and workflow configuration (Tailored in the CMS UI)

Everything outside that locked identity is an authoring-time configuration decision. These settings remain fully editable on the implementing content type, allowing teams to tune the editorial experience for each specific content model without altering the GraphQL schema:

Dropdown choices and options: A choice property defined on a contract establishes that a scalar string is returned. Individual content types can freely define, add, or refine the specific list of selectable choices (e.g., a blog article offering editorial topics while an event page offers conference tracks). In Optimizely Graph, the value is stored and queried as a valid scalar string regardless of which option the editor selects.
Localization (Unique value per language): Whether a field must be translated independently per language branch or shared across all locales can be toggled per content type based on editorial requirements.
Allowed and restricted reference types: Content reference constraints can be tuned to fit the exact nesting rules of that specific component or page.
Input limits: Character bounds (maxLength, minLength) and array counts (minItems, maxItems) that guide editorial entry.
Default values: Whether the field starts empty, inherits a default, or pre-populates a custom value.
Editorial presentation: The display name, explanatory help text, property group tab, and display order seen by editors in the CMS editing view.

Why this division matters

Separating field identity from authoring configuration solves a classic enterprise dilemma: it provides API uniformity without forcing editorial rigidity.

Optimizely Graph receives a consistent, queryable property across all types implementing the contract. At the same time, content authors receive domain-specific labels, tailored dropdown choices, and relevant help text that match their daily workflow. The contract secures the data architecture; the CMS UI empowers the authoring experience.

The trade-offs worth knowing before you go further

No pattern is free, and this one has trade-offs worth naming clearly.

Definitions repeat. Each implementing type declares its own properties. "Composition" here does not mean one definition consumed in many places — it means many declarations validated against one shape. If that feels like duplication, that is a fair reading. It is the price of a model that maps one-to-one onto a GraphQL interface.

Contract changes fan out. Add a property to a contract and every implementing type needs updating. The platform validates conformance; it does not perform the change on your behalf. For a contract with fifteen implementers, that is fifteen declarations to keep aligned.

Branch and release coordination becomes yours. In teams with multiple developers working across separate feature branches, contracts represent a shared dependency. The CLI is vigilant here: when a contract change creates an incompatibility with existing content types, the push command halts with a breaking change warning and prompts whether you want to proceed with the --force flag. But in an automated CI/CD pipeline — and in any higher environment (QA, Staging, or Production) where --force is rightly restricted to protect valuable content — an uncoordinated push simply stops the deployment. If Developer A updates a contract for one type, but other implementers across active branches have not yet caught up, the pipeline halts until the entire contract family is reconciled.

Granularity is entirely your call. One broad contract with twenty properties forces implementers to carry fields they do not need. Fifteen micro-contracts produce query fatigue and cognitive overhead. There is no platform guidance that decides this for you, and no automated signal that you have drawn the line badly. Modelling around functional capabilities — routable, categorizable, SEO-trackable — provides a proven heuristic to keep contracts cohesive and reusable.

Inheritance instincts assume automatic propagation. Because contracts standardize shared fields, it is natural to assume that modifying a contract will automatically propagate changes down to all implementing types. Recognizing that contracts are validation interfaces rather than base classes is an essential mental model to establish across the team early.

Structure can be validated; intent cannot. A property can match a contract's shape perfectly and still drift semantically — same type, same key, quietly different meaning across two implementers. No schema check catches that. It is a modelling discipline question, and it stays a human one.

The governance the platform will not build for you

A clear conceptual framing helps teams navigate this transition:

The compiler did not disappear. It moved.

Previously, a server-side compiler and startup routine verified model integrity. In a decoupled SaaS architecture, that responsibility naturally shifts to your deployment pipeline and engineering conventions. That is not a limitation — it is the natural consequence of moving to a declarative, multi-tenant platform. But it does mean the discipline must be deliberate rather than automatic.

Three practices keep this model robust at scale.

Shared definitions in code

Rather than hand-maintaining the same property definition across implementers, define the shared shape once and compose it:

export const categorizable = {
  Category: { type: 'string' },
  Tags: { type: 'array', items: { type: 'string' } },
} as const;

import { categorizable } from '../contracts/categorizable';

export const articlePage = {
  key: 'ArticlePage',
  baseType: '_page',
  contracts: ['Categorizable'],
  properties: {
    ...categorizable,
    Excerpt: { type: 'string' },
  },
};

The structural definition has one home. Per-type presentation settings layer on top of the spread. If you want to go further, a TypeScript helper that accepts only presentation keys as overrides will let the compiler block structural divergence before it reaches a push — which is, pleasingly, the compiler coming back to help in a slightly different form.

A contract change protocol

Treat a contract change as a coordinated unit of work rather than an individual edit: identify every implementing type, update them together, deploy them together, then verify the generated schema reflects what you expected. Writing this down as a short runbook takes twenty minutes and prevents branches or environments from falling out of sync.

Contract ownership

Decide who can create a contract and what justifies one. A simple rule that has served well: do not create a contract until a genuine second implementer exists. Shared shapes should emerge from observed reuse rather than from anticipated reuse.

Where schema governance moves next

With the release of the Model Context Protocol (MCP) server for CMS SaaS, AI tooling can now access live CMS schema context directly. Rather than treating AI as a content generation tool alone, this capability opens up a natural extension for architectural governance.

The decisions that remain challenging in a structural model are not structural invariants — the platform validates those on push. They are architectural judgements: should a capability be one contract or two? Has a contract update been coordinated across all implementers? Has a field drifted in meaning while remaining structurally valid?

These are pattern-matching evaluations against an established schema framework. An AI assistant with live schema context can serve as an effective decision accelerator: surfacing implementers across active branches, identifying uncoordinated contract updates, or evaluating whether a proposed property belongs on a shared contract or directly on a specific content type.

The objective here is decision acceleration, not decision delegation. Content modeling choices fundamentally require human domain understanding. Yet providing architects and development teams with an automated, context-aware first pass on schema alignment is a compelling architectural evolution.

The compiler was once a server-side runtime, then it became a CI/CD pipeline, and it is increasingly becoming an intelligent assistant.

Closing thought

The transition from base classes to contracts can initially feel like a loss — moving away from something a server-side runtime previously handled automatically.

Yet in a composable architecture — where content flows across a CMS, an external DAM, a commerce catalog, and connected sources simultaneously — structural conformance addresses a reality that a single application runtime was never designed to span.

The enforcement did not vanish when the server-side runtime left; it relocated to your deployment pipeline, your code conventions, and your team's shared understanding of the model. Designing for that relocation from day one is what turns a potential governance challenge into a durable, scalable architecture.

This article is grounded in the Optimizely Graph schema specifications, official CMS SaaS documentation, and real-world CLI deployment workflows.

Documentation references: Create contracts, Define content types, Create content type API reference, Content base types, CMS (SaaS) MCP server overview.

Optimizely Opti ID Integration: Why the API Key Was Missing from the DXP Management Portal

Fri, 18 Sep 2026 16:32:00 GMT

While working on an Optimizely CMS 12 Opti ID integration recently, we ran into an issue that initially appeared to be related to SSO authentication...

The post Optimizely Opti ID Integration: Why the API Key Was Missing from the DXP Management Portal appeared first on Madhu Anbalagan's Blog.

Extending a Contract: What You Can Override

Fri, 18 Sep 2026 09:41:29 GMT

Contracts share fields across content types — but not every field setting can be overridden. Push the same contract onto several components, and CMS will accept some changes and reject others. This post lists what can change, and what will fail the push.

Building a Blazor Server UI Inside the Optimizely CMS 13 Admin Shell

Thu, 17 Sep 2026 08:00:00 GMT

What I learned shipping a Blazor Server UI inside Optimizely CMS 13 — Razor components in a NuGet package, the Blazor hub next to MapContent(), prerendering.

Giving Optimizely 13 Content Types Meaningful Icons and Thumbnails

Wed, 16 Sep 2026 13:55:46 GMT

When working with an Optimizely CMS solution that has evolved over time, it is common to end up with many content types. As the number grows, the default editor UI can become harder to scan. Editors may need to spend more time working out what a content type represents before they can create, find or […]

force-dynamic vs connection() for Optimizely Graph

Wed, 16 Sep 2026 13:01:39 GMT

If you have built an Optimizely CMS SDK site, you already know getContentByPath on a catch-all. This post is about the part that file never says out loud: when that Graph call runs. We will unpack force-dynamic versus await connection(), and how each one changes prerendering for Optimizely Graph.

I built a thing - nOSC & nOCP - an experiment?

Tue, 15 Sep 2026 14:00:55 GMT

I don't think I'm always that convensional. And that's where this starts...

So firstly, I was lucky enough to see OCP UI extensions for Optimizey SaaS a few months back - these are apps that extend the capabilities of the SaaS CMS platform using typescript apps built and hosted on the Optimizely Connect Platform (OCP). And I was even more lucky to get to be involved in the Beta program, getting first hand experience of what the platform can do. And well, let's just say that firstly I was impressed and then secondly I got carried away.

Content Transfer got migrated. A client we're working with uses Frontify as a DAM, so a picker got spun out of the OCP UI boiler plate - complete with it's own new search functionality and image manipulation features. This was partnered with a Focal Point Editor that allows CMS users to tell their websites' Head where the focus of the image should be. Then I used the Webhook mechanisms within OCP to create a whole CSP management suite with reporting. And then I built a full redirection management system, complete with solves for moved pages in the CMS and handling 404s.

As I say, I got carried away.

Then two things made me stop pretty much dead in my tracks - first, it turns out that actually, OCP isn't the most performant platform on the planet, and "Please Try Again" when trying to open apps is very infuriating, and then secondly, having considered OCP to be free when not using the database, it turned out that this wasn't the case, and subsequently that the pricing model for hosting OCP UI apps hadn't (hasn't?) been decided - so I'd been solving my real world problems in OCP, and it could well turn out that the cost of hosting them would make running a bunch of them significantly less than attractive - and they might keep returning "Please try again" on content queries.

Which is when my sneaky, non-conventional brain kicked in - I thought what if we could...

Host apps freely?
Be assured of their performance?
Secure apps on our own terms?
Upload them in seconds, not minutes?
Have apps share information between panes and be able to actually effect change in the CMS, and not be restricted to Graph and the API for Optimizely content?

So, I built it.

"not Optimizely's SaaS Companion" - nOSC. It rolls off the tongue.

It's a Chrome extension that (amongst other things*) acts as a harness for nOCP apps - what are nOCP apps? Definitely not OCP apps. But yes, they're typescript apps (or not), that can be hosted anywhere you want (my favourite free hosting choice is Lambda on AWS); there is a security contract that must be observed, including a token to ensure you can't just sideload other peoples nOCP apps into your nOSC harness, but ultimately you can build an app in whatever language or framework you like, so long as it conforms to "the contract" and token exchange rules.

nOSC works by injecting into your SaaS CMS (sidebar and fullscreen), but unlike the Optimizely OCP apps, because of the Chrome app proxy, there is two way communication between CMS and app - AND - access to the numeric page ID of whatever content you're looking at in the CMS, which means that in building nOCP apps you can actually control the top level page and use the page ID to link directly to editable content.

Here are 4 docked oCP apps, and 1 docked nOCP app - can you tell the difference?

But more than that - you can also push content into the CMS! As well as porting over a few of the OCP UI apps that I've built to be nOCP apps, I've also built a Category Explorer around the new SaaS Taxonomy implementation - an implementation that sees you guessing what categories might be called with some kind of predictive search interface. I did not like that so nOSC and nOCP to the rescue - Graph allows me to list categories, my Chrome app allows me to push selected categories into the Category field of the CMS content item.

You can see a selection of my nOCP apps at https://github.com/mattpallatt/nOCP-apps - along with more information on that security contract I mentioned.

They're configured both on server for connections into secure endpoints (once), and then in browser to pull the app into the harness (everyone who wants the app).

Excecpt of course, it would be really annoying trying to make sure that your entire SaaS CMS team have the same set of tools, right? So there's a import/export feature, and more importantly a "Load from Global configuration" in nOSC - set your enviroments, apps and other configs up once, export them as an encrypted configuration file and save it somewhere that the internet can see, then your entire teams browsers can automatically download and configure the app when their Chrome/Edge browser starts - apps automatically synced with everyone having access to the same tools with no fuss.

Right, so back to that asterisk up there. It's not _just_ about loading apps - one of my pet peeves with SaaS is not being able to allow CMS users to use custom styles in TinyMCE, so nOSC aims to handle that too.

On an enviroment by environment, text property type configuration (minimal, standard, enhanced) basis, you can add new styling options that are either applied as inline styles, or by dropping class names onto selected text. It's not quite "in the dropdown", but it's a meaningful step in the right direction IMO.

That's nOSC.

I would very much like to know what people think of this - I've said it's an experiment, and maybe OCP apps come out in October and they are free to host, and they bump up the performance, and releasing to hosting takes less than 5 minutes, and you don't have to worry about timeouts - but, if all that doesn't happen, then does this "experiment" become something that you and clients could use? "No, you crazy person" is a perfectly reasonable response.

A day in the life of an Optimizely OMVP: OptiA11y: accessibility help for Optimizely editors that refuses to lie to them

Tue, 15 Sep 2026 10:42:54 GMT

Most accessibility tooling in the CMS space has the same shape. A crawler walks your published site, renders each page, runs axe-core over the DOM, and hands back a dashboard with a number on it. That number goes into a slide deck. Everybody feels better.

There are two problems with this.

The first is that a crawler sees a page, and an editor edits a property. When the report says "image missing alt text on /products/kayaks", the editor still has to work out which of the four content blocks on that page owns the image, open the right one, and find the right field. The tool found the problem in the artefact; the human has to find it in the source.

The second problem is worse. Automated checks can only detect a fraction of WCAG failures, and the checks that matter most to editors, is this alt text actually describing the image, does this link text make sense out of context, is this paragraph readable, are exactly the ones a machine cannot be certain about. Tools resolve that uncertainty in one of two ways: they stay silent (useless), or they assert a pass/fail verdict they have no business asserting (dangerous). A green score on a page full of alt="IMG_04213.jpg" is not neutral. It is actively misleading, and somebody will eventually put it in front of a regulator.

OptiA11y is my attempt at the third option: an Optimizely add-on that analyses content at the property level, tells editors precisely where a problem lives, and is architecturally incapable of claiming certainty it doesn't have.

The Confidence invariant

Everything else in the codebase is downstream of one design decision, so let's start there.

Every finding OptiA11y produces carries a Confidence:

public enum Confidence
{
    Pass,

    /// <summary>
    /// A heuristic judgement flagged something worth an editor's attention, but it is not
    /// a certain violation. This is the default for anything involving natural-language quality.
    /// </summary>
    NeedsReview,

    /// <summary>A deterministic, unambiguous violation of the success criterion.</summary>
    Fail
}

The rule is simple and absolute: a rule whose judgement depends on natural-language quality or editorial intent must never emit Fail. Fail is reserved for deterministic structural facts, a missing alt attribute, a skipped heading level, a contrast ratio mathematically below 4.5:1, an <iframe> with no title. Everything else, whether alt text is good, whether link text is descriptive, whether that manually bulleted paragraph is really a list, is NeedsReview.

Severity is a completely separate axis. Severity is impact; confidence is certainty. A NeedsReview finding can be Critical, and a Fail can be Info. Conflating the two is how you end up with a score that means nothing.

You can see both axes in one rule. Here is the alt-text rule, interesting precisely because it straddles the line:

private Finding? EvaluateImage(ImageFragment image)
{
    // Attribute entirely absent is a deterministic, unambiguous violation.
    if (image.AltText is null)
    {
        return Fail(image, "This image has no alt attribute at all. Add one, or mark it decorative if it conveys no information.");
    }

    // An empty alt is a valid, deliberate way to mark an image as decorative — but only
    // when the surrounding context supports that. We cannot be certain, so this is a review.
    if (image.AltText.Length == 0)
    {
        return image.IsDecorativeCandidate
            ? null
            : NeedsReview(image, "This image has empty alt text but doesn't look decorative. Confirm it truly conveys no information, or add a description.");
    }

    var altText = image.AltText.Trim();

    if (FilenamePattern.IsMatch(altText))
    {
        return NeedsReview(image, $"The alt text \"{image.AltText}\" looks like a filename rather than a description. Consider describing what the image shows.");
    }

    // ... redundant "image of" prefixes, excessive length — all NeedsReview
}

A missing alt is a fact. alt="IMG_04213.jpg" is a very strong hint, and still only a hint, there is a vanishingly small world in which that filename is the correct description. So the tool says so, in those words, and lets a human decide.

A design principle only counts if something enforces it. Here that something is a test file called HeuristicRulesNeverFailTests, which feeds every heuristic rule inputs designed to trip its judgement branches and asserts nothing comes back as a Fail:

[Fact]
public void ReadingLevelRule_NeverReportsFail()
{
    var rule = new ReadingLevelRule();
    const string difficultPassage =
        "Notwithstanding the aforementioned considerations, the organizational infrastructure " +
        "necessitates a comprehensive reevaluation of preexisting methodological frameworks ...";

    var findings = rule.Evaluate(new AuditDocument("content-1",
        new ContentFragment[] { new TextFragment(TestLocations.OnMainBody(0), difficultPassage, null) })).ToList();

    Assert.NotEmpty(findings);
    Assert.DoesNotContain(findings, f => f.Confidence == Confidence.Fail);
}

The Assert.NotEmpty matters as much as the DoesNotContain. It stops a future refactor from satisfying the invariant by accidentally making the rule silent.

The file also documents the deliberate exceptions, which is the part I'd encourage you to steal if you take nothing else from this post. HeadingStructureRule may fail, a skip from H1 to H3 is a structural fact, but its missing-H1 check is a judgement call, because in a CMS the H1 very often comes from the page template rather than the property being audited. So that rule gets two tests: one asserting the structural branch does fail, and one isolating the heuristic branch and asserting it doesn't. The exceptions are as tested as the rule.

ColorContrastRule has the same shape. Contrast is arithmetic, so it fails, unless the background came from rendered CSS and turned out to be an image or a gradient:

if (fragment.BackgroundIsImage)
{
    yield return new Finding(..., Confidence.NeedsReview, fragment.Location,
        $"Text \"{fragment.SampleText}\" sits over an image or gradient background rather than a flat color. " +
        $"Its computed contrast ratio ({fragment.ContrastRatio:F2}:1) isn't reliable - check contrast manually " +
        "against the busiest part of the image behind it.");
    continue;
}

The sampled colour there is whatever solid colour happens to sit behind the image, not what a user actually sees. The arithmetic is still perfectly valid arithmetic over the wrong input, and a rule that can't tell the difference will confidently fail text that is fine, or pass text that isn't. Downgrading to NeedsReview is the honest answer.

Ports and adapters, because the CMS is the least interesting part

The data flow for every audit is one line:

host content source → adapter → AuditDocument (ContentFragment[]) → RuleEngine → Finding[]

OptiA11y.Core holds the engine, the model, and all 36 rules. Its only dependency is HtmlAgilityPack. It has no Optimizely/EPiServer reference, and that isn't tidiness for its own sake, it's what makes the entire rule set unit-testable with no CMS present, no host, no database, and no initialization pipeline. The core test project references Core alone and runs in seconds. That's the difference between a rule set people extend and one they're afraid to touch.

Rules never see HTML, a DOM, or a CMS API. They see typed fragments:

public sealed class AuditDocument
{
    public string ContentReference { get; }
    public IReadOnlyList<ContentFragment> Fragments { get; }

    public IEnumerable<T> Get<T>() where T : ContentFragment => Fragments.OfType<T>();
}

…and a rule is therefore about as small as a rule can be:

public interface IContentRule
{
    string RuleId { get; }            // "alt-text-quality"
    string SuccessCriterion { get; }  // "1.1.1"
    WcagLevel Level { get; }

    IEnumerable<Finding> Evaluate(AuditDocument document);
}

One contract is worth calling out from the XML doc on Evaluate: rules must not throw for content that is merely unusual. Editors produce genuinely strange markup, pasted from Word, half-migrated, hand-edited in a source view at 5pm on a Friday. An unexpected shape means "nothing to flag", never an exception. An audit that dies on one weird table is worth less than one that quietly skips it.

Every fragment carries a SourceLocation, and this is what solves the "which block was it in?" problem from the top of this post:

public sealed record SourceLocation(
    string ContentReference,
    string PropertyName,
    IReadOnlyList<string> BlockPath,   // ["MainContentArea/Block:abc123", "NestedArea/Block:def456"]
    int Ordinal);

Content reference, property name, the full path of nested blocks leading to the fragment, and an ordinal to disambiguate the third image in a rich-text property from the first. That's enough to reconstruct an editor URL, but Core deliberately doesn't reconstruct one. URL shapes differ between PaaS edit views and SaaS deep links, so Core exposes IEditorLinkResolver as a port and leaves it unimplemented. The payload lives in the model; the resolution lives in the host.

RuleEngine is then almost trivially boring, which is the point:

return findings
    .OrderBy(f => f.Location.ContentReference, StringComparer.Ordinal)
    .ThenBy(f => f.Location.PropertyName, StringComparer.Ordinal)
    .ThenBy(f => f.Location.ToPathString(), StringComparer.Ordinal)
    .ThenBy(f => f.Location.Ordinal)
    .ThenBy(f => f.RuleId, StringComparer.Ordinal)
    .ToList();

Sorting by location rather than rule order means results are stable across runs regardless of how DI happened to enumerate the rule set, which matters the moment you start diffing audit output between two versions of a page.

One parser, or the guarantee evaporates

HtmlFragmentParser (~900 lines, in Core/Parsing) is the single HTML→ fragment entry point. PaaS content, SaaS content and rendered-style enrichment all funnel through it. That's what makes rule behaviour identical regardless of where content came from, and there's a test standing over it:

[Fact]
public async Task PaasAndSaasAdapters_ProduceEquivalentFragmentCounts_ForEquivalentInput()
{
    // same HTML, one via PaasContentAdapter, one via SaasContentAdapter
    Assert.Equal(paasDocument!.Get<HeadingFragment>().Count(), saasDocument!.Get<HeadingFragment>().Count());
    Assert.Equal(paasDocument.Get<ImageFragment>().Count(), saasDocument.Get<ImageFragment>().Count());
    Assert.Equal(paasDocument.Get<LinkFragment>().Count(), saasDocument.Get<LinkFragment>().Count());

    var paasHeading = paasDocument.Get<HeadingFragment>().Single();
    var saasHeading = saasDocument.Get<HeadingFragment>().Single();
    Assert.Equal(paasHeading.Text, saasHeading.Text);
    Assert.Equal(paasHeading.Location.PropertyName, saasHeading.Location.PropertyName);
}

Add parsing anywhere else and that guarantee is gone — silently, and you won't notice until a customer on SaaS reports findings a customer on PaaS doesn't get.

The rule catalogue

36 rules today, spanning WCAG A, AA and a few AAA criteria. Grouped roughly:

Text alternatives - alt text quality; accessible names for inline SVG, image-map <area>, <object>/<embed>.
Structure - heading levels, faux headings (a short bold paragraph doing a heading's job), fake lists (manually bulleted text), table headers, table complexity, deprecated presentational tags.
Links - accessible name, link purpose, document links that don't say they're a PDF.
Forms - labels, fieldset/legend, input purpose (autocomplete), button names.
ARIA and interaction - invalid roles and aria-* names, broken aria-labelledby references, nested interactive controls, aria-hidden on focusable elements, positive tabindex, duplicate accesskey, title misuse.
Media - captions, transcripts, audio description, unmuted autoplay.
Language - lang declarations, and inline passages in another writing system with no override.
Readability and presentation - colour contrast, justified text, sub-12px fonts, ALL CAPS runs, Flesch reading ease, sensory-characteristic instructions ("click the green button on the right"), page titling.

Each is registered individually in DI (ServiceCollectionExtensions.AddOptiA11y), so a host can drop the ones it doesn't want. RuleEngine takes IEnumerable<IContentRule>, so adding your own is a class and one registration.

Adding a rule to the project itself is five steps: emit (or reuse) a fragment from the parser, write the rule, register it, add a row to the README catalogue table, it's the user-facing contract, and, if it's heuristic, extend HeuristicRulesNeverFailTests.

Installing as a CMS 12/13 add-on: zero host code

The whole point of shipping this as an add-on is that a developer shouldn't have to wire anything up. Install the package and it self-registers through EPiServer's own extension points:

[InitializableModule]
[ModuleDependency(typeof(EPiServer.Web.InitializationModule))]
public sealed class OptiA11yCmsModule : IConfigurableModule
{
    public void ConfigureContainer(ServiceConfigurationContext context)
    {
        context.Services.AddOptiA11y();
        context.Services.AddScoped<IPaasContentLoader, EPiServerPaasContentLoader>();
        context.Services.AddTransient<IStartupFilter, OptiA11yStartupFilter>();
        context.Services.AddControllersWithViews();
    }
}

That IStartupFilter is the piece I like most, because it removes the last line of host code:

internal sealed class OptiA11yStartupFilter : IStartupFilter
{
    public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next) => app =>
    {
        next(app);
        app.UseEndpoints(endpoints =>
        {
            endpoints.MapRunAuditEndpoint();
            endpoints.MapRunAuditPanelEndpoint();
        });
    };
}

No MapRunAuditEndpoint() in the host's Program.cs. Two more attributes do the UI: a [MenuProvider] the shell discovers automatically for the "Accessibility audit" menu entry, and an iframe component plugin that puts a findings panel in the assets pane of the edit view, so an editor sees issues for the page they're on without leaving it. (The shell appends the current editor context as an id query parameter and reloads the iframe on context change — which is why the panel endpoint reads id, falling back to contentLink.)

The report view renders through IRazorViewEngine directly rather than requiring the host to register MVC controllers, is styled to sit inside the Optimizely admin chrome, and supports client-side filtering and sorting, including by confidence, so an editor can take the certain fails first and the judgement calls when they have time.

The EPiServer types are confined to exactly one file, EPiServerPaasContentLoader, which maps IContent / XhtmlString / ContentArea (recursing into nested blocks) onto the CMS-agnostic PaasContentNode / PaasProperty records. Everything below that line, PaasContentAdapter, the parser, the engine, the rules, stays CMS-free.

The optional browser slice

By default OptiA11y runs no browser at all, which is the right default: audits are fast, deterministic, and run anywhere. But it means contrast and readability rules only see inline style="" attributes. Anything from a stylesheet, a class, or a theme is invisible, and five checks have no static signal to work from whatsoever, because they're about a rendered page.

OptiA11y.Rendering is a separately packaged, opt-in slice that drives headless Chromium via Playwright and, for a content item's preview URL:

reads computed CSS for every visible text node (colour, background, size, weight, alignment, and whether the background is an image or gradient);
measures the bounding box of every interactive element, and whether its appearance changes at all on focus - target size (2.5.8) and focus indicator (2.4.7);
scans for automatically-starting, infinitely-repeating CSS animations (2.2.2);
resizes to a 320px-equivalent viewport and checks for horizontal overflow (1.4.10);
injects the WCAG 1.4.12 reference text-spacing overrides and checks which text clips (1.4.12).

The important part is how it plugs into the rules. It doesn't. RunAuditHandler appends the results as the same fragment shapes the static parser produces, before the engine runs:

var diagnostics = await _renderedStyleProvider.CaptureAsync(previewUrl, cancellationToken);
if (diagnostics.IsEmpty)
{
    return document;
}

var renderedFragments = RenderedStyleFragmentBuilder.Build(diagnostics, location);
return new AuditDocument(document.ContentReference, document.Fragments.Concat(renderedFragments).ToList());

ColorContrastRule and TextReadabilityRule need no knowledge that any of this happened. The five rendered-only rules simply find no fragments and produce nothing when the slice isn't installed.

And the provider fails soft, without exception:

catch
{
    // Rendering is a best-effort enrichment; any failure (browser unavailable,
    // navigation timeout, unreachable URL) should not fail the whole audit.
    return RenderedPageDiagnostics.Empty;
}

A bare catch is usually a smell. Here it's the contract. A missing Chromium binary on a build agent, a preview URL behind auth, a page that never reaches network-idle, none of those are reasons an editor should see an error instead of the findings the static path already computed. Enrichment that can break the audit isn't enrichment.

Opting in is two registrations, and the second is mandatory by design:

services.AddOptiA11y();                 // unaffected
services.AddOptiA11yRenderedStyles();   // opt-in

// Required: the default resolver returns null, which skips enrichment entirely.
services.AddSingleton<IContentPreviewUrlResolver, MyContentPreviewUrlResolver>();

Only the host knows how to build a preview URL for a content item, so the default resolver returns null and the whole slice no-ops rather than guessing.

What it deliberately does not do

The non-goals list is short and I intend to keep it:

No crawler. Property-level analysis of content an editor owns, not site-wide scanning.
No accessibility score. A number invites optimising the number.
No automated fixing. Every heuristic finding is a judgement call; auto-fixing judgement calls at scale is how you get ten thousand images described as "image".
No publish blocking. A warning on publish is on the roadmap (warn-only, severity configurable). A gate is not.

And the headline commitment, stated in the README and worth repeating: a clean OptiA11y result means OptiA11y found no issues it was able to detect. It is not a legal position and should never be shown to a client, auditor, or regulator as proof of WCAG or ADA conformance. It's a second pair of eyes for editors, not a substitute for a professional audit.

Where it is, and what's next

Version 0.3.1, targeting .NET 8 and .NET 10. Four packages (OptiA11y.Core, OptiA11y.Rendering, OptiA11y.Cms, OptiA11y.Cms12) versioned and shipped together, 220 test methods across four test projects, and a sample host seeded with deliberately broken content, including a nested block — so you can dotnet run and hit GET /optia11y/audit/page-home without a CMS anywhere in sight.

Four slices are done: single-item audit with deep linking, the self-registering CMS 12/13 add-on, the rule expansion, and the optional rendering slice. Next up:

Issue register - persisted findings across content, filterable, with status. EF Core, following the Stott Security pattern rather than DDS, for fewer host assumptions and a cleaner uninstall. Until then, RunAuditHandler holds no persistence at all, deliberately.
Dismissal with a recorded reason - who, when, why. If the tool is going to flag judgement calls, dismissing one has to be a first-class, auditable act rather than a checkbox.
Publish warning - content event handler, warn only, severity configurable.
SaaS adapter - scaffolded and covered by the equivalence suite, not yet wired to a real tenant.

Three things I'm still honestly unsure about, all listed in the repo: whether the Razor Class Library plus menu provider add-on pattern holds across future CMS 12/13 minors; whether DDS remains available (moot until persistence lands, but it decides whether the EF Core choice is a preference or a necessity); and correlating rendered DOM text nodes back to a specific SourceLocation, which is currently matched on trimmed visible text and will be ambiguous on a page with repeated identical strings.

The code is at github.com/adayinthelifeofapro/OptiA11y. If you take one idea from it, make it the confidence split, most tools in this space would be more useful if they were more willing to say "I'm not sure, look at this."

Graham Carr, Technical Architect

I am an experienced Technical Architect with over 30 years’ experience in a wide range of products and technologies. I have helped companies deliver their digital vision from concept all the way through to delivery. I have a particular passion for DXPs (Digital Experience Platforms) and am a certified developer for Optimizely as well as a Platinum OMVP.

You can also follow me on https://adayinthelife.pro

OptiPowerTools.ScheduledJobsInsights: Execution History for Optimizely’s Native Scheduled Jobs

Tue, 15 Sep 2026 08:00:00 GMT

A drop-in base class and Blazor UI that records what Optimizely CMS 13 scheduled jobs actually did — logs, metrics, result summaries, and retention.

A day in the life of an Optimizely OMVP: Commerce Connect 15 isn't an upgrade. It's a reset.

Mon, 14 Sep 2026 18:49:06 GMT

The version number is doing a lot of work to look harmless. Fourteen to fifteen. A nudge, surely. Bump the packages, run the build, ship it Friday.

It is not that. If you've shipped a few of these you can feel it coming, the kind of release where the changelog is mostly the word "removed" and the real project plan lives in everything that doesn't compile afterwards.

Here's the practitioner read on what actually changed, and where the work hides.

The headline nobody puts in the headline

Commerce Connect 15 doesn't travel alone. You can't take Commerce to 15 without taking CMS to 13 at the same time. They're welded together. So the moment you commit to 15, you've also signed up for .NET 10, mandatory Optimizely Graph, mandatory Opti ID, and Visual Builder replacing on-page editing.

That's the bit to land with stakeholders early. "We're upgrading Commerce" undersells it. You're moving the whole platform foundation in one go. Scope it as a programme, not a package update, and the rest of the conversation gets a lot easier.

Find is gone. Plan for it.

Search & Navigation → Find does not exist in this world. There's no .NET 8 escape hatch and no quiet "Find still works for now." It's replaced by a commerce-specific Graph search provider (Optimizely.Graph.Commerce) that powers the catalog panel, global search, and the order-management line-item lookup.

Think of it like swapping the engine while the car's still on the drive. The pedals are in the same place — the CMS 13 Graph SDK gives you a fluent Where() / SearchFor() / Limit() API that reads a lot like Find did, so the muscle memory transfers. But underneath, your indexing, your queries, and anything clever you built on EPiServer.Find.Commerce all need rethinking. If your catalog search is load-bearing, and on commerce it always is. This is your single biggest architectural item. Treat it as such.

Where the real hours go

Three places. Every time.

The workflow engine is gone. Mediachase.Commerce.Workflow and the old ActivityFlow engine have been pulled. Anything calling RunWorkflow(), OrderGroupWorkflowManager, or OrderStatusManager moves to the processor APIs — IPaymentProcessor, IPurchaseOrderProcessor, IShipmentProcessor. This is the work that passes the compiler and then bites you at runtime, because order state transitions are exactly the thing your test coverage tends to be thin on. Budget for it and test the full cart → promotion → checkout → payment → fulfilment path like your bonus depends on it.

Credit-card storage is gone. ICreditCardPayment, the CreditCard class, the lot, removed on PCI grounds. If you were storing card data (and you shouldn't have been), you're now tokenising through Stripe / Adyen / PayPal and hanging tokens off IPayment. Mostly a good-news story; occasionally a nasty surprise in an older codebase.

Serialization moved. Newtonsoft.Json out, System.Text.Json in, matching CMS 13. If you wrote custom converters into the Commerce pipeline, they need rewriting, ReadJson/WriteJson become Read/Write over Utf8JsonReader/Utf8JsonWriter. And Newtonsoft is no longer riding along as a transitive dependency, so if your own code leaned on it, reference it explicitly before it disappears out from under you.

There's also 50-odd deprecated methods finally being shown the door, plus the usual constructor-signature changes. None of it individually is hard. Collectively, on a mature build, it adds up.

The genuinely new bits

It's not all subtraction. IOrderRepository finally gets a proper async surface, LoadAsync, SaveAsync, SaveAsPurchaseOrderAsync, the lot, all with CancellationToken. Sync stays for compatibility, but new code should go async from day one.

And the direction of travel is obvious once you stand back. Catalog entries are now CMS content types, which means they inherit Visual Builder, Content Manager's search-first editing, and, the actual point of all this, Opal. There's already a Product Promotion agent that builds and configures promotions, assigns products and variants, and applies promotion types for you. Catalog data as content, delivered through Graph, operated by agents. That's the whole thesis. Fifteen is the version where it stops being a slide and starts being the product.

So what do you actually do

Same play we run every time, in order:

Assess on 14. Inventory your .csproj files, every EPiServer.* reference, every add-on, and every deprecated API you're still calling. Fail the build on those warnings now.
Clear the obsoletes while you're still on 14. Most of them are removed in 15, so fixing them early turns a wall of compiler errors into a handful.
Do the coupled jump in a branch. .NET 10, CMS 13, Commerce 15, and pin to the latest 15.x patch, not 15.0.0. Wire up Graph and Opti ID. Rewrite the converters. Move order processing to the processor APIs.
Test the order pipeline hardest. It's the thing that compiles clean and breaks live.

One more, and it's the one that quietly sinks timelines: the add-on long tail. At and just after GA, the connectors were still rolling out, ODP, Service API, PIM. Check the NuGet server for your specific add-ons before you commit a date to anyone. A green build on the core packages means nothing if the connector your client lives on hasn't shipped yet.

None of this is a reason to flinch. It's a reason to plan properly. The technical upgrade is increasingly a solved exercise, we're encoding chunks of it into agent skills already. The craft is in the content-model work, the order pipeline, and refusing to let "it's just a version bump" anywhere near the estimate.

Fifteen is a good release. Just give it the respect a reset deserves.

Graham Carr, Technical Architect

You can also follow me on https://adayinthelife.pro

Shareable stakeholder previews for Optimizely SaaS CMS

Mon, 14 Sep 2026 13:52:54 GMT

In August, Nikki Punjabi wrote about a gap in Optimizely SaaS CMS: there is no out-of-the-box way to share a draft page with someone outside the CMS. The editor preview is session-bound. If a legal reviewer or brand owner without a CMS account needs to approve a page, you have to build that yourself.

The post set out a design. The link should be a signed "permission slip" rather than a credential: it grants access to one draft page until an expiry date. Links should be internal-only by default, with external sharing an explicit choice. No database should be needed, CMS keys should stay on the server, and drafts should be hidden from search engines.

We built that design as a CMS UI Extension on the Optimizely Connect Platform (OCP). This post covers how.

Why a CMS UI Extension

Authors should create the link next to the page they are editing, not in a separate admin tool. That is what CMS UI Extensions do: an OCP app can register a sidebar panel inside the editing view. The panel is told which content item is open (key, version, locale) and updates as the editor moves between pages.

The same app also carries its backend functions, a settings screen and storage, so the whole feature ships as one unit. The manifest declares everything:

functions:
  cms_extension:
    entry_point: CmsUiExtension
    accepts: cms_ui_extension     # callable only from the panel
  preview:
    entry_point: Preview
    accepts: http                 # public, reviewer-facing endpoint

ui_extensions:
  sidebar:
    - name: share-preview
      entry_point: SharePreview
      display_name: Share preview

The panel is a React component registered through @optimizely/cms-extensibility-sdk:

register((context) => (
  <AxiomProvider>
    <SharePreviewPanel context={context} />
  </AxiomProvider>
));

context.content.subscribe() gives the panel the open page; context.extension.invokeFunction() calls the app's backend. We built the UI with Optiaxiom, Optimizely's component library, so the panel matches the rest of the CMS.

That is the full setup: a manifest, a React entry point, a backend class, and ocp app prepare --publish to deploy to all regions.

The link

The link contains an HMAC-SHA256 signed token over six fields:

{ contentKey, version, locale, scope, iat, exp }

There are no credentials in it and no session behind it. When a reviewer opens the link, the server recomputes the signature, checks the expiry against its own clock and enforces the scope. Editing the URL to extend the expiry or change the scope breaks the signature.

Internal links only open from configured office or VPN IP ranges. If no ranges are configured, they refuse rather than falling back to shareable behaviour. Shareable is a per-link choice and the panel warns you what it means.

The other guardrails from Nikki's design are all present: noindex via meta tag and X-Robots-Tag, no-store caching, read-only rendering, a clear page for expired links, and a hard refusal when the app is unconfigured. If the page has been published since the link was created, the link redirects to the live page.

Rendering the real page

A metadata summary of the draft is not enough; stakeholders want the page as designed, and in a headless setup only the front end can render it.

Our first attempt was to mint Optimizely Graph tokens from the app, both self-signed with the Graph secret and via an OAuth exchange. Graph rejected both. The documentation is clear once you read it properly: bearer tokens must come from an OIDC authorisation server.

The working approach came from Optimizely's own SaaS demo site, which includes a route at /.well-known/optimizely/preview-psk for exactly this purpose. You send key, ver and loc plus an HMAC signature over those parameters, keyed with a pre-shared token the head already holds. The head validates the signature, fetches the draft with its own server-side Graph credentials, and renders it with its real components. No CMS or Graph credential ever reaches the browser.

That stock route has one problem for this use case: the signature never expires, so the URL a reviewer lands on works forever. We added a sibling route that includes an exp timestamp in the signed data and refuses once it has passed. Our app issues those redirects freshly signed on each visit, valid for ten minutes. The link the author shares remains the single entry point where expiry, scope and revocation are checked.

The key-value store

The first iteration stored nothing, as the original design suggested. Two requirements changed that: authors wanted to see a page's existing links after a refresh, and to revoke one.

OCP apps have a key-value store with atomic read-modify-write and per-row TTL. We keep one row per content item. Each write prunes expired entries and resets the row's TTL to the furthest expiry, so the platform deletes the row once the last link dies. The panel filters by expiry on read, so expired links drop out of the list immediately.

Two details are worth copying:

The KV store documentation says not to store tokens, and our URLs contain one. HMAC tokens are deterministic, so the registry stores only metadata (id, version, locale, scope, issued and expiry times) and the app re-signs the URL when listing. No sensitive value is ever stored.
Revoking moves a link's entry to a deny-list in the same row. The public preview function checks the incoming token's payload against that list. The token format is unchanged, so earlier links are revocable too. A revoke that hits a storage error fails loudly; a viewer request that cannot read the registry fails closed.

Configuration

Everything above is driven by install-time settings, and OCP generates the settings screen for you. The fields are declared in a YAML form definition in the app (forms/settings.yml); a lifecycle hook validates and saves them into the app's settings store, which is the right home for credentials, unlike the key-value store. The app never needs its own admin UI.

The settings map directly to the decisions Nikki's post said to make before building:

Signing secret: leave it blank and the app generates one on save. Rotating it voids every link.
Optimizely Graph credentials: used by the server to fetch drafts.
Front-end preview route and pre-shared key: for rendering the real page.
Live site base URL: published pages redirect here.
Internal network ranges: defines what "internal" means.
Default link expiry: used when the author doesn't pick one.

What it offers

For authors: a panel next to the page with an audience choice (Internal by default, Shareable deliberately), an expiry choice (1, 3 or 7 days), one click to create, copy and send. The table of active links survives refreshes, shows which draft version each link was pinned to, and revokes per row with a confirm step.

For reviewers: a link that opens without an account or login, showing the real page rendered by the front end. Expired and revoked links get clear explanations.

For the organisation: link creation and revocation are logged with content key, version, scope and expiry. Rotating the signing secret voids every link at once. CMS and Graph credentials never leave the server.

Closing

External preview links are a small feature that touches security, caching, indexing and publishing policy, and a SaaS CMS UI Extension handled all of it in one deployable app. If your editors need something the CMS does not ship, this is a good route to it.

Thanks to Nikki Punjabi for the original design.

A day in the life of an Optimizely OMVP: Scoping a Search & Navigation - Optimizely Graph migration with Roslyn

Sat, 12 Sep 2026 19:05:13 GMT

If you have an Optimizely solution of any real age, you have Find code. Not in one tidy SearchService.cs, either, it's spread through page controllers, view components, scheduled jobs, and that one static helper somebody wrote in 2019 that everything quietly depends on.

At some point a conversation starts about moving to Optimizely Graph, and someone asks the question that decides the whole project:

How big is this, actually?

The honest answer is usually "we don't know yet." So somebody greps for .Search<, counts the hits, multiplies by a gut-feel number, and that becomes the estimate. I've watched that estimate be wrong by a factor of three, in both directions.

I built OptiGraphMigrator to replace the guess with a report. It's a Roslyn analyzer and dotnet CLI tool that reads your solution semantically, finds every Search & Navigation call, maps each one to its Optimizely Graph equivalent, and, the important part, tells you which ones have no equivalent at all.

Why grep doesn't work here

Two reasons.

The first is that Find queries are fluent chains, and the interesting part is usually at the end. Consider:

var query = _client.Search<Article>();

if (applyGeoFilter)
{
    query = query.OrderBy(a => a.Title).DistanceFrom(latitude, longitude);
}

var results = query.GetContentResult();

Grepping for Search< finds line 1 and tells you nothing. The thing that will actually derail your migration is DistanceFrom - a geo/spatial filter - three lines later, inside a conditional, attached to a variable. A text search finds the string but can't tell you it belongs to the same query, or what content type it's filtering.

OptiGraphMigrator resolves that chain through Roslyn's semantic model. It walks from the outermost invocation back down through the receivers, and it follows local-variable reassignment, so the example above is understood as one query with a geo filter on it, not three unrelated fragments.

The second reason is that "found a Find call" is not useful information. What you need to know is what happens when you try to port it. Which brings me to the part of the design I think actually matters.

Three buckets, not one number

Every rule in the tool classifies a construct into one of three levels of translatability:

Bucket	Meaning	What it costs you
Exact	A mechanical, behaviour-preserving 1:1 mapping exists.	Hours. Sometimes automatic.
Caveat	A mapping exists, but the semantics differ.	A developer has to read it and decide.
Blocked	No clean translation. The feature must be redesigned.	A conversation with your product owner.

Filter(), OrderBy(), Skip(), Take(), GetContentResult() - these are Exact. They map onto Graph's where, orderBy, skip, limit and query execution almost mechanically. If your codebase is 90% this, your migration is a port and your estimate should be small.

Language(), FilterForVisitor(), Select() projections, MatchContained() - these are Caveat. There's a target to aim at, but the behaviour isn't identical, so a human has to confirm each one. Find's For() free-text search is in here too: it applies BM25-style ranking across all indexed fields, and Graph's full-text match will rank results differently. The code compiles either way. Whether the search results still look right is a different question.

And then there's Blocked: BestBets(), DidYouMean(), Autocomplete(), MoreLikeThis(), RemoveDuplicates(), MinScore(), DistanceFrom(), the statistical aggregations (AverageOf/SumOf/MaximumOf/MinimumOf), custom scoring via Boost()/CustomScore(), query-time synonyms, and direct push-based indexing (Index()/UpdateIndex()/DeleteIndex()).

The Blocked list is the real output of this tool. Everything else is work you can plan. The Blocked list is work you have to design, and it's the reason migrations slip. Finding out in week six that the editorial team depends on Best Bets is considerably worse than finding out on day one.

There's a fourth category worth mentioning: patterns that are technically legal Find but which only work because Find can fall back to evaluating them outside the index. A Filter() whose lambda calls arbitrary .NET code is the classic case. Graph's where clauses can only express what the index itself can evaluate, so that logic has to become either an indexed field comparison or an explicit post-query filter in application code. The tool flags those specifically rather than letting them hide inside the friendly-looking "Filter() → where" mapping.

What it looks like

Point it at a solution or a project:

optigraph-migrate scan MySolution.sln --format console

WARNING OGM001   FindUsageSamples.cs(39,27): Find 'Filter(...)' can be translated to a Graph 'where' clause
        -> Graph equivalent: .Where(x => <translated predicate>)
WARNING OGM003   FindUsageSamples.cs(39,27): Find 'OrderBy(...)' can be translated to a Graph 'orderBy' clause
        -> Graph equivalent: .OrderBy(x => <field>)
INFO    OGM007   FindUsageSamples.cs(39,27): Find 'Take(...)' can be translated to a Graph 'limit' argument
        -> Graph equivalent: .Take(<count>)
WARNING OGM010   FindUsageSamples.cs(82,27): Find 'StaticallyCacheFor(...)' has no built-in Graph SDK equivalent; caching must be implemented by the caller
        -> Graph equivalent: Cache the GraphQL response in the calling application (for example via IMemoryCache) for an equivalent duration
WARNING OGM103   FindUsageSamples.cs(114,13): Find indexing convention 'ShouldIndex(...)' has no in-code Graph equivalent; configure the schema in Graph instead
WARNING OGM104   FindUsageSamples.cs(123,26): 'FindByContentType(...)' is an IContentLoader helper backed by Find; migrate the call site to the Graph SDK client
WARNING OGM202   FindUsageSamples.cs(131,27): Find custom scoring 'Boost(...)' has no clean Graph SDK translation

Summary: 0 error(s), 48 warning(s), 44 info

The Markdown format is the one to hand to a lead or put in a ticket, because it leads with the shape of the problem rather than the list of findings:

# OptiGraphMigrator report

0 error(s), 48 warning(s), 44 info

- Exact (auto-fixable): 48
- Caveat (needs review): 19
- Blocked (no clean translation): 15

## Top blocking patterns

| Rule | Title | Occurrences |
|---|---|---|
| OGM202 | Custom relevance scoring has no Graph equivalent | 2 |
| OGM021 | DistanceFrom(...) geo/spatial filter has no direct Graph equivalent | 2 |
| OGM203 | Query-time synonym expansion has no Graph equivalent | 1 |
| OGM018 | BestBets(...) has no direct Graph equivalent | 1 |

That "Top blocking patterns" table is the slide you take to the planning meeting.

Four output formats are supported: console, markdown, html, json, and sarif. SARIF is proper 2.1.0, so Azure DevOps and GitHub code scanning will render the findings inline on pull requests without any extra glue.

Beyond the query chains

Queries are the obvious target, but they're not the whole migration. The tool also covers three areas that tend to get missed during scoping:

Indexing conventions. client.Conventions.ForInstancesOf<T>().ShouldIndex(...).IncludeField(...) is C# configuration that has no in-code Graph equivalent, it becomes schema configuration in Graph instead. Easy to overlook, because it usually lives in an initialization module nobody has opened in two years.

Find-backed IContentLoader helpers. FindByContentType<T>(), FindPagesWithCriteria<T>(), GetChildrenWithFind<T>() - these don't look like search code at the call site. They look like content loading. Every one is a call site that needs to become an explicit Graph query.

The static singleton. SearchClient.Instance has no Graph SDK equivalent, and every usage is a place where you'll need to introduce proper dependency injection as part of the port.

Installing and running it

The tool targets .NET 10 and uses MSBuildWorkspace (falling back to a source-only heuristic scan for legacy, non-SDK-style CMS 11 projects) to analyze your solution, so you need a .NET SDK installed — Visual Studio/Build Tools MSBuild is not required. It analyzes the code statically; it does not need credentials, an index, or a running Find instance, and it makes no network calls, whether your solution targets modern SDK-style CMS 12+ projects or legacy CMS 11 (.NET Framework, packages.config) projects.

From source

git clone <REPO-URL>
cd OptiGraphMigrator
dotnet build OptiGraphMigrator.slnx
dotnet run --project src\OptiGraphMigrator.Tool\OptiGraphMigrator.Tool.csproj -- scan <path-to-your-solution> --format markdown

As a global tool

dotnet pack src\OptiGraphMigrator.Tool\OptiGraphMigrator.Tool.csproj -c Release
dotnet tool install --global --add-source artifacts OptiGraphMigrator.Tool

optigraph-migrate scan MySolution.sln --format markdown --output migration-report.md

Options

Option	Description
`--format <console\|sarif\|html\|json\|markdown>`	Report format. Defaults to `console`.
`--output, -o <file>`	Write to a file instead of stdout.
`--rules <file>`	A rule catalogue that overrides or extends the built-in mappings.
`--severity-threshold <info\|warning\|error>`	Minimum severity to include in the report.
`--fail-on <info\|warning\|error>`	Minimum severity that produces a non-zero exit code.

In CI

Exit codes are designed to be gated on:

0 - scan completed, nothing met the --fail-on threshold.
1 - scan completed, findings met the threshold.
2 - the scan could not run (bad path, workspace load failure, unexpected error).

The distinction between 1 and 2 matters. 2 is an infrastructure problem and should always break the build; 1 is a finding and you get to decide how strict to be. A useful pattern during an active migration is to run with --fail-on error so the build breaks only when someone introduces new Blocked-tier Find usage into a codebase you're trying to move off it.

As an analyzer, while you're actually porting

The CLI is for scoping. Once the migration is underway, there's a second mode: the analyzer and code fix provider pack as a normal analyzer package, so you get the same diagnostics as squiggles in Visual Studio or Rider, on the file you're editing, with the suggested Graph equivalent right there in the tooltip.

The mappings marked isAutoFixable in the rule catalogue also ship a code fix, so the genuinely mechanical ones can be applied with Ctrl+. rather than by hand.

Scope with the CLI, port with the analyzer.

Teaching it your codebase

There are 47 rules today: 34 declarative mappings plus 12 hand-written rules for patterns that need real semantic inspection (checking what's inside a Filter() lambda, for instance).

The declarative ones live in a JSON catalogue, and you can override or extend it without touching the code, point --rules at your own file, or drop an optigraph.rules.json next to your solution and it'll be discovered by walking up the directory tree, the same way .editorconfig works. A rule looks like this:

{
  "id": "OGM001",
  "title": "Filter(...) maps to Graph where(...)",
  "severity": "warning",
  "category": "filtering",
  "translatability": "exact",
  "findSymbolPattern": {
    "containingType": "EPiServer.Find.Api.Querying.FilterExtensions",
    "methodName": "Filter",
    "minArguments": 1,
    "matchDerivedTypes": true
  },
  "graphEquivalent": ".Where(x => <translated predicate>)",
  "graphQlSnippetTemplate": "where: {{ {0} }}",
  "caveats": [
    "Find's Filter() predicates are evaluated server-side against the index; confirm the equivalent Graph 'where' clause targets the matching indexed field name."
  ],
  "isAutoFixable": true
}

Rules with a matching id replace the built-in ones; new ids are appended. So if your solution wraps Find in your own extension methods, and most mature solutions do, you can teach the tool about your wrappers in a few lines of JSON and get them classified alongside everything else. That's the difference between a report that covers 60% of your search code and one that covers all of it.

What it won't do

Worth being direct about the limits:

It does not rewrite your queries for you. A handful of Exact mappings have code fixes. The rest is a map, not a migration. Anyone promising automated Find → Graph translation for anything beyond the trivial cases is overselling.
Caveat findings genuinely need a human. The tool tells you the semantics differ and why; it cannot tell you whether your users will notice.
Unrecognised API surface is reported, not hidden. If a chain can't be fully resolved, an overload the catalogue doesn't know, or a compilation error, you get an OGM901 info-level finding saying so, rather than a silent gap in the report. If you see a lot of those, that's a signal to extend the catalogue.
It needs your solution to build. Roslyn needs a working compilation for symbol resolution.

Try it on your worst solution

If you're weighing up a Find → Graph migration, the most valuable thing you can do this week is run this against your largest legacy solution and look at nothing but the Blocked list. It takes about five minutes and it will tell you whether you're looking at a port or a redesign.

I'd particularly like to hear about two things: Find API surface that produces OGM901 unresolved findings (that's a gap in the catalogue and easy to fix), and any mapping you think is classified wrong, especially anything I've marked Exact that bit you in practice. The translatability calls are judgement, and they get better with more codebases behind them.

Source, rules documentation and issues: OptiGraphMigrator/OptiGraphMigrator at main · adayinthelifeofapro/OptiGraphMigrator

Graham Carr, Technical Architect

You can also follow me on https://adayinthelife.pro

Machines Are Reading Your Content Model

Sat, 12 Sep 2026 17:46:40 GMT

How Optimizely CMS (SaaS) separates presentation intent from content — and why that now matters for AI discoverability.

Start with a requirement that looks completely reasonable

A client asks for a Heading content type. The requirements are modest:

A field for the heading text
A dropdown so the author can choose H1 through H6
A toggle for an underline
A colour choice for that underline — red or white

Nothing here is unusual. Most of us have built something close to it. It takes an afternoon, the client is happy, and the content type ships.

Before going further, the sanity checks are worth doing — because sometimes the answer is simply "this is fine":

Is this a one-off page, or a pattern that will repeat across the site?
If the brand colour changes next year, how many content items need editing?

For a small site updated twice a year: build the dropdown and move on. Not every project needs an abstraction layer.

But on an enterprise build with hundreds of pages and a multi-year lifespan, those questions start to sting. And there is a fourth one that has only recently become interesting:
what does a machine see when it reads this page?

The actual problem: a vocabulary mismatch

A headless CMS is designed to store meaning. Authors think and speak in appearance — bigger, bolder, red, underlined. That is not a failure on their part. It is the only vocabulary any CMS has ever offered them. Text field, dropdown, colour picker: the interface quietly teaches everyone that appearance is a thing you store.

So when an author asks for a style option, they are very often expressing a semantic fact in visual language. When we build exactly what was asked for, we store the visual consequence and throw the semantic fact away.

Look again at those three requirements. They are not three styling options — they belong to three different layers.

"H1 through H6" — when an author picks H3, they are rarely thinking about document outline. They are thinking "I want text roughly this big." A heading level is a statement about document structure. Size is a statement about visual emphasis. The author was asking for the second and we gave them control over the first. That is how pages end up with three H1s, or an outline that jumps from H2 straight to H5.

"Red or white" — ask why they want white. In my experience the answer is always: "because on the dark sections the red doesn't work." The author is not choosing a colour. They are restating the background of the section they are sitting in, by hand, on every heading. The section already knows whether it is light or dark. Let the heading inherit from that.

"Underline on or off" — this one survives. It is genuinely decorative and the author's judgement is the right input. Although even here, a name like accent travels better than underline, because it describes the role rather than the rendering.

One out of three requirements was really a style choice.

A three-layer way of thinking about it

Most teams think in two layers — content and style — and that is why the boundary collapses. There is a third layer in the middle that tends to get forgotten.

Layer	The question it answers	Channel-neutral?
Content	What is true?	Yes
Presentation intent	What does the author mean? (emphasis, prominence)	Yes — semantic, not visual
Presentation implementation	What does it look like here?	No

The two failure modes are collapsing the middle layer into either neighbour. Push it into content and you get colour values in your content types. Push it into implementation and authors lose all control — and start requesting new content types instead.

A practical test: would this value still mean something to a channel that has no screen? "This is the primary call to action" survives. "This is #0A2540 with 24 pixels of padding" does not.

Where Optimizely CMS (SaaS) fits

This is the part I find genuinely well designed.

In CMS (SaaS), display templates are defined separately from the content type's property schema. You define templates that carry settings, and Optimizely Graph indexes the selected template and settings alongside the content and delivers both to the front end. Each node in the composition model can carry a displayTemplateKey and a set of displaySettings — key/value pairs the front end interprets however it likes. See Configure Visual Builder and Manage styles for the details.

That separation is exactly the middle layer the three-layer model is asking for. The platform gives you a dedicated channel for presentation intent that never touches your content schema.

What the platform cannot do is police the vocabulary you put in it. A display setting choice is a string — it will happily store "primary" or "#E4002B" and return either one. Which leads to the single highest-leverage habit in this whole discussion, and it costs nothing: the stored key and the label the author sees are separate values. Let the author see "Red" and "White". Store "primary" and "inverse". The client gets precisely the choice they asked for. You keep the abstraction. When red becomes crimson, you change one token.

To make the difference concrete, here is the shape of both approaches. These are conceptual illustrations — not production schemas — but the pattern is the one worth internalising.

The approach to avoid — presentation stored directly as content type properties:

// Illustrative — shows the pattern to avoid
{
  "key": "HeadingElement",
  "properties": {
    "text":            { "type": "string" },
    "headingTag":      { "type": "string" },
    "underlineColour": { "type": "string" }
  }
}

Every channel that is not a web browser now receives a heading tag and a colour hex value it has no use for.

The cleaner approach — content type holds only content, display template carries intent:

// Content type — only what is semantically true
{
  "key": "HeadingElement",
  "properties": {
    "text":          { "type": "string" },
    "levelOverride": { "type": "string" }
  }
}

// Display template — semantic intent, not visual values
// The author sees "Red" / "White". Graph stores "primary" / "inverse".
{
  "key": "HeadingStyle",
  "contentType": "HeadingElement",
  "settings": {
    "size":         { "choices": { "large":   { "displayName": "Large"      },
                                   "medium":  { "displayName": "Medium"     } } },
    "accent":       { "choices": { "none":    { "displayName": "None"       },
                                   "rule":    { "displayName": "Underlined" } } },
    "accentColour": { "choices": { "primary": { "displayName": "Red"        },
                                   "inverse": { "displayName": "White"      } } }
  }
}

The author gets the control they asked for. Graph delivers clean semantic keys. The front end resolves the token. The heading arrives usable on every channel.

Conceptually, the front end then owns a single mapping from semantic intent to channel-specific implementation — the only place that knows what "prominent" actually looks like on this channel. That is the pattern worth establishing, whatever your stack.

If you would rather not hand-write display template payloads, Opal Chat exposes tools for listing, retrieving, creating and updating them conversationally — which also makes auditing straightforward. Asking for a list of every display template and its choice keys is a quick way to spot hex values that have crept in.

The part that has changed recently

Until recently, the argument for keeping presentation out of content ran into a simple objection: "we are a web-only business." And the counter-argument — hypothetical future channels — never beats a delivery date.

That objection is weaker now, because there is a channel already consuming this content that nobody commissioned.

When an AI system reads a page — for a summary, an answer, a citation — it works primarily with text and structure. A red underline communicates nothing to it. Heading hierarchy, on the other hand, is one of the main signals for understanding how a document is organised and where one idea ends and the next begins. That H1-to-H6 dropdown, built in good faith as a small author convenience, is quietly working against discoverability in a channel the client does care about.

I want to be careful not to overstate this. Crawlers vary in sophistication, and large language models are genuinely capable of extracting meaning from messy documents. This is not a claim that a disorganised heading structure makes you invisible. It is a claim about direction: the more meaning that lives in structure rather than appearance, the more of it survives into a system that cannot see your stylesheet. The general guidance for AI-era discoverability — crawlability, clear structure, structured data — is the same advice good content modelling has always produced as a by-product.

Look at how Optimizely's own Opal agents interact with this, because their operational requirements illustrate the point clearly.

The GEO Schema Optimization agent analyzes page content and preview URLs to generate JSON-LD schema markup, which it writes directly back into a schema property in CMS. While the agent can parse rendered HTML, the output needs a structured home. If your content model provides explicit metadata fields and a designated schema property, the workflow is automated and durable. When metadata has to be reverse-engineered from visual text styles, the process becomes lossy.

Similarly, the SEO Metadata Implementation agent evaluates SEO properties and updates metadata fields in CMS (SaaS). For an agent to push automated improvements, the destination fields must exist in the content model. If title or description semantics are treated merely as visual heading blocks rather than typed metadata, automated governance has nowhere to land its changes.

The Content Model Creation agent takes a URL or image and suggests a content model, specifically comparing its recommendations against your existing content types to classify them as "New" or "Modified". This is where content modeling habits compound: the agent references what is already registered in your CMS instance. If your existing models are already cleanly separated into content fields and display templates, new recommendations naturally align with that standard. If existing types mix styling flags into content properties, extending them propagates that debt.

AI agents are effective at analyzing and automating workflows across your CMS, but their leverage depends on the clarity of the underlying schema. Clean structure gives automation clean inputs and reliable destinations.

Honest limitations

This model is not complete, and it is worth saying so before someone else does.

Reused content across surfaces — "the parent owns surface, the child owns emphasis" works well in hierarchical composition. When a block genuinely appears in both a light section and a dark one, inheritance is not enough, and I do not think there is one settled answer yet.
Vocabulary discipline — a semantic layer is only as stable as the names in it. Someone has to own that vocabulary across teams and years. A hex value is at least unambiguous.
Scale — most of this assumes an enterprise build with a long life and multiple teams. For smaller projects the machinery can outweigh the problem.

The question that does most of the work

If there is one thing worth taking from this, it is a question to ask in the next content modelling session, whenever someone requests a visual option:

"Why do you want to be able to choose that?"

The answer is usually a semantic fact wearing visual clothing.

"H1 through H6" → I want it this big → that is size
"Red or white" → the background is dark → that is theme
"Underline it" → sometimes it really is just decoration, and that is fine

One of those three was a genuine style choice. Finding out which is the whole exercise.

Your content model is a contract. You have always been signing it on behalf of your authors and your developers. The new part is that you are now also signing it on behalf of every machine that helps decide whether anyone finds you.

Content Transfer addon comes to CMS 13

Fri, 11 Sep 2026 12:23:12 GMT

Whilst we're waiting the release of OCP UI apps and with it Content Transfer for SaaS, I thought I'd pull the features and functionality from the CMS 12 Content Transfer add-on across to CMS 13, and so I give you Content Transfer for CMS 13.

Unlike with CMS 12 there's no need for the Content Management or Content Delivery API as all the work is done with the REST API that comes out of the box with CMS 13.

Featurewise, it works exactly the same - it allows you to push published content (pages, blocks, images, references, documents, videos, etc.) between different DXP (or any CMS 13 instance for that matter) environments - though in a preview to what the SaaS tool is bringing, retargeting has been added, allowing you to now move content to anywhere in the target CMS!

So, choose what you want to move...

Then watch it and associated items wing their way to the environment of your choosing...

As always, feedback is appreciated.

Meet the latest OMVPs - H2 2026 Cohort!

Thu, 10 Sep 2026 12:07:34 GMT

Hi, I’m Raiyan Binte Abdullah, and I’m really excited to introduce myself as the newest member for managing the OMVP program and the digital community.

As this is my first time stepping into this role, I’m looking forward to getting to know more of you, hearing your ideas, and being someone you can reach out to whenever you need support. Whether you have questions about the OMVP program, want to share a community contribution, have an idea for content or events, or simply aren’t sure who to reach out to — I’m here to help connect you with the right person or resource.

Please don’t hesitate to reach out to me directly. I’d genuinely love to hear from you, and I’m looking forward to working with and getting to know the OMVP community better!

📩 Reach out: raiyanbinta.abdullah@optimizely.com

Some people don't just use Optimizely — they champion it. They stay late to answer a stranger's forum question, turn a hard-won project lesson into a blog post so the next team doesn't hit the same wall, and step on stage to share what they've learned. Every year, the Optimizely Most Valuable Professional (OMVP) program exists to celebrate exactly these people.

OMVPs are the practitioners who build brilliant things on the platform and give their knowledge away freely — mentoring peers, sparking discussions, and lifting the whole community as they grow. They come from every corner of the ecosystem: solution architects and developers, strategists and digital leaders, each with their own story and their own way of moving Optimizely forward. What they share is generosity: through blogs, talks, technical contributions, and real-world work, they make everyone around them better.

Today, we're proud to introduce the newest cohort — the 2026 H2 Optimizely MVPs. Every name here represents deep expertise, hard-earned experience, and a genuine commitment to sharing it.

So let's meet them. 👏

YiLun Miao

YiLun Miao has a rare talent: making emerging technology feel less like a leap and more like a natural next step. As Country Manager for Niteco ANZ, he's become one of the most recognizable champions of Optimizely and its AI capabilities across the ANZ and APJ markets, famous for explaining Opal through everyday moments like learning to ski or eating a Dutch herring sandwich, analogies now quoted on stage by Optimizely's own leadership.

Behind the storytelling is real momentum: enterprise POCs, region-defining workshops, and a knack for connecting customers, partners, and technology so digital transformation actually lands. Generous with what he knows, YiLun shares practical insight freely with the wider Optimizely community, and this cycle, he earned the program's highest contribution score.

Igor Safonov

Igor Sufonov is a Solutions Architect at Niteco with more than 15 years of experience working with digital platforms and enterprise technology. He works across the Optimizely platform, with a particular focus on CMS, content operations, solution architecture, integrations, experimentation, and AI.

Igor enjoys sharing practical experience from real projects through articles, discussions, and community events. Recently, he has been particularly interested in Optimizely Opal and exploring how AI can be applied to real-world content, marketing, and solution delivery challenges.

Vipin Banka

Vipin Banka is a technology leader, architect, and mentor with a passion for digital experience platforms, composable architecture, integrations, and AI-enabled engineering. He enjoys helping organizations navigate complex technology decisions and designing scalable solutions that balance business needs with long-term sustainability.

As an active member of the Optimizely community, Vipin shares implementation learnings, architecture insights, and best practices through Optimizely World articles and community engagement. Beyond technology delivery, he is particularly interested in how AI and emerging technologies can enhance engineering productivity, solution design, and customer outcomes.

Piotr Nowak

Piotr Nowak is a Senior .NET Developer and Optimizely SME at ROCKWOOL Group, with nearly seven years on the platform spanning architecture, development, cloud migration, and DevOps automation across more than 40 global markets. He architects and builds on Optimizely CMS (PaaS and SaaS), Commerce, and Headless CMS with GraphQL.

Piotr plans and executes complex migrations — monolith to headless with Next.js, and Windows to Optimizely DXP cloud-native Linux — on Azure infrastructure built as Infrastructure as Code via Azure DevOps and the Optimizely Deployment API. He also runs internal workshops on DXP migration, headless architecture, and best practices, and earned all eight Optimizely certifications in October 2025.

Jill George

Jill George is Senior Sales and Client Director at Niteco, where she works at the point where Optimizely's product direction meets how UK enterprises actually buy. She's built her platform knowledge deliberately rather than by default, holding multiple accreditations across the Optimizely ecosystem, and regularly shares insight into what each new release actually means for the businesses using it, not just what's new, but what it changes.

Jill is passionate about closing the gap between what Optimizely can do and how well UK enterprises currently understand it, and is a passionate, visible voice for the platform.

Tom Denbigh

Tom Denbigh is a Commercial Director at Netcel. He has spent the last decade on a simple conviction: that the best digital strategies start with people, not platforms. He helps organisations keep users at the heart of every objective — and makes sure the technology follows, rather than leads.

With deep expertise across platform strategy, personalisation, and user experience, Tom guides companies in getting real, measurable value from their Optimizely and marketing-technology investments. But his contribution reaches well beyond client work: through Netcel's webinar programme, his Opticon panels, and the Future Ready Forum he founded for senior digital leaders, he's created spaces for the whole community to learn from one another.

Kiran Patil

Kiran Patil is a Group Technology Director at Horizontal, where he leads technical strategy and delivery across digital experience platform engagements. With 19 years in the industry building premium digital experiences for Fortune 100 clients, Kiran brings a full-lifecycle perspective to every project — spanning architecture, discovery, estimation, and go-live planning — working closely with tech leads and development teams to bring solutions to life.

He currently focuses on Optimizely SaaS CMS implementations and large-scale digital transformation initiatives, and holds both Optimizely SaaS CMS and Opal certifications. A long-time community contributor and knowledge sharer, Kiran is passionate about helping practitioners learn from real-world experience rather than just documentation, and is especially excited about what SaaS CMS, Opal, and Experimentation can unlock for marketing teams.

William Parr

With 18 years in web development, William Parr is a Lead Engineer and Optimizely Chapter Lead at iO, specialising in translating client requirements into scalable solutions and bridging business needs with technical implementation.

His expertise spans back-end development, enterprise content management, and DXP architectures, with a primary focus on Optimizely. An active community contributor, William holds certifications including Optimizely Certified CMS Developer, Optimizely One Technical Sales Accredited, and Opal Development Accredited.

Phil Heywood

Phil Heywood is Head of Experience at Netcel, working at the strategy and experience end of digital programmes rather than the build. He focuses on framing business outcomes clearly and building a Goal Tree so a programme stays anchored to them. Using Core Modelling, Phil identifies the "core pages" where a priority user task meets a priority business goal — insight that then feeds the CMS and DXP content model and Optimizely Graph's composable structure.

He sets experimentation and personalisation strategy across Web Experimentation and Feature Experimentation, helping clients move up the maturity curve, and owns Netcel's experience-optimisation practice. Phil also advises organizations on where Opal and agentic workflows can remove friction from everyday content and optimisation work.

Nicholas Sideras

Nicholas Sideras is a CMS Architect and Optimizely Platform Lead at Velir, a full-service digital agency and data studio, where he sets technical direction for CMS implementation projects. He started working in the CMS space twenty years ago, with over twelve years of experience on integration-heavy e-commerce projects connecting websites to back-office OMS, ERP, product information, and payment systems. While launching sites on the Optimizely platform over the past seven years, he has earned ten active certifications, including SaaS CMS, PaaS CMS, Opal, and Web Experimentation.

Nicholas has held both in-house and agency engineering roles, working with organizations ranging from local businesses to global brands. That experience — including client-side management of agencies — has taught him the weight digital projects place on sponsoring teams, a perspective he brings to his client work and to the technical writing and talks he shares with the community.

Keshav Dave

Keshave Dave is a Senior Lead Optimizely Engineer working with RAKBANK in Dubai, with 10 years of experience working with the Optimizely platform and digital experience solutions. He has hands-on experience across the Optimizely ecosystem, including CMS SaaS/PaaS, Commerce Connect, Optimizely Graph, Web and Feature Experimentation, Optimizely Opal, and other Optimizely products. He also has extensive experience building integrations using Optimizely APIs and services, as well as designing and developing scalable content and commerce solutions.

Beyond his project work, he's passionate about exploring new Optimizely capabilities and contributing to the Optimizely community through technical knowledge sharing, blogs, community support, and Dev Meetups.

Muhammad Talha

Muhammad Talha brings a customer-centric mindset to digital transformation and digital experience programs, having led initiatives for renowned brands across professional services, consumer products, insurance, and asset management.

He works closely with business stakeholders to define digital strategies and roadmaps that maximize the value of the Optimizely platform, guiding customers on the effective adoption of Optimizely CMS, Commerce, and Digital Experience solutions while leading end-to-end delivery from ideation and solution design through to production release. Talha also supports customers on their AI transformation journey, enabling the adoption of Optimizely Opal and identifying opportunities for AI-driven capabilities to enhance content management, digital experiences, and operational efficiency.

Mark Ames

Mark Ames is a Technical Director at Netcel, has spent 15 years shaping how organisations build on Optimizely, from Episerver's earliest days to today's agentic, AI-accelerated platform. His work sits where technical direction meets architectural governance: guiding teams through digital transformations, complex integrations, and version migrations, and making the hard calls on where a platform should be pointed to deliver real value.

Lately, that focus has turned to AI. Mark has developed a structured, human-in-the-loop approach to AI-accelerated Optimizely delivery, championing what agentic tooling like Opal can genuinely do, while keeping a clear head about where human judgement has to stay in the loop. He led Netcel's Optimizely Opal hackathon effort, contributes thoughtfully to technical discussions across Optimizely World, and works quietly behind the scenes to mentor colleagues and widen his team's footprint in the community. Generous with hard-won lessons, Mark is exactly the kind of practitioner the OMVP program exists to recognise.

Wojciech Seweryn

Wojciech Seweryn is the kind of developer who turns hard-won project experience into something the whole community can use. As Lead Backend Developer at NoA Ignite, he's spent more than eight years deep in the Optimizely platform — currently leading backend work on The Royal Mint, where he owns everything from architecture to go-live across CMS, Commerce, ODP, Product Recommendations, and both Web and Feature Experimentation, including a heavily customized Commerce Bundles build.

But it's what he does beyond the code that stands out. On his blog at wseweryn.dev, Wojciech has published a steady run of practical, no-nonsense technical guides on ODP real-time audiences, CMS 13 upgrades, Graph migration, and Product Recommendations customization, the kind of writing that saves other developers hours of trial and error. He's just as active in the forums, where his answers have earned rare "accepted" marks from the people he's helped. Generous, precise, and consistently useful, Wojciech is a natural fit for the OMVP program.

Niklas Andersson

Niklas Andersson spent more than eight years inside Optimizely, back when it was still called Episerver — building teams around Customer Success, Support, Partner Success, and Managed Services. Today he leads the Optimizely practice at Precio Fishbone in Stockholm, moving from asking partners to do great work to delivering it himself.

He is currently deep in Opal, GEO/AEO, and figuring out how AI fits into real enterprise DXP setups without breaking anything important. Outside of work, Niklas is usually on a boat, underwater, or being politely folded up on a Brazilian Jiu-Jitsu mat.

Rikard Ljungman

Rikard Ljungman has been around Optimizely since the EPiServer days in 2007, and has seen the platform move through several eras — this one, he believes, being the biggest.

At Niteco, he focuses on helping clients make genuine sense of Opal and the AI shift: not just adopting new tools, but rethinking how teams work now that a lot of what used to require a developer no longer does. That is what he wants to bring to the OMVP program, helping people navigate what is genuinely new, informed by having watched what came before it.

Arnold Macauley

Arnold Macauley is a Partner at Nansen leading the AI and Opal practice, owning strategy and architecture for agent work on Optimizely: which agents get built, in what order, and how they connect to CMS, CMP, and Experimentation. He runs the "Prompts to Production" workshop method — moving from a blank page to around 60 use cases in under an hour — and handles commercial shape, account leadership, and change management through delivery.

Arnold built the Road Scholar Opal program, cutting an 81-hour sustainability review to five to seven minutes and reducing an activity-notes audit by 96% across 940 programs, with more than 40 everyday agents now live.

Karla Santi

Karla Santi is the CEO and founding partner of Blend Interactive, a digital agency that guides organizations through complex web and content challenges. Since 2008, when Blend became Optimizely's first North American partner, she has grown the agency into an Optimizely Platinum Partner backed by a team of experts across Optimizely's solutions.

Karla serves on Optimizely's Partner Advisory Board and is a frequent speaker and voice in the CMS community, bringing a strategic perspective on how organizations put technology to work for real results.

Augusto Davalos

Augusto Davalos is a Senior Project Manager, Agile practitioner, and digital experience strategist with more than 15 years of experience helping teams turn business strategy into measurable outcomes. He is passionate about Lean and Agile thinking, reducing waste, and making sure teams focus their effort on work that creates real value.

For more than four years, Augusto has been part of Oshyn, where he has worked on and led Optimizely initiatives ranging from ongoing maintenance and platform upgrades to migrations and broader digital experience projects. His focus is always on connecting technology decisions with business goals, delivery realities, and the people responsible for making change happen. As an Optimizely enthusiast, he enjoys sharing practical lessons from real projects and helping organizations get more value from their digital experience platforms while contributing back to the community.

Welcome to the OMVP Community

The Optimizely community thrives because of individuals who are willing to share their expertise, mentor others, and push the platform forward. This new cohort of OMVPs embodies exactly that spirit.

This announcement highlights just a portion of the talent and dedication that makes the Optimizely community so strong. Our OMVPs represent a wide range of roles, industries, and regions, but they all share a common passion: helping others succeed with the Optimizely platform.

We're excited to see how this new cohort will continue to contribute their expertise, share practical knowledge, and inspire the broader ecosystem in the months ahead.

👉 Know someone who should be an OMVP? Encourage them to apply or nominate them directly

Getting Started with Forms in Optimizely SaaS CMS

Tue, 08 Sep 2026 10:03:30 GMT

Getting Started with Forms in Optimizely SaaS CMS.

Two more database surprises when upgrading from CMS 11 to CMS 13

Tue, 08 Sep 2026 09:45:31 GMT

Back in June I wrote about four database surprises when upgrading from CMS 11 to CMS 13 (old post). Here are two more, found on another CMS 11 upgrade. Both come from the same place — the site name — and both break the new Application Manager while the public site keeps working as if nothing were wrong.

The background for both: the CMS 13 upgrade copies your site name verbatim from tblSiteDefinition into the new tblApplication table, where it becomes the application's identifier — with rules CMS 11 never had.

Whitespace in the site name: Application Manager won't even load the site

If the name has a trailing space ("My Swedish Site " — easy to have sat unnoticed for years), every attempt to view the site in Application Manager fails with:

System.NullReferenceException
at EPiServer.Cms.UI.Admin.ApplicationManager.Internal.CompositeApplicationRepository.ToModel(Application application)

The name is round-tripped as a URL route key, where the trailing space is lost. The repository lookup on the other side is an exact dictionary hit (StringComparer.OrdinalIgnoreCase — forgives casing, not whitespace), so it returns null, and ToModel dereferences it without a guard.

This one is sneaky twice over: the public site keeps working (content binds via GUIDs, host resolution is unaffected), and the stack trace ends in whatever middleware sits first in your pipeline — pointing you at your own code instead of the actual problem.

Fix: RTRIM the name columns and restart — the application dictionary is cached under ep:apps. SQL in the gist below.

Swedish characters in the site name: Application Manager loads — but nothing can be saved

With the whitespace gone, a name like "My Swedish Sité" loads and displays just fine. But try to save anything — a new hostname, for example — and you get a validation error saying the name isn't valid. Renaming the application in the UI doesn't help; the error keeps pointing at the old name.

The reason is in EPiServer.Applications.Application:

/// The name must start with a letter and can only contain
/// letters, digits, and underscores.
[Required]
[ResourceName] // ^[A-Za-z][_0-9A-Za-z]+\z — ASCII only
public string Name { get; private set; }

The name is validated on every save against ^[A-Za-z][_0-9A-Za-z]+\z — ASCII only. Any å, ä, ö or space fails it. And the kicker: Name has a private setter, so it cannot be changed through the admin UI or any public API. Save clones the stored application — old name and all — validates the whole entity, and fails on the stored name no matter what you type. A migrated site with a non-ASCII name is permanently unmanageable in Application Manager until the name is fixed directly in the database.

The working fix: set a new ASCII Name in tblApplication and keep the human-readable name in DisplayName, which only has a length limit and is what editors see. Nothing else is derived from the name — hosts, entry point and assets bind via keys and their own columns — so the rename is safe. Restart afterwards, same cache.

Both issues are reported to Optimizely: the missing null guard, the missing name validation/normalization at migration, and the absence of any rename path for names the migration itself created in an invalid state.

Wrapping up

Same lesson as last time, with two more entries for the pre-flight runbook: check your site names before the first CMS 13 boot — both for whitespace and against ^[A-Za-z][_0-9A-Za-z]+\z. Detection and fix SQL is in this gist — as always, read it, understand it, and run it at your own risk: [Gist]