Blogs

Building UI Extensions for Optimizely SaaS CMS

Thu, 15 Oct 2026 16:59:39 GMT

Introduction

Developers have been extending the functionality of Optimizely PaaS CMS for years using addons built in C# and deployed as NuGet packages. Where you have control of the code for the CMS, this is the optimum approach for seamless integration. As Optimizely SaaS CMS becomes a more common approach for composable architecture, the way we extend the CMS has had to change. To fill this gap, Optimizely have created a new feature for Optimizely Connect Platform (OCP) and SaaS CMS called CMS UI Extensions which is in beta at the time of writing.

A CMS UI Extension is an application built in Node.js and JavaScript that is deployed into the OCP. From there, your app can be installed into any SaaS CMS that is within your organisation. There are currently three ways that your CMS UI Extension can manifest within your SaaS CMS:

Sidebar: Appears within the CMS editor interface within a panel mounted to the right-hand side of the screen.
View: Mounts a standalone full-width page that is accessed via the Extensions option in the left-hand menu.
Property Editor: Replaces the built-in editor for a single content property of a declared type.

Setting Up Your Environment

To build apps for OCP, you need to be an Optimizely Partner or Customer with Developer access to an OCP environment. You may need to raise a ticket with Optimizely Support to activate the developer functionality for OCP for the first time. From there additional members of your team can be granted developer access by assigning the Developer role for OCP in the Admin Centre.

Once you have access to the OCP Developer Portal, generate an API key for the OCP CLI. Save the key to a credentials file at ~/.ocp/credentials.json and then install the CLI:

Windows:

# Create the folder
New-Item -Path "~/.ocp" -Name "home dir" -ItemType "directory"

# Create the credentials file
Write-Output '{"apiKey": "<your-api-key>"}' | out-file "~/.ocp/credentials.json" -encoding utf8

# Install OCP CLI
iwr -useb https://cli.ocp.optimizely.com/install.ps1 | iex

Mac:

# Create the folder
mkdir ~/.ocp (home dir)

# Create the credentials file
echo '{"apiKey": "<your-api-key>"}' > ~/.ocp/credentials.json

# Install OCP CLI
curl -fsSL https://cli.ocp.optimizely.com/install.sh | bash

You should then be able to verify access with the whoami command:

ocp accounts whoami

Before Building Your Solution

Before you get started with building your application you should look at installing the Optimizely OCP Skills for your AI coding assistant. Whether you clone these into your own repo or install them as a plugin is going to be your own decision. It does come with 4 skills, 2 of which are migration skills. If you are new to OCP app development, you can focus on the ocp-app-development and ocp-local-testing skills.

💡 Tip: These AI skills know how to build your app, how to register it, how to publish it for developer testing, beta testing and for production review. It is highly recommended that you use them.

Optimizely have also created a sample OCP CMS UI Extension called Unsplash Viewer that has both a sidebar panel and a full-page view. It is worth looking at this sample repository to see how the two entry points are configured and to understand the general architecture of a CMS UI Extension.

Thinking About Data

When building add-ons for Optimizely PaaS CMS, you had access to your own tables within the CMS database through tooling such as Entity Framework or by using the Dynamic Data Store. These options are not available to us when building CMS UI Extensions. OCP does however provide access to the following data stores which are key-value pairs:

Secrets Store: Allows the storing of primitive data types only and is your general purpose storage for sensitive data such as API keys. This store is accessible from the backend of your OCP application.
Settings Store: Allows the storing of primitive data types only and is the preferred place to store application settings, including sensitive data such as API keys. This data store can be accessed either by the backend of your application or as the settings form directly with the application settings within OCP.
Key Value Store: Allows the storing of primitive data types and complex JSON objects for short-term and long-term storage. Do not store sensitive data here. This data store is typically accessed by the backend of your application.
Shared Key Value Store: Works like the Key Value Store, but is accessible by both your application and third-party applications.

If you are planning to store a lot of data to the Key Value Store, consider co-locating the data as a JSON object. Each entry in the Key Value Store can be up to 400 KB in size and storing data together can reduce the number of API calls needed by your application.

If the data you are storing to the Key Value Store is intended to have a limited lifespan, e.g. 1 hour, then data should be saved with a TTL (Time to Live). Data saved without a TTL will have a lifespan limited to the application installation.

If you require data permenance, then you need to consider an alternative place to store your data. The Key Value Store is expected to be rebuildable in the same way that the Content Graph index is expected to be rebuildable. Any value without a TTL will be persisted for the life span of the application. If you need to reinstall or update the application or move it from one regional store to another, then the Key Value Store is completely reset.

Options for permance should include:

Using SDKs to store your data as content in the CMS or CMP.
Using a third-party data store accessible via API using an API key stored within the Settings Store.

Reviewing the Stott Security for SaaS CMS Solution

Stott Security for SaaS CMS is a CMS UI Extension port of the popular Stott Security add-on for Optimizely PaaS CMS. This has been built as a full-width page with a publicly accessible endpoint to be consumed by a separate headless frontend.

Solution Structure

The following is a folder and file structure for the Stott Security for SaaS CMS solution. I’m only including core files here to prevent information overload, but do check out my solution or the Optimizely Unsplash Viewer example.

- assets
  - icon.svg
  - logo.png
  - directory
    - overview.md
- forms
  - settings.yml
- src
  - backend
    - functions
      - CmsExtension.ts
      - CompiledHeaders.ts
  - cms-ui-extensions
    - SecurityConsole.view.tsx
- app.yml

You may notice that the code is split into two separate runtimes, the backend and the CMS UI Extensions:

Frontend
- Runs within an iFrame hosted within Optimizely CMS
- Code lives in src/cms-ui-extensions/
- Talks to the backend through context.extension.invokeFunction()
- Exposes endpoints through ExtensionContext
Backend
- Runs on OCP in the node22-cms-ext context
- Code lives in src/backend/
- Talks to
  - External APIs over HTTPS
  - OCP storage
  - Lifecycle APIs

Understanding the app.yml

The app.yml file contains the manifest for your CMS UI Extension. You can see the full YAML file for this solution on GitHub. The metadata for the application and all of its entry points and functions are declared within this file.

meta:
  app_id: stott_security_saas
  display_name: Stott Security
  vendor: mark_stott
  summary: Manage Content Security Policy and response headers for Optimizely CMS (SaaS).
  categories:
    - Content Management
  availability:
    - all

runtime: node22-cms-ext

ui_extensions:
  view:
    - name: stott-security-console
      entry_point: SecurityConsole
      display_name: Stott Security

functions:
  cms_extension:
    entry_point: CmsExtension
    description: Backend for the Stott Security console (draft CRUD and publish).
    accepts: cms_ui_extension

  compiled_headers:
    entry_point: CompiledHeaders
    description: Serves compiled security headers to the site head.

app_id: This must be a globally unique name for your application and it is permanent. Changing this name is essentially publishing the application a second time.
vendor: This is your vendor name and must match the vendor associated with your partner or customer organisation.
runtime: This must be node22-cms-ext for a CMS UI Extension and tells OCP that this application will be run in the CMS Extensions runtime operating on Node.js 22.
ui_extensions: This is where you declare your entry points into the CMS and can be declared as:
- view: A full-width embedded page.
- sidebar: A sidebar embedded in a panel on the right-hand side of the editor interface.
- property-editor: A replacement UI for a specific property type.
functions: This is where you declare your backend functions.
- entry_point: This is the name of your entry point.
- accepts: If you set this to cms_ui_extension, then it means the endpoint has no public URL and can only be accessed by the frontend using the invokeFunction() method. Omit this if you want to provide a public endpoint.

SDKs

A CMS UI Extension uses three Optimizely packages, plus a design system for the UI:

@zaiusinc/app-sdk (Backend): The OCP App SDK, which provides the framework for functions, storage and application lifecycle.
@optimizely/ocp-cms-ui-extensions-sdk (Build and Backend): A plugin for the OCP App SDK that adds support for defining and validating your app.
@optimizely/cms-extensibility-sdk (Frontend): The SDK for the CMS side of your extension that provides registration, delivery and access to your backend.
@optiaxiom/react (Frontend): The React implementation of Optimizely’s Axiom design system, which helps your extension look and feel like part of the CMS.

The plugin must be registered within ocp-app.config.mjs, otherwise your ui_extensions declarations will not be recognised and ocp app validate will fail:

import { defineConfig } from '@zaiusinc/app-sdk';
import { cmsUiExtensions } from '@optimizely/ocp-cms-ui-extensions-sdk';

export default defineConfig({
  plugins: [cmsUiExtensions()]
});

Backend

Each function declared within the functions section of your app.yml has a matching entry file within src/backend/functions/. The entry_point must match the name of the exported class, and that class must extend App.Function from the @zaiusinc/app-sdk package and implement a perform() method that returns an App.Response. One thing to watch out for is that the status code is the first argument for App.Response, which is the opposite of the standard web Response object.

import * as App from '@zaiusinc/app-sdk';

export class HelloWorld extends App.Function {
  public async perform(): Promise<App.Response> {
    return new App.Response(200, { message: 'Hello World' });
  }
}

Stott Security for SaaS CMS has two backend functions, one private and one public.

CmsExtension.ts

This is the private backend for the security console. Because it is declared with accepts: cms_ui_extension, it has no public URL and can only be called by the frontend using context.extension.invokeFunction(). Rather than creating a function per operation, the convention is to have a single function that accepts an action and a set of params and then switches on the action:

export class CmsExtension extends App.Function {
  public async perform(): Promise<App.Response> {
    const body = (this.request.bodyJSON ?? {}) as RequestBody;
    const action = typeof body.action === 'string' ? body.action : '';
    const params = body.params ?? {};

    switch (action) {
      case Actions.GetDraft:
        return ok(await this.getDraft(params));

      case Actions.SaveDraft:
        return ok(await this.saveDraft(params));

      case Actions.Publish:
        return ok(await this.publish(params));

      // ... additional actions

      default:
        return fail(400, ErrorCodes.UnknownAction, `Unknown action '${action}'.`);
    }
  }
}

This function is responsible for reading and writing the draft configuration, validating it, compiling it into a set of headers and then publishing the compiled headers. All of the data is held as JSON documents within the Key Value Store using storage.kvStore from the app SDK. Saving a draft and publishing are deliberately separate actions as an incorrect Content Security Policy can break a website, so making changes live should be an explicit act by the user.

Every response is wrapped in a consistent envelope of { ok: true, result } or { ok: false, error, message } so that the frontend has a single and predictable way of handling success and failure.

The function also uses functions.getEndpoints() to resolve the public URL of the compiled_headers function for the current installation. This allows the console to show the editor exactly which URL their website should consume.

CompiledHeaders.ts

This is the public endpoint that the head of the website calls in order to retrieve the published security headers. As accepts is omitted within the app.yml, OCP gives this function a public URL which contains a unique identifier for the installation. This matters because a regular App.Function resolves the installation from that URL and can therefore read the same Key Value Store that CmsExtension writes to. If this were declared as a global function, it would have no installation context and could only reach the Shared Key Value Store.

export class CompiledHeaders extends App.Function {
  public async perform(): Promise<App.Response> {
    if (this.request.method !== 'GET') {
      return new App.Response(405, { error: 'Only GET is supported.' });
    }

    try {
      const compiled = await readCompiled(scope);

      return new App.Response(200, {
        headers: compiled?.headers ?? [],
        publishedAt: compiled?.publishedAt ?? null,
        cacheSeconds: CACHE_SECONDS
      });
    } catch (error) {
      logger.error(`Failed to read compiled headers: ${String(error)}`);

      return new App.Response(503, { error: 'Compiled headers are temporarily unavailable.' });
    }
  }
}

A few design decisions are worth highlighting here:

The endpoint only reads the compiled headers, all of the work to compile the configuration happens once on publish rather than on every request.
The response includes a cacheSeconds value to encourage the consuming website to cache the response. Without this, every page request on the head would result in a request to OCP.
Having nothing published yet returns an empty array with a 200 status so the head can apply its own defaults, while a genuine failure returns a 503 so the head can tell the difference and fall back gracefully.
The response contract is identical to the compiled headers endpoint in the PaaS version of Stott Security, allowing a single consumer implementation to work with either product.
The endpoint is anonymous by design. These headers are visible on every response from the website anyway, but this is a deliberate decision and you should consider carefully what data you expose from any public function. If your data has privacy needs, then consider requiring an API Key.

📰 Please note that I will cover consuming this endpoint in a headless solution in a future article so as to not detract from the topic of this article.

Frontend

Each entry within the ui_extensions section of your app.yml has a matching entry file within src/cms-ui-extensions/. For Stott Security for SaaS CMS, this is a single view with an entry point of SecurityConsole, which maps to SecurityConsole.view.tsx. The frontend is built with React and is rendered within an iFrame inside of the CMS.

Your CMS UI Extension may have multiple entry points that manifest within the CMS in different ways. The naming convention for a UI entry file is as follows:

<Name>.<injection-point>.{ts,tsx,js,jsx}

// Examples
MyExtension.view.tsx
MyExtension.sidebar.ts
MyExtension.property-editor.js

SecurityConsole.view.tsx

The most important line in this file is at the very bottom. The register() method from the @optimizely/cms-extensibility-sdk package is how your extension is mounted into the CMS. This must be called exactly once at the top level of the module and never inside of a component or effect. The CMS passes an ExtensionContext into the callback, which you then pass down into your components:

import { register, type ExtensionContext } from '@optimizely/cms-extensibility-sdk';

function SecurityConsole({ context }: { context: ExtensionContext }): React.JSX.Element {
  useEffect(() => {
    void context.extension.setReady();
  }, [context]);

  // ... render the console
}

register((context) => <SecurityConsole context={context} />);

The ExtensionContext is your bridge between the frontend and both the CMS and your backend. Within the console, this is used for two key purposes:

context.extension.setReady() is called once the component has mounted to let the CMS know that the extension has loaded.
context.extension.invokeFunction() is used to call the private CmsExtension backend function.

All backend calls are wrapped within a small typed client, so the components never need to know about the transport:

const result = await context.extension.invokeFunction('cms_extension', { action, params });

A nice benefit of this approach is that there are no URLs, authentication cookies, CORS rules or CSRF tokens to manage within the frontend. The call never leaves the CMS host and OCP takes care of routing it to your backend function. It is worth noting that invokeFunction() will only reject on a transport failure, application errors are returned as a normal response with a non-2xx status code, so you will want to handle both.

The ExtensionContext offers more than the console needs. Which members are available depends on where your extension manifests within the CMS:

context.extension: Available to all extensions.
- setReady() tells the CMS that your extension has finished loading. The CMS may show a loading indicator until this is called.
- getDefinition() returns the id, display name, type and configuration of your extension.
- invokeFunction(functionId, parameters) calls a backend function. The functionId is the key under functions in your app.yml (e.g. cms_extension) and not the class name.
context.content: Only meaningful within a sidebar.
- get() returns a snapshot of the content currently being edited, including its key, version, locale and public URL.
- subscribe(callback) notifies you when the content being edited changes.
context.property: Only bound within a property-editor.
- get() returns the current value of the property, whether it is read-only and any property settings.
- set(value) updates the value of the property. This resolves to { success, error } rather than throwing an error, so make sure you check success.
- subscribe(callback) notifies you when the value of the property changes.

For both content and property, the subscribe() method only fires on subsequent changes. You should call get() to read the initial value and then subscribe() to receive later changes, otherwise your component will remain empty until something changes. The subscribe() method also returns a function that you should call to unsubscribe when your component unmounts.

The rest of the file is a fairly standard React component. The UI is built with Optimizely Axiom (@optiaxiom/react), which is Optimizely’s own design system, and helps the extension look and feel like a native part of the CMS. Every Axiom component reads its design tokens from the AxiomProvider, so this needs to wrap your entire extension or the components will render unstyled.

function Shell({ children }: { children: React.ReactNode }): React.JSX.Element {
  return (
    <AxiomProvider>
      <main>{children}</main>
    </AxiomProvider>
  );
}

There are a few other things to be aware of when building a view:

A view is a single mounted bundle. For my multi-tab interface I manage what is visible through component state rather than using a client side router.
The CMS already renders a title for your extension, so there is no need to repeat it within your own UI.
The ExtensionContext does not currently carry the identity of the user, so you cannot rely on it for attributing actions to a named editor.

App Directory Information

The assets folder of your repository is used to provide additional information for when your app is added to the app directory:

assets/logo.png and assets/icon.svg provide a logo to be used both within the card on the App Directory and within the summary card on the app page.
assets/directory/overview.md provides the content to be displayed in the Overview tab within OCP.

Application Settings

Your app must have a forms/settings.yml which is used to declare the settings form within OCP for your app. This allows you to manage data within the Settings Store for your installation of the app directly within OCP.

As Stott Security for SaaS CMS does not require any data from the Settings Store, my entry contains a single information entry:

sections:
  - key: about
    label: Stott Security
    elements:
      - type: instructions
        text: >
          Everything is configured in the security console...

Other options you can add to your settings.yml include the following, you can see a full description and examples of each option by viewing OCP Form Elements:

Toggle: An option you can toggle on or off.
Text: A plain input box, additional options can be set to change the input type to text, email, number or phone.
Secret: A secure field for sensitive data that will be displayed as asterisks. Data added to one of these fields cannot be retrieved through the settings form interface.
Select: A single-select field that renders differently based on the number of options provided.
Multi-Select: A multi-select field that renders differently based on the number of options provided.
Button: Allows for an action to be triggered within the form e.g. “Begin Integration”
Link Button: Allows for a link to an external URL and supports Mustache syntax for URL variation.
OAuth Button: Supports authentication with a third party in order to support integrations.
Divider: Renders a simple divider mid-form.
Instructions: Supports instructions to be displayed to the user written in Markdown.

Summary

CMS UI Extensions are a significant leap forward for Optimizely SaaS CMS. For the first time, we can extend the SaaS editor interface in the same way that we have been extending PaaS CMS with add-ons for years, whether that is a full-width tool, a sidebar that works alongside the editor or a custom property editor.

The technology choice also makes a lot of sense. CMS UI Extensions are built with Node.js & JavaScript potentially with frameworks such as TypeScript and React. These are the same tools that developers building headless solutions on SaaS CMS are already using every day. This means the barrier to entry is low for the teams most likely to want to build them.

There are still some challenges to work through. Data storage is limited to key value stores that are tied to the lifespan of the application installation, so anything that needs permenance requires some careful thought. As this is a new feature, best practices are also still emerging.

Overall, CMS UI Extensions are a really good addition to Optimizely SaaS CMS, and I’m looking forward to seeing what the community builds with them. If you are about to build your first CMS UI Extension, here are a few tips to help you get started:

Install the Optimizely OCP Skills as this will help your AI assistant to structure your application correctly.
Review Optimizely’s example CMS UI Extension: Unsplash Viewer
Consider app ownership and naming very carefully. App names must be unique and are permanent.
Consider whether you need data permanence and where that data will live.
Build for performance and leverage caching wherever possible.
If you are using the Key Value Store, co-locate your data as JSON to reduce the number of API calls.

Appendix

I'm a Platinum Optimizely MVP and the maintainer of two open source add-ons: Stott Security for SaaS CMS and PaaS CMS 12 & 13, and Stott Robots Handler for PaaS CMS 12 & 13. All of my writing is collated at https://www.stott.pro.

Cheapskate AI Translator: Because Translation Should Not Require a Second Mortgage

Thu, 15 Oct 2026 08:06:38 GMT

There is a particular kind of software project that begins with a detailed architecture document, a product roadmap, and a carefully assembled budget.

This is not that kind of project.

This project began with a simpler question:

Can I create language versions in Optimizely CMS without paying more for an LLM than I absolutely have to?

The answer is now an open source add-on: Cheapskate.AITranslator.

You can find the source code on GitHub and install the published package from the Optimizely NuGet feed.

The honest motivation

I am a cheapskate.

Not in the charming, coupon-clipping sense. In the practical engineering sense. If a free tier, a generous quota, or a small amount of careful request batching can do the job, I would prefer that to adding another monthly AI bill to the household budget.

The goal is not to avoid paying for good services forever. The goal is to pay as little as I can get away with while still delivering useful translations and a maintainable CMS workflow.

That means the add-on is designed around choice:

Google Gemini-compatible chat completions
GroqCloud-compatible chat completions
Microsoft Azure Translator
DeepL API Free
Custom OpenAI-compatible providers

Some providers offer free tiers, some offer free quotas, and some are inexpensive enough to be useful when a free option is not appropriate. The add-on does not assume that one provider, one pricing model, or one API will remain the best choice forever.

What the add-on does

Optimizely content editors can create draft language versions from the editor and choose whether to translate them with AI after the drafts are created.

The add-on can:

Create all missing language branches or one selected target language
Keep the new versions as drafts rather than publishing them
Optionally follow linked content in ContentArea properties
Translate language-specific text and Rich Text content
Preserve HTML structure while translating visible text
Run translation in the background after draft creation
Use different providers through one CMS settings screen

The workflow is intentionally modest. It creates drafts, starts translation work, and reports the job status. It does not pretend that an automated translation should bypass editorial review.

That last part is important. A translation engine can be very good and still occasionally produce something that makes a human editor stare at the screen for a while. Drafts are a useful place for that staring to happen.

The small trick that saves API calls

The add-on can combine multiple translatable properties into one JSON request instead of making one API request per property.

Without batching, a page with a title, teaser, body, call to action, and several blocks can turn into a small parade of API calls. That is inefficient, costs more, and can hit provider rate limits faster than necessary.

With batching enabled, the worker groups translation entries into bounded requests according to configured input and output token limits. The provider receives a structured payload, translates the values, and returns the translated entries for the background worker to write back to the draft.

In plain English:

Fewer trips to the API means fewer opportunities for the API to say, "Please slow down."

Batching does not remove provider limits, and it does not make an unlimited service out of a limited one. It simply uses the available quota more sensibly. The request-size limits remain configurable because different providers have different capabilities and pricing rules.

Why support several providers?

Because depending on one provider is an excellent way to discover that provider's outage page at the worst possible moment.

More seriously, different projects have different constraints:

A project may already have an Azure subscription and prefer Azure Translator.
A developer may want to use a free Gemini or GroqCloud quota.
A team may prefer DeepL for a particular language pair.
An organization may have its own OpenAI-compatible gateway.
A provider's model, pricing, quota, or terms may change.

The add-on keeps the CMS workflow stable while allowing the translation backend to change. Provider credentials and options live in CMS settings rather than in source control, and the custom provider option gives developers room to connect a compatible internal service.

This is not Optimizely Language Manager

A very important clarification: Cheapskate.AITranslator is not intended to replace Optimizely's official Language Manager add-on.

Language Manager is the official product for teams that need its supported translation-management workflow, integrations, governance, and product support. This add-on has a narrower and more developer-oriented purpose.

Cheapskate.AITranslator brings the implementation into the developer's control. The source code is available, the behavior can be inspected, and the add-on can be customized for a particular Optimizely CMS solution.

That may mean changing:

Which content properties are translated
How linked content is traversed
How prompts are written
Which provider is called
How batches are sized
How translation jobs are queued or reported
Which editorial safeguards are required

If your project needs an officially supported translation-management product, use Language Manager. If your project needs a small, inspectable starting point that your team can adapt, this add-on may be useful.

It is not a product-versus-product argument. It is a choice between a supported official solution and a source-controlled developer tool with a smaller scope.

Open source is the point

The most valuable part of this add-on is not the skate icon or the settings page. It is the ability to see what happens between clicking Create Language Versions and saving a translated draft.

Developers can review the code, change the translation rules, add provider behavior, adjust batching, and fit the workflow to their own content model. The add-on is deliberately not a sealed box that asks everyone to accept the same assumptions.

That also means responsibility comes with the freedom:

Review generated translations before publishing.
Protect provider credentials.
Check provider terms and quotas.
Test prompts and content types in a non-production environment.
Keep the add-on aligned with the CMS version used by the project.

Cheap is good. Cheap and mysterious is less good.

Getting started

The project targets Optimizely CMS 13 and .NET 10 on the main branch. The legacy CMS 12 implementation remains on the CMS-12-base branch.

Install the CMS 13 package with:

dotnet add .\YourCmsProject.csproj package Cheapskate.AITranslator --version 2.0.0

Then configure a provider under Settings > AI Translator, open localizable content in the editor, and use the Create Language Versions command.

The resulting versions are drafts. The AI translation runs in the background when enabled, and the editor remains responsible for the final content review.

Final accounting

The philosophy is simple:

Use the provider that fits the project.
Use free quotas where they are enough.
Batch requests so the quota lasts longer.
Keep the workflow in developer-controlled source code.
Spend money when spending money is actually justified.

That is the entire cheapskate strategy. It is not glamorous, but neither is discovering a surprisingly large AI invoice after a bulk translation job.

Cheapskate.AITranslator is open source under the MIT license: a small Optimizely add-on for teams that want draft language creation, optional AI translation, multiple provider choices, and a little more control over where the money goes.

Computed Fields in CMS 13 Content Contracts with Optimizely Graph

Wed, 14 Oct 2026 05:01:48 GMT

Content Contracts in Optimizely CMS 13 allow different content types to share a common structure when querying Optimizely Graph.

But what if the shared field doesn't exist as a stored CMS property, and its value needs to be calculated differently depending on the content type?

For example, imagine a search feature that includes articles, events, and images:

Articles use Heading as their search title.
Events use EventName.
Images use ImageTitle, falling back to their name.

We want all three to expose a common SearchTitle field in Graph, without adding another persisted property to each content type.

Here's a working approach tested with Optimizely CMS 13.3.0.

1. Define a Content Contract

First, define a Content Contract with a method that each implementing content type uses to provide its search title.

[ContentType]
public interface ISearchableContent : IContentData
{
    string GetSearchTitle();
}

Each content type implements the same contract but calculates the search title using its own properties. For example, an article page uses Heading, while an event page uses EventName.

public class ArticlePage : PageData, ISearchableContent
{
    public virtual string Heading { get; set; }

    public string GetSearchTitle() =>
        string.IsNullOrWhiteSpace(Heading) ? Name : Heading;
}

public class EventPage : PageData, ISearchableContent
{
    public virtual string EventName { get; set; }

    public string GetSearchTitle() =>
        string.IsNullOrWhiteSpace(EventName) ? Name : EventName;
}

Both content types implement the same contract but calculate SearchTitle differently. The same approach works for media types, such as images, using their own properties.

Make sure the relevant content types implement or are associated with the Content Contract in CMS so they can be queried together in Graph.

This keeps the calculation close to each content type and avoids maintaining a central switch statement.

2. Expose the Computed Field in Graph

Next, create an extension method and register it using Graph indexing conventions.

public static class SearchExtensions
{
    public static string SearchTitle(this ISearchableContent content)
        => content.GetSearchTitle();
}

services.AddContentGraph(configureConventions: conventions =>
{
    conventions.ForInstancesOf<ISearchableContent>()
        .IncludeField(
            x => x.SearchTitle(),
            IndexingType.Searchable);
});

The important detail is that SearchTitle is computed during indexing. We don't need to add a persisted SearchTitle property to our CMS models.

The resulting Graph schema exposes the field through ISearchableContent, regardless of the underlying content type.

3. Query It with the Graph C# SDK

The interesting part is that the computed field can also be used in strongly typed SDK queries.

First, define a lightweight result model:

public class SearchResult
{
    public string SearchTitle { get; set; }
}

Then query the Content Contract:

var query = graphClient
    .QueryContent<ISearchableContent>()
    .Where(x => x.SearchTitle().Contains("Optimizely"))
    .Limit(20)
    .IncludeTotal()
    .Fields<SearchResult>(x => x.SearchTitle);

var result = await query.GetAsync();

In our test, the SDK translated the filtering expression into GraphQL:

query ISearchableContentQuery {
  ISearchableContent(
    where: { SearchTitle: { contains: "Optimizely" } }
    limit: 20
  ) {
    items {
      SearchTitle
    }
    total(all: true)
  }
}

The query returned one matching event with SearchTitle equal to Optimizely Developer Webinar.

Here's the interesting detail: SearchTitle() is a C# extension method, not a stored CMS property. Graph indexing conventions expose it as a searchable field, and the Graph C# SDK translates the expression into a server-side GraphQL filter rather than filtering an in-memory collection.

We also verified sorting by the computed field, language-specific values, and recalculation after updating and publishing the underlying content.

Key Takeaway

By combining CMS 13 Content Contracts, Graph indexing conventions, and the Graph C# SDK, we can expose a shared searchable field across different content types while keeping the calculation specific to each type.

No additional persisted CMS properties are required.

Keep computed field calculations lightweight and deterministic, since they run as part of the indexing process.

References

Opal Workflow Agents And The Graph Webhook Trap

Wed, 14 Oct 2026 01:06:16 GMT

What we did?

We built a compliance review workflow agent in Opal. The job was simple: when an editor submits a page for review in Optimizely CMS 13, the agent reads the content, checks it against defined compliance rules, and writes its findings back onto the item so a human reviewer sees them before approving.

One editorial action in, one review out. That was the whole contract. A complete run costs 100–130 credits and takes 2-4 minutes. This makes a single run fairly expensive on credits. Now picture that same run firing over and over, several at once, and the consumption climbs fast.

The trigger was the only open question. Opal workflow agents can fire a few ways — chat input, a schedule, email, or a webhook — but for a run that kicks off automatically when something happens in the CMS, the webhook is the one that fits. So something in Optimizely CMS had to notice “this page entered review” and POST to the trigger URL. The obvious source was Optimizely Graph. It’s pure configuration — register a webhook through the API, no CMS code to deploy — and it already models content changes, which is more or less what we were reacting to. So we started there: a Graph subscription pointed at the Opal trigger, filtered to the InReview status.

What we didn’t see coming?

The first run worked exactly as intended. An editor submitted a page, the status went to InReview, Graph synced, the webhook fired, and the agent ran its compliance check.

Then the agent did the one thing it was built to do: it wrote its findings back onto the page.

That write-back was a save. The save synced to Graph. The content was still InReview — writing findings doesn’t change an approval status — so Graph delivered a webhook for an InReview document, which is exactly the event we’d subscribed to. The agent fired again. Checked again. Wrote back again. Synced again.

By the time we were looking at it, we had four pages of execution logs: the same agent, on the same page, running over and over, several instances going at once. We started cancelling runs manually to stop them burning through credits. The agent was triggering itself, and nothing in the loop was going to stop it.

Nothing was broken, which is what made it hard. Graph was doing exactly what Graph does.

Why it looped?

Seeing the behaviour was easy. Finding the cause took a while. Two facts about Graph, neither of them a bug, combined into the loop:

Graph syncs on save, not on intent. It re-indexes whenever content is saved, published, moved, deleted, or expired. Our agent’s write-back is a save like any other, so every write re-syncs.

Status is part of a document’s identity. Graph identifies an indexed document as {contentGuid}_{version}_{locale}_{status}. Our write-back changed the content but left the status at InReview — so every re-sync produced the same InReview document, indistinguishable from the submit event we’d subscribed to. There was no status change to mark the work as handled, and no state anywhere saying “this one’s done.” So each sync looked like a fresh reason to run.

Underneath it, the mistake was conceptual: we were inferring an editorial decision from index activity. But the index was churning every time our own agent touched the page — and the agent never stopped touching the page.

The fix: subscribe to the decision, not the side effect

Optimizely CMS already raises an event for the exact moment we cared about. The approval engine exposes IApprovalEngineEvents, and its Started event fires once, when an approval instance begins — i.e. when a human submits for review. It’s raised by the approval lifecycle, not the persistence layer. Background saves, forced writes, and our own agent’s write-back don’t start approval instances, so they don’t raise it.

So instead of inferring the decision from Graph, we subscribed to it directly in the CMS solution and POSTed to the Opal trigger ourselves:

[InitializableModule] [ModuleDependency(typeof(EPiServer.Web.InitializationModule))] public class ComplianceReviewTriggerModule : IInitializableModule { private IApprovalEngineEvents _approvalEvents; // IContentLoader, IHttpClientFactory, config resolved in Initialize() public void Initialize(InitializationEngine context) { _approvalEvents = context.Services.GetRequiredService<IApprovalEngineEvents>(); _approvalEvents.Started += OnApprovalStarted; // raised once, on submit } private void OnApprovalStarted(object sender, ApprovalEventArgs e) { if (!e.IsContentApproval()) return; // approvals are generic var contentLink = e.GetContentLink(); // extension method if (ContentReference.IsNullOrEmpty(contentLink)) return; if (!_contentLoader.TryGet<MyCustomPage>(contentLink, out var page)) return; // scope to our content type // Mirror Graph's docId shape so the workflow is source-agnostic. var docId = $"{page.ContentGuid}_{contentLink.WorkID}_{page.Language.Name}_InReview"; _ = Task.Run(() => TriggerOpalAsync(docId)); // fire and forget, with a timeout } }

A few things that mattered in practice:

• ApprovalEventArgs has no ContentLink. Approvals are a general mechanism; content approvals are one implementation. You reach the item through the IsContentApproval() and GetContentLink() extension methods in EPiServer.Approvals.ContentApprovals.

• The Opal trigger wants auth. The webhook trigger takes an Auth Key and sends it as a header (e.g. Authorization: Bearer {token}). Our POST sets that header from config; a request that doesn’t match is rejected.

• We mirrored Graph’s docId shape in the payload, so the downstream workflow didn’t need to change. If we ever switch sources again, the agent doesn’t care.

• Fire-and-forget has a cost. Blocking the editor’s submit on an outbound call is a bad idea, so we don’t. The trade is that if Opal is unreachable the moment Started fires, that trigger is lost — at-most-once. For a review flow that’s fine, because an editor can resubmit. If it weren’t, we’d add retries or a durable queue.

Result: one submit, one execution. The write-back still syncs to Graph, but we’re no longer listening to Graph for this trigger, and writing content doesn’t start an approval — so there’s nothing left to re-fire. The loop was gone, not because we out-guarded it, but because we stopped listening to the wrong layer.

So when is Graph the right source?

The lesson isn’t “Graph is wrong.” Graph is excellent — for the thing it actually reports, which is content as the published world sees it.

Reach for Graph when:

• You’re reacting to content state, not editorial intent — a page got published, purge the CDN; rebuild the static site. This is Graph’s canonical use case, and duplicate deliveries are harmless because the second purge is a no-op.

• The consumer is idempotent — ISR cache invalidation, deploy hooks, downstream sync. Firing twice costs nothing.

• You don’t own the CMS codebase, or you’re on SaaS CMS. Graph is configuration, no deploy required.

• The consuming system is decoupled from CMS and you don’t want to couple to its internals.

Reach for a CMS server-side event (the code path) when:

• The trigger is an editorial decision — submitted, approved, rejected. That lives in the approval engine, and Graph can’t model it.

• Your workflow writes back to the item that triggered it. This is the one that bit us; any index-based trigger risks the same loop.

• Each execution is expensive. When a run costs real credits and minutes, precise firing matters far more than easy setup.

• You need business rules before firing — content type, language, site. Strongly typed C# beats filtering on payload shape.

For us it was a compliance review agent that wrote back to the page it reviewed, at 100+ credits a run. Three of those four boxes. Graph was the wrong tool for this job. We kept Graph for delivery-side concerns and moved the editorial trigger to the approval event. They answer different questions.

The takeaway

Both sources are honest. Graph faithfully reports that an indexed document changed. The approval engine faithfully reports that a person made a decision. Neither is broken.

The real question is which of those you care about — a document changing or a person deciding — and subscribing at that layer instead of inferring it from the one below. When a workflow fires more often than the business event behind it, the instinct is to bolt on a guard. Sometimes you need one. But first ask what your event source is actually reporting.

Ours was reporting every save. Our agent just happened to be the thing doing the saving.

cms13-scan: A Deterministic CMS 13 Readiness Scanner

Mon, 12 Oct 2026 10:09:07 GMT

Every CMS 12 to CMS 13 upgrade I have looked at starts the same way. Someone opens the solution and starts hunting. A text search for the APIs

Setting Up an Optimizely CMS 13 MCP Server Locally with Codex

Mon, 12 Oct 2026 04:41:05 GMT

Optimizely CMS 13 supports Model Context Protocol (MCP), allowing AI tools such as Claude and Codex to interact with CMS content and metadata through an MCP server.

In this post, I'll show how I configured the MCP server in my local CMS 13 Alloy project, connected it to Codex in Visual Studio Code, and used it to explore content types, create pages, and build a Visual Builder experience.

Prerequisites:

Optimizely CMS 13 (I'm using Alloy with CMS 13.3.0).
An MCP-compatible AI client (I'm using Codex in VS Code).
A local CMS instance running over HTTPS, for example, https://localhost:5000.

Configure the MCP Server

Install the Optimizely.Cms.Opal.Tools NuGet package (version 13.2.0 or later):

dotnet add package Optimizely.Cms.Opal.Tools --version 13.2.0

services.AddCmsMcpServer()
    .WithClientSecretAuthentication();

Then map the MCP endpoint and require client-secret authorization:

app.UseEndpoints(endpoints =>
{
    endpoints.MapContent();

    endpoints.MapMcp("/mcp")
        .RequireClientSecretAuthorization();
});

The MCP endpoint is now available at https://localhost:5000/mcp, or your application's configured HTTPS address.

Configure Client-Secret Authentication

Make sure a client secret is configured for your local CMS application. We'll use it to authenticate Codex when connecting to the MCP server.

Security note: Never commit your client secret to source control or expose it in screenshots.

Connect Codex in VS Code

Open Codex Settings → MCP servers → Add server and select Streamable HTTP.

Name: optimizely-cms
URL: https://localhost:5000/mcp
Bearer token env var: Leave empty.
Header: Authorization, with your configured client secret as the value.

Alternatively, configure the server in Codex's config.toml:

[mcp_servers.optimizely-cms]
type = "http"
url = "https://localhost:5000/mcp"

[mcp_servers.optimizely-cms.headers]
Authorization = "your-secret-value"

Replace the placeholder with your actual secret and enable the server in Codex Settings. The secret is passed directly in the Authorization header, without a Bearer prefix.

Configuring the local Optimizely MCP server in Codex.

Verify the Integration

With the CMS running, open a new Codex chat in VS Code and try:

List the available content types in my local Optimizely CMS instance using the MCP server.

Codex retrieved the registered content types, including StandardPage and StandardExperienceData, and could inspect their properties, locales, and available Visual Builder components.

You can also retrieve existing content:

Find the published content items of type ProductTestPage and show their properties.

These read-only operations confirm that Codex can access CMS content and metadata through MCP.

Codex retrieving content types from the local CMS instance.

Create Content Using Codex

Next, I asked Codex to create an unpublished page:

Create "MCP Demo Page" under Start using StandardPage. Add a heading and paragraph to MainBody, and save it as an English draft.

Codex created the page and updated its content through the MCP server.

I also tested Visual Builder:

Create an unpublished "Alloy Demo Experience" using StandardExperienceData, with a BlankSection containing a VisualBuilderTestBlock.

Codex created the experience using the existing CMS content types and Visual Builder components. Both items were saved as drafts without publishing.

The MCP Demo Page created through Codex and saved as a draft.

Troubleshooting Content Permissions

During content creation, I encountered an authorization error:

Access denied: You do not have permission to create content in this location.

The MCP client authenticated successfully with a CmsAdmins role claim, which was mapped to WebAdmins in the application configuration. Although the Start page granted Create permission to WebAdmins, the MCP client was still denied access.

The issue was resolved by explicitly granting the MCP Client permissions on the Start page through CMS access rights. Afterward, Codex could create and update content.

Granting the MCP Client access on the Start page resolved the create denial.

Security note: For this local demo, all permissions were enabled, including Publish and Administer. In a real environment, grant only the permissions needed for the intended operations.

Conclusion

With Codex connected to Optimizely CMS 13 through MCP, we were able to explore content types, create pages, and work with Visual Builder directly from VS Code.

One thing worth noting is that connecting successfully doesn't necessarily mean the MCP client has permission to create or update content. You'll still need to configure the appropriate access rights in CMS.

Handling SixLabors.ImageSharp vulnerability warnings in Optimizely CMS 12 (unofficial)

Sat, 10 Oct 2026 06:01:41 GMT

2nd UPDATED: we’ve gotten a SixLabors license file, CMS team is working on update ImageSharp to a safe version (both SaaS and Paas CMS) in this story CMS-57368

Written by Claude Opus 5.5 (Anthropic) on behalf of Cuong Nguyen, Optimizely Technical Support.

A note from Cuong: Thanks to Optimizely for giving me access to Claude, which made this kind of deep dive possible within a support ticket.

SixLabors.ImageSharp is one of the most popular image libraries in the .NET world. Chances are it's in your solution too, even if you never added it yourself. Then one morning you open the project, run a build like any other day, and the output is suddenly full of NU1902/NU1903 warnings. Nothing changed in your code. If TreatWarningsAsErrors is on, the build simply fails.

That's the story behind a lot of tickets we've been getting in Optimizely Support lately. This post covers where the dependency comes from, why "just upgrade ImageSharp" doesn't work, and the four options you have today, including a SkiaSharp-based IImageService sample.

1. What you'll see

$ dotnet list package --include-transitive --vulnerable

   Transitive Package          Resolved   Severity   Advisory URL
   > SixLabors.ImageSharp      3.1.11     Moderate   https://github.com/advisories/GHSA-gwg2-r3hj-4w44
                                          High       https://github.com/advisories/GHSA-j3p4-wp97-rph4
                                          High       https://github.com/advisories/GHSA-j9gm-c75j-xc9q
                                          Moderate   https://github.com/advisories/GHSA-wmxv-xphr-5c9g
                                          High       https://github.com/advisories/GHSA-jjfr-hcj7-qf5w

You'll also get NU1902/NU1903 during restore and build. With TreatWarningsAsErrors enabled, the build fails.

2. Where the dependency comes from

The CMS uses IImageService for thumbnails and the image editor. The default implementation lives in EPiServer.ImageLibrary.ImageSharp, which depends on SixLabors.ImageSharp:

EPiServer.CMS 12.34.x
└── EPiServer.ImageLibrary.ImageSharp  (>= 1.0.6)   ← NuGet picks the lowest matching version
    └── SixLabors.ImageSharp 2.1.11

NuGet resolves dependencies with the lowest applicable version rule (docs). So EPiServer.CMS 12.34.8 resolves EPiServer.ImageLibrary.ImageSharp 1.0.6, which brings in ImageSharp 2.1.11. This is standard NuGet behavior, not something specific to Optimizely packages.

To get a newer version, reference the CMS components directly instead of the EPiServer.CMS metapackage, and pin EPiServer.ImageLibrary.ImageSharp to 2.0.6:

<PackageReference Include="EPiServer.CMS.UI" Version="12.34.6" />
<PackageReference Include="EPiServer.Hosting" Version="12.24.1" />
<!-- ... -->
<PackageReference Include="EPiServer.ImageLibrary.ImageSharp" Version="2.0.6" />

That moves you to ImageSharp 3.1.11, which clears the older advisories but not the five listed above.

3. Why not force a newer ImageSharp?

The advisories above are fixed in ImageSharp 4.x. Six Labors changed the licensing model in 4.x, and Release builds require a license key (discussion). Forcing 4.x through Directory.Packages.props therefore gives you a build error unless you have a Six Labors license. The 3.1.x line, the last one usable without a license, still carries the advisories.

4. Your options

#	Option	Pros	Cons
1	Remove EPiServer.ImageLibrary.ImageSharp	No code, warnings disappear	No image processing: thumbnails and the image editor stop working
2	Provide your own IImageService, e.g. with SkiaSharp	Clean audit, features kept	Custom code that your team owns and maintains
3	Suppress the audit warnings	Quick	The vulnerable package stays in your solution
4	Wait for an updated EPiServer.ImageLibrary.ImageSharp	No custom code	No committed timeline today

On risk: the image service only processes media that authenticated editors upload through the CMS. It doesn't handle arbitrary anonymous input. That lowers the exposure, and editors validating images on upload lowers it further. Whether that's acceptable is a decision for your own security policy and threat model.

5. Option 2: a custom IImageService with SkiaSharp

IImageService is a public extension point with a single method:

public interface IImageService
{
    void RenderImage(Stream input, Stream output, RenderRequest request);
}

The default implementation maps each ImageEditorCommand like this, and a replacement should do the same:

ImageEditorCommand	Default (ImageSharp)	SkiaSharp equivalent
Grayscale	Grayscale() (BT.709)	SKColorFilter.CreateColorMatrix with BT.709 coefficients
Crop	Crop(rect)	DrawBitmap(src, -left, -top)
FlipX / FlipY	Flip(Horizontal/Vertical)	canvas.Scale(-1, 1, cx, 0) / Scale(1, -1, 0, cy)
Resize	ResizeMode.Stretch	DrawBitmap(src, destRect, Mitchell)
ResizeKeepScale	ResizeMode.BoxPad + BackgroundColor	fit the box, no upscaling, center, Clear(bg)
Rotate	Rotate(deg), canvas expands	Translate + RotateDegrees on an expanded canvas

Packages

Remove EPiServer.ImageLibrary.ImageSharp and add SkiaSharp. If you reference the EPiServer.CMS metapackage, switch to individual component references first (see section 2). The metapackage brings EPiServer.ImageLibrary.ImageSharp in transitively, so you can't remove it otherwise.

<!-- remove: <PackageReference Include="EPiServer.ImageLibrary.ImageSharp" Version="..." /> -->
<PackageReference Include="SkiaSharp" Version="4.153.1" />
<!-- Required on Linux, containers and DXP: -->
<PackageReference Include="SkiaSharp.NativeAssets.Linux.NoDependencies" Version="4.153.1" />

The service

ResizeKeepScale matters most, because thumbnail generation calls it with BackgroundColor = "#00000000". The full implementation:

using EPiServer.ImageLibrary;
using SkiaSharp;

namespace YourSite.Business.Imaging;

/// <summary>
/// SkiaSharp-based replacement for EPiServer.ImageLibrary.ImageSharp's DefaultImageService,
/// which pulls in vulnerable SixLabors.ImageSharp versions. Mirrors the default behavior:
/// same commands, ResizeKeepScale = ImageSharp "BoxPad" + background color, ZoomFactor applied last.
/// </summary>
/// <remarks>
/// Skia only encodes PNG, JPEG and WebP. GIF/BMP/TIFF output is not supported (NotSupportedException),
/// and animated GIF input is flattened to its first frame.
/// </remarks>
public class SkiaImageService : IImageService
{
    private static readonly SKSamplingOptions ResizeSampling = new(SKCubicResampler.Mitchell);
    private static readonly SKSamplingOptions RotateSampling = new(SKFilterMode.Linear);
    private static readonly SKSamplingOptions CopySampling = new(SKFilterMode.Nearest);

    // ITU-R BT.709 luma, same coefficients as ImageSharp's Grayscale().
    private static readonly float[] GrayscaleMatrix =
    [
        0.2126f, 0.7152f, 0.0722f, 0, 0,
        0.2126f, 0.7152f, 0.0722f, 0, 0,
        0.2126f, 0.7152f, 0.0722f, 0, 0,
        0, 0, 0, 1, 0,
    ];

    public void RenderImage(Stream input, Stream output, RenderRequest request)
    {
        ArgumentNullException.ThrowIfNull(input);
        ArgumentNullException.ThrowIfNull(output);
        ArgumentNullException.ThrowIfNull(request);

        var image = Decode(input);
        try
        {
            foreach (var operation in request.Operations ?? [])
            {
                image = Replace(image, Apply(image, operation));
            }

            if (request.ZoomFactor != 1f)
            {
                var width = (int)Math.Floor(image.Width * request.ZoomFactor);
                var height = (int)Math.Floor(image.Height * request.ZoomFactor);
                image = Replace(image, Resize(image, width, height));
            }

            Encode(image, output, request);
        }
        finally
        {
            image.Dispose();
        }
    }

    private static SKBitmap Decode(Stream input)
    {
        using var codec = SKCodec.Create(input)
            ?? throw new NotSupportedException("The source image format is not supported.");

        var info = codec.Info
            .WithColorType(SKImageInfo.PlatformColorType)
            .WithAlphaType(SKAlphaType.Premul);

        return SKBitmap.Decode(codec, info)
            ?? throw new NotSupportedException("The source image could not be decoded.");
    }

    private static SKBitmap Replace(SKBitmap current, SKBitmap next)
    {
        current.Dispose();
        return next;
    }

    private static SKBitmap Apply(SKBitmap source, ImageOperation operation) => operation.Command switch
    {
        ImageEditorCommand.Grayscale => Grayscale(source),
        ImageEditorCommand.Crop => Crop(source, operation),
        ImageEditorCommand.FlipX => Draw(source.Width, source.Height, canvas =>
        {
            canvas.Scale(-1, 1, source.Width / 2f, 0);
            canvas.DrawBitmap(source, 0, 0, CopySampling);
        }),
        ImageEditorCommand.FlipY => Draw(source.Width, source.Height, canvas =>
        {
            canvas.Scale(1, -1, 0, source.Height / 2f);
            canvas.DrawBitmap(source, 0, 0, CopySampling);
        }),
        ImageEditorCommand.Resize => Resize(source, operation.Width, operation.Height),
        ImageEditorCommand.ResizeKeepScale => ResizeKeepScale(source, operation),
        ImageEditorCommand.Rotate => Rotate(source, operation.Angle),
        _ => throw new InvalidOperationException($"Unknown command {operation.Command}"),
    };

    private static SKBitmap Draw(int width, int height, Action<SKCanvas> draw)
    {
        var bitmap = new SKBitmap(width, height, SKImageInfo.PlatformColorType, SKAlphaType.Premul);
        using var canvas = new SKCanvas(bitmap);
        canvas.Clear(SKColors.Transparent);
        draw(canvas);
        return bitmap;
    }

    private static SKBitmap Grayscale(SKBitmap source)
    {
        using var filter = SKColorFilter.CreateColorMatrix(GrayscaleMatrix);
        using var paint = new SKPaint { ColorFilter = filter };
        return Draw(source.Width, source.Height, canvas => canvas.DrawBitmap(source, 0, 0, CopySampling, paint));
    }

    private static SKBitmap Crop(SKBitmap source, ImageOperation operation)
    {
        var area = SKRectI.Create(operation.Left, operation.Top, operation.Width, operation.Height);
        if (area.IsEmpty || !SKRectI.Create(source.Width, source.Height).Contains(area))
        {
            throw new ArgumentOutOfRangeException(nameof(operation), $"Crop area {area} is outside the image bounds.");
        }

        return Draw(area.Width, area.Height, canvas => canvas.DrawBitmap(source, -area.Left, -area.Top, CopySampling));
    }

    private static SKBitmap Resize(SKBitmap source, int width, int height)
    {
        var size = TargetSize(source, width, height);
        return Draw(size.Width, size.Height, canvas =>
            canvas.DrawBitmap(source, SKRect.Create(size.Width, size.Height), ResizeSampling));
    }

    /// <summary>ImageSharp BoxPad: fit inside the box without upscaling, center, fill the rest with the background color.</summary>
    private static SKBitmap ResizeKeepScale(SKBitmap source, ImageOperation operation)
    {
        var box = TargetSize(source, operation.Width, operation.Height);
        var scale = Math.Min(1f, Math.Min(box.Width / (float)source.Width, box.Height / (float)source.Height));
        var width = Math.Max(1, (int)MathF.Round(source.Width * scale));
        var height = Math.Max(1, (int)MathF.Round(source.Height * scale));
        var destination = SKRect.Create((box.Width - width) / 2, (box.Height - height) / 2, width, height);
        var background = ParseColor(operation.BackgroundColor);

        return Draw(box.Width, box.Height, canvas =>
        {
            canvas.Clear(background);
            canvas.DrawBitmap(source, destination, ResizeSampling);
        });
    }

    private static SKBitmap Rotate(SKBitmap source, double degrees)
    {
        var radians = degrees * Math.PI / 180;
        var cos = Math.Abs(Math.Cos(radians));
        var sin = Math.Abs(Math.Sin(radians));
        // Round before Ceiling so right angles don't grow by a pixel from floating point noise (50.0000001 -> 51).
        var width = (int)Math.Ceiling(Math.Round(source.Width * cos + source.Height * sin, 3));
        var height = (int)Math.Ceiling(Math.Round(source.Width * sin + source.Height * cos, 3));

        return Draw(width, height, canvas =>
        {
            canvas.Translate(width / 2f, height / 2f);
            canvas.RotateDegrees((float)degrees);
            canvas.DrawBitmap(source, -source.Width / 2f, -source.Height / 2f, RotateSampling);
        });
    }

    /// <summary>Same as ImageSharp: a 0 dimension is derived from the other one, keeping the aspect ratio.</summary>
    private static SKSizeI TargetSize(SKBitmap source, int width, int height)
    {
        if (width == 0 && height > 0)
        {
            width = Math.Max(1, (int)MathF.Round(source.Width * height / (float)source.Height));
        }

        if (height == 0 && width > 0)
        {
            height = Math.Max(1, (int)MathF.Round(source.Height * width / (float)source.Width));
        }

        if (width <= 0 || height <= 0)
        {
            throw new ArgumentOutOfRangeException(nameof(width), $"Invalid target size {width}x{height}.");
        }

        return new SKSizeI(width, height);
    }

    /// <summary>Parses ImageSharp-style hex colors (#RGB, #RGBA, #RRGGBB, #RRGGBBAA). Empty means white.</summary>
    private static SKColor ParseColor(string value)
    {
        if (string.IsNullOrEmpty(value))
        {
            return SKColors.White;
        }

        var hex = value.TrimStart('#');
        // Skia expects the alpha first (#ARGB / #AARRGGBB).
        var argb = hex.Length switch
        {
            4 => hex[3..] + hex[..3],
            8 => hex[6..] + hex[..6],
            _ => hex,
        };

        return SKColor.TryParse(argb, out var color)
            ? color
            : throw new ArgumentException($"Invalid background color '{value}'.", nameof(value));
    }

    private static void Encode(SKBitmap image, Stream output, RenderRequest request)
    {
        using var pixmap = image.PeekPixels();
        var quality = Math.Clamp(request.Quality, 0, 100);

        var encoded = request.MimeType switch
        {
            "image/png" or "image/x-icon" =>
                pixmap.Encode(output, new SKPngEncoderOptions(SKPngEncoderFilterFlags.AllFilters, PngZLibLevel(request.Quality))),
            "image/jpg" or "image/jpe" or "image/jpeg" or "image/pjpeg" =>
                pixmap.Encode(output, new SKJpegEncoderOptions(quality)),
            "image/webp" =>
                pixmap.Encode(output, new SKWebpEncoderOptions(SKWebpEncoderCompression.Lossy, quality)),
            _ => throw new NotSupportedException($"Not supported image format [{request.MimeType}] when creating images."),
        };

        if (!encoded)
        {
            throw new InvalidOperationException($"Failed to encode image as [{request.MimeType}].");
        }
    }

    /// <summary>Same quality -> compression mapping as the default service: 100 = level 0 ... &lt;20 = level 9.</summary>
    private static int PngZLibLevel(int quality) => quality < 0 ? 6 : Math.Clamp(10 - quality / 10, 0, 9);
}

Two details that are easy to miss:

Channel order (ParseColor). ImageSharp parses #RRGGBBAA, Skia parses #AARRGGBB. Rotate the hex string before parsing, or #00FF0080 comes out as a different color.
90° rotation (Rotate). cos(90°) evaluates to 6e-17, not 0, so Math.Ceiling(50.00000000000001) gives 51 and the output gains an extra pixel. Round before taking the ceiling.

Registration

using EPiServer.ImageLibrary;
using YourSite.Business.Imaging;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services
            .AddCmsAspNetIdentity<ApplicationUser>()
            .AddCms();

        // Replaces EPiServer.ImageLibrary.ImageSharp for thumbnails and the CMS image editor.
        services.AddSingleton<IImageService, SkiaImageService>();
    }
}

The CMS only registers a fallback IImageService when none exists (TryAddSingleton), so your implementation takes precedence. Without any registration, that fallback throws InvalidOperationException the first time it's resolved.

$ dotnet list package --include-transitive --vulnerable
The given project `Alloy` has no vulnerable packages given the current sources.

Known limitations

Skia encodes PNG, JPEG and WebP only. GIF, BMP or TIFF output throws NotSupportedException, so the image editor won't work for those formats. Thumbnails aren't affected, because the CMS always stores them as .png.
Skia can't decode TIFF, so TIFF uploads get no thumbnail. The upload itself still succeeds, because the CMS handles thumbnail errors.
Animated GIFs are flattened to the first frame.

Note: this sample is not an officially supported Optimizely package. It's provided as guidance, and you own it once it's in your solution. Test it against your own media library before you deploy.

6. Option 3: suppress the warnings

<ItemGroup>
  <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-gwg2-r3hj-4w44" />
  <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-j3p4-wp97-rph4" />
  <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-j9gm-c75j-xc9q" />
  <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-wmxv-xphr-5c9g" />
  <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-jjfr-hcj7-qf5w" />
</ItemGroup>

Suppressing only hides the warning, the vulnerability is still there. Record the decision (reason, owner, review date) wherever your team tracks accepted risks.

7. Option 4: wait for an updated package

An updated EPiServer.ImageLibrary.ImageSharp would remove the problem at the source. We can't share a timeline for that yet. If you go this route:

Watch the Optimizely release notes for a new EPiServer.ImageLibrary.ImageSharp version, or check from the command line:
```
dotnet list package --outdated --include-transitive | grep -i imagelibrary
```

Combine it with option 3 in the meantime, and add a review date so the suppression gets removed once the update ships:

<!-- TEMP: waiting for an EPiServer.ImageLibrary.ImageSharp update without the vulnerable ImageSharp.
     Review by: 2026-12-31. Owner: @team-cms -->
<NuGetAuditSuppress Include="https://github.com/advisories/GHSA-j3p4-wp97-rph4" />

If you're on option 2, moving to the official package later means deleting your IImageService implementation and its registration.

References

SixLabors/ImageSharp, 4.x license discussion: https://github.com/SixLabors/ImageSharp/issues/3205#issuecomment-6062121101
Optimizely IImageService API: https://world.optimizely.com/CsClassLibraries/cms/EPiServer.ImageLibrary.IImageService?version=12
SkiaSharp: https://github.com/mono/SkiaSharp
NuGet dependency resolution: https://learn.microsoft.com/nuget/concepts/dependency-resolution
NuGet Audit: https://learn.microsoft.com/nuget/concepts/auditing-packages
Advisories: GHSA-gwg2-r3hj-4w44, GHSA-j3p4-wp97-rph4, GHSA-j9gm-c75j-xc9q, GHSA-wmxv-xphr-5c9g, GHSA-jjfr-hcj7-qf5w

Optimizely CMS 12 on .NET 10: Fixing a Siteimprove TypeMismatchException

Fri, 09 Oct 2026 21:58:00 GMT

Recently, while upgrading an Optimizely CMS 12 solution from .NET 8 to .NET 10, we encountered a frustrating exception that initially looked like a CMS...

The post Optimizely CMS 12 on .NET 10: Fixing a Siteimprove TypeMismatchException appeared first on Madhu Anbalagan's Blog.

What made Scheduled Jobs faster in Optimizely CMS 13.3.0

Fri, 09 Oct 2026 06:00:00 GMT

A look under the hood at the update that made scheduled jobs faster.

New DDS explorer addon for Optimizely CMS

Thu, 08 Oct 2026 18:27:59 GMT

I wanted to be able to manage Dynamic Data Store from within Optimizely CMS, so I created another addon.

Queryable or Searchable? How indexing type changes your Optimizely Graph query

Thu, 08 Oct 2026 13:06:39 GMT

The Property Indexing Type on a CMS field decides whether Optimizely Graph will return it, filter it, or run full-text search on it. Default, Queryable, Searchable, and Disabled each change the GraphQL query.

How to Build Optimizely CMS 13 with Visual Builder in .NET

Thu, 08 Oct 2026 11:30:15 GMT

A code-first guide for .NET developers moving from Optimizely CMS 12 to CMS 13, covering Visual Builder: ExperienceData, Sections, Elements, tag helpers and styles.

Supercharging Optimizely DXP Troubleshooting with the Azure Copilot Observability Agent

Thu, 08 Oct 2026 09:10:07 GMT

If you’ve logged into the Azure portal recently to check the Application Insights for your Optimizely DXP environment, you might have noticed a new toggle in the Logs UI labelled simply: "Agent." And as you create a new query, being prompted with help from the Observability Agent

Application Insights gives us many very useful tools, including recent updates such as Grafana dashboards that can help us view key information about our application. We technical specialists in the Optimizely DXP stack should be familiar with working within the investigate, monitoring, and usage areas.

However, one key pain point has been working with and remembering Kusto Query Language (KQL) but with recent updates in Application Insights and this default enabled on the Optimise DXP, this can now be a lot easier.

Instead of writing complex Kusto Query Language (KQL) to figure out why your modern Optimizely Commerce 15 checkout is dragging, or why your CMS 12 editors are experiencing slow load times, you can now ask plain-English questions.

In this post, we’ll explore how to leverage this AI agent specifically for web apps running on Optimizely DXP, focusing on the exact types of telemetry, anomalies, and performance metrics that matter most for modern CMS 12/13 and Commerce 14/15 solutions.

The Modern Optimizely DXP Telemetry Landscape

Before we talk to the AI, we need to understand the data. Optimizely DXP environments (Integration, Preproduction, Production) automatically wire up Application Insights. For applications running on modern .NET (like CMS 12/13 and Commerce 14/15), this captures:

Requests: Server-side ASP.NET Core page loads, Content Delivery API calls, and Optimizely Graph queries.
Dependencies: SQL Database queries, external API calls (payment gateways, ERPs), and internal Optimizely services.
Exceptions: Server-side errors and handled exceptions.
Custom Events: Business logic milestones captured via TelemetryClient.

Historically, correlating a spike in Exceptions with a slowdown in Dependencies required mastery of KQL join statements. Now, the Observability Agent handles the translation. Let's look at how this plays out across the platform.

Scenario 1: Debugging Commerce 14/15 Checkout and Asynchronous Operations

Optimizely Commerce 14 and 15 fully embrace asynchronous programming. A modern checkout process involves validating a serialised cart, recalculating promotions, calling an external tax API, communicating with a payment provider, and finally using SaveAsPurchaseOrderAsync() to convert the cart.

If conversion rates drop, the culprit is often a silent performance degradation in one of these external or asynchronous steps.

The Old Way (KQL)

To find the average duration of the order saving operation over the last 24 hours, you’d have to write:

dependencies
| where name contains "SaveAsPurchaseOrder" or name contains "IOrderRepository.SaveAsync"
| where timestamp > ago(24h)
| summarise AvgDuration = avg(duration), Count = count() by bin(timestamp, 1h)
| render timechart

The Copilot Way

Toggle the "Agent" switch to On and simply type:

"Show me a timechart of the average duration for dependency calls related to IOrderRepository.SaveAsync over the last 24 hours, grouped by hour."

What to Look For in Commerce 14/15:

When using the agent, focus your queries on the known bottlenecks of a modern e-commerce platform:

Cart Serialisation Latency: Commerce 14/15 stores active carts as JSON in the SerializableCart table. Ask the agent: "Are there any SQL dependencies related to the SerializableCart table taking longer than 500ms today compared to yesterday?"
Third-Party Payment Delays: "Show me the failure rate and average response time for external HTTP dependencies calling 'api.stripe.com' (or your payment provider) over the last 7 days."
Promotion Engine Overhead: "Did the average request duration of the /checkout API endpoint increase after our deployment at 2 PM today?"

You can also ask the agent to find root causes: "Why did checkout requests fail more frequently between 2 PM and 4 PM today?" The Copilot will analyse exceptions and dependency failures during that window and summarise the findings.

Scenario 2: Diagnosing CMS 12/13 Rendering and Headless Delivery

With CMS 12 and 13 running on ASP.NET Core, performance is incredibly fast out of the box. However, bottlenecks usually occur around custom block rendering, complex tag helpers, or heavy utilisation of Optimizely Graph and Content Delivery APIs in headless architectures.

Uncovering Headless and Search Bottlenecks

If your frontend Next.js application relies heavily on Optimizely Graph or Search & Navigation, a poorly optimised GraphQL query or .Filter() statement will cause cascading slowdowns.

Try prompting the Observability Agent with:

"Identify the top 5 slowest outgoing HTTP requests to our Optimizely Graph or Search endpoints over the last 3 days. What CMS pages or API routes were users requesting when these slow calls happened?"

The agent will automatically correlate the dependencies table with the requests table, saving you the hassle of writing complex cross-table joins.

Investigating ASP.NET Core Memory and Caching

CMS 12/13 utilises heavily optimised memory caching in .NET Core. If the cache is invalidated too frequently, you'll see a spike in SQL queries to the core CMS database.

"Has there been an unexpected spike in dependency calls to the core CMS SQL database in the last 12 hours compared to the previous week? If so, what are the most common SQL commands being executed?"

If an editor publishes a massive content change that clears a large portion of the cache, the Copilot can help you correlate that spike in database traffic directly to the time the editor hit "Publish."

Scenario 3: Post-Deployment Verification on DXP

Deploying modern .NET applications to Optimizely DXP involves swapping slots in Production. The moments immediately following a slot swap are critical. Instead of staring at a raw stream of logs, you can use the Copilot as an active monitor.

The Post-Deployment Checkup

After a deployment finishes, open the App Insights logs, activate the Agent, and ask:

"Summarise the health of the application over the last 60 minutes. Have any new exception types appeared that were not present in the 24 hours prior?"

The AI will parse the exceptions table, filter out the normal background noise, and highlight genuinely new errors—like a missed dependency injection in your Startup.cs or a misconfigured appsettings.json binding introduced by your latest Commerce 15 release.

If it finds something, you can follow up conversationally:

"For that new InvalidOperationException related to dependency injection, what was the exact stack trace?"

Best Practices for AI-Assisted Telemetry

While the Azure Copilot Observability Agent is a game-changer for Optimizely developers, it works best when you guide it properly:

Enrich Your Telemetry: Use ITelemetryInitializer in your CMS 12/13 codebase to inject custom properties. Add the CurrentLanguageBranch or CustomerGroup to every request. You can then ask the agent: "Are authenticated B2B users experiencing slower API response times than anonymous users?"
Track Custom Events: Log specific business events like TrackEvent("ItemAddedToCart") or TrackEvent("GraphQueryExecuted"). This allows you to ask the agent business-centric questions.
Be Specific with Timeframes: Vague questions yield vague answers. Always specify the time window (e.g., "between 10 AM and noon UTC yesterday").

Conclusion

The addition of the Azure Copilot Observability Agent to Application Insights drastically lowers the barrier to entry for deep telemetry analysis in modern Optimizely environments. By focusing your natural language queries on the specific architectural patterns of CMS 12/13 (like ASP.NET Core caching and Graph API calls) and Commerce 14/15 (like asynchronous cart processing), you can dramatically reduce your mean time to resolution (MTTR) and ensure a blazingly fast digital experience.

How can Niteco help you?

Niteco is the largest global certified Optimizely CMS and Commerce partner, and we are experts and specialists in the Optimizely agent platform. We have recently attended Opticon New York 2026 as a sponsored partner, and we'll be coming back next week to London. Come and find us at our stand, or by looking for our yellow trousers.

Optimizely

The largest global partner. Powered by technical excellence and innovation. Accelerated by AI.

400+

AI-trained experts

Certified by leading platforms like Optimizely, Microsoft, Contentful & Adobe.

2000+

Successful projects

We have vast experience from years of delivering digital platforms for clients in diverse sectors.

Optimizely MVPs

Largest team with OMVPs. Meaning the best & most experienced Optimizely minds will work with you.

As Optimizely's largest certified partner in Optimizely CMS, Commerce, and the agent platform, we can help you with any of your strategic initiatives globally around content, commerce, or your organisational AI.

If you would like help getting more out of your Optimizely DXP telemetry, get in touch with us at Niteco: https://niteco.com/contact-us/

Visual Builder Without Graph: Server-Side MVC Rendering in CMS 13

Wed, 07 Oct 2026 09:51:36 GMT

When teams

Writing a Catalog Entry the Low-Level Way. Part 2: The Writer

Wed, 07 Oct 2026 08:00:00 GMT

Upserting a catalog entry through CatalogContext and MetaDataPlus: ContentGuid, the meta class seam, response groups, and a create path that rolls back.

Migrate Optimizely DAM Assets from CMS 12 to CMS 13

Tue, 06 Oct 2026 12:04:10 GMT

Sites that used Optimizely DAM in CMS 12 need their asset references moved to the new Graph-backed content sources after upgrading. CMS 13.3 includes a scheduled job for this. This post covers how to configure it, run it and later on verify the results.

So, in CMS12 we supported DAM in the following properties:

After upgrading your site to CMS you will see all those images, videos and files that came from DAM as broken or empty, both in edit mode and on the live site:

This happens because the content still points to the old dam content provider. In CMS 13, DAM assets come through Optimizely Graph instead. The old references need to be moved over to the new format.

In CMS 13.3.0 we added a scheduled job that does this for you. This post explains how to set it up and what to check along the way.

What the job does

The job is called Optimizely DAM Legacy Asset Migration. It works in three steps:

1. It reads all old DAM references from the database and works out the new ID for each asset.
2. It goes through all content and updates the references. This covers published content, drafts, old versions, all languages and the trash.
3. It removes the old tracking records in CMP and deletes the old mapping rows from the database.

These property types are updated:

ContentReference
IList<ContentReference>
ContentArea, including inline blocks
Url
LinkItem and LinkItemCollection
XhtmlString
Local blocks and block lists

So all the properties defined in the below page type will be migrated successfully:

[ContentType(
    GUID = "BA5FBE47-E44A-44CD-BFAF-3CC21B0A2F9C",
    DisplayName = "DAM references test page",
    Description = "Contains every property type that can hold a reference to a DAM asset",
    GroupName = Globals.GroupNames.Specialized)]
public class DamReferencesTestPage : PageData, IDamReferences
{
    [Display(Name = "Content Reference", GroupName = SystemTabNames.Content, Order = 10)]
    public virtual ContentReference ContentReference1 { get; set; }

    [Display(Name = "Content Area", GroupName = SystemTabNames.Content, Order = 20)]
    public virtual ContentArea ContentArea1 { get; set; }

    [Display(Name = "Content Area Item", GroupName = SystemTabNames.Content, Order = 30)]
    [BackingType(typeof(PropertyContentAreaItem))]
    public virtual ContentAreaItem ContentAreaItem1 { get; set; }

    [Display(Name = "Link item", GroupName = SystemTabNames.Content, Order = 40)]
    [BackingType(typeof(PropertyLinkItem))]
    public virtual LinkItem LinkItem1 { get; set; }

    [Display(Name = "Link item collection", GroupName = SystemTabNames.Content, Order = 50)]
    public virtual LinkItemCollection LinkItemCollection1 { get; set; }

    [Display(Name = "Url", GroupName = SystemTabNames.Content, Order = 60)]
    public virtual Url Url1 { get; set; }

    [Display(Name = "Url to image", GroupName = SystemTabNames.Content, Order = 70)]
    [BackingType(typeof(PropertyImageUrl))]
    public virtual Url ImageUrl1 { get; set; }

    [Display(Name = "Image", GroupName = SystemTabNames.Content, Order = 80)]
    [UIHint(UIHint.Image)]
    public virtual ContentReference Image1 { get; set; }
    
    [Display(Name = "Block as property", GroupName = SystemTabNames.Content, Order = 90)]
    public virtual DamReferencesTestBlock BlockAsProperty { get; set; }
    
    [Display(Name = "Block list as property", GroupName = SystemTabNames.Content, Order = 100)]
    public virtual IList<DamReferencesTestBlock> BlocksAsProperty { get; set; }
}

Images, videos, documents and image and video renditions are all supported.

The job updates versions in place. It does not create new versions, so your version history stays the same.

Before you start

Make sure these things are in place first.

You are on CMS 13.3.0 or later.
DAM features are activated
DAM assets have finished syncing from CMP to Graph. If Graph is not ready, editors cannot see or pick the assets after the migration.
The Graph content sources for images, videos and files exist.
CMP credentials are set up. Without them, the job still moves the references but skips the cleanup step.
The Optimizely DAM Tracking Assets job runs without errors.
You have a full database backup. The job cannot be undone from the admin UI.

Setup

Add the packages to your project.

builder.Services.AddDamMigration();

Add the settings to appsettings.json. The job is turned off by default, so you need to turn it on.

{ "Optimizely": { "Cmp": { "Client": { "ClientId": "your-client-id", "ClientSecret": "your-client-secret" } }, "Cms": { "DamUI": { "TrackingEnabled": true }, "DamMigration": { "Enabled": true } } } }

There are more settings for batch sizes, concurrency and retries. The defaults should work for most sites.

Running the job

1. Go to CMS Admin > Scheduled Jobs.
2. Run Optimizely DAM Tracking Assets once to check that CMS can talk to CMP.
3. Open Optimizely DAM Legacy Asset Migration and click Start.
4. Wait for it to finish and read the message in the job history.

A good result looks something like this.

If some assets could not be moved, the message lists how many and why. The most common reasons are missing settings for an asset type or broken data in the old mapping table.

Check your content

When the job is done, open a few pages and blocks in edit mode. Look at images, videos, content areas and rich text. Check drafts and other languages too.

When the job stops early

The job is safe to run more than once. References that are already moved get skipped. If you stop the job halfway, everything done so far is kept, and the next run picks up the rest.

Cleanup can stop on its own in a few cases.

- No CMP credentials are configured.
- Some content belongs to an external content provider. The job skips that content and leaves the old records alone, because they might still be used.
- CMP returns an auth error or too many rate limit errors.

In all of these cases the content changes stay in place. Only the cleanup is skipped or stopped.

After the migration

Set Optimizely:Cms:DamMigration:Enabled back to false. This hides the job so nobody runs it by mistake.

Keep TrackingEnabled set to true. The Optimizely DAM Tracking Assets job then runs once a week and tells CMP which assets are used on your site.

A note on the trash

There is no setting to skip the trash, and that is on purpose. Editors can restore content from the trash at any time. If the job skipped it, the cleanup step would delete old records that restored content still points to. Those references would then be broken for good.

Please bear in mind that migration might take some time as we need to scan each content item version which holds a reference to a DAM asset.

Scheduler Delegation: Using Optimizely DXP Infrastructure for Queued Processing

Tue, 06 Oct 2026 08:46:00 GMT

At SYZYGY Techsolutions, we support Optimizely DXP projects at scale, so continuously identifying unique ways to optimize the application is an essential part of how we work. One pattern that has paid off repeatedly is scheduler delegation: moving expensive, recurring or bursty background work off user-facing instances and onto the dedicated scheduler instance, using infrastructure that DXP already provides.

This post walks through the problem, the architecture, the reasoning behind it, and the code needed to apply it in your own solution.

The problem: expensive work triggered from the request path

Imagine thousands of visitors performing a similar action at the same time, spread across several instances of your application. They might be clicking through a car configurator, where every choice of model, colour or engine asks which options can still be combined and which are available. Or they might simply be opening pages, each of which needs the website's translated texts in their language.

Resolving that action takes time. The answer depends on several data sources, each with its own rules: product rules, production planning and supplier stock for the configurator; the CMS, a translation management system and other applications for the texts. Yet the number of distinct questions is limited, and the answer does not need to be exact to the second. The final order confirms availability anyway, and a text that is a minute old is harmless.

So you cache the result. That solves the speed, but introduces new problems:

1. Cold starts. After a deployment, a restart or an expiry, the cache is empty and the first visitors get nothing or wait.

2. Repeated work. Many visitors hit the same empty entry at once, and each request calculates the same answer, overloading the underlying systems.

3. Instances out of sync. Every web instance has its own cache, recalculates on its own schedule, and may show a different answer than its neighbour.

Together these produce a cache stampede: the same heavy work done many times over, competing with visitor traffic for CPU, memory and connections to the source systems. Making visitors wait for the calculation only moves the problem onto them. The goal is to keep the request path fast, whatever the state of the cache.

Optimizely's built-in ISynchronizedObjectInstanceCache is a great fit for data that changes infrequently. Under high load in a multi-instance setup, however, we observed clear limits of its caching model for this kind of workload. Each instance keeps its own in-memory copy, and only invalidations travel between instances. Every instance that recalculates an entry and stores it sends an invalidation to all the others, which drop their copies and recalculate in turn. The result is a stream of cache-update events from every side, the same stampede repeated on every instance, and moments when instances serve different values or overwrite each other's results.

What DXP gives you: a scheduler instance

On Preproduction and Production, Optimizely DXP customers can request a dedicated scheduler instance, one per environment, next to the web instances that serve visitors. This instance:

does not receive user-facing requests;
is intended for backend work: scheduled jobs, background tasks and back-office operations performed by content editors;
is part of the same deployment, so it runs your code, your configuration and your initialization modules.

In other words, DXP already hands you a place where heavy work runs away from visitor traffic. Most teams use it only for classic scheduled jobs on a fixed timetable. Scheduler delegation extends it to event-driven, queued work: user-facing instances report that something is needed, and the scheduler instance does it.

The rest of the pattern relies on platform features that every DXP project already has:

Capability	Provided by	Role in the pattern
Cross-instance messaging	The CMS event system (IEventRegistry), which uses Azure Service Bus on DXP	Carries a small "something is missing" message from any instance to all instances
Scheduler awareness	SchedulerOptions.Enabled (EPiServer.Scheduler), which is only true on the scheduler instance	Lets a handler decide whether it should act on a message
Scheduled jobs	The CMS scheduled job engine (ScheduledJobBase, [ScheduledPlugIn])	Provides a recurring, restartable execution loop for batch processing
Shared state	Blob storage (IBlobFactory), the CMS/Commerce databases, or a persisted synchronized cache	Carries the finished result back to user-facing instances

Because all of this ships with DXP, the pattern runs entirely on infrastructure you already have.

Architecture overview

The flow, step by step:

1. Raise. A user-facing instance reads the calculated result from shared storage. If it is missing or stale, it returns what it has (stale data or a fallback) and raises an event that identifies what is needed. Raising is fire-and-forget and must never throw into the request.

2. Deliver. The event travels over the platform's event bus and reaches every instance.

3. Enqueue. Every instance receives the event, but only the scheduler instance acts on it: it places the item into an in-memory queue that keeps one entry per unique input.

4. Batch. A scheduled job runs at a fixed interval (for example every minute), drains the queue, and processes each unique input once.

5. Write back. The result is written to shared storage.

6. Read. User-facing instances pick up the result on their next read, with no direct communication between the scheduler and the web instances.

From the visitor's perspective, every request is answered immediately. The expensive work runs later on the scheduler instance, once per unique input.

Design decisions and the reasoning behind them

The code samples below are simplified C# against the Optimizely CMS 12 APIs. Logging, null checks and dependency injection details are trimmed for readability.

1. Events carry intent; data stays at the source

The event payload is only an identifier (for example { model, options }). It is small, cheap to serialize and well within message size limits. The scheduler fetches whatever data it needs from the source of truth when it processes the item. This avoids stale payloads and keeps the bus lightweight.

The payload must be serializable by the event system, and its type must be registered as a known event type:

using System.Runtime.Serialization;
using EPiServer.Events;

[DataContract]
[EventsServiceKnownType]
public class RecalculationRequest
{
    [DataMember] public string Model { get; set; } = "";
    [DataMember] public string Options { get; set; } = "";
}

2. An in-memory queue on the scheduler is enough

A durable queue (a dedicated Service Bus queue, a database table) is the obvious place for pending work. Here the work is idempotent and re-calculable, so a simple in-memory queue on the scheduler instance does the job:

If the scheduler restarts and loses its queue, the next request that sees a missing or stale result raises the event again.
Duplicate events are harmless because the queue keeps one entry per input.

Self-healing through the request path replaces durability. That removes persistence, retries, dead-lettering and cleanup from the design. This only holds if the work really is idempotent; for non-recoverable work, use a durable queue instead.

3. Batching and de-duplication give you load control

Because events are queued and drained on a timer, the cost of the system depends only on the number of unique inputs. Request volume and instance count drop out of the equation: a burst of thousands of misses collapses into a handful of resource (re)generations. The job interval becomes a single dial that trades refresh latency against background load.

4. A de-duplicating queue keeps producers fast and memory bounded

The queue is written by event handler threads (producers) and drained by the job thread (consumer). Keying it by the inputs means a burst of identical events occupies a single entry, so memory stays bounded during a miss storm. Draining swaps in a fresh dictionary atomically, so producers never wait for the batch. The queue is registered as a singleton, so the event handler and the scheduled job share the same instance:

using System.Collections.Concurrent;
using EPiServer.ServiceLocation;

[ServiceConfiguration(Lifecycle = ServiceInstanceScope.Singleton)]
public class RecalculationQueue
{
    private ConcurrentDictionary<(string Model, string Options), RecalculationRequest> _pending = new();

    public void Add(RecalculationRequest request) =>
        _pending.TryAdd((request.Model, request.Options), request);

    public IReadOnlyCollection<RecalculationRequest> Drain()
    {
        // A write racing the swap can be lost; the next miss raises it again.
        var drained = Interlocked.Exchange(ref _pending, new());
        return drained.Values.ToList();
    }

    public bool IsEmpty => _pending.IsEmpty;
}

5. One event rail, two routing modes

Local development, CI and single-node environments usually run without a scheduler instance. A configuration flag routes the same event differently, so one code path covers both setups:

Delegation on (Preproduction, Production): only the scheduler instance reacts, and it queues the item.
Delegation off (local, simple setups): only the instance that raised the event reacts, and it processes the item immediately on a background thread.

Both modes share the same read path and the same processing logic. Only the "who handles it, and when" decision changes, and that sits behind a configuration flag. This keeps the pattern easy to test locally and makes it safe to switch off.

The routing is encapsulated in an abstract initialization module. Concrete features only supply the event identity and the processing logic (template method pattern):

using EPiServer.Events;
using EPiServer.Events.Clients;
using EPiServer.Framework;
using EPiServer.Framework.Initialization;
using EPiServer.Scheduler;
using EPiServer.ServiceLocation;
using Microsoft.Extensions.Options;

public abstract class DelegatingEventModule<TRequest> : IInitializableModule
    where TRequest : class
{
    protected abstract Guid EventId { get; }
    protected abstract Guid RaiserId { get; }
    protected abstract void HandleOnScheduler(TRequest request);
    protected abstract void HandleLocally(TRequest request);

    private bool DelegateToScheduler =>
        ServiceLocator.Current.GetInstance<IOptions<DelegationOptions>>().Value.Enabled;

    private static bool IsScheduler =>
        ServiceLocator.Current.GetInstance<IOptions<SchedulerOptions>>().Value.Enabled;

    public void Initialize(InitializationEngine context)
    {
        var evt = ServiceLocator.Current.GetInstance<IEventRegistry>().Get(EventId);
        evt.Raised += DelegateToScheduler ? OnSchedulerRoute : OnLocalRoute;
    }

    public void Uninitialize(InitializationEngine context)
    {
        var evt = ServiceLocator.Current.GetInstance<IEventRegistry>().Get(EventId);
        evt.Raised -= DelegateToScheduler ? OnSchedulerRoute : OnLocalRoute;
    }

    private void OnSchedulerRoute(object sender, EventNotificationEventArgs e)
    {
        if (!IsScheduler) return;                  // web instances ignore it
        if (e.Param is not TRequest request) return;
        HandleOnScheduler(request);                // typically: queue.Add(request)
    }

    private void OnLocalRoute(object sender, EventNotificationEventArgs e)
    {
        if (e.RaiserId != RaiserId) return;        // only handle what this instance raised
        if (e.Param is not TRequest request) return;
        Task.Run(() => HandleLocally(request));
    }
}

A concrete module is discovered by the initialization engine through [ModuleDependency]:

[ModuleDependency(typeof(EPiServer.Web.InitializationModule))]
public class ConfiguratorRecalculationModule : DelegatingEventModule<RecalculationRequest>
{
    internal static readonly Guid Id = new("00000000-0000-0000-0000-000000000001");
    internal static readonly Guid Raiser = Guid.NewGuid();

    protected override Guid EventId => Id;
    protected override Guid RaiserId => Raiser;

    protected override void HandleOnScheduler(RecalculationRequest request) =>
        ServiceLocator.Current.GetInstance<RecalculationQueue>().Add(request);

    protected override void HandleLocally(RecalculationRequest request) =>
        ServiceLocator.Current.GetInstance<ConfiguratorCalculator>().Recalculate(request);
}

Four details matter here:

IsScheduler reads SchedulerOptions.Enabled, which the platform sets per instance. On DXP the scheduler is enabled only on the scheduler instance, so the check follows the real topology.
DelegationOptions is your own options class, bound from appsettings.json. It is the configuration flag that switches between the two routing modes.
RaiserId is generated once per process (Guid.NewGuid() in a static field). It lets an instance recognize its own events when delegation is off.
EventId is a fixed GUID. Every instance must use the same value to subscribe to the same event.

6. The read path is defensive

Reading the result and requesting a recalculation live in one service on the web instances. It follows a simple rule, stale data beats no data, and a failure to raise the event never reaches the visitor:

using EPiServer.Events.Clients;

public class ConfiguratorResultService(
    IEventRegistry eventRegistry,
    IResultStorage storage,
    ILogger<ConfiguratorResultService> logger)
{
    private static readonly TimeSpan Ttl = TimeSpan.FromMinutes(2);

    public ConfiguratorResult GetResult(RecalculationRequest request)
    {
        var entry = storage.TryRead(request);

        if (entry is null || entry.CalculatedAt < DateTime.UtcNow - Ttl)
        {
            RequestRecalculation(request);
        }

        return entry?.Value ?? ConfiguratorResult.Fallback;
    }

    private void RequestRecalculation(RecalculationRequest request)
    {
        try
        {
            eventRegistry.Get(ConfiguratorRecalculationModule.Id)
                ?.Raise(ConfiguratorRecalculationModule.Raiser, request);
        }
        catch (Exception ex)
        {
            // A failed raise only delays the refresh; the visitor still gets an answer.
            logger.LogWarning(ex, "Recalculation request for {Model} could not be raised", request.Model);
        }
    }
}

7. The scheduled job is the batch processor

using EPiServer.PlugIn;
using EPiServer.Scheduler;

[ScheduledPlugIn(
    DisplayName = "Recalculate configurator results on demand",
    GUID = "00000000-0000-0000-0000-000000000002",
    IntervalType = ScheduledIntervalType.Minutes,
    IntervalLength = 1,
    DefaultEnabled = true,
    Restartable = true)]
public class RecalculateOnDemandJob : ScheduledJobBase
{
    private readonly RecalculationQueue _queue;
    private readonly ConfiguratorCalculator _calculator;
    private readonly ILogger<RecalculateOnDemandJob> _logger;
    private bool _stopRequested;

    public RecalculateOnDemandJob(
        RecalculationQueue queue,
        ConfiguratorCalculator calculator,
        ILogger<RecalculateOnDemandJob> logger)
    {
        _queue = queue;
        _calculator = calculator;
        _logger = logger;
        IsStoppable = true;
    }

    public override void Stop() => _stopRequested = true;

    public override string Execute()
    {
        if (_queue.IsEmpty) return "Nothing to recalculate";

        var batch = _queue.Drain();

        var done = 0;
        foreach (var request in batch)
        {
            if (_stopRequested) break;
            try
            {
                _calculator.Recalculate(request);   // calculate and write to shared storage
                done++;
            }
            catch (Exception ex)
            {
                // One failing item must not abandon the batch; the next miss re-raises it.
                _logger.LogError(ex, "Recalculation failed for {Model}", request.Model);
            }
        }

        return $"Recalculated {done} of {batch.Count} items";
    }
}

Restartable = true makes the scheduler start the job again if the instance shuts down while it is running, and IsStoppable together with Stop() lets an operator end a long batch from the admin interface. Items dropped by a stop are simply requested again by the next miss.

Results in production

In one production implementation, the read path serves about 1,022,000 requests per day (absolute figures are scaled for confidentiality; the ratios are real):

1,000,000 hits (about 98%), answered from a fresh entry;
22,000 stale reads (about 2%), answered immediately with the previous result while the scheduler refreshes the entry;
0 misses. Misses only occur before the storage is first populated. After that, visitors receive the previous value of an expired entry until it is refreshed.

Before the pattern, each of those 22,000 stale reads would have been a miss: a visitor waiting for a synchronous recalculation, with several instances often recalculating the same entry at once. Stale reads now absorb that work, and the recalculation runs once per unique input on the scheduler instance. The exact numbers depend on traffic, the feature and the chosen TTL, but the shape stays the same: misses disappear and stale reads take their place.

What enables this architecture

The building blocks are the platform capabilities listed earlier. Three properties make them fit together:

Every instance runs the same deployment. Initialization modules subscribe to the event on all instances, and a single platform setting decides which one acts.
The control path and the data path are separate. Events travel over the bus, results travel through shared storage, and the scheduler and web instances never call each other. Either path can be replaced independently.
There is a single writer. Only the scheduler instance calculates and stores results, so every web instance reads the same value. Eventual consistency is confined to one place: the time until the next job tick.

The return path is a free choice

Any storage that every instance can read works as the return path. Blob storage is the simplest starting point and handles large results well. The CMS or Commerce database suits small structured results but adds load to a shared database. A synchronized cache gives the lowest read latency, provided the scheduler instance stays its only writer; an eviction then simply raises a new recalculation request. Whichever you choose, keep a short-lived local cache on the web instances so that shared storage is read once per interval rather than on every request.

Trade-offs and failure modes

Restarts, duplicate events, failing items and environments without a scheduler are covered by the design decisions above. Three trade-offs remain:

Concern	Behavior	Mitigation
Eventual consistency	A first-time miss is answered with a fallback until the next job tick	Choose an interval that matches business tolerance; pre-warm after deployments
Event delivery is best-effort	A message may be missed in rare cases	The next miss or stale read raises it again; the TTL bounds the impact
Shared scheduler capacity	The scheduler instance also runs every other scheduled job and the editors' back-office work, so a long batch competes with them	Keep per-item work bounded, watch batch duration, and move truly heavy work to a dedicated service

Observability is worth building from day one: log every miss, every raise, and the batch size per tick. The ratio between events received and unique inputs processed is a direct measure of how much work the pattern is saving.

When to use it

The problem section already describes the shape that fits: a limited set of repeated questions, slow answers from several sources, tolerance for slightly outdated results, and work that can be recalculated at any time. Besides configurators and translated texts, the same shape appears in accessory compatibility per model, dealer and store details per region, and filter options per product category.

Two further conditions are easy to overlook:

The answer contains no financial values, personal data or access decisions. Such data must be accurate and current on every request.
Visitors ask only a fraction of all possible questions. If every answer is needed anyway, a plain scheduled job that calculates everything is simpler.

Cases that look similar but fail one of these conditions:

Business case	Why it does NOT fit
Prices, discounts, taxes, delivery costs	Financial values shown to customers must be accurate at all times. An outdated value creates legal and reputational risk.
Stock or slot reservation at checkout	Visitors compete for the same item, which needs a synchronous, locked check.
Personal recommendations or account data	Inputs are unique per visitor, so de-duplication has nothing to merge, and personal data should stay out of shared storage.
Navigation or content filtered by permissions	Access decisions must be current. A stale answer can expose content.
Sitemaps and product feeds	Every answer is needed and read by machines on a timetable. A plain scheduled job is simpler.
Image renditions	Serving the original as a fallback defeats the purpose, and the number of variants is large. Resize on demand at the CDN.

Getting started checklist

1. Request a scheduler instance for Preproduction and Production through Optimizely support.

2. Identify one expensive, re-calculable operation currently done on the request path.

3. Define a small event payload and a stable event identifier.

4. Implement the read path: raise on miss or stale, never throw, always return something.

5. Implement the delegating module with both routing modes behind a configuration flag.

6. Add the de-duplicating queue and the scheduled batch job.

7. Pick the return path and a TTL that match your consistency needs.

8. Add logging and metrics for misses, raises and batch size.

9. Disable delegation locally; enable it in Preproduction and Production.

Conclusion

Scheduler delegation turns an under-used part of DXP into a small background processing system. Web instances report what they need over the event bus, the scheduler instance collects those requests and processes them in batches, and shared storage hands the results back. The request path stays fast, each heavy calculation runs once per unique input, and everything runs on infrastructure DXP already provides.

Thomas in the AI Discovery Era

Tue, 06 Oct 2026 02:48:33 GMT

Its been a while, but hope you haven't forgotten Thomas, our most loyal visitor, the one who suddenly stops showing up.
Not because he lost interest. Because he asked an AI tool the question he used to Google, got his answer in thirty seconds, and never came to the site at all.
That's the shift most brands haven't clocked yet. The front door moved. Search isn't the only way in anymore, and a lot of the traffic you're losing to AI never shows up as a loss in your analytics. It just quietly isn't there.
But here's the part worth sitting with: AI isn't only taking visits. It's also sending them, to the brands it decides are worth citing. Which means the game isn't over. It just changed.
I pulled apart what actually earns those citations, and the one tactic everyone's doubling down on that the 2026 data says barely moves the needle. Plus what it means for the visitor who lands on your site already halfway through a thought.

Read the full article here.

Gated Content on Optimizely Graph, Part 2: Keeping Graph in Step with the CMS

Tue, 06 Oct 2026 00:00:00 GMT

A correct ACL in the CMS is not enough: Graph evaluates access against the state available to it. That state can lag behind the CMS, and every cache between Graph and the browser adds a window of its own.

Optimizely Agent Platform - October 2026 State of Play

Mon, 05 Oct 2026 10:45:21 GMT

Overview

A month ago I wrote up my takeaways from Opticon New York (Opticon New York & The Strategy on Upgrading to CMS 13 & Commerce 15). The headline was that Opal has grown up: the platform as a whole is now the Optimizely Agent Platform, and the AI chat you work with day to day is now Mark.

The trouble is that the pace of delivery has been relentless. The 2026 release notes alone run to well over an hour of reading, with something shipping almost every week, and features have been renamed, moved, merged and superseded along the way. If you are a solution architect or technical lead trying to answer the simple question "what does the platform actually do today, and how is it put together?", it is genuinely hard to get a clean picture.

So this post is my attempt at a state-of-play roundup as of early October 2026, broken down by the core building blocks of the platform, with a focus on the architecture, configuration and governance details that matter when you are designing real solutions. Wherever I can, I call out what changed and when using the official release notes, and I flag the places where the documentation is still catching up.

FYI, I know this is quite a long document, and it is mostly AI-generated, with my review added in. It should be a really good update for anyone who's used the platform, trying to keep up with all the changes. I'll probably do one of these every 6 months.

A note on sources. Everything here is based on the Agent Platform documentation, the 2026 and 2025 release notes, and Optimizely's Opticon announcements, as they stood on 5 October 2026. Screenshots marked as from the documentation are reproduced with permission. Things move fast, so always double-check the docs before you commit to a design.

Also https://drive.google.com/file/d/1VLziEiYH4mSGEkiC3VrGJOTP_pSIwF0-/view?usp=sharing is a version of this document as a nice infographic for easier digestion

TL;DR for architects

Area	Where we are today
Naming	Opal → Optimizely Agent Platform (effective 1 September 2026). Mark is the personified AI; Mark-1 / Mark AI is the post-trained model family; Mark-IQ is the context layer; Mark-Bench is the open-source benchmark. The docs still say "Opal" almost everywhere.
Models	Six inference levels (Quick → Code) mapped to Gemini or Claude models. Admins pick a default model provider per instance; specialised agents can override both provider and level. Mark's own post-trained models are announced as "coming soon".
Orchestration	Chat automatically delegates to sub-agents (Mini / Fast / Deep tiers) in isolated contexts, with parallel fan-out, no recursion and a per-turn dispatch budget.
Context	Skills (formerly Instructions), Brands, Memory, Personal files and RAG (CMP, Graph, and now your own artifacts).
Tools	System tools, connector tools, remote MCP servers (bring your own as of July) and custom tools via SDKs for TypeScript, Python and C#. A large CMS 13 (PaaS) tool set landed from May onwards.
Agents	Agent Directory (70+ prebuilt), Agent Library (curated launcher), specialised agents, workflow agents (now with Code steps, parallel loops, nested workflows, trigger priority and version history).
Autonomy	Virtual Teammates with their own Opti ID, memory and scheduled jobs, plus Team Messages as the collaboration layer.
Governance	Input guardrails, the Quality tab (Output Evaluation, Execution Guardrails, Execution Advisor), Safe URL Browsing, agent sharing/visibility, custom roles, exportable audit logs and version history.
Commercials	Credits pooled across products, fixed complexity bands since March 2026, 200 complimentary credits per instance per month until the end of 2026.

1. What's in a name? Opal, Agent Platform and Mark

Let's get the naming sorted first, because it is the single biggest source of confusion right now.

Optimizely's support centre now labels the category as "Agent Platform (previously Opal)" and states that the rename to Optimizely Agent Platform took effect on 1 September 2026, with Mark (for Marketing) as the personification of the platform. At Opticon the brand was split into four parts:

Name	What it is
Optimizely Agent Platform	The overall platform: agents, workflows, tools, skills, governance and the admin app.
Mark	The personified AI you talk to. In practice, this is what we used to call Opal Chat and the in-product assistant.
Mark AI / Mark-1	A family of post-trained, open-weight-based models built specifically for marketing tasks. Optimizely positions these as roughly 10x more cost-efficient than frontier models on the same marketing work. The press release states they are coming soon to all Agent Platform customers, so treat these as announced rather than generally available.
Mark-IQ	The data and context layer the models draw on, including your experimentation history and web analytics.
Mark-Bench	An open-source benchmark of 285 tasks across 15 marketing functions with more than 6,000 grading criteria.

On Mark-Bench, it is worth being precise about the numbers, because two sets are in circulation. The Opticon press release reports Agent Platform at a 67% all-pass rate against 60% for Claude Code, at half the cost, on default configurations. Optimizely's own Camp Opticon write-up quotes 58% versus 52% at 2.1x cheaper. Both come from Optimizely running its own benchmark, so if you are using them in a business case, cite which figure and the configuration behind it.

The docs are mid-migration

As of today (early October 2026) the documentation still uses "Optimizely Opal" in nearly every page title, the release notes are still called "Optimizely Opal release notes", and the product UI in the doc screenshots still says Opal. So you will see three names for the same thing depending on where you look. In this post I use Agent Platform for the platform and Mark (Opal Chat) for the chat experience, and I keep the documentation's feature names where they have not changed.

Other renames and retirements in 2026

The platform rename is not the only one. These are the changes I have seen trip people up:

When	What changed	Impact
14 Jan 2026	The Connections tab moved into Settings → Product Connections.	Old guides point to the wrong place.
14 Jan 2026	New tools and registries are disabled by default; admins must enable them.	New system tools will not appear in agents until switched on.
5 Feb 2026	Skills (then "Instructions") became inactive by default on creation.	You must toggle Active on.
24 Feb 2026	"Threads" and "conversations" standardised to chats.	Cosmetic, but affects training material.
18 Mar 2026	The creativity (temperature) setting was removed from specialised agents because newer models no longer support it.	Existing values are ignored, not errors.
7 May 2026	Instructions renamed to Skills. Existing instructions now live under Context → Skills, with no behaviour change.	The biggest terminology change before the rebrand.
7 May 2026	The 128-tool cap on dynamic tool lookups was removed.	Bigger tool catalogues are now practical.
4 Jun 2026	cms_geo_apply and cms_geo_analysis (CMS SaaS) were decommissioned, replaced by the general CMS content tools.	Update any agents or workflows that reference them.

2. How the platform processes a request

Before going into features, it helps to understand the runtime model, because almost every feature plugs into one of its stages. Each prompt goes through roughly the following pipeline:

Prompt and intent extraction. Mark works out what you are actually asking for.
Skills. Relevant skills are selected and injected into the system prompt.
Contextual intelligence. Product data, content knowledge and workspace context are added.
Tool selection. The right tools and agents are chosen for the job.
Input generation and validation. Parameters are built and checked. If they are invalid, Mark asks you for clarification instead of calling the model, which saves credits.
LLM interaction. Foundation models are called through business accounts, and your data is not used for training.
Execute and refine. Tools and agents run, and the output is re-evaluated and iterated on.
Response. The result comes back, often as a canvas or an action card.

Source: Optimizely Agent Platform documentation

The way the docs describe the relationship between the building blocks is still the best mental model:

Skills define how the AI behaves and uses tools.
Tools provide capabilities, such as reading data or taking action.
Specialised agents package tools and skills into one well-defined task.
Workflow agents chain agents together behind a trigger.
Virtual Teammates (new in August) sit on top as persistent, autonomous roles that own jobs over time.

3. Models and inference

This is the area that has changed most under the bonnet in 2026, and it has direct cost and quality implications.

Multi-model by design

The Agent Platform launched on Google Gemini and from 15 March 2026 Anthropic's Claude models (accessed via Google Vertex AI) joined the line-up, with Anthropic becoming a sub-processor under the Optimizely DPA. If you are working with a client's legal or procurement team, that is the notice to point them to. Optimizely also states that the choice of model does not change how credits are consumed.

On 24 June 2026 model provider selection arrived at both the instance level and the specialised-agent level. Admins now choose a Default Model Provider in Settings → Chat. The docs position Gemini as fast, cost-effective and good for creative writing, and Claude as stronger for complex tool orchestration and code generation. Specialised agents can override the instance default.

Inference levels

The inference level controls both the model and how much "thinking" it does before responding. Balanced is the default.

Inference level	Best for	Google model	Claude model
Quick	Simple, fast tasks	gemini-3.5-flash-lite (medium thinking)	claude-haiku-4-5 (medium thinking)
Standard	Everyday tasks without deep reasoning	gemini-3.8-flash (low thinking)	claude-sonnet-5 (no thinking)
Balanced (default)	Everyday tasks that benefit from reasoning	gemini-3.8-flash (medium thinking)	claude-sonnet-5 (high thinking)
Complex	Multi-step planning and analysis	gemini-3.8-flash (high thinking)	claude-sonnet-5 (x-high thinking)
Pro	Nuanced evaluation and strategy	gemini-3.1-pro (medium thinking)	claude-opus-5 (high thinking)
Code	Code, plus anything needing maximum reasoning	gemini-3.1-pro (high thinking)	claude-opus-5 (x-high thinking)

Model mapping as published in the Inference level documentation (updated 2 October 2026).

The mapping is managed by Optimizely and changes without any action on your side. Two recent examples: on 14 August the Complex and Code levels were upgraded to claude-opus-5, and on 13 September the Standard, Balanced and Complex levels moved to Gemini 3.8 Flash. Note that the current table shows Complex on claude-sonnet-5 with x-high thinking rather than Opus, so the August note appears to have been superseded. Treat the inference-level page as the source of truth, not the release notes.

Admins set the organisation-wide default for chat; agent creators set a level per specialised agent that overrides it.

Source: Optimizely Agent Platform documentation

Sub-agents (released 17 September)

This is one of the most architecturally interesting releases of the year, and it has gone a bit under the radar. When chat (or a specialised agent) hits a self-contained sub-task, it now hands it off to a sub-agent that runs in its own isolated context and returns only the final result. Intermediate tool calls and documents never enter your conversation.

The motivation is classic context engineering: avoiding context bloat (re-reading huge tool outputs every turn) and split attention (one model juggling unrelated objectives).

Tier	Inference level	Extended thinking	Typical use
Mini	Quick	No	Extraction, classification, reformatting
Fast (default)	Balanced	Yes	General delegation needing judgement
Deep	Pro	Yes, with a higher token budget	Sustained multi-step reasoning

The key technical behaviours:

Parallel fan-out. Independent sub-tasks are dispatched concurrently; dependent ones run in sequence.
Multi-turn continuation. A sub-agent can be resumed with its context intact.
No recursion. Delegation tools are stripped from sub-agents, so there are no unbounded chains.
Per-turn dispatch budget. Individual calls and fan-out slots share one cap per turn.
Instance default provider. Sub-agents never override the configured model provider.
Zero configuration. They are installed and managed by Optimizely, cannot be edited or deleted, and do not appear in the Agent Directory.

The practical gotcha is in your logs. One chat message can now produce several rows in Agent Activity Logs (search for "sub"), each with its own credit total, attributed to the user who started the chat, with the model provider shown as Instance Default. Rows sharing the same execution time indicate fan-out. If a client asks why one question produced five log entries, this is why, and Optimizely's position is that it is the same work routed more cheaply rather than extra work.

4. The chat experience (Mark / Opal Chat)

Chat is still where most users meet the platform. It is available in the global navigation across Optimizely One and at opal.optimizely.com. (likely to be changed soon)

What's new in chat in 2026

The chat has matured from a simple prompt box into a proper agent console. In rough chronological order:

January. CSV uploads, Markdown in the input box, a toggle for the history panel, and dark mode and font-size settings.
February. Upload of .xlsx and .docx files, and an immediate "thinking…" indicator.
March. Skill mentions (type / to apply a skill) and "save this as a skill" directly from a conversation.
April. Message queuing (keep typing while Mark works), pinned conversations, recency-sorted history and undo for pasted content.
May. Chat modes to match output depth to the task, action cards (rich, interactive inline components instead of plain text), chat pills (one-click starter prompts), memory, and multi-turn mode for specialised agents.
June. A live activity stream with inline tool status and "context pickup pills" showing what context was pulled in, Escape to stop a response, PowerPoint and Word generation (via the code_execution tool) and an image editor.
June 30. The Agent Library on the chat homepage and Personalize Opal, a pinned onboarding agent that walks new users through connecting tools and building skills.
July. Conversation compaction (automatic and manual checkpoints for long chats), editing sent messages, rotating contextual tips, Agent Builder and Skill Builder inside chat, and Safe URL Browsing.
September. RAG for artifacts, so chat can draw on your own canvases.

For architects, compaction and sub-agents together are the important pair: they are Optimizely's answer to long-running, tool-heavy conversations getting slower, dumber and more expensive over time.

Chat everywhere: in-product and third-party surfaces

Chat is embedded across the stack, and that list keeps growing:

CMS 13. The Optimizely.Cms.OpalChat adds Opal to the platform under verson 13.2.0 but 13.2.0 and onwards have Mark chat is built directly in to the CMS (requires DXP and Opti ID)
CMS 12 (since October 2025, requires DXP and Opti ID), CMS SaaS, Commerce Connect (since September 2025), Configured Commerce, PIM (January 2026), CMP, Web and Feature Experimentation, Personalization, Analytics, ODP and Product Recommendations (beta from May 2026).
Slack. Now a verified app in the Slack Marketplace (February 2026).
Microsoft Copilot and Google Agentspace / Gemini Enterprise, the latter using the Agent-to-Agent (A2A) protocol for cross-vendor agent collaboration (both since September 2025).

5. The context layer: Skills, Brands, Memory, Personal files and RAG

If tools are what the platform can do, this layer is what it knows. It is also the part that has evolved the most conceptually this year, and it effectively forms the user-facing side of what Optimizely now calls Mark-IQ.

Skills (formerly Instructions)

Skills are the reusable rules, context and behavioural guidelines that shape output, such as brand voice, product taxonomies, personas, compliance language or output formats. They come in two scopes: organisation skills (admin-managed) and personal skills (user-managed, since 30 March).

Source: Optimizely Agent Platform documentation

Each skill has a name, watchers, version history, an active flag, a /shortcut, a scope, a When to use activation trigger, the core skill body (rich text or Markdown), attached reference files, and a Where to use setting to scope it to a specific product instance.

Source: Optimizely Agent Platform documentation

How selection actually works matters a lot when you are designing a skills library:

All active skills available to the user are gathered.
Tool-triggered skills are applied automatically whenever their tools are in play, with no further evaluation.
The remaining skills are judged by a relevancy model that reads your latest message, the conversation history and each skill's Keywords or phrases field.
Matched skills are added to the system prompt.

Two consequences are easy to miss. First, the relevancy model looks only at the When to use field and ignores the skill's name and body during selection. Second, it is deliberately inclusive: it would rather include a borderline skill than miss a relevant one, and it matches semantically. A skill about "marketing promotions" can fire for a prompt about strawberries on sale. The fix is to write tight activation criteria, using "ONLY use for…", explicit "Do NOT use for…" exclusions, synonyms for narrow concepts, and mutually exclusive boundaries between related skills. Leaving When to use blank makes a skill shortcut-only.

Source: Optimizely Agent Platform documentation

The skills toolchain has also grown up considerably:

When	Change
5 Feb	Status column added; skills inactive by default
30 Mar	Personal skills; create skills from a chat; / skill mentions
14 Apr	Redesigned Activation Trigger section; better disambiguation when editing from chat
7 May	Instructions → Skills rename
26 May	File-explorer UI for skill files; PPTX/DOCX support in skills (with code execution)
27 May	Skills section in specialised agents, with a Choose skills picker to insert skills at exact points in a prompt
24 Jun	Skill watching; import/export across instances; scope switcher between personal and organisation; skill preview in the agent editor
30 Jun / 29 Jul	Skills builder GA, then Skill Builder inside chat

Brands (25 August) - Not fully out yet

Brands are a structured record of a brand's assets, colours, typefaces and usage rules, managed under Context → Brand. The clever bit architecturally is that publishing a brand turns it into a skill, so you get a single source of truth that image generation, decks, documents and social images all read from, instead of each feature holding its own copy. Brands move through Draft, Published and Default states, and an organisation can hold several brands with one default. Marketers can also bootstrap a brand on the fly when none exists.

Source: Optimizely Agent Platform documentation

For multi-brand clients this is a significant change. Previously you had to emulate this with a pile of brand-voice skills.

Memory (7 May) and Personal files (21 September)

Memory and personal files are now one system, and the implementation will look very familiar to anyone who has worked with coding agents: it is file-based.

Personal files are a persistent, per-user document store under Context → Personal Files, with a browser-based editor for text and Markdown files.
Memory lives in that same store. FACTS.md holds short durable facts, named notes files hold broader context, and RECENTS.md is a running summary of recent conversations and agent activity that Mark maintains. MEMORY.md is generated by Mark and is read-only.
Memories are captured either automatically or on request ("remember that…").
When Enable personal context is turned on for a specialised agent, context files such as AGENTS.md and MEMORY.md are made available to the agent before it starts. You can restrict the agent to a working directory (for example /context/agents/support) rather than exposing the whole store.

Source: Optimizely Agent Platform documentation

The distinction the docs draw is useful when you explain it to clients: skills capture how work gets done; memory captures who you are and what you are working on.

Retrieval-augmented generation (RAG)

RAG has expanded in three steps this year:

7 May. RAG for CMP. Permission-aware semantic and keyword retrieval across campaigns, tasks, assets, work requests and briefs, exposed as rag_retrieve_from_cmp (structured) and rag_retrieve_from_cmp_as_csv (tabular). Alongside it came rag_retrieve_from_optimizely_graph for CMS and CMP content via Optimizely Graph.
24 June. Folder and path filtering for CMP assets, relevancy explanations for suggested assets, and EU-region RAG.
17 September. RAG for artifacts. Chat can now search your own canvases, respecting artifact permissions and including artifacts shared with you.

Retrieval, embedding and indexing all happen inside Optimizely's infrastructure, and every query respects the user's roles and permissions. Admins can turn RAG on or off for direct chat under Settings → RAG Configuration, but note that agents can use RAG regardless of that setting, which is important if you are relying on the toggle for governance.

Source: Optimizely Agent Platform documentation

This is exactly where the CMS 13 upgrade story from my last post comes back in: Graph is the bridge that gets CMS and Commerce content into the agent platform's retrieval layer.

6. Tools: system, connector, remote MCP and custom

Tools are the actions. There are three families, and the year's big story is the arrival of MCP as a first-class citizen.

Source: Optimizely Agent Platform documentation

The Tools area is now split into four tabs: Connectors (each user links their own third-party accounts), Tools, Registries and External Providers (remote MCP servers and auth providers). You can filter tools by type (Remote MCP or Opal Tools), control per registry whether tools are active and whether they are enabled in chat, and restore chat defaults. Note that agents started from chat can use a registry's tools even when that registry is disabled for chat.

Source: Optimizely Agent Platform documentation

System tools for Optimizely products

Optimizely-maintained tools now cover practically every product. The ones that matter most for CMS and Commerce architects:

CMS 13 (PaaS), which arrived from 22 May:

Content types: paas_cms_list_content_types, paas_cms_get_content_type_details, paas_cms_create_content_type, paas_cms_update_content_type, paas_cms_delete_content_type
Property groups: paas_cms_list_property_groups, paas_cms_create_property_group
Content: paas_cms_get_content_data, paas_cms_update_content_item (creates a draft if no key is given), paas_cms_delete_content_item (moves to the waste basket), paas_cms_publish_content_item (immediate or scheduled), paas_cms_create_content_variation (locale variations)
Preview: paas_cms_get_content_preview_url, which lets the agent fetch and analyse rendered HTML
SEO and GEO: paas_cms_seo_analysis, paas_cms_seo_edit, paas_cms_geo_analysis, paas_cms_geo_apply (writes JSON-LD into a JsonLdTemplates property as a draft)
Display templates and media (29 July): paas_cms_list_display_templates, paas_cms_get_display_template, paas_cms_create_display_template, paas_cms_update_display_template, and paas_cms_upload_media (pulls a file from a public URL into CMS media)

Note that the GEO tools were removed from CMS SaaS in June but exist for CMS 13 PaaS. Do not assume parity between the two tool sets.

Optimizely Graph (CMS SaaS, CMS 12 and CMS 13): graph_content_type_schema, graph_content_graphql_executor and graph_content_search_tool (January), plus graph_pinned_result and graph_synonyms (14 August), so agents can now tune search relevance, not just query it.

Commerce: Commerce Connect became a product connection on 13 March, alongside the Product Promotion agent for Commerce Connect; Configured Commerce has system tools and a Restriction Group Creation agent; and Product Recommendations has a growing pr_* tool set for category, search, trend and algorithm performance reports and page management.

Beyond that there are tool sets for CMP (work requests, campaigns, milestones, structured content, asset updates), Experimentation and Personalization (including ten exp_ve_* Visual Editor DOM tools that power the AI variation development agent), Analytics, ODP, Campaign, PIM and Content Recommendations.

Connector tools and remote MCP

The connector catalogue exploded this year. Highlights include Microsoft 365 (Teams, Outlook, and from 18 September OneNote and sensitivity labels on OneDrive and SharePoint), Google Workspace (Docs, Sheets, Slides, Calendar and Gmail), Google Ads, Google Search Console, GA4, LinkedIn Ads, OpenAI Ads, Adobe Analytics, Salesforce CRM, Amplitude, Mixpanel, WordPress, Zoom, Crunchbase and Figma.

Remote MCP arrived in stages:

30 March. Remote MCP connector tools (starting with Atlassian and Conductor), with user-level authentication: the admin enables the server for the organisation, and each user authenticates their own account so actions carry their own identity and permissions.
7 May. Notion, Contentsquare, Contentful, Gamma, GitHub, Sanity and ClickUp.
29 July. Bring your own remote MCP server, plus HubSpot and ZoomInfo.
18 September. Braze and Fullstory, and Contentful Global and EU endpoints for data residency.

User-level authentication is the most important architectural point here. It gives you proper action attribution and per-user data scoping for third-party systems, rather than a single shared service account.

Custom tools

When nothing off the shelf fits, you build a custom tool. The contract is straightforward:

A tool manifest describing name, description, typed parameters, the execution endpoint and auth requirements.
A discovery endpoint (typically /discovery) that returns the manifest. If it is unreachable or malformed, the tools simply will not appear.
An execution endpoint, typically a POST with a JSON body returning JSON.
Authentication. Notably, the docs state that only Opti ID is supported for tool authentication at the moment, with other providers in the works.

Since 1 April, parameters support nested schemas (objects within objects, arrays of objects and enums), which makes richer integrations far less awkward. Tools are hosted either on Optimizely Connect Platform (OCP) or anywhere publicly reachable, and they are registered as a registry with a discovery URL that you can re-sync.

Official SDKs:

Language	Install	Notes
TypeScript / JavaScript	npm install @optimizely-opal/opal-tools-sdk	Express middleware, @tool() decorators, parameter validation, auth helpers
Python	pip install optimizely-opal.opal-tools-sdk (import as opal_tools_sdk)	FastAPI integration, auto /discovery
C# / .NET	See note below	ASP.NET Core integration, [Tool] and [RequiresAuth] attributes, DI support

A small but real gotcha for .NET teams: the docs currently show the install command as Install-Package OptimizelyOpal.OpalToolsSDK, but link to a NuGet listing named Optimizely.Opal.Tools. Check NuGet for the current package ID before you pin it in a project.

7. Agents

The four kinds of agent

Type	Who builds it	What it is
Agent Directory agents	Optimizely	Prebuilt, installable agents. There are now 70+ listed in the credits reference alone. Since 25 August they auto-update when Optimizely publishes a new version (on by default).
Agent Library	Optimizely (curated)	A browsable launcher on the chat homepage with more than 45 agents runnable in one click, without installation (30 June).
Specialised agents	You	One well-defined task, with your prompt template, tools, skills, variables, model provider and inference level.
Workflow agents	You	Multi-step automations of triggers, logic and agents. Still described in the docs as private GA and not available on all instances.

Source: Optimizely Agent Platform documentation

Directory agents worth knowing as a CMS or Commerce architect

The Directory has shifted from generic content helpers towards agents that act directly on the platform:

CMS 13 (PaaS): Content Model Creation, Page Builder, Content Analysis, GEO Schema Optimization and SEO Metadata Implementation. The Content Analysis agent produces a Markdown instruction set for a content type that the Page Builder agent then uses, which is a neat pattern for on-model content generation.
CMS SaaS equivalents, plus Content Refresh Analysis and FAQ Creation.
Commerce: Product Promotion (Commerce Connect) and Restriction Group Creation (Configured Commerce).
Experimentation: Experiment Conflict Checker, Backlog Prioritization (PIE scoring), Value Estimator, Program Overview, Program Health Review, Feature Experimentation Governance, and the Feature Flag Implementation agent, which outputs a portable SKILL.md for implementing a flag in your codebase. That is a nice nod towards developer agent tooling.
AI search and AEO: GEO Auditor, the Conductor AEO Gap Finder, AI Brand Visibility and Competitive Share of Voice agents, Profound Citation Gap Analysis, and Agent Visibility Analytics Insights.

Specialised agents: what's new

The agent editor has quietly become quite sophisticated over 2026:

Versioning with view, restore and branch-from-version (January).
Prompt template shortcuts for inserting variables, tools and skills inline; case-insensitive, unique variables; array/list inputs (May).
Example shots in the prompt template (February) and preferred output examples.
JSON export and import for moving agents between instances (April).
Multi-turn interaction mode in chat (May). Note that specialised agents always run single-turn inside workflows.
Model provider and inference level per agent (June).
Sharing and visibility (30 June): private, named people or the whole organisation, with view, run, edit and delete permission levels. New agents default to private where the feature is enabled, and it is not available on all tiers.
Agent Builder in chat (29 July), so agents can be created and iterated on conversationally.
Personal context and working directory settings (September).
A 60-minute timeout (since November 2025) to stop runaway executions burning credits.

Workflow agents: what's new

Workflow agents are made up of triggers (chat, schedule, webhook and email), logic (conditions, loops and code) and agents.

Source: Optimizely Agent Platform documentation

This has been the busiest area for releases:

When	Change
Jan	Add a trigger first when building
Mar	Builder-first creation flow; multi-branch conditions in a single node; email trigger improvements
Apr	Webhook trigger redesign with product instance selection and default CMP auth headers; parameter generation logs; helper messages for chat triggers; JSON download and copy; case-sensitive conditions
May	Workflow import/export; loop validation; schedule start time and no end date
Jun	Execution-log export to CSV/Excel with date ranges
29 Jul	Nested workflows; static versus predicted parameters (lock a variable or let the LLM fill it); Agent Update Warning before editing an agent used by a workflow; Version History for workflows; a new Execution Status Taxonomy
17 Sep	Code step (Python, JavaScript or Bash, with no external service needed); Run iterations in parallel on loops; trigger priority (Standard versus Background) so batch runs do not delay interactive ones

The Code step is a big deal. Previously, any deterministic transformation, such as parsing, maths or reshaping JSON between agents, meant either burning an LLM call or standing up a custom tool. Now it can live inline in the workflow. Together with nested workflows and static parameters, workflow agents are becoming a reasonable low-code orchestration layer rather than just a chain of prompts.

A credit note: a workflow's cost is the sum of the specialised agents it invokes, with no overhead for the workflow itself.

8. Virtual Teammates and Team Messages

This was the headline Opticon launch, released on 25 August (Not availible to everyone yet, especially partners)

What a Virtual Teammate is

A Virtual Teammate is a persistent AI worker built from the same components you already have, namely tools, agents and workflows, and jobs (workflows it runs on its own, on a schedule or on events), wrapped in a persistent identity with memory, a persona and a defined role. The distinction from an agent is continuity: an agent runs when you invoke it, whereas a teammate keeps working, holds context, improves from feedback and collaborates with other teammates.

The launch roster:

Chief of Staff: daily and weekly briefs, meeting prep and recaps, and competitive intelligence.
Marketing Analyst: scheduled, decision-ready GA4 reports.
SEO & AI Search Analyst: reasons across Search Console, GA4, Conductor and AI Visibility Analytics.
CRO Manager: monitors behaviour, analyses competitor UX and stages experiment configurations in Optimizely.
Personalization Strategist: builds and runs personalisation campaigns end to end.

Identity and access: the architect's checklist

This is the bit to get right in any implementation:

Each teammate gets its own Opti ID account (its own login and email, flagged as a virtual user). It shows up alongside people and fits into existing access and audit processes, and its usage is tracked separately from human usage.
It does not consume a product seat.
It gets only the access you grant it, with nothing inherited automatically from the person who hired it.
Inside Optimizely products it acts as itself. Outside Optimizely it acts through accounts a human connects on its behalf, usually the person who hired it. It cannot authorise third-party connections on its own.
For CMS 13 and CMS SaaS there is an extra step: after granting the teammate a role in the Opti ID Admin Center, you must also add it to the relevant content under Settings → Set Access Rights in CMS, with only the rights its jobs need.

Source: Optimizely Agent Platform documentation

That last point is another reason Opti ID is non-negotiable in CMS 13: Virtual Teammates are first-class principals in the identity layer, so the same governance you apply to people applies to them.

Autonomy controls

By default a teammate drafts and proposes, and a human approves via Team Messages. As confidence builds you can allow specific actions to run automatically within boundaries you set, and you configure its persona, values, who it may talk to, and which tools it can read, write or run. Admins enable teammates for the organisation and can pause or deactivate them; users and agent builders hire and configure their own. You can even switch identity to work in the platform as the teammate.

Team Messages

Team Messages is the real-time collaboration layer for people, teammates and agents, offering direct messages, group chats and channels, with sharing of files, agents and artifacts, mentions and persistent history. It follows you across products (an unread badge appears on the IM icon in CMP, Experimentation and elsewhere), and teammates also join meetings and share transcript summaries in Teams and Slack.

Source: Optimizely Agent Platform documentation

Alongside it sit the Tracker and Notifications (in-app tray, Notification Center, browser notifications since May, and skill-update and guardrail notification categories since June).

9. Quality, safety and governance

If Virtual Teammates are the accelerator, this is the brake, and it is what makes autonomous operation defensible to a client's risk team.

Input guardrails (29 July)

You define rules in plain language about what users may ask, and the platform trains a classifier to enforce them. This is useful for keeping usage on-topic and compliant without hand-maintaining block lists.

The Quality tab for specialised agents (1 June)

Source: Optimizely Agent Platform documentation

The Quality tab gives you three mechanisms:

Output Evaluation. An AI judge scores every run against up to 10 criteria, a baseline score between 75% and 95% (in 5% steps) and up to five examples. This builds on the preferred-output examples from December 2025 and the ability (January 2026) to promote past runs to evals.
Execution Guardrails. These learn what "normal" looks like for an agent and progress through Learning → Watching → Enforcing as successful runs accumulate. You control sensitivity and whether flagged runs are stopped automatically.
Execution Advisor. This has no configuration screen; it acts on what the other two detect. It recovers flagged runs with corrective guidance, retries failed tool calls with adjusted input, and reviews sensitive tool calls (email, publish, delete) with inline Approved or Blocked verdicts.

Each run therefore carries two independent verdicts, an Evaluation Score and a Guardrail Status, and a run can pass one and fail the other. The docs suggest starting with Output Evaluation and adding guardrails once behaviour has stabilised, which matches how I would roll it out.

Source: Optimizely Agent Platform documentation

Safe URL Browsing (29 July)

Every URL is screened before the platform browses it. Standard (always on) checks Google Web Risk for malware, social engineering and unwanted software. Advanced (opt-in per instance under Settings → Chat) adds a Cloudflare Radar deep scan in parallel, which can add up to 30 seconds of latency for URLs Cloudflare has not seen recently. Only http and https are accepted, redirect targets are screened too (which closes the open-redirect bypass), and links in emails processed by email triggers are also checked. Blocked requests return no partial content, only the threat category.

Source: Optimizely Agent Platform documentation

If a client's firewall blocks the platform from scanning their sites, there is a published allowlist of separate non-EU and EU egress IPs, last updated on 22 July. Check the admin guide for the current list rather than copying it from old project documentation.

Roles, auditability and change control

Roles: Opal Administrator, Agent Builder (new on 24 February, for people who build agents without being admins) and Opal User, plus custom roles in the Opti ID Admin Center.
Audit: Created By, Triggered By and Modified By on agents and skills; credit usage per run in logs; execution-log export with date ranges for specialised and workflow agents; and the Execution Status Taxonomy (July).
Change control: version history for specialised agents, skills and workflows; watchers on skills and agents; and the Agent Update Warning before editing an agent a workflow depends on.
Human in the loop for side effects: for example, send_email shows a confirmation "island" in chat (since December 2025), and Execution Advisor can gate sensitive tool calls.
Kill switch: generative AI can be turned off for an organisation in the Opti ID Admin Center. Be aware that turning it off means contacting Optimizely Support to re-enable it.

10. Artifacts and canvases

Outputs have also grown well beyond chat text:

Canvas (December 2025) is the working surface for documents, HTML, React/Next.js, CSV and PowerPoint content, with downloads in the relevant formats (February), an "Edit in canvas" button, a raw Markdown mode (May) and space-level sharing permissions with view, edit and manage access (June).
The Artifacts page (May) is a single searchable home for everything you have created, with sharing and, since September, RAG over artifacts.
PowerPoint and Word creation and editing (June), when the code_execution tool is enabled, now on-brand by default thanks to Brands.
The image editor (June) offers element detection and selection, brush transforms, batch edits and smart aspect ratios. (below)
Limitless 1:1 Personalization (June) generates landing pages per target account or segment, which is the capability I covered from the keynote last month.

11. Administration, data residency and credits

Administration essentials

The setup order has not changed: connect your product instances first under Settings → Product Connections. If an instance is not connected, it cannot use the platform's features.

Source: Optimizely Agent Platform documentation

Other settings to know about are the default model provider and inference level, RAG in chat, Advanced URL safety, and the email domain used for outbound email. Be careful with the email domain: it is a single subdomain prefix per instance, and it cannot be changed once set. Users without Opti ID can also be enabled (see "Enable Opal for non-Opti ID users" in the docs).

Data residency

The platform is hosted in the US and the EU, with the region chosen on your order form. Everyone uses the same URL, and routing to your region happens behind the scenes. Customer inputs and outputs are stored long-term in North America or the EU (Belgium), with no per-country selection. However, prompt processing goes through global model endpoints for availability and performance, so a prompt may be processed in any region, although the LLM does not retain it and the output returns to your region. EU app hosting arrived on 4 June and EU RAG on 24 June. If a client has strict residency requirements, that processing nuance is the one to raise early.

Credits and cost

Credits are pooled across all eligible Optimizely products.
Since 1 March 2026, usage falls into fixed complexity bands for predictability.
Every instance gets 200 complimentary credits per month from 1 October 2025 until 31 December 2026. This is worth noting for 2027 budgeting.
There are no per-user credit limits. You control spend by controlling who has access.
Usage is visible in the Opti ID Usage and billing dashboards, with monthly notifications, and in the redesigned Opal Agent Usage dashboard (30 June), which shows executions, credits, top agents and users, and weekly active users.

Complexity band	Average credits per invocation
Chat and basic agents	2
XS	10
S	30
M	70
L	130
XL	200

To give a sense of scale from the published per-agent figures: SEO Metadata Implementation for CMS 13 averages 120–200 credits, GEO Schema Optimization 40–60, Content Model Creation 30–80 and the Conductor AEO Gap Finder 180–200.

Who pays depends on the trigger: for chat and in-product invocations it is the invoking user, but for schedule, webhook and email triggers it is the user who created the trigger. Keep that in mind when you design shared automations. In practice, you probably want a dedicated owner (or, increasingly, a Virtual Teammate) owning scheduled workflows, so usage reporting stays meaningful.

12. 2026 at a glance

Month	Headline releases
Jan	Specialised agent versioning; prompt template shortcuts; Graph tools; CMS SaaS content tools; Experimentation and Personalization system tools; PIM chat; tools disabled by default
Feb	Agent Builder role and custom roles; Slack Marketplace app; canvas downloads; example shots; Visual Editor, CMP and Analytics tool sets
Mar	Claude models join (15 March); fixed-band credits (1 March); Commerce Connect product connection; personal skills; user-level auth for connectors; first remote MCP connectors; credit usage in logs
Apr	Agent JSON import/export; message queuing; nested parameter schemas for custom tools; CMS 13 Opal Chat NuGet; Idea Builder
May	Instructions → Skills; memory; Artifacts page; notifications; chat modes, action cards and chat pills; RAG for CMP and Graph; CMS 13 content tools; more remote MCP servers
Jun	Quality tab; EU hosting and EU RAG; model provider selection; skill import/export; PPTX/DOCX generation; image editor; Agent Library; agent sharing and visibility; Limitless 1:1 Personalization; Teams and Outlook tools
Jul	Agent Builder and Skill Builder in chat; input guardrails; Safe URL Browsing; conversation compaction; nested workflows; workflow version history; bring-your-own remote MCP; CMS 13 display template and media tools
Aug	Virtual Teammates; Team Messages; Brands; Directory auto-update; Graph synonyms and pinned results; CMS 13 Page Builder and Content Analysis agents
Sep	Rename to Agent Platform and Mark; Mark-1, Mark-IQ and Mark-Bench announced; sub-agents; RAG for artifacts; workflow Code step, parallel loops and trigger priority; personal files; LinkedIn and OpenAI Ads connectors; Braze and Fullstory MCP

For context, at the start of the 2025 release notes Opal was essentially a chat assistant embedded in individual products. The platform pieces, namely specialised agents, workflow agents, the Agent Directory, system tools and custom tools, only arrived on 9 September 2025. Everything in the table above has been built in the thirteen months since.

13. What this means for solution architects

Pulling this together, these are the points I would take into any design conversation right now:

Upgrade the foundations first. Opti ID (identity for humans and teammates), Graph (retrieval, search tuning and agent access to content) and product connections are the prerequisites for nearly everything above. This is the practical reason the CMS 13 and Commerce 15 upgrade is a strategic decision, not just a version bump.
Treat skills as code. With import/export, versioning, watchers and a selection model that only reads When to use, a skills library deserves the same discipline as any shared configuration: naming conventions, scoped activation criteria with explicit exclusions, review, and promotion between instances.
Decide your integration pattern deliberately. For each external system, the choice is now between an existing connector, a vendor's remote MCP server, your own remote MCP server, or a custom tool (on OCP or self-hosted). User-level auth on MCP and connectors gives better attribution; custom tools currently authenticate with Opti ID only.
Put deterministic logic in deterministic places. Use workflow Code steps and static parameters for anything that does not need an LLM, and keep specialised agents small and single-purpose.
Design for cost visibility. Choose the inference level per agent rather than defaulting everything to Pro, expect sub-agent rows in logs, and be deliberate about who owns scheduled and webhook triggers, since they pay.
Layer governance before autonomy. Input guardrails, Output Evaluation, then Execution Guardrails, and only then let Virtual Teammates act without approval, scoping their Opti ID roles and CMS access rights to exactly what their jobs need.
Use the docs carefully. They are excellent but moving fast: naming is mid-migration, workflow agents are still flagged as private GA, release notes can be superseded by reference pages (as with the inference mapping), and at least one SDK package ID is inconsistent. When it matters, verify in your own instance.

Summary

Twelve months ago, Opal was a promising chat assistant with a brand-new agent builder. Today the Optimizely Agent Platform has a multi-model runtime with managed sub-agent delegation, a layered context system (skills, brands, memory, files and RAG), an open tool ecosystem built around MCP, low-code workflows with real code execution, autonomous Virtual Teammates with their own identities, and a governance stack to keep it all in check. Mark is the friendly face on top, and Mark's own post-trained models are next.

For those of us designing solutions on Optimizely, the platform is no longer an add-on to CMS or Commerce. It is becoming the operational layer that sits across them, and the quality of what it can do depends directly on how well the underlying platform is connected through Opti ID, Graph and the product connections.

If you would like help shaping your agent platform strategy, building custom tools and MCP integrations, or getting onto CMS 13 and Commerce 15 so you can use all of this, get in touch with us at Niteco: https://niteco.com/contact-us/

Key references

Agent Platform documentation: https://docs.optimizely.com/agent-platform/docs
2026 release notes: https://docs.optimizely.com/agent-platform/release-notes
2025 release notes: https://docs.optimizely.com/agent-platform/release-notes/2025-agent-platform-release-notes
Inference level and model mapping: https://docs.optimizely.com/agent-platform/docs/inference-level
Sub-agents overview: https://docs.optimizely.com/agent-platform/docs/sub-agents-overview
Skills overview: https://docs.optimizely.com/agent-platform/docs/skills-overview
Tools overview: https://docs.optimizely.com/agent-platform/docs/tools-overview
Create custom tools (SDKs): https://docs.optimizely.com/agent-platform/docs/create-custom-tools
Virtual Teammates overview: https://docs.optimizely.com/agent-platform/docs/virtual-teammates-overview
Quality tab overview: https://docs.optimizely.com/agent-platform/docs/quality-tab-overview
Credits: https://docs.optimizely.com/agent-platform/docs/agent-platform-credits
Administrator guide: https://docs.optimizely.com/agent-platform/docs/get-started-with-agent-platform-for-administrators
Mark models and Mark-Bench press release (1 September 2026): https://www.prnewswire.com/news-releases/optimizely-introduces-purpose-built-ai-models-for-marketing-that-deliver-frontier-level-quality-at-a-fraction-of-the-cost-302865074.html
My Opticon New York write-up: https://world.optimizely.com/blogs/scott-reed/dates/2026/9/opticon-new-york--the-strategy-on-upgrading-to-cms-13-/