Blogs

Blogs2026-06-24T11:26:37.0000000Zhttps://world.optimizely.com/blogs/ Optimizely World Migrating from Find to Graph: Lessons Learned from a Real CMS 13 ProjectWhile migrating a search solution from Optimizely Search & Navigation (Find) to Optimizely Graph in CMS 13, I encountered several issues that were not immediately obvious from the documentation. Most of these issues were discovered through experimentation, debugging startup errors, investigating generated Graph schemas, and comparing behavior with Search & Navigation. Here are details about them: 1. Graph Conventions Only Existing Starting from CMS 13.1.0 It took me quite some time to figure out how to apply Graph Conventions based on the following documentation while working on a CMS 13.0.0 project: <a href="https://docs.developers.optimizely.com/content-management-system/v13.0.0-CMS/docs/indexing-conventions">https://docs.developers.optimizely.com/content-management-system/v13.0.0-CMS/docs/indexing-conventions</a> The documentation describes Graph Conventions using APIs such as: <pre><code>services.ConfigureGraphConventions(...)</code></pre> <pre>OR <code>services.AddContentGraph(configureConventions: c => { //add conventions here });</code></pre> However, I was unable to find this API in a CMS 13.0.0 implementation. After further investigation, I discovered that the Graph Convention API was introduced in CMS 13.1.0 together with Optimizely.Graph.Cms 13.1.0 and is not available in earlier CMS 13 releases. This initially caused some confusion because the documentation is published under the CMS 13 documentation section without clearly indicating the minimum version required for the feature. My recommendation is to use CMS 13.1.0 or later if you plan to leverage Graph Conventions during your migration. And It would be helpful if the documentation included version-specific notes or minimum version requirements for Graph Convention APIs, as this could save developers a considerable amount of troubleshooting time during migration projects. 2. Extension Methods Work for Queries but Not for Facets<span style="font-size: 12.0pt; font-family: 'Aptos',sans-serif; mso-ascii-theme-font: minor-latin; mso-fareast-font-family: Aptos; mso-fareast-theme-font: minor-latin; mso-hansi-theme-font: minor-latin; mso-bidi-font-family: 'Times New Roman'; mso-bidi-theme-font: minor-bidi; mso-ansi-language: EN-US; mso-fareast-language: EN-US; mso-bidi-language: AR-SA;"> One of the first surprises I encountered was that extension methods included through Graph Conventions can be queried successfully but cannot be used for faceting. Here is sample code: - Configuration <code>services.ConfigureGraphConventions(conventions => {     conventions         .ForInstancesOf<StandardPage>()         .IncludeField(x => x.ContentTypeName(), IndexingType.Searchable); });</code> - Extension method: <pre><code>public static string ContentTypeName(this ISitePageData sitePageData) { return sitePageData.GetOriginalType().Name; }</code></pre> However, when attempting to create a facet using the extension method: <code>query.Facet(x => x.ContentTypeName()); </code> I saw this error <img src="/link/52e5237e18cf42718fe3a17a10072ee9.aspx" width="1029" height="664" /> I tried running the same facet query directly in Graph Explorer, and it worked as expected. This leads me to believe that the issue may originate from the Optimizely Graph Client API when it builds the query from a lambda expression. However, I'm not sure whether this behavior is intentional or if it should be considered a bug. Impact: Existing Find implementations that rely on calculated fields for faceting may require redesign when migrating to Graph. 3. Search By Base Type Works Differently Than Search & Navigation In Search & Navigation, it is common to search across multiple content types by using a shared base class or marker interface. Examples: <code>Search<SitePageData>()</code> or <code>Search<ISearchableContent>()</code> Many developers expect the same approach to work in Optimizely Graph. Unfortunately, Graph uses a different model and does not automatically support these patterns. - What does not work The following approaches do not create a shared Graph schema that can be queried across all implementing content types. Simple interfaces: <code>public interface ISearchableContent { }</code> Abstract base classes: <code>public abstract class SearchablePage : PageData { }</code> Although these patterns work well in Search & Navigation, Optimizely Graph does not automatically generate a queryable Graph contract from them. - What works To query multiple content types through a shared schema, Optimizely Graph requires a Graph Contract. For example: <code>[ContentType]</code> <code>public interface ISitePageData</code> The contract must then be implemented by each content type that should participate in the shared schema: <code>public class ArticlePage : ISitePageData</code> <code>public class NewsPage : ISitePageData</code>   When content is synchronized to Graph, a shared Graph type is generated for the contract, allowing queries across all implementing content types. Content Type Management UI Behavior One side effect of using a Graph Contract is that the interface becomes visible in the CMS Content Type Management UI. For example, after adding the <code>[ContentType]</code> attribute to the interface: <pre><code>[ContentType] public interface ISitePageData { }</code></pre> the contract appears as a content type in the CMS administration interface as following: <img src="/link/abee47fc9c3149f891781f28a055797b.aspx" width="1437" height="414" /> This behavior can be surprising at first, especially since the interface is not intended to be created or edited by content editors. However, this is currently the mechanism Optimizely Graph uses to discover and generate shared schema contracts. Key takeaway: In Optimizely Graph, interfaces annotated with <code>[ContentType]</code> enable cross-type queries. Base class inheritance does not. Impact: Search architectures based on inheritance hierarchies or marker interfaces must be redesigned using Graph Contracts. This can affect query models, schema design, and migration effort. 4. Using the Content Type Management UI to Change a Property's Indexing Type <img src="/link/0c261ffa36a241f09ab67bea6b4d32e6.aspx" width="1147" height="535" /> Note: The indexing convention API cannot be used to exclude a field from Graph indexing. It only supports extension methods for calculated properties, not actual content type properties. I tried to add this below to disable an actual field: <pre><code>services.AddContentGraph(configureConventions: c => { c.ForInstancesOf<StandardPage>().IncludeField(x => x.ContentAreaCssClass, IndexingType.Disabled); }); </code> Here is the error when I try to disable a field from indexing via convention: <img src="/link/c483e294bb81491b89e2937c0d7b958e.aspx" width="792" height="268" /></pre> To disable indexing for a field, use the Content Type Management UI or apply the following attribute to the property in your content type: <pre><code>[IndexingType(IndexingType.Disabled)] public virtual bool HideSiteFooter { get; set; }</code></pre> 5. <span style="font-size: 12.0pt; font-family: 'Aptos',sans-serif; mso-ascii-theme-font: minor-latin; mso-fareast-font-family: Aptos; mso-fareast-theme-font: minor-latin; mso-hansi-theme-font: minor-latin; mso-bidi-font-family: 'Times New Roman'; mso-bidi-theme-font: minor-bidi; mso-ansi-language: EN-US; mso-fareast-language: EN-US; mso-bidi-language: AR-SA;">Graph Contracts and Content Types Must Use the Same IndexingType When working with Graph Contracts, I discovered an unexpected validation rule that can prevent the application from starting. Optimizely Graph validates property metadata across the entire contract hierarchy during startup. If the same property exists on both a Graph Contract and a content type, the IndexingType must be identical everywhere. Example Graph Contract: <pre><code>[ContentType] public interface ISitePageData { string ContentTypeName { get; } }</code></pre> Base content type: <pre><code>public abstract class SitePageData : PageData, ISitePageData { [GraphProperty(IndexingType.Queryable)] public virtual string ContentTypeName => GetOriginalType().Name; }</code></pre> Here is the error you will see if this happens: <img src="/link/2162fb9599484f8cb164cddc1b8897a3.aspx" width="849" height="535" /> Impact: Inconsistent indexing metadata can prevent the application from starting. This validation rule becomes especially important when multiple teams maintain shared contracts and content models. 6. Getter-only/fallback properties are included in the Graph schema, but their indexed values are null For example: <pre><code>public string ContentAreaCssClass => "teaserblock";</code></pre> <pre><code>public virtual string TeaserText { get { var teaserText = this.GetPropertyValue(p => p.TeaserText); // Use explicitly set teaser text, otherwise fall back to description return !string.IsNullOrWhiteSpace(teaserText) ? teaserText : MetaDescription; } set => this.SetPropertyValue(p => p.TeaserText, value); }</code></pre> Here are the their value when indexing: <img src="/link/f52a342aacf54f4c9cad1852c93e61dd.aspx" width="935" height="461" /> Impact: Properties that appear to work correctly in CMS may produce unexpected Graph results. Search queries, filters, and facets relying on computed values may silently return incorrect data. 7. Extension Methods Cannot Be Added to a Graph Contract as Calculated Fields When using a Graph Contract, extension methods cannot be added as calculated fields on the contract itself. Here is the error that I got when trying to do this: <img src="/link/12b8f476d6424d569475e365043348c1.aspx" width="779" height="264" /> Impact: Shared Graph Contracts cannot be enriched with convention-based calculated fields. Developers may need to duplicate calculated properties across content types or redesign their schema strategy. <h3>Conclusion</h3> Optimizely Graph provides a powerful and flexible search platform, but it differs significantly from Search & Navigation in several areas. When migrating existing Find implementations, pay particular attention to: - Graph Contracts - Graph Convention limitations - Faceting behavior - Property indexing rules - Calculated fields Understanding these differences early can save significant debugging and migration effort.2026-06-24T11:26:37.0000000Z

Blog post

Optimizely: Upgrade Opti-ID and .NET 10 in CMS 12Many Optimizely customers are planning their roadmap around a future migration to Optimizely CMS 13. As a result, upgrades such as Opti ID adoption and... The post <a href="https://madhuanbalagan.com/optimizely-upgrade-opti-id-and-net-10-in-cms-12">Optimizely: Upgrade Opti-ID and .NET 10 in CMS 12</a> appeared first on <a href="https://madhuanbalagan.com">Madhu Anbalagan's Blog</a>. 2026-06-23T16:22:29.0000000Z

Blog post

Understanding Optimizely Graph: Caching, Webhooks & Avoiding Stale Content (Optimizely SaaS CMS)📌 Scope: This post covers Optimizely CMS (SaaS) only — using the official @optimizely/cms-sdk and @optimizely/cms-cli packages with Next.js 15. If you’re on Optimizely CMS 12 (PaaS/DXP), the caching architecture and tooling are different. See the DXP ISR docs for that path. Your editor hit Publish. Five minutes later the page still shows the old […]2026-06-23T04:28:27.0000000Z

Blog post

Optimizely Content APIs: the Setup the Docs Don't Walk You ThroughCMS 13 is pushing things firmly in the direction of Optimizely Graph, but plenty of teams are still running on older CMS versions, or have good reasons to stick with the Content Delivery, Content Definitions, or Content Management APIs regardless of what version they're on. This guide is for those teams. What follows is a step-by-step walkthrough to get any of the content APIs up and running, tested locally, and fully understood, in one place. No jumping between API reference pages, no piecing together fragments from several different resources. Just the things the documentation doesn't make obvious, learned the hard way. <hr class="border-border-200 border-t-0.5 my-3 mx-1.5" /> <h3 class="text-text-100 mt-3 -mb-1 text-[1.125rem] font-bold">The mental model first</h3> Optimizely uses OpenID Connect (via a library called OpenIddict under the hood) to issue JWT bearer tokens. When you want a system to be able to call one of the content APIs, you define it as an OpenID Connect application, either in code, in the CMS Admin UI, or both. We'll cover the specifics of each in the steps below. "Application" in this context is not referring to your CMS instance or front-end site, it refers to discrete client identities registered specifically for machine-to-machine communication. Your CMS can have as many of these as you need. <h4 class="text-text-100 mt-2 -mb-1 text-base font-bold">Why grant_type=client_credentials and not something else</h4> OAuth 2.0 has several grant types: different flows for getting a token, each suited to a different kind of requester or use case. authorization_code is for interactive users: a person clicks login, gets redirected, enters their credentials, and the app receives a token on their behalf. client_credentials is for machine-to-machine communication. Your service acts as itself, not on behalf of a user. There are no redirects, it simply exchanges its credentials directly for a token. <h4 class="text-text-100 mt-2 -mb-1 text-base font-bold">Why the token endpoint is at /connect/token</h4> This is OpenIddict's default endpoint path, and OpenIddict is the OpenID Connect server library Optimizely uses under the hood. Optimizely didn't invent this URL, it's baked into the library. The /api/episerver prefix in front of it is the actual Optimizely part of the route, sitting in the same legacy episerver namespace you'll see across the older API paths. The flow from here is straightforward: you request an access token for one of these applications, then pass that token in subsequent requests to the content APIs. Importantly, the access rights you configure in the CMS are tied to the application identity itself, so when a request comes in using that token, content access is evaluated against whatever permissions that application has been granted. <img src="/link/97584b3856524d738de8085f065eccdb.aspx" /> <img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-6axZYk-gPv/0d7f2a7de1e85c0b2044c8e8f0f8d8592c1549a00a4746a00110d39d57f2a00ea426e35a907df27fefe33102d25f33b8158227cf15f4e51bef79f26d202ef1f636a7da0e82114cb5dc624aaddad115be213b1da5054a9af57d4bfbf223a6c0f0f6565710?fit=max&fm=webp&lossless=true" alt="image.png" /> The Add User/Group dropdown showing the Applications section with two OpenID applications listed <hr class="border-border-200 border-t-0.5 my-3 mx-1.5" /> <h3 class="text-text-100 mt-3 -mb-1 text-[1.125rem] font-bold">Let's set it all up</h3> <h4 class="text-text-100 mt-2 -mb-1 text-base font-bold">Step 1: Install the required NuGet packages</h4> <div class="relative group/copy bg-bg-000/50 border-0.5 border-border-400 rounded-lg focus:outline-none focus-visible:ring-2 focus-visible:ring-accent-100"> <div class="overflow-x-auto"> <pre class="code-block__code !my-0 !rounded-lg !text-sm !leading-relaxed p-3.5"><code>dotnet add package EPiServer.OpenIDConnect dotnet add package EPiServer.OpenIDConnect.UI # Optional</code></pre> </div> </div> You'll also need the API package for whichever API you're securing: <ul class="[li_&]:mb-0 [li_&]:mt-1 [li_&]:gap-1 [&:not(:last-child)_ul]:pb-1 [&:not(:last-child)_ol]:pb-1 list-disc flex flex-col gap-1 pl-8 mb-3"> <li class="font-claude-response-body whitespace-normal break-words pl-2">Content Delivery API: EPiServer.ContentDeliveryApi.Cms</li> <li class="font-claude-response-body whitespace-normal break-words pl-2">Content Management API: EPiServer.ContentManagementApi</li> <li class="font-claude-response-body whitespace-normal break-words pl-2">Content Definitions API: EPiServer.ContentDefinitionsApi</li> </ul> Version gotcha: Make sure your EPiServer.OpenIDConnect version is compatible with your CMS version. Mismatched versions are a common source of silent failures at startup. <h4 class="text-text-100 mt-2 -mb-1 text-base font-bold"> </h4> <h4 class="text-text-100 mt-2 -mb-1 text-base font-bold">Step 2: Wire up the configuration in code</h4> In your Startup.cs, you need to configure OpenID Connect and register whichever content APIs you need: <div class="relative group/copy bg-bg-000/50 border-0.5 border-border-400 rounded-lg focus:outline-none focus-visible:ring-2 focus-visible:ring-accent-100"> <div class="overflow-x-auto"> <pre class="code-block__code !my-0 !rounded-lg !text-sm !leading-relaxed p-3.5"><code>public void ConfigureServices(IServiceCollection services) { // ASP.NET Identity must be configured before OpenID Connect services.AddCmsAspNetIdentity<ApplicationUser>(); services.AddOpenIDConnect<ApplicationUser>( useDevelopmentCertificate: _webHostingEnvironment.IsDevelopment(), createSchema: true, options => { // Seeding an application here is optional: see note below options.Applications.Add(new OpenIDConnectApplication { ClientId = "your-client-id", ClientSecret = "your-client-secret", Scopes = { "epi_content_delivery", "epi_content_management", "epi_content_definitions" } }); }); services.AddOpenIDConnectUI(); // Optional: adds the OpenID Connect panel in CMS Admin services.AddContentDeliveryApi(OpenIDConnectOptionsDefaults.AuthenticationScheme); services.AddContentDefinitionsApi(OpenIDConnectOptionsDefaults.AuthenticationScheme); services.AddContentManagementApi(OpenIDConnectOptionsDefaults.AuthenticationScheme); }</code></pre> </div> </div> A few things worth noting here: <ul class="[li_&]:mb-0 [li_&]:mt-1 [li_&]:gap-1 [&:not(:last-child)_ul]:pb-1 [&:not(:last-child)_ol]:pb-1 list-disc flex flex-col gap-1 pl-8 mb-3"> <li class="font-claude-response-body whitespace-normal break-words pl-2">Each API registration method accepts an authentication scheme parameter, don't leave it out. Without it, the API has no way to validate incoming Bearer tokens and will return a 401 regardless of whether your token is valid. Pass OpenIDConnectOptionsDefaults.AuthenticationScheme to wire them up correctly.</li> <li class="font-claude-response-body whitespace-normal break-words pl-2">useDevelopmentCertificate : tying this to IsDevelopment() means it uses a local dev certificate in your local environment and expects a real one in production. On DXP, certificates are provided automatically via EPiServer.CloudPlatform.Cms 1.6.1 or later.</li> <li class="font-claude-response-body whitespace-normal break-words pl-2">Scopes: each scope string controls which API that client is permitted to call, and must match the scope you pass when requesting a token. There are constants available if you'd prefer not to use raw strings: ContentDeliveryOptionsDefaults.Scope, ContentDefinitionsApiOptionsDefaults.Scope, and ContentManagementApiOptionsDefaults.Scope.</li> <li class="font-claude-response-body whitespace-normal break-words pl-2">Seeding applications in code is optional. The options.Applications.Add(...) block pre-creates the client on startup, which is convenient for local development. If you'd rather manage clients entirely through the UI, you can omit it, that's what the AddOpenIDConnectUI() line enables. It adds an OpenID Connect section under Settings in CMS Admin where you can create and manage applications directly.</li> </ul> <img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-oki8fxiyA7/5cd57dd6794f296df6654bc4c7aa473b1171a4d8575e67bd58ded795e9c955eead6210f9123ca6f85e7f93ea9de301c69d838208b36c8325f6744862c30110e55fd837c8291ec1448d6c817c7bd3e8ff859e13f6e235447f2ac3d73256f2466a0dfb76c4?fit=max&fm=webp&lossless=true" alt="image.png" /> The "OpenID Connect" settings panel can be seen in the screenshot above. <h4 class="text-text-100 mt-2 -mb-1 text-base font-bold"> </h4> <h4 class="text-text-100 mt-2 -mb-1 text-base font-bold">Step 3: Request a token</h4> Once you have an application configured, either in code or the UI, you first need to request an access token for the application before calls to any of the content APIs can be made. Using curl: <div class="relative group/copy bg-bg-000/50 border-0.5 border-border-400 rounded-lg focus:outline-none focus-visible:ring-2 focus-visible:ring-accent-100"> <div class="overflow-x-auto"> <pre class="code-block__code !my-0 !rounded-lg !text-sm !leading-relaxed p-3.5"><code>curl -X POST https://your-site.com/api/episerver/connect/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret&scope=epi_content_management"</code></pre> </div> </div> Using Postman: <img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-gPVIKzvOJE/f7bf91e744372274b5dccfdc85dd0dbc9baa8eb91fdee7b93a4b8c26793ee8898b698a77b9c5aa805a5fc3934d04b8642cbc3a6059ffaa92136afd1eaa2eb5f17688bd706702a0fc3613ac6f7c6d74fb7898db17dbd5b35368fd65fae32753032b11c7e6?fit=max&fm=webp&lossless=true" alt="image.png" /> Set the request to POST, the URL to your token endpoint, and under the Body tab select x-www-form-urlencoded. Add the four key-value pairs: grant_type, client_id, client_secret, scope  A successful response looks like this: <div class="relative group/copy bg-bg-000/50 border-0.5 border-border-400 rounded-lg focus:outline-none focus-visible:ring-2 focus-visible:ring-accent-100"> <div class="overflow-x-auto"> <pre class="code-block__code !my-0 !rounded-lg !text-sm !leading-relaxed p-3.5"><code>{ "access_token": "eyJhbGci...", "expires_in": 3599, "token_type": "Bearer" }</code></pre> </div> </div> Copy the access_token value, you'll use it in Step 5. <h4 class="text-text-100 mt-2 -mb-1 text-base font-bold"> </h4> <h4 class="text-text-100 mt-2 -mb-1 text-base font-bold">Step 4: Assign CMS access rights to the client</h4> This is the most commonly missed step, and it causes some of the most confusing symptoms, you have a valid token, your requests aren't getting 401s, but you're getting empty results or unexpected 403s. The API client you created is effectively a user in the CMS. Like any user, it needs to be granted access rights to the content it's trying to read or write. There are different levels you could configure access rights, let's get into them below. <h5 class="text-text-100 mt-2 -mb-1 text-base font-bold"> </h5> <h5 class="text-text-100 mt-2 -mb-1 text-base font-bold">Global access rights</h5> Global access rights apply at the page or section level in your content tree and cascade down to every item beneath. For instance, if you want to deny a specific OpenID application Read access to a sensitive area, say, an "Admin" page or a "Members Only" section, you set the restriction at that page, and the cascade ensures every sub-page inherits the same rule automatically. You don't have to configure each one individually. <img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-wHVz_SRQT6/9a2b8822c3e7ca4442dfc503adbbff00f14ed9b74eedbd81d1487dec35f33061b21d46266513d0c1e8ecbc519ea9c4fe60e0db4cdf5c8676fc955aad580be95add7cc628e35c54434f4363ddf43a528a0c579d79c3413007238721d09e47b0710261574c?fit=max&fm=webp&lossless=true" alt="image.png" />On this level, either all content is returned, or none of it. Either 200-OK, or 403-Forbidden   Navigate to Settings → Set Access Rights, select the page or section you want the client to access, and add it using Add User/Group. Your registered applications (from either the code or created in the CMS on the OpenID Connect settings panel) will appear under the Applications group in the dropdown. Grant it the appropriate permissions: Read is sufficient for Content Delivery, while Content Management will need Read, Change, and Publish depending on what operations you need to perform. Check Apply settings for all subitems to cascade the rights down the content tree. <img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-G7Oqc_d9dv/65f22110078ca502ef75b1a83a1ec3652580830c21791120f685a2cfde53b42d62737429b8ba88f183d645b66eb5160468ef90752518b2e807fd94ba6fff3b580442c4c65a742453a0e8a73515650aa577db9adad1b41ccb824c0997d8618475f3621c33?fit=max&fm=webp&lossless=true" alt="image.png" /> alloy-client application granted Read access on the Start page, cascading to all subitems.   Why this matters: Skipping this step produces one of two outcomes depending on your setup: either the API returns a 403 Forbidden response, or it returns content that was never actually restricted to begin with, because the Everyone group already has read access. In the latter case everything appears to be working, but your access rights configuration isn't doing anything. If you ever tighten down content permissions, your client will silently lose access. <h5 class="text-text-100 mt-2 -mb-1 text-base font-bold"> </h5> <h5 class="text-text-100 mt-2 -mb-1 text-base font-bold">Content-level access rights (per page/block instance in the tree)</h5> Content-level access rights give you more granular control than the global settings screen, you can restrict access to specific pages or blocks directly in the content tree rather than applying a blanket rule across everything. A practical example: imagine you have a pricing page that should only be visible to authenticated partners. Rather than locking down your entire content tree, you can grant your API client access to everything by default and then explicitly restrict access on those specific items, or invert it entirely, grant no global access, and only open up the specific content the client needs to see. <img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-KagMkB0nHI/84fd374988f4ffa674e61c110c8dd272a70b53a3aaac9b9e69a3c7a2f7904af1773ebb6a4731948214519ccbc5ec37577bafd38a338a450b09e5e0eba3bb6fa71cdd6284c0442e856b1467f4de13af0e9fd093cf7735eb69e73f71e0c32465a8cf3f00c1?fit=max&fm=webp&lossless=true" alt="image.png" /> Same request, different response. The restricted client's "Pricing" entry isn't returned as a 403 error, it's simply omitted from the response. This is what makes content-level access rights powerful: the client doesn't need to know what they can't see, and the API does the filtering server-side.   The result isn't binary. It's not just 200 or 403, you can build quite precise access models by combining global and content-level rights. Content-level access rights are set directly on a specific page or block in the edit interface. To access them, right-click the item in the content area or page tree and select Edit, then look for the Visible to panel at the top of the properties view. If access is unrestricted it will show as Everyone. Click Manage to open the Access Rights dialog and configure it the same way as the global screen. <img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-qR4ivN8SRr/b1a50ba1bf085a982d94ee754c078da101225a16e25244fc5d9c8cbc736292fe097f308e83577c3f01d0fae8184840d72d542e812eb4618722716dc813d7e5abb3de10c714b93db366a20b4bd0b3c5b580d83a9ddbd9f031491b687fa4d36d3d1d50f4ca?fit=max&fm=webp&lossless=true" alt="image.png" /> Right-clicking a content item in the page tree to access its properties   <img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-WSEoq3HxlV/50e6bbbae79aa96c3d964669a0a78de6d46fef1b38a276d48351652090e0cf572a26a24277995b9aac202280dd6e1a98f69eb35f29ab8c264b53d408910f12febb1db17a875ab48629dde4cf5385c47fd04443d133025250ed1f71e4beddb28d649acdcf?fit=max&fm=webp&lossless=true" alt="image.png" /> The "Visible to" panel showing the current access restriction status for a content item, with the Manage link to open the Access Rights dialog   <img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-gRug85CPa2/a655f207b12969e892ee42f18c06fe4559edc2458edd8eac4fdba97ca66f1b57940a77f4656e4e94deb5d320983ab7ce7b56f93992910a7c1f502243c1294c8c8349eb52f165b0cbd6caddda4cbe605aaf827322729400de2e1d68bc28f44516d684351c?fit=max&fm=webp&lossless=true" alt="image.png" /> The Access Rights dialog for a specific content item, with alloy-client granted Read access and "Inherit settings from parent item" unchecked to override the global defaults <h4 class="text-text-100 mt-2 -mb-1 text-base font-bold"> </h4> <h4 class="text-text-100 mt-2 -mb-1 text-base font-bold">Step 5: Make your first authenticated request</h4> With your token in hand (from Step 3) and access rights set, you can now call the API. Pass the token as a Bearer token in the Authorization header. <div class="relative group/copy bg-bg-000/50 border-0.5 border-border-400 rounded-lg focus:outline-none focus-visible:ring-2 focus-visible:ring-accent-100"> <div class="overflow-x-auto"> <pre class="code-block__code !my-0 !rounded-lg !text-sm !leading-relaxed p-3.5"><code>curl -X GET https://your-site.com/api/episerver/v3.0/content/{contentGuid} \ -H "Authorization: Bearer eyJhbGci..."</code></pre> </div> </div> <img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-FU_Ev1Aesh/e10d121a20a2164e0dae719606c8455da4b0249791f5133404aa422e9e1305da7a25b2c0c706bad935e45143206bb1573e2b9cc0d2ba6bd276a2b647b477549c2853b76b35191888168aaa288e0c1580f4596e7bf7d5c0283f5f076a95e09b06e0cebea2?fit=max&fm=webp&lossless=true" alt="image.png" /> <img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-NXSO-5LtU5/e6aa4fcd051b0c43b89b8c85ad1dce2c781e14eb93a6f63afb206b3780777bf8e57bab1dadce5aa8e54b7a205305f2ba10bfb1a792846708e43936e9ae6a37e80ab382f0de3587e031b5aaa2dc4a88bf2655eece10f86e21527fd89bd1e5f87d155ff6b0?fit=max&fm=webp&lossless=true" alt="image.png" /> Success response from the Content Delivery API (200 - OK)   However, if I revoke read access from the OpenId Application, I get the following: <img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-qxuy8jsqAm/3bb819b8f43ca3a5307fb37c86c495da49bb3b98fede2645dcb989df111a4d3581549553ca3323489dbc9c169cdfbba8cfcf395c34c048d66d598408810c86281c422c293e4bed5605e2a0e7099c49380d8c3bbc2d3725707840509617be42aa044340b0?fit=max&fm=webp&lossless=true" alt="image.png" /> <img src="https://codaio.imgix.net/docs/-XvL0D-nmX/blobs/bl-4bM8czjC1c/1f9f13813cdbbf1744799c9aa89168fde0b36192909142daf589b5707d800ec9b9c91de53a2dfe3bf26c28d318cf550e9cedf3f32a18daea6b22f5dd0f884ca723c2ec77b1a9270724da6dc853706a241ee58975287d316102a1a095bef86ee8849e61bb?fit=max&fm=webp&lossless=true" alt="image.png" /> Forbidden response from Content Delivery API (403 - Forbidden) <hr class="border-border-200 border-t-0.5 my-3 mx-1.5" /> <h3 class="text-text-100 mt-3 -mb-1 text-[1.125rem] font-bold">Common errors and what they actually mean</h3> For the last example, the 403 is exactly what we'd expect, but it's worth understanding the difference between a 401 and a 403, since they're easy to confuse and point to very different problems. 401 Unauthorized means the API doesn't recognise or can't validate the token itself. Either it's malformed, it's expired, or the API isn't configured to accept it. Check that you're passing OpenIDConnectOptionsDefaults.AuthenticationScheme into your API registrations in Startup.cs, that your token hasn't expired (3599 seconds), and that your client_id and client_secret match exactly what's registered in CMS Admin. 403 Forbidden means the token is valid and recognised, but the application it belongs to doesn't have permission to access that content. This is the access rights problem covered in the previous step, the API knows who you are, it just won't let you in. Token endpoint returns 404. The OpenID Connect middleware isn't registered, or the package isn't installed. Confirm the NuGet package is installed and correctly configured in Startup.cs. invalid_client error from the token endpoint. The client_id or client_secret doesn't match what's registered in CMS Admin (or code). These must be identical, including case. invalid_scope error from the token endpoint. The scope you're requesting (epi_content_management, etc.) doesn't match what was registered for the client in CMS Admin. unsupported_grant_type from the token endpoint. The client was not registered with the client_credentials grant type. Check the application configuration in CMS Admin and ensure Client Credentials is selected as a permitted grant type. <hr class="border-border-200 border-t-0.5 my-3 mx-1.5" /> <h3 class="text-text-100 mt-3 -mb-1 text-[1.125rem] font-bold">Conclusion</h3> Getting the Optimizely content APIs working for the first time involves piecing together information from several different sources, the official docs, community posts, and a fair amount of trial and error. Hopefully this post brings it all into one place and saves someone the same legwork. If you're already on CMS 13 or considering the move, Optimizely Graph changes the delivery layer significantly and much of the authentication setup described here won't apply in the same way. But for teams on CMS 12 or those still needing to use any of the content APIs, this remains the path.2026-06-22T13:31:38.0000000Z

Blog post

Translating content in Optimizely CMS with Anthropic ClaudeAn add-on with an Anthropic translator provider that lets you translate content in Optimizely CMS using Anthropic Claude.2026-06-20T05:48:44.0000000Z

Blog post

Controlling Optimizely Forms Cookie Expiration in .NET CoreLearn how to make Optimizely Forms cookies behave as session cookies in CMS 12+ (.NET Core) using a simple middleware - and why the official documentation won't help you get there.2026-06-19T07:43:39.0000000Z

Blog post

ReloadOnChange in Optimizely CMS: The Attribute Nobody Talks AboutOptimizely CMS has a little-known attribute that reloads the editor when a property changes — perfect for dependent dropdowns and checkboxes. Here is how I found it, proved it worked, and shipped it on a Product Detail Page.2026-06-19T00:00:00.0000000Z

Blog post

Opal: Beyond the ObviousA couple of less-obvious ways I'm using Optimizely's Opal to automate real work across Salesforce, GitHub, and Teams.2026-06-18T21:52:49.0000000Z

Blog post

EOL Announcement for Preview3 CMS REST API<img src="https://statics.teams.cdn.office.net/evergreen-assets/personal-expressions/v2/assets/emoticons/stopsign/default/30_f.png?v=v6" alt="🛑" width="20" />Action Required: Migrate Preview3 API Integrations to CMS REST API v1 Before August 1, 2026 If your SaaS CMS applications are currently using the Preview3 CMS REST API endpoints, please plan to migrate to CMS REST API v1 before August 1, 2026. On August 1, 2026, we will retire the Preview3 endpoints and begin disabling access. Applications that continue to rely on Preview3 after this date may experience failed requests and service interruptions. <h3>Who Is Affected?</h3> You are affected by this change if your SaaS CMS integrations are currently making requests to Preview3 endpoints (typically URLs containing <code>/preview3/</code>). If your applications are already using CMS REST API v1, no action is required. We recognize that API migrations require planning and effort, and we appreciate the work our customers invest in keeping their integrations current. To help ensure a smooth transition, we've provided a migration guide (see below) and have maintained support for both versions since the release of v1 in May. This announcement is the first to underscore the importance of staying current and making the change to CMS REST API v1 to avoid disruption. <h2>What Is Changing?</h2> With the general availability of CMS REST API v1 on May 5, 2026, the Preview3 APIs entered a deprecation phase and are now approaching end-of-life. Key points to know: <ul> <li>Preview3 support ends August 1, 2026.</li> <li>Preview3 was released as an experimental API and was not recommended for production workloads.</li> <li>CMS REST API v1 provides the same core capabilities through stabilized, production-ready endpoints.</li> <li>Mixing Preview3 and v1 endpoints is supported until the August 1, 2026 retirement date.</li> <li>No new fixes, enhancements, or support updates are being made to Preview3. All ongoing investment is focused on v1 and future releases.</li> </ul> <h2>Will There Be Breaking Changes?</h2> Yes. Some breaking changes were introduced as part of the transition from Preview3 to v1. Before migrating, please review the migration documentation: <ul> <li><a class="fui-Link ___1q1shib f2hkw1w f3rmtva f1ewtqcl fyind8e f1k6fduh f1w7gpdv fk6fouc fjoy568 figsok6 f1s184ao f1mk8lai fnbmjn9 f1o700av f13mvf36 f1cmlufx f9n3di6 f1ids18y f1tx3yz7 f1deo86v f1eh06m1 f1iescvh fhgqx19 f1olyrje f1p93eir f1nev41a f1h8hb77 f1lqvz6u f10aw75t fsle3fq f17ae5zn" title="https://docs.developers.optimizely.com/content-management-system/v1.0.0-cms-saas/reference/migrate-content-api-preview3-to-v1" href="https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/reference/migrate-content-api-preview3-to-v1">Migrate from Content API Preview3 to CMS REST API v1</a></li> <li><a class="fui-Link ___1q1shib f2hkw1w f3rmtva f1ewtqcl fyind8e f1k6fduh f1w7gpdv fk6fouc fjoy568 figsok6 f1s184ao f1mk8lai fnbmjn9 f1o700av f13mvf36 f1cmlufx f9n3di6 f1ids18y f1tx3yz7 f1deo86v f1eh06m1 f1iescvh fhgqx19 f1olyrje f1p93eir f1nev41a f1h8hb77 f1lqvz6u f10aw75t fsle3fq f17ae5zn" title="https://docs.developers.optimizely.com/content-management-system/v1.0.0-cms-saas/reference/experimental-apis" href="https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/reference/experimental-apis">Experimental APIs Documentation</a></li> </ul> These resources provide detailed guidance on the changes and recommended migration approach. <h2><img src="https://statics.teams.cdn.office.net/evergreen-assets/personal-expressions/v2/assets/emoticons/1f552_threeoclock/default/30_f.png?v=v13" alt="🕒" width="20" />Why Are We Retiring Preview3?</h2> Maintaining multiple API versions increases complexity for both customers and Optimizely. As v1 has been generally available for several months and provides a stable, supported alternative, retiring Preview3 allows us to focus on delivering higher reliability, better performance, and faster innovation across the platform. <h2><img src="https://statics.teams.cdn.office.net/evergreen-assets/personal-expressions/v2/assets/emoticons/1f4e2_publicaddressloudspeaker/default/30_f.png?v=v8" alt="📢" width="20" />How Can I Stay Informed?</h2> We recommend subscribing to the following channels for future API lifecycle and platform updates: <ul> <li>CMS Release Notes (support.optimizely.com)</li> <li>Optimizely Slack Community</li> <li>Optimizely Developer Blog Community (World.optimizely.com)</li> </ul> These channels are typically the first places where deprecations, support timelines, and migration guidance are communicated. For additional information about API lifecycle and support policies, please refer to the <a class="fui-Link ___1q1shib f2hkw1w f3rmtva f1ewtqcl fyind8e f1k6fduh f1w7gpdv fk6fouc fjoy568 figsok6 f1s184ao f1mk8lai fnbmjn9 f1o700av f13mvf36 f1cmlufx f9n3di6 f1ids18y f1tx3yz7 f1deo86v f1eh06m1 f1iescvh fhgqx19 f1olyrje f1p93eir f1nev41a f1h8hb77 f1lqvz6u f10aw75t fsle3fq f17ae5zn" title="https://docs.developers.optimizely.com/content-management-system/v1.0.0-cms-saas/reference/experimental-apis" href="https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/reference/experimental-apis">CMS API documentation</a>. <h2>Thank You</h2> Thank you for your partnership and for helping us continue to improve the CMS developer experience. If you have questions about your migration strategy or encounter challenges during the transition, please reach out to our team—we're here to help.2026-06-18T15:05:21.0000000Z

Blog post

Environmental DXP badgesI recently released my first Optimizely add-on in a while, that was based on some client feedback on the Optimizely DXP – they wanted to be able to <a href="https://nuget.optimizely.com/packages/mp.dxpcontenttransfer/">push content from preproduction to production</a> due to their workflow involving content creation taking place in the non-live environment. Whilst working to make the UI for that tool as clean and helpful as I could - chiseling all the corners and gilding all the lilies, etc. - I ended up putting in a little UI mechanism to allow editors and administrators to see what environment they are in. Just a little badge, that makes it clear where you are so that you know where your content is coming from... <img src="/link/811af14eb171458a837399012fd247c0.aspx" width="424" height="155" /> Having put it into the content transfer tool, I then came across this… <a href="https://feedback.optimizely.com/forums/966081-cms-paas-content-management-system/suggestions/50995978-ui-change-to-distinguish-prod-from-preprod-and-int">https://feedback.optimizely.com/forums/966081-cms-paas-content-management-system/suggestions/50995978-ui-change-to-distinguish-prod-from-preprod-and-int</a> …and thought it might actually be nice to also give people who don’t want to copy content between DXP environments the same UI niceties to help them know which environment they’re working in - so it's now standalone, removed from content transfer tool, and working in CMS 12 and 13. It's mega simple and also completely configurable on a per environment basis, so you're not stuck with integration, preproduction and production if your pipeline uses different terminology - TEST, UAT, LIVE, etc. <img src="/link/29491f1ced1c4d00a3f24131fa3599c5.aspx" width="602" height="201" /> You can nuget it over at <a href="https://nuget.optimizely.com/packages/mp.dxpenvironmentindicator/">https://nuget.optimizely.com/packages/mp.dxpenvironmentindicator/</a> if you're interested.2026-06-18T09:02:56.0000000Z

Blog post

CI/CD deployment failure in Optimizely DXP Passportal. .NET 10 and GitHub Runner Compatibility<h3>.NET 10 and GitHub Runner Compatibility</h3> With the release of .NET 10, the <code>windows-latest</code> and <code>ubuntu-latest</code> GitHub Actions runners may use the latest installed .NET SDK by default. As a result, if your application is built using a different SDK version and no SDK version is explicitly specified, the build and deployment process may use the latest SDK available on the runner. This can lead to build failures, deployment issues, or the website failing to start after deployment. To avoid this issue, define the required SDK version in a <code>global.json</code> file at the root of your repository. This ensures that the build pipeline consistently uses the intended .NET SDK version regardless of updates to the GitHub-hosted runners. Example: <pre><code>{ "sdk": { "version": "8.0.100" } }</code></pre> By pinning the SDK version in <code>global.json</code>, you can ensure predictable builds and deployments across different environments and runner updates.2026-06-16T13:43:41.0000000Z

Blog post

Integrating Optimizely CMP Assets into an Existing Document Listing PageIntegrating Optimizely CMP Assets into an Existing Document Listing Page In some projects, there may be a requirement to retrieve assets from Optimizely CMP and display them alongside existing content on the website. <h3>Scenario</h3> Consider an existing Document Listing page where all documents are managed in Optimizely CMS and indexed through Episerver Search & Navigation (Find). A new requirement is introduced to display assets stored in Optimizely CMP within the same listing page, together with CMS documents. <h3>Available Options for Retrieving CMP Assets</h3> <h4>1. Optimizely CMP Graph API</h4> <a href="https://cg.optimizely.com/app/graphiql?auth={singlekey">https://cg.optimizely.com/app/graphiql?auth={singlekey</a>} <h4>2. Optimizely CMP Open REST API</h4> <a href="https://www.postman.com/optimizely/optimizely-s-postman-collection-s/collection/9vnewz3/optimizely-cmp-open-rest-api?sideView=agentMode">https://www.postman.com/optimizely/optimizely-s-postman-collection-s/collection/9vnewz3/optimizely-cmp-open-rest-api?sideView=agentMode</a> <a href="https://developers.welcomesoftware.com/openapi.html">https://developers.welcomesoftware.com/openapi.html</a> <h3>Proposed Solution</h3> Implement a dedicated CMP API Service responsible for retrieving assets from Optimizely CMP. The service should: <ul> <li>Fetch asset data using either the CMP Graph API or Open REST API.</li> <li>Map CMP asset data to a common document model already used by the existing Document Listing page.</li> <li>Merge CMP assets and Optimizely CMS documents into a unified collection.</li> <li>Apply existing filtering, sorting, and pagination logic consistently across both content sources.</li> <li>Render the combined results on the same listing page without requiring significant changes to the front-end implementation.</li> </ul> This approach allows the existing listing page to support content from multiple sources while maintaining a consistent user experience and minimizing changes to the current architecture.2026-06-16T12:56:07.0000000Z

Blog post

Setting up Opti Id SSO with and without SCIM<span style="font-size: 11.0pt; line-height: 107%; font-family: 'Verdana',sans-serif; mso-fareast-font-family: Calibri; mso-fareast-theme-font: minor-latin; mso-bidi-font-family: Helvetica; mso-ansi-language: #0C00; mso-fareast-language: EN-US; mso-bidi-language: AR-SA;">This blog compiled learnings, when setting up Opti Id for large enterprises using SCIM and its pros and cons when setting up Opti Id without SCIM. <h2>What is Opti ID and why does provisioning matter?</h2> Opti ID is Optimizely's unified identity layer — a single login that spans all Optimizely products including CMS, CMP, and beyond. Once authenticated, users access every product and instance they are entitled to from a single dashboard, without logging in again. But authentication is only part of the story. For large, fluid user populations, the harder challenge is provisioning — how user accounts are created, kept current, and deactivated as people join, change roles, or leave. Opti ID supports two distinct models for this.   <table class="MsoNormalTable" style="width: 901px; border-collapse: collapse; border-image: initial; height: 229px; border: medium none currentcolor;"> <tbody> <tr style="height: 229px;"> <td style="width: 422.344px; border: 1pt solid rgb(216, 221, 232); background: rgb(255, 248, 245); padding: 9pt 10pt; height: 229px;"> APPROACH A SSO without SCIM Users authenticate through your identity provider via SAML or OIDC. Access rights, roles, and group assignments are configured and maintained manually within the Opti ID Admin Centre. Works with any standards-compliant IdP. </td> <td style="width: 422.344px; border-width: 1pt 1pt 1pt medium; border-style: solid solid solid none; border-color: rgb(216, 221, 232) rgb(216, 221, 232) rgb(216, 221, 232) currentcolor; border-image: initial; background: rgb(232, 241, 255); padding: 9pt 10pt; height: 229px;"> APPROACH B SSO with SCIM Authentication is federated via your IdP, and user provisioning is fully automated via the SCIM protocol. Users and groups defined in your IdP are pushed to Opti ID automatically — including creation, updates, and deactivation. Requires Entra ID, Okta, or PingOne. </td> </tr> </tbody> </table>   <h2>▸  APPROACH A</h2> <h2>SSO without SCIM — Setup & Considerations</h2> This approach uses your identity provider purely for authentication. All user management — invitations, group assignments, role changes, and deactivations — is carried out manually inside the Opti ID Admin Centre. Any IdP supporting SAML or OIDC is compatible. <h3>Setup Steps</h3>      1. Designate a technical owner — One person logs into Opti ID first to establish the organisation and handle initial configuration. This person acts as the first Opti ID administrator and delegates access from there.      2. Configure SSO connections in your IdP — Add Opti ID as a SAML or OIDC application in your identity provider. Up to five SSO connections can be configured — useful for separating geographies, business units, or external users under distinct connections.      3. Register your organisational domains — In Opti ID Admin Centre under Settings > SSO/ Domains, register the SSO / DNS domains your internal users authenticate with. This auto-routes users to the correct SSO connection at login.      4. Handle external and partner users via selective local login — Enable selective local login to give partner individuals a standalone Opti ID account (email + password, MFA optional). Internal users continue authenticating via SSO; external users get a local account managed per-user in the Admin Centre. 5. Create groups and assign roles manually — Build a group structure in the Admin Centre reflecting your organisational needs — by region, product, or access tier. Invite users individually, assign them to groups, and those groups determine which product instances and roles each user can access. <table class="MsoNormalTable" style="width: 1121px; border-collapse: collapse; height: 214px; border-image: initial; border: medium none currentcolor;"> <tbody> <tr style="height: 214px;"> <td style="width: 531.688px; border: 1pt solid rgb(216, 221, 232); background: rgb(240, 255, 248); padding: 9pt 10pt; height: 214px;"> + ADVANTAGES •    Works with any SAML or OIDC identity provider — no vendor restriction •    Simpler to configure and operate; fewer integrated components •    Partners and external users onboarded via local login without changes to your corporate IdP •    Lower initial setup risk; easier to troubleshoot </td> <td style="width: 533px; border-width: 1pt 1pt 1pt medium; border-style: solid solid solid none; border-color: rgb(216, 221, 232) rgb(216, 221, 232) rgb(216, 221, 232) currentcolor; border-image: initial; background: rgb(255, 245, 245); padding: 9pt 10pt; height: 214px;"> − DISADVANTAGES •    No automated offboarding — access must be manually revoked when users leave •    At large scale, individual invitations and role assignments are operationally unsustainable •    Compliance and audit readiness require continuous manual effort •    High risk of orphaned accounts if offboarding processes are not rigorously followed </td> </tr> </tbody> </table>     ▸  APPROACH B <h2>SSO with SCIM — Setup & Considerations</h2> <span style="font-size: 11.0pt; line-height: 107%; font-family: 'Verdana',sans-serif; mso-fareast-font-family: Calibri; mso-fareast-theme-font: minor-latin; mso-bidi-font-family: Helvetica; color: #1a202c; mso-ansi-language: #0C00; mso-fareast-language: EN-US; mso-bidi-language: AR-SA;">SCIM (System for Cross-domain Identity Management) extends your SSO setup by automating the full user lifecycle. Your identity provider becomes the single source of truth — users and groups defined are pushed to Opti ID automatically, including deprovisioning when someone leaves. Officially supported with Microsoft Entra ID, Okta, and PingOne. <h3>Setup Steps</h3>       1. Designate a technical owner and configure SSO — Same starting point as Approach A. Configure your primary SSO connection first — the SCIM configuration option only becomes available after at least one SSO connection is active.       2. Generate a SCIM token in Opti ID — Navigate to Admin Centre > Settings > Authentication > SCIM. Select the SSO connection you want to associate SCIM with and generate the bearer token. This token authenticates your IdP when it pushes user data to Opti ID.       3. Create a SCIM provisioning app in your IdP — Most enterprise IdPs require a separate application for SCIM provisioning, distinct from the SSO app. Configure it using the Opti ID SCIM endpoint URL and token generated above. Some IdPs (such as Okta) allow combining SSO and SCIM in a single app — check your provider's documentation. <span style="font-style: normal; font-variant: normal; font-size-adjust: none; font-language-override: normal; font-kerning: auto; font-optical-sizing: auto; font-feature-settings: normal; font-variation-settings: normal; font-weight: normal; font-stretch: normal; font-size: 7pt; line-height: normal;">          4. Design your group structure and push groups from your IdP — Create groups in your IdP corresponding to the access tiers you need — by region, role, or product. Assign users to these groups. When SCIM syncs, those groups and members are automatically created in Opti ID. Future membership changes propagate within minutes.        5. Map groups to product instances and roles in the Admin Centre — SCIM delivers users and group memberships — it does not configure product instance access or role assignments. In the Admin Centre, map each SCIM-synced group to the appropriate instances and permission levels.   <table class="MsoNormalTable" style="width: 1217px; border-collapse: collapse; border-image: initial; border: medium none currentcolor;"> <tbody> <tr style="mso-yfti-irow: 0; mso-yfti-firstrow: yes; mso-yfti-lastrow: yes;"> <td style="width: 580.344px; border: 1pt solid rgb(216, 221, 232); background: rgb(240, 255, 248); padding: 9pt 10pt;"> + ADVANTAGES •    Full user lifecycle automated — joiners, movers, and leavers handled at IdP level without manual Opti ID steps •    Scales to large user populations with no proportional increase in admin overhead •    Access revocation is immediate when a user is removed from an IdP group •    Single source of truth — your IdP directory drives everything; Opti ID stays in sync •    Significantly reduces compliance audit effort — IdP logs are the system of record <span style="font-size: 11.0pt; line-height: 107%; font-family: 'Verdana',sans-serif; mso-fareast-font-family: Calibri; mso-fareast-theme-font: minor-latin; mso-bidi-font-family: Arial; mso-bidi-theme-font: minor-bidi; color: #1a202c; mso-ansi-language: #0C00; mso-fareast-language: EN-US; mso-bidi-language: AR-SA;">•   Eliminates orphaned account risk through automated deprovisioning </td> <td style="width: 580.344px; border-width: 1pt 1pt 1pt medium; border-style: solid solid solid none; border-color: rgb(216, 221, 232) rgb(216, 221, 232) rgb(216, 221, 232) currentcolor; border-image: initial; background: rgb(255, 245, 245); padding: 9pt 10pt;"> − DISADVANTAGES •    Only officially supported with Entra ID, Okta, and PingOne •    SCIM is restricted to one SSO connection — separate IdP tenants per region means only one gets full automation •    Product instance assignments and role mappings still require one-time manual setup in the Admin Centre •    Initial setup is more complex — requires two separate IdP apps (SSO + SCIM) •    Partner users on external domains cannot share the SCIM-enabled connection </td> </tr> </tbody> </table>2026-06-16T12:37:47.0000000Z

Blog post

Understanding Optimizely Opal Cost vs ValueEvery Opal conversation seems to start with the same question: "What does it cost?" Fair, but it's only half the question. Cost tells you what you'll spend. Value tells you whether it was worth it, It can be completely different for a retailer - chasing campaign speed, a bank - protecting compliance, or an experimentation team - measuring throughput. In my follow-up to "Understanding Optimizely Opal Cost," I try to determineif we can actually measure Opal's value. <a href="https://www.linkedin.com/pulse/optimizely-opal-cost-vs-value-khurram-khan-vsume/">https://www.linkedin.com/pulse/optimizely-opal-cost-vs-value-khurram-khan-vsume/</a> 2026-06-15T14:02:57.0000000Z

Blog post

Leverage — The CMS Edits One Item at a Time. The Work Doesn't.Editorial work arrives in batches — a product rename across two hundred support articles, five hundred FAQs that should become blocks, an SEO refresh across a whole section. The productivity group in Editor Power Tools exists for exactly that: bulk editing, bulk import, and the views that keep a site's operational rhythm visible.2026-06-15T00:00:00.0000000Z

Blog post

“Learning by Doing – Optimizely OPAL Series” | Episode 02 is Live!<div style="text-align: left;"><h2 style="text-align: left;"><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi3TSnigp1qGyhNZM3pexS2hxFe0BQFA2Ichdjro5EOBY7MVlyyeEF6RIA0sWbJoBnnGPvBa1mh4SNwpLXmIdNGmN2hfsKJcKqKZQoCxULwhKLFzTI1SPKrQ_8WmMG3iC5zrlCbX0PeNfeoWmsDbWE_e_vuMyzvpsow7q1p3z3sECrGPtCEE_KOKHv2PhA/s1024/OptimizleyBlogBanner.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="1024" data-original-width="1024" height="636" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi3TSnigp1qGyhNZM3pexS2hxFe0BQFA2Ichdjro5EOBY7MVlyyeEF6RIA0sWbJoBnnGPvBa1mh4SNwpLXmIdNGmN2hfsKJcKqKZQoCxULwhKLFzTI1SPKrQ_8WmMG3iC5zrlCbX0PeNfeoWmsDbWE_e_vuMyzvpsow7q1p3z3sECrGPtCEE_KOKHv2PhA/w636-h636/OptimizleyBlogBanner.png" width="636" /></a></div> Introduction</h2> </div><div style="text-align: left;">With Optimizely OPAL, we’re not just generating content—we’re designing intelligent workflows. But after working with teams and experimenting hands-on, I noticed a recurring pattern: <ul style="text-align: left;"><li>Many are using OPAL</li><li>But not getting consistent results</li><li>And often struggling to move beyond basic prompts</li></ul>The reason is simple: <ul style="text-align: left;"><li>OPAL is only as powerful as the prompts you give it.</li></ul></div><div style="text-align: left;"> That’s exactly what Episode 02 focuses on. <h3 style="text-align: left;"><a href="https://youtu.be/95Ox0sXLs9Y" target="_blank">Episode 02: Prompt to Better Prompt</a></h3>The second episode is now live—and this is where things start getting practical. <ul style="text-align: left;"><li> Because this is not about using AI…</li><li> This is about using AI effectively</li></ul> In this episode, we cover <ul style="text-align: left;"><li> What is Prompt Engineering and why it matters</li><li> Why most AI outputs fail (and how to fix them)</li></ul></div><h3 style="text-align: left;">Popular frameworks:</h3><div style="text-align: left;"><ul style="text-align: left;"><li>RACE (Speed & simplicity)</li><li>CRISPE (Creativity & refinement)</li><li>COSTAR (Marketing & audience alignment)</li><li>CLEAR (Most practical for OPAL)</li><li>KERNEL (Automation & consistency)</li></ul> <h3 style="text-align: left;">The Shift: Prompt → Better Prompt</h3>One of the most important ideas in this episode is a simple but powerful shift: <ul style="text-align: left;"><li> Don’t struggle writing prompts manually</li><li>Instead:</li><ul><li>Use tools like Copilot / ChatGPT</li><li>Ask them to generate structured prompts (using frameworks)</li><li>Refine with your business context</li><li>Use them inside OPAL</li></ul></ul> Key Insight Use AI to improve your prompts → Then use OPAL to execute them  </div><div style="text-align: left;"><h3 style="text-align: left;">Real Use Case Covered</h3>We also walk through a real-world enterprise scenario: Building an SEO Blog Generator Agent <ul style="text-align: left;"><li>Where the agent can generate:</li><li>SEO-optimized titles</li><li>Meta descriptions</li><li>Structured headings (H2, H3)</li><li>Engaging introductions</li><li>Full content body</li><li>Internal & external link suggestions</li><li>Call-to-action</li><li>Related keywords</li></ul><h3 style="text-align: left;"> Why this matters</h3>This is not a simple prompt. <ul style="text-align: left;"><li>It requires:</li><ul><li>Structure</li><li>Context</li><li>Constraints</li><li>Output definition</li></ul></ul> And that’s where prompt frameworks become critical. </div><div style="text-align: left;"><h3 style="text-align: left;"> What Makes This Episode Different?</h3>Instead of just explaining frameworks… This episode focuses on: <ul style="text-align: left;"><li> When to use each framework</li><li> How to think structurally</li><li> How to apply it in OPAL</li><li> How to scale prompts into reusable agents</li></ul> Who Should Watch This Episode? <ul style="text-align: left;"><li>If you fall into any of these categories, this episode is for you:</li><li>Optimizely developers & architects</li><li>Digital marketers working with AI</li><li>DXP practitioners exploring OPAL</li><li>Anyone struggling with inconsistent AI outputs</li></ul>Watch the video here:</div><div style="text-align: left;"> </div><div style="text-align: left;"><div class="separator" style="clear: both; text-align: center;"><iframe allowfullscreen="" class="BLOG_video_class" height="354" src="https://www.youtube.com/embed/95Ox0sXLs9Y" width="426" youtube-src-id="95Ox0sXLs9Y"></iframe></div> </div>2026-06-14T17:53:38.0000000Z

Blog post

Content Variations in CMS 13, Part 3: Audiences vs Audiences<blockquote style="margin: 24px 0; padding: 18px 20px; background: #f5f5f4; border: 1px solid #e7e5e4; border-radius: 6px;"> Executive summary. Part 2 left the experiment running against Everyone. Real projects don't look like that. So this part wires those same CMS Content Variations to two rival audience engines and measures what each actually does. Every number below comes from a live CMS 13.1.0 + FX SDK instance. A targeted delivery served variant_a to 60 of 60 mobile visitors; at 100% allocation that is deterministic, so a single miss would be a bug rather than noise. The desktop experiment held its 33/33/34 split (χ² = 1.465, n = 300). The MVC head and the headless Next.js head agreed on the arm and the rule for 20 of 20 visitor/device pairs, with zero coordination code. The same runs found the boundary. CMS Audiences evaluate only inside the CMS runtime: a personalized block vanished from Optimizely Graph entirely, invisible to every headless consumer, and nothing threw an error. If your requirement says “both heads”, the audience decision is made before anyone asks about features. </blockquote> Parts 1 and 2 built the machine: Content Variations as the quiet hero of CMS 13, then Feature Experimentation as its stats engine, with one string, VariationKey == variation name, as the entire integration contract. This part answers the question that contract postpones: who decides who the visitor is? CMS 13 has an answer. FX has a different answer. Both are called Audiences now, and they are not the same thing. Everything below ran on CMS 13.1.0 with the C# SDK 4.3.0 and the JavaScript SDK 6.4.0. Every number is from those runs. In this part: the Audiences naming collision · the three-layer opt-in (and the startup self-check it forced) · the five-attribute pipeline with native geolocation · targeted delivery semantics the docs bury · the coexistence proof and the Graph void · the day the headless head went dark · three QA override levels · a troubleshooting runbook · eight sharp edges ranked by blood · FAQ · glossary. <h2>The machine at a glance</h2> One picture before the prose. Both heads serve the same experiment from the same definitions. The only shared state is configuration-as-data: <figure style="margin: 24px auto; text-align: center; max-width: 800px;"><img style="max-width: 100%; height: auto; border: 1px solid #e1e4e8; border-radius: 6px;" src="https://pino-labs.com/blog/content-variations-cms-13-part-3/machine-at-a-glance.svg" alt="Both heads read the same FX datafile and CMS Graph index. The MVC head runs Decide, loads the CMS variation and renders, with the CMS Audience filtering content-area items server-side. The Next.js head runs the same decision and renders via a Graph query, but the personalized items are absent from Graph." /> <figcaption style="font-size: 13px; color: #666; margin-top: 6px;">Both heads serve the same experiment from the same definitions; only the Graph path drops the personalized item. The CMS Audience layer has no representation on the headless route.</figcaption> </figure> The CMS Audience layer simply has no representation on the Graph path. The rest of this article is the evidence for every arrow. <h2>Two engines, one word: both of them are called Audiences now</h2> Start with the vocabulary trap, because it will find you anyway. Visitor Groups have been rebranding to Audiences since the CMS 12 admin redesign. CMS 13 finishes the job: the admin package describes itself as the “audiences management UI”, the docs say “an audience (formerly called a visitor group)”, and the old name survives mostly in role names and API types. Feature Experimentation has shipped Audiences for years. Same word, two engines, and they answer the same question with opposite architectures: <table style="border-collapse: collapse; width: 100%; margin: 20px 0; font-size: 14px;"> <thead> <tr> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;"> </th> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">CMS Audiences (formerly Visitor Groups)</th> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">FX Audiences</th> </tr> </thead> <tbody> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Evaluated by</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">The CMS, server-side, during rendering</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Every SDK, in-process, at Decide()</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Evaluation input</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">IPrincipal + HttpContext, full request, roles, visit history</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Only the attributes your code passed at context creation</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Definition lives in</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">CMS admin (VisitorGroupAdmins role)</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">FX dashboard, ships in the datafile</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Personalizes</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">A fragment, one content-area item</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">A page version, via the variation key contract from part 2</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Works headless</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">No, and the docs say so out loud</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Yes, the evaluation is a pure function, portable by construction</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Measurement</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">“Enable statistics” view counts, with no exposures, no conversions, no significance</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">The stats engine: exposures, conversions, significance</td> </tr> </tbody> </table> The last two rows are the ones that matter. A CMS Audience can reach into everything the CMS knows about the request, and pays for it by existing only where the CMS renders. An FX Audience knows nothing you didn't tell it, and pays for that with a pipeline you must build. But the function (datafile + attributes) → bool runs identically in C#, in Node, in anything with an SDK. Keep that trade in view. Every decision below falls out of it. One governance row to add to part 2's who-does-what table: audience definitions get owners too. CMS Audiences belong to whoever holds VisitorGroupAdmins. FX Audiences belong to the dashboard. Attribute keys, though, are an API contract between the codebase and the dashboard: a developer renames device and the marketer's audience quietly stops matching. Write them down somewhere both sides actually read. <h2>Switching the engine on: in CMS 13, personalization is opt-in three layers deep</h2> Part 2's sharp-edges list opened with a package that crashed CMS 13 at startup. This part's equivalent is gentler and stranger: in CMS 13, Visitor Groups are not in the box you already have. The EPiServer.CMS metapackage ships neither the evaluation core nor the UI. The install docs state the philosophy plainly: “every NuGet package your project references must have its services explicitly registered, or the application fails at startup.” The documented pair of calls is services.AddVisitorGroupsMvc().AddVisitorGroupsUI(), which also adds the EPiServer.CMS.UI.VisitorGroups 13.1.0 package. I learned what each one carries the honest way, by registering less than that. AddVisitorGroupsUI() alone boots clean. Then the Audiences screen throws Unable to resolve service for type 'IVisitorGroupCriterionRepository' the moment an editor clicks it: the screen's own API services, the ones that load criterion lists and persist rules, resolve against registrations the UI package does not carry. A UI that renders is not a UI that saves. Registering the two internal layers that error message points at fixes the admin screen. It also quietly skips the rendering layer, so personalized blocks would render for everyone. That's the worst possible failure mode: a working configuration surface for a filter that doesn't run. AddVisitorGroupsMvc() wraps all of it: repositories, the built-in criteria, the content-area rendering filter, and the “View as Audience” impersonation service. Notice what the docs promised and what actually happened. The promise: misregistration fails at startup. The observation: it failed at click time, with a green boot log. So the demo project now resolves the services the Audiences API needs at startup, in Development, and logs every registered criterion: DeviceCriterion, DisplayChannelCriterion, … TimeOfDayCriterion, … (22 of them), making the documentation's promise true at exactly the layer where it broke. Twenty-two criteria, including RoleCriterion and UserProfileCriterion that the docs list doesn't mention, plus DeviceCriterion, which is ours. The whole class fits on a slide, and it earns the line this demo is built around: one definition of “who you are”, two engines reading it. <pre style="background: #f6f8fa; border: 1px solid #e1e4e8; border-radius: 6px; padding: 16px; overflow: auto; font-family: Consolas,Monaco,monospace; font-size: 13px; line-height: 1.5;">[VisitorGroupCriterion( Category = "Technical", DisplayName = "Device class", Description = "Matches the visitor's device class (mobile / tablet / desktop) " + "using the same User-Agent heuristic that feeds the FX 'device' attribute.")] public class DeviceCriterion(IVisitorAttributesProvider attributesProvider) : CriterionBase<DeviceCriterionModel> { public override bool IsMatch(IPrincipal principal, HttpContext httpContext) { // Editors type the value by hand - trim + lowercase forgives "Mobile " // (the FX exact matcher would not; see sharp edge #1). var expected = Model.Device?.Trim().ToLowerInvariant(); return !string.IsNullOrEmpty(expected) && attributesProvider.GetAttributes().TryGetValue("device", out var device) && Equals(device, expected); } }</pre> Constructor injection works (the built-in geographic criteria take IClientGeolocationResolver the same way), [VisitorGroupCriterion] registers the class through plugin scanning, and the model is CriterionModelBase with one string property and a Copy() => ShallowCopy(). The built-in OSBrowserCriterion could classify devices without custom code. Ours exists for consistency with the FX attribute, not for extra capability. <h3>Reference card: the CMS 13 personalization bill of materials</h3> <table style="border-collapse: collapse; width: 100%; margin: 20px 0; font-size: 14px;"> <thead> <tr> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">Call</th> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">Package</th> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">What it actually registers</th> </tr> </thead> <tbody> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">AddVisitorGroupsMvc()</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">EPiServer.Cms.AspNetCore.Mvc (already referenced)</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">The whole working engine: repositories and statistics, role infrastructure, the built-in criteria, the content-area rendering filter, fragment handlers, View-as-Audience impersonation</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">AddVisitorGroupsUI()</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">EPiServer.CMS.UI.VisitorGroups (add it; not in the metapackage)</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">The Audiences management screen (protected module VisitorGroups.zip) and its API controllers</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">AddCmsClientGeolocation(o => o.LocationHeader = …)</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">EPiServer.Geolocation (already referenced)</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Header-based geolocation: feeds the geographic criteria and anything else consuming IClientGeolocationResolver</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">[VisitorGroupCriterion] on your class</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">your project</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Custom criteria via plugin scanning; explicit AddVisitorGroupsCriterion<T>() only if you disable scanning</td> </tr> </tbody> </table> And the criteria catalog as measured on 13.1.0, the self-check log, deduplicated and grouped, because no docs page currently lists all of them: <table style="border-collapse: collapse; width: 100%; margin: 20px 0; font-size: 14px;"> <thead> <tr> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">Group</th> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">Criteria</th> </tr> </thead> <tbody> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Behavior</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">NumberOfVisits, ViewedPages, ViewedCategories, Download, TimeOnSite, Event</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Arrival</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Referrer, SearchWordReferrer, StartUrl, QueryString</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Time</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">TimeOfDay, TimePeriod</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Place & client</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">GeographicLocation, GeographicCoordinate, IPRange, OSBrowser, DisplayChannel, SelectedLanguage</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Identity</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Role, UserProfile, VisitorGroupMembership</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Custom (this demo)</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">DeviceCriterion</td> </tr> </tbody> </table> Two of those built-ins, configured: a time-of-day window and a country match, both reading request and CMS state the FX engine never sees. <figure style="margin: 24px auto; text-align: center; max-width: 800px;"><img style="max-width: 100%; height: auto; border: 1px solid #e1e4e8; border-radius: 6px;" src="https://pino-labs.com/blog/content-variations-cms-13-part-3/vg-criterion-timeofday.png" alt="Built-in Time of Day criterion on an Office hours CMS audience: 08:00-16:00, Monday to Friday." /> <figcaption style="font-size: 13px; color: #666; margin-top: 6px;">Built-in Time of Day criterion on an “Office hours” CMS audience: 08:00–16:00, Monday to Friday.</figcaption> </figure> <figure style="margin: 24px auto; text-align: center; max-width: 800px;"><img style="max-width: 100%; height: auto; border: 1px solid #e1e4e8; border-radius: 6px;" src="https://pino-labs.com/blog/content-variations-cms-13-part-3/vg-criterion-geo.png" alt="Built-in Geographic Location criterion on a Visitors from PL CMS audience: Europe / Poland." /> <figcaption style="font-size: 13px; color: #666; margin-top: 6px;">Built-in Geographic Location criterion on a “Visitors from PL” CMS audience: Europe / Poland.</figcaption> </figure> <h2>The attribute pipeline: FX only knows what you tell it</h2> The part-2 provider sent two attributes derived from the request: device from the User-Agent, location from geo headers. Part 3 grows it to five, and the growth is where the lessons are: <pre style="background: #f6f8fa; border: 1px solid #e1e4e8; border-radius: 6px; padding: 16px; overflow: auto; font-family: Consolas,Monaco,monospace; font-size: 13px; line-height: 1.5;">return new Dictionary<string, object?> { ["device"] = ResolveDevice(request), // "mobile" | "tablet" | "desktop" ["location"] = ResolveLocation(context), // "PL", "SE", ... | "unknown" ["logged_in"] = context?.User.Identity?.IsAuthenticated == true, // a real bool ["cms_role"] = ResolveCmsRole(context?.User), // "admin" | "editor" | "none" ["consent"] = HasConsent(request) // a real bool, from a cookie };</pre> <figure style="margin: 24px auto; text-align: center; max-width: 800px;"><img style="max-width: 100%; height: auto; border: 1px solid #e1e4e8; border-radius: 6px;" src="https://pino-labs.com/blog/content-variations-cms-13-part-3/fx-attributes.png" alt="FX dashboard, Settings to Audiences to Attributes: the five registered attribute keys." /> <figcaption style="font-size: 13px; color: #666; margin-top: 6px;">The five registered attribute keys (cms_role, consent, device, location, logged_in), the code-to-dashboard contract.</figcaption> </figure> Three rules. All three carried more weight than I expected when I wrote them down. (Throughout this article, “the panel” means part 2's instrument set. The demo page renders a variation pill carrying the served arm plus a data-rule attribute naming the rule that served it, and a Development-only diagnostics panel showing the visitor ID, the attribute dictionary and the SDK's Decide reasons. Every measurement below reads off those two surfaces.) <figure style="margin: 24px auto; text-align: center; max-width: 800px;"><img style="max-width: 100%; height: auto; border: 1px solid #e1e4e8; border-radius: 6px;" src="https://pino-labs.com/blog/content-variations-cms-13-part-3/demo-diagnostics.png" alt="The variation pill and the FX decision diagnostics." /> <figcaption style="font-size: 13px; color: #666; margin-top: 6px;">“The panel”: the variation pill and the FX decision diagnostics: visitor ID, served variation, the attribute dictionary, and the SDK INCLUDE_REASONS trace.</figcaption> </figure> Types are the contract. Attributes are untyped in the dashboard. The value you send decides which comparisons can match. Send the string "true" against a boolean condition and the condition is skipped: evaluated to UNKNOWN, audience false, visitor falls through, nobody logs an error at default verbosity. The booleans above are real booleans for exactly that reason. (Sharp edge #3 has the measurement.) Absent and false are different inputs. An anonymous visitor on the MVC head sends logged_in = false. If the headless head simply omitted the key, an audience targeting logged_in is false would match on one head and skip on the other. Same visitor, same flag, different arms, and you would hunt the bug in the hashing where it isn't. The Next.js head therefore sends the constants its reality justifies: its visitors are, truthfully, never logged in. One request, one context, attributes enter once. The decision service is request-scoped and builds the SDK user context a single time. The banner flag, the experiment and the conversion all agree on who the visitor is. Change an attribute mid-request and nothing happens. That's by design, and worth a comment in the code so nobody “fixes” it. <h3>Geolocation: one header now feeds both engines</h3> The hand-rolled four-header geo parser from part 2 is gone. CMS 13 ships native client geolocation: country from a single configured CDN header, no local IP database. One line wires it: services.AddCmsClientGeolocation(o => o.LocationHeader = "CF-IPCountry"). The same IClientGeolocationResolver now answers two callers: our FX location attribute and the built-in geographic criterion of CMS Audiences. One configuration line, two engines. That also means one spoofed header fools both at once. curl -H "CF-IPCountry: SE" and the panel reads location=SE. The part-2 caveat about attacker-supplied input didn't go away. It doubled its blast radius. And a detail measured the hard way: the resolver wants an uppercase ISO code. PL resolves; pl resolves to nothing. Cloudflare sends uppercase, so production works. But any homegrown proxy that normalizes headers to lowercase turns your geographic targeting off, both engines' worth of it, with no warning, no log line, no sound. The diagnostics panel reading location=unknown while the header is plainly there is the only tell. The consent attribute is not an attribute. Or rather: it is targetable like any other, but its real job is a switch. Impression and conversion events carry the visitor ID and the attribute dictionary to Optimizely's backend. That payload is precisely the thing a non-consenting visitor declined. So when consent is false, the service calls Decide with DISABLE_DECISION_EVENT and turns Track into a logged no-op. Flags keep working, because the datafile evaluation is local, but nothing leaves the building. Consent isn't an audience attribute. It's an event-egress switch. (The demo toggles it with a cookie; a real implementation wires it to your CMP. And the conversion button now reports tracked: false instead of celebrating an event that never left. A demo that lies to you is worse than no demo.) One boundary disclosed rather than implied: the visitor-ID cookie itself is set, and bucketing happens, before any consent. This build treats the identifier as functional state and gates only what leaves the building. Your CMP, or your DPO, may read that line differently. That conversation belongs in your project rather than an SDK option. One honest note before moving on: FX has no server-side bot filtering. A crawler's User-Agent contains no “Mobi”, so every bot enters your experiment as a desktop visitor and dilutes whatever it touches. Either gate Decide on known-bot UAs, or accept the noise with your eyes open. <h2>Targeted Delivery: personalization without the dice</h2> The plan was seductively simple: put a targeted rule above the everyone-else A/B test. Mobile gets the personalized arm, everyone else keeps experimenting. The dashboard said no, and the way it says no is the finding. The ruleset isn't one sortable list. It's three fixed sections whose headings literally narrate the evaluation order: <ol> <li>First, match experiment rule → a_b_test (A/B, audience: Non-mobile visitors)</li> <li>Then, the following rules will be evaluated for all visitors → mobile_delivery (deliver variant_a, 100%)</li> <li>Then, for everyone else → Off</li> </ol> <figure style="margin: 24px auto; text-align: center; max-width: 800px;"><img style="max-width: 100%; height: auto; border: 1px solid #e1e4e8; border-radius: 6px;" src="https://pino-labs.com/blog/content-variations-cms-13-part-3/ruleset-layered.png" alt="The ruleset three fixed sections: experiment first, then deliveries for all visitors, then everyone-else." /> <figcaption style="font-size: 13px; color: #666; margin-top: 6px;">The ruleset's three fixed sections: experiment first, then deliveries for all visitors, then everyone-else. No shared list to drag a delivery above an experiment.</figcaption> </figure> <figure style="margin: 24px auto; text-align: center; max-width: 800px;"><img style="max-width: 100%; height: auto; border: 1px solid #e1e4e8; border-radius: 6px;" src="https://pino-labs.com/blog/content-variations-cms-13-part-3/rule-targeted.png" alt="The mobile_delivery rule: Targeted Delivery, audience Mobile visitors, 100%, deliver variant_a." /> <figcaption style="font-size: 13px; color: #666; margin-top: 6px;">The mobile_delivery rule: Targeted Delivery, audience Mobile visitors, 100%, deliver variant_a.</figcaption> </figure> <figure style="margin: 24px auto; text-align: center; max-width: 800px;"><img style="max-width: 100%; height: auto; border: 1px solid #e1e4e8; border-radius: 6px;" src="https://pino-labs.com/blog/content-variations-cms-13-part-3/fx-audience-mobile.png" alt="The Mobile visitors FX audience: device equals mobile." /> <figcaption style="font-size: 13px; color: #666; margin-top: 6px;">The Mobile visitors FX audience: device equals “mobile”, with all five attribute keys in the browser on the right.</figcaption> </figure> <figure style="margin: 24px auto; text-align: center; max-width: 800px;"><img style="max-width: 100%; height: auto; border: 1px solid #e1e4e8; border-radius: 6px;" src="https://pino-labs.com/blog/content-variations-cms-13-part-3/fx-audience-codemode.png" alt="The same audience in Code Mode: match_type exact." /> <figcaption style="font-size: 13px; color: #666; margin-top: 6px;">The same audience in Code Mode: match_type “exact”. The datafile the SDKs evaluate spells the field match (sharp edge #1).</figcaption> </figure> <figure style="margin: 24px auto; text-align: center; max-width: 800px;"><img style="max-width: 100%; height: auto; border: 1px solid #e1e4e8; border-radius: 6px;" src="https://pino-labs.com/blog/content-variations-cms-13-part-3/fx-audience-nonmobile.png" alt="The Non-mobile visitors audience: device equals desktop OR tablet." /> <figcaption style="font-size: 13px; color: #666; margin-top: 6px;">The Non-mobile visitors audience used to carve the experiment: a positive list, device equals desktop OR tablet, so an unknown device matches nothing and lands on master.</figcaption> </figure> FX evaluates experiments before deliveries. Always. The UI encodes the law in its page structure rather than enforcing it with an error. So carving mobile out of the experiment happens in the audience, not in rule order. The A/B rule's audience changed from Everyone to Non-mobile visitors: a deliberately positive list (device = desktop OR tablet) rather than a negation. That way a visitor with a missing or mangled device attribute matches nothing and lands on master, which is the honest outcome for “we don't know who this is”. Two semantics from the docs that almost nobody quotes, both load-bearing: <ul> <li>An experiment whose audience matches but whose traffic allocation misses rolls down to the next rule. A delivery in the same situation jumps straight to everyone-else, skipping any deliveries below it.</li> <li>Deliveries produce no Results page: “No decision events show up on the results page.” A delivery is deployment, not measurement. Our mobile visitors get their personalization and leave the experiment's bookkeeping entirely. The A/B sample quietly becomes a desktop-and-tablet sample. Write that sentence in your analysis doc before someone asks why the experiment's traffic dropped.</li> </ul> And one behavioral nuance that will eventually puzzle a stakeholder: bucketing is sticky, attributes are not. The same visitor who taps “Request desktop site” in mobile Chrome flips device mid-cookie, exits the delivery, and enters the experiment. Same visitor ID, different arm, both serves correct. Attribute-driven targeting re-evaluates every request. Only the hash is forever. Configuration footnote from the audience builder: the dashboard's Code Mode validates conditions with the key match_type, while the datafile the SDKs download spells the very same field match. Two serializations of one concept. Harmless until you copy a condition from the datafile into Code Mode and the validator rejects what the SDK just evaluated. The SDK's own log line later in this article shows the match spelling in the wild. <h2>Can both engines coexist on one page? Yes, at different layers, measurably</h2> This is the part people actually google, so here is the layered setup, built and measured. FX picks the page version (mobile → variant_a via the delivery), and inside that version one block carries a CMS Audience (Mobile visitors (CMS), our DeviceCriterion). Two engines, two layers, same page. <figure style="margin: 24px auto; text-align: center; max-width: 800px;"><img style="max-width: 100%; height: auto; border: 1px solid #e1e4e8; border-radius: 6px;" src="https://pino-labs.com/blog/content-variations-cms-13-part-3/vg-audiences-list.png" alt="CMS Audiences admin: Mobile visitors (CMS), Office hours, Visitors from PL." /> <figcaption style="font-size: 13px; color: #666; margin-top: 6px;">CMS Audiences admin: Mobile visitors (CMS), Office hours, Visitors from PL.</figcaption> </figure> <figure style="margin: 24px auto; text-align: center; max-width: 800px;"><img style="max-width: 100%; height: auto; border: 1px solid #e1e4e8; border-radius: 6px;" src="https://pino-labs.com/blog/content-variations-cms-13-part-3/vg-admin.png" alt="The Mobile visitors (CMS) audience on the custom Device class criterion." /> <figcaption style="font-size: 13px; color: #666; margin-top: 6px;">The Mobile visitors (CMS) audience on the custom Device class criterion (value “mobile”), statistics enabled.</figcaption> </figure> <figure style="margin: 24px auto; text-align: center; max-width: 800px;"><img style="max-width: 100%; height: auto; border: 1px solid #e1e4e8; border-radius: 6px;" src="https://pino-labs.com/blog/content-variations-cms-13-part-3/vg-personalize.png" alt="Assigning the audience to a content-area block inside variant_a in the CMS editor." /> <figcaption style="font-size: 13px; color: #666; margin-top: 6px;">Assigning the audience to a content-area block inside variant_a in the CMS editor, with the rendered variant on the right.</figcaption> </figure> The measurement needed care, because FX variation noise would drown the block signal. Take one visitor ID that desktop-buckets into variant_a through the experiment, then request the page twice: same visitor, same page version, only the User-Agent differs. <table style="border-collapse: collapse; width: 100%; margin: 20px 0; font-size: 14px;"> <thead> <tr> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">Probe (same visitor, same variant_a)</th> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">Rule that served it</th> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">Content area</th> </tr> </thead> <tbody> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Desktop</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">a_b_test</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">empty, block filtered out</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Mobile</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">mobile_delivery</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">“Mobile Quiet Hero” renders</td> </tr> </tbody> </table> Pure visitor-group effect, isolated from FX. The coexistence answer: no conflict, different layers. The FX decision happens in the controller before rendering. The CMS Audience filters content-area items during rendering. The pitfall isn't a conflict, it's unreachability: personalize a block for mobile in the master version and no one will ever see it, because under this ruleset mobile never receives master. The FX rule one layer up decides which content area exists at all. There's a sour bonus measurement. An earlier build of this demo, the one registered from decompiled internals instead of the documented AddVisitorGroupsMvc(), served that personalized block to the desktop probe too. Same content, same audiences, one missing rendering filter, zero errors. Keep that pair of runs. It's the cleanest argument I own for “configure from the docs, not from the decompiler”. <h3>What does Content Graph actually do with a personalized block?</h3> The same page travels to the Next.js head through Optimizely Graph. The personalized item doesn't: <pre style="background: #f6f8fa; border: 1px solid #e1e4e8; border-radius: 6px; padding: 16px; overflow: auto; font-family: Consolas,Monaco,monospace; font-size: 13px; line-height: 1.5;">variant_a → MainContentArea: [] (the block the MVC head demonstrably renders) original → MainContentArea: [] control → MinimalPage.HeroArea: [{ "Heading": "EN Heading" }] // non-personalized area expands fine</pre> <figure style="margin: 24px auto; text-align: center; max-width: 800px;"><img style="max-width: 100%; height: auto; border: 1px solid #e1e4e8; border-radius: 6px;" src="https://pino-labs.com/blog/content-variations-cms-13-part-3/graph-void.png" alt="Optimizely Graph: all three DemoPage arms are in the index with distinct DemoTitle, yet every MainContentArea is empty." /> <figcaption style="font-size: 13px; color: #666; margin-top: 6px;">Optimizely Graph: all three DemoPage arms (variant_a, variant_b, master) are in the index with distinct DemoTitle, yet every MainContentArea is []. The page variation survives; the personalized content-area relation does not.</figcaption> </figure> Not a leak. A void. The VG-personalized item vanishes from the index for every Graph consumer, including the mobile visitors who would have matched. No API error, no warning in the sync job, nothing for the front-end to even detect. The shape of the void is worth a second look: the block itself is still in the index, four QuietHeroBlock documents, each with its own identity and content, but the page's content-area relation to it is gone. The explanation consistent with every measurement is that indexing evaluates the page without a visitor to personalize for, and an audience-gated item has no honest answer to “should this exist?”, so it doesn't. Whatever the internals, the contract you can rely on is the measured one: personalization severs the composition, not the content. The docs say it without decoration: “audiences do not work on headless sites.” The measurement above is what that sentence costs in practice. So what do you actually do when the roadmap says headless? There are three shapes, in order of preference. First, move that personalization up a layer to FX Audiences and Content Variations. That is this article's whole thesis, and it needs nothing new. Second, take the CMS 13.1.0 Graph Conventions API and customize indexing so the head receives the items plus enough metadata to filter client-side. Workable, but now you own the audience semantics on every head. Third, stand up a membership endpoint on the CMS that the head consults per request. It works, and it is exactly the coordination code this series exists to avoid. There is no fourth option where the block just shows up. <h3>The decision table</h3> <table style="border-collapse: collapse; width: 100%; margin: 20px 0; font-size: 14px;"> <thead> <tr> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">You need…</th> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">Engine</th> </tr> </thead> <tbody> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">The same personalization on every head, today and after the next re-platform</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">FX Audiences + Content Variations</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Criteria that read CMS state: roles, visit history, time of day</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">CMS Audiences</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Measurement: exposures, conversions, significance</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">FX (deliveries excluded, they don't report)</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Kill switch without a deploy</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">FX (latency = datafile propagation; measured at ~75 s here)</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Fragment-level personalization, CMS-rendered site, no measurement need</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">CMS Audiences</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Zero marginal license cost</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">CMS Audiences (in the CMS license; FX is usage-billed, though deliveries fire no impressions, only experiment bucketing does)</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Per-request evaluation cost approaching zero</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">FX (pure in-memory function; VG criteria may do I/O per content-area item)</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Ownership by content editors: instant, local, visual</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">CMS Audiences (VisitorGroupAdmins; no deploy, no datafile, changes land on publish)</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Ownership by product managers and analysts</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">FX Audiences, with attribute-key discipline as the price: keys are a code-to-dashboard contract, and once created an attribute stays in the datafile permanently</td> </tr> </tbody> </table> A word of architectural restraint: a personalized block inside an experiment variation multiplies your test matrix: arms × audiences × consent states. The demo does it to prove the layering. Production teams should default to one personalization axis per page, and budget QA explicitly before crossing them. ODP deserves its one paragraph: when the attributes should come from customer data rather than the current request, Real-Time Segments for Feature Experimentation syncs ODP audiences into the same rule slots. Segments stay out of the datafile, qualification typically lands under thirty seconds, and Optimizely's own docs concede that when you need 100% accuracy you should fall back to plain custom attributes. Different source, same predicate machinery. That's the whole story here. This demo has no ODP account on purpose. <h2>From prose to proof: the day the headless head went dark</h2> Here is the embarrassing measurement first, because it earns the rest of the section. The moment the A/B rule's audience changed from Everyone to Non-mobile visitors, the Next.js head, which part 2 proudly demonstrated holding a perfect 33/33/34, went one hundred percent dark: <pre style="background: #f6f8fa; border: 1px solid #e1e4e8; border-radius: 6px; padding: 16px; overflow: auto; font-family: Consolas,Monaco,monospace; font-size: 13px; line-height: 1.5;">default (master) 300 (100.00 %) FAILED: "300 request(s) were served the master page (no FX decision) - check that the rule is Running, Traffic Allocation is 100% and the SDK key matches the rule's environment."</pre> Rule running, allocation 100%, SDK key correct. The test's own diagnostic, written by me in part 2, blames everything except the actual cause: the head's decide() sent no attributes, so the visitor matched neither audience and fell through to everyone-else-off. No errors, green dashboards, a misleading failure message, and a head silently serving master to every visitor from the minute the audience shipped. Audiences don't add a feature to your architecture. They add a requirement to every head you run. The fix is a mirror: a buildAttributes() on the Next side that reproduces the .NET pipeline byte for byte. The parity contract lives in one file with a comment that says exactly that: if the heuristics drift, parity dies at the attribute layer while everyone debugs the hash. The contract itself fits in a table, which is how it should be reviewed: <table style="border-collapse: collapse; width: 100%; margin: 20px 0; font-size: 14px;"> <thead> <tr> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">Attribute</th> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">The rule both heads obey</th> </tr> </thead> <tbody> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">device</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Substring tests, case-insensitive: iPad/Tablet → tablet, else Mobi → mobile, else desktop</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">location</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Header path is strict: ^[A-Z]{2}$ and ≠ XX, no case folding (mirrors the measured CMS resolver); the Accept-Language fallback does fold case (pl-PL → PL)</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">logged_in, cms_role</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Real types, truthful constants on the auth-less head (false, "none"): absent and false are different inputs</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">consent</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">bool.TryParse semantics: case-insensitive true, anything else false</td> </tr> </tbody> </table> Upgrading the JS SDK to v6 along the way produced one trap worth its own line. v6 is explicit-opt-in across the board: polling config manager, logger, and ODP all opt-in. So is the event processor: omit createBatchEventProcessor() and decisions keep flowing while the SDK dispatches no events at all. Served-but-unmeasured, the exact failure shape this series keeps finding, now available at the initialization layer. (The same modularity quietly fixed an old log nag: no ODP manager, no “ODP is not integrated” warnings.) Two Next.js-specific notes earned their scars. The SDK instance is cached on globalThis, the same trick Prisma clients use, because next dev's Fast Refresh re-evaluates modules. A module-level singleton would leak a fresh polling manager and event processor on every save, and your datafile CDN would meet them all. And one asymmetry to disclose rather than hide: the C# head flushes its event queue on shutdown because the DI container disposes the client (part 2's contract). A Node process has no such container. The batch rides flushInterval, and what happens at the end of a process's life depends entirely on what kind of life it had: <ul> <li>Long-running Node (next start, a container): safe. The queue drains on the interval, and a tail lost to a SIGTERM is a rounding error.</li> <li>Serverless / edge: risky. The platform can freeze the instance the moment the response returns, and a consented conversion dies in the buffer as a zombie event.</li> <li>The fix where it matters: shrink the batch to the point of synchronicity, or await client.close() before the invocation ends, and accept the latency as the price of the data.</li> </ul> Pretending the queue always drains would be exactly the kind of silence this series hunts. <figure style="margin: 24px auto; text-align: center; max-width: 800px;"><img style="max-width: 100%; height: auto; border: 1px solid #e1e4e8; border-radius: 6px;" src="https://pino-labs.com/blog/content-variations-cms-13-part-3/next-head.png" alt="The Next.js headless head on a mobile viewport serving variant_a via mobile_delivery." /> <figcaption style="font-size: 13px; color: #666; margin-top: 6px;">The Next.js headless head on a mobile viewport: the same FX decision serves variant_a via mobile_delivery, and the variation's title arrives through Optimizely Graph, with zero coordination with the MVC head.</figcaption> </figure> Then the green numbers, all in one evening: <table style="border-collapse: collapse; width: 100%; margin: 20px 0; font-size: 14px;"> <thead> <tr> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">Check</th> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">Result</th> </tr> </thead> <tbody> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Mobile, 60 fresh visitors (hard assertion: a delivery rolls no dice)</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">60/60 variant_a via mobile_delivery</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Desktop distribution, n = 300, against the Next head</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">103 / 105 / 92, χ² = 0.985 (critical 13.816 at α = 0.001, df = 2)</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Same regression against the MVC head</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">99 / 109 / 92, χ² = 1.465</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Cross-head parity: 4 fixed + 6 random visitors × desktop and mobile</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">arm AND rule identical on both heads, 20/20 pairs</td> </tr> </tbody> </table> <figure style="margin: 24px auto; text-align: center; max-width: 800px;"><img style="max-width: 100%; height: auto; border: 1px solid #e1e4e8; border-radius: 6px;" src="https://pino-labs.com/blog/content-variations-cms-13-part-3/next-distribution.svg" alt="The desktop chi-square run against the headless Next.js head: 103 / 105 / 92 over n = 300, chi-square 0.985." /> <figcaption style="font-size: 13px; color: #666; margin-top: 6px;">The desktop chi-square run against the headless Next.js head: 103 / 105 / 92 over n = 300, χ² = 0.985, well under the 13.816 critical value. Every decision came from Optimizely FX in the Node SDK, zero coordination with the MVC head.</figcaption> </figure> The parity test asserts the rule key, not just the arm. “mobile got variant_a” and “mobile happened to be bucketed into variant_a” are different claims, and only data-rule in the markup separates them. MurmurHash plus deterministic audience evaluation. Still zero coordination code. The arithmetic deserves to be shown once, not just asserted. For the MVC regression (99 / 109 / 92 over n = 300, expected ≈ 100 per arm): <pre style="background: #f6f8fa; border: 1px solid #e1e4e8; border-radius: 6px; padding: 16px; overflow: auto; font-family: Consolas,Monaco,monospace; font-size: 13px; line-height: 1.5;">χ² = (99−100)²/100 + (109−100)²/100 + (92−100)²/100 = 0.01 + 0.81 + 0.64 ≈ 1.46</pre> (The suite reports 1.465 because it tests against the configured 33.33/33.33/33.34 rather than exact thirds.) With df = k − 1 = 2 and α = 0.001, the critical value is 13.816, and 1.465 ≪ 13.816, so the null hypothesis (“the split matches the configuration”) survives comfortably. In words: after carving the mobile segment out with an audience, the hash shows no distributional anomaly in what remains. The same computation on the Next head's 103 / 105 / 92 gives 0.985, comfortably inside the spread a fair split throws at n = 300. Threats to validity, disclosed as ever: the chi-square run verifies the bucketing distribution, not content delivery (part 2's caveat stands). The mobile check is exhaustive rather than statistical, because a 100% delivery is deterministic: a single counterexample falsifies it, no α required. And every test here runs without a consent cookie, which after the egress gate means the suite sends zero impressions to FX. Three hundred requests of load testing used to pollute Results. Now the same suite is invisible to it. That started as a privacy control and turned out to be test hygiene. <h2>QA: three override levels, three owners</h2> “How does QA see the variant for a segment they don't belong to?” That is the question audiences force on every test plan. Three answers, escalating by who owns them: <ol> <li>New visitor (the cookie-reset button, part 2): owned by anyone with a browser. Re-rolls the dice but can't cross an audience boundary. The button also demonstrates something subtler: rotating the visitor ID re-buckets every experiment, leaves a delivery unmoved (its audience is deterministic in the attributes, not the ID), and the CMS Audience doesn't even notice; its criteria never saw your visitor ID in the first place. One page, three different notions of who “you” are. QA plans that conflate them chase ghosts.</li> <li>Allowlist (dashboard, per rule, up to fifty IDs): owned by the marketer, pins a visitor ID to an arm. Measured here: an allowlisted ID came back variant_b with the SDK reason “is forced in variation”. Caveat: allowlisted traffic still fires impressions, so your QA session pollutes Results.</li> <li>?fx_force=demo_ab_test:variant_b (this part): owned by the developer, a Development-only query parameter mapped to the SDK's forced-decision API. It bypasses audiences and allocation (forced mobile, forced desktop, doesn't matter), and, deliberately unlike the allowlist, a forced request also suppresses its decision events. QA that leaves no fingerprints on the data it's there to protect.</li> </ol> <figure style="margin: 24px auto; text-align: center; max-width: 800px;"><img style="max-width: 100%; height: auto; border: 1px solid #e1e4e8; border-radius: 6px;" src="https://pino-labs.com/blog/content-variations-cms-13-part-3/ab-rule-allowlist.png" alt="The A/B Test rule: audience Non-mobile visitors, 100%, the split, and the allowlist pinning a QA visitor ID to variant_b." /> <figcaption style="font-size: 13px; color: #666; margin-top: 6px;">The A/B Test rule: audience Non-mobile visitors, 100%, the 33.33 / 33.33 / 33.34 split, and the allowlist pinning a QA visitor ID to variant_b.</figcaption> </figure> The whole mechanism is one small source behind one small interface, so the SDK types stay where part 2 put them: <pre style="background: #f6f8fa; border: 1px solid #e1e4e8; border-radius: 6px; padding: 16px; overflow: auto; font-family: Consolas,Monaco,monospace; font-size: 13px; line-height: 1.5;">var forced = forcedDecisionSource.GetForcedDecisions(); // [] outside Development foreach (var (flagKey, variationKey) in forced) { userContext.SetForcedDecision( new OptimizelyDecisionContext(flagKey), new OptimizelyForcedDecision(variationKey)); } _eventsAllowed &= forced.Count == 0; // QA traffic never reaches Results</pre> While we're holding the decide call open, the full option set gets a reference table (part 2 named these in prose): <table style="border-collapse: collapse; width: 100%; margin: 20px 0; font-size: 14px;"> <thead> <tr> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">Decide option</th> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">What it does</th> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">Where this series uses it</th> </tr> </thead> <tbody> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">INCLUDE_REASONS</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Returns the evaluation trace: which rule matched, why audiences failed</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Every call; feeds the diagnostics panel</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">DISABLE_DECISION_EVENT</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Evaluates without sending an impression</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">No-consent requests; forced QA requests</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">ENABLED_FLAGS_ONLY</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Filters DecideAll to enabled flags</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">n/a</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">IGNORE_USER_PROFILE_SERVICE</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Skips UPS stickiness for this call</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">n/a (this demo runs without UPS)</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">EXCLUDE_VARIABLES</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Omits variable payloads for cheaper decisions</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">n/a</td> </tr> </tbody> </table> The CMS side has its own counterpart, View as Audience in the editor, with one boundary note: it previews visitor groups, not FX arms, and the docs scope it to CMS-rendered sites only. Pair the two in your test plan. Neither substitutes for the other. Forced decisions don't persist. They clear with the user context, which in this architecture means they last exactly one request. That's not a limitation. Per-request is the only scope that can't leak into someone's real session. <h2>Runbook: “the page always serves master”, audience edition</h2> Part 2 ended with a checklist for the all-master symptom. Audiences roughly double it. The developer's mental map first: data-rule on the pill is the fork in the road. <ul> <li>data-rule is empty, no decision happened at all: SDK key, datafile or flag off (part 2's checklist).</li> <li>data-rule = default-rollout-…, “everyone else” fired, so no audience matched: <ul> <li>Attributes row wrong or missing → context pipeline gap (the dark-head failure: a head sending nothing).</li> <li>Attributes row correct → condition-side defect (whitespace, case, type); open the audience in Code Mode, where quotes make it visible.</li> </ul> </li> <li>data-rule = a real rule, arm = original, working as designed: the control arm serves master via fallback.</li> </ul> And the full ordered checklist, where each step assumes the previous ones passed: <table style="border-collapse: collapse; width: 100%; margin: 20px 0; font-size: 14px;"> <thead> <tr> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">#</th> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">Check</th> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">Where the truth shows</th> </tr> </thead> <tbody> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">1</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">SDK key matches the rule's environment; ruleset Running; variation toggles ON</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Part 2's checklist (dashboard)</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">2</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">The decision reached a rule at all</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">data-rule on the pill: default-rollout-… means everyone-else fired</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">3</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">The attributes you think you send are the attributes you send</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Diagnostics panel, Attributes row, wrong name, wrong case, wrong type, missing key are all visible here</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">4</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">The audience condition matches those attributes byte-for-byte</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Reasons: “collectively evaluated to FALSE” while the panel shows the right value means a condition-side defect; open the audience in Code Mode, quotes make it visible</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">5</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Type mismatches</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">SDK log (not reasons): “evaluated to UNKNOWN because a value of type … was passed”, requires the part-2 logger</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">6</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">The head sends attributes at all</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">The dark-head failure: decide() without attributes matches nothing, and the test diagnostics will blame the rule</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">7</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Datafile freshness</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Audience edits propagate on the polling interval like every other change</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">8</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">(CMS side) the personalized block's layer is reachable</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">A block personalized in a version the visitor never receives is invisible by construction</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">9</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">(CMS side) the rendering layer is registered</td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Audiences screen working ≠ filter running, AddVisitorGroupsMvc(), then the startup self-check proves it</td> </tr> </tbody> </table> <h2>Sharp edges, part 3: ranked by blood actually drawn</h2> Same tradition, same ordering rule. Every one of these happened on this instance, this week. 1. A trailing space in an audience condition. The audience said device = "mobile ". The builder keeps whatever the clipboard delivered, and exact-match fields are not trimmed. Exact match means exact: every mobile visitor silently fell through two rules to master while every dashboard stayed green. The only witness was the diagnostics panel: attributes showed device=mobile, reasons showed Audiences for rule "mobile_delivery" collectively evaluated to FALSE, and the contradiction between those two lines is the diagnosis. Code Mode confirms it fastest. JSON quotes make whitespace visible. Cost: the better part of an evening, and it produced this list's ordering. 2. One [OutputCache] attribute defeats both engines and privacy at once. Swap the demo's no-store guard for platform output caching, and the measurement reads like an incident report: a desktop visitor received the mobile visitor's page from cache, wrong arm, wrong personalization, and the other person's visitor ID rendered in the panel, Age: 0 confirming the hit. The CMS-aware output cache has been gone since the CMS 12 rewrite, and CMS 13 still gives the platform layer nothing that knows your pages are personal (verified: no output-cache type exists anywhere in the 13.1.0 assemblies). The fix is not a smarter cache key. It is classifying pages: personalized means no-store, full stop. (The CDN analog is “ignore cookies in the cache key”, which produces the same leak at planetary scale.) 3. Type mismatch evaluates to UNKNOWN, and only the logger says so. Send device as a boolean and INCLUDE_REASONS reports a flat “collectively evaluated to FALSE”. The why lives one layer down, in the SDK log the part-2 adapter made visible: Audience condition {"match":"exact","name":"device","value":"mobile"} evaluated to UNKNOWN because a value of type "Boolean" was passed. Wire the logger on day one was part 2's advice. This is the day it pays. (Note the "match" spelling: the datafile serialization, not the dashboard's match_type.) 4. A missing attribute is quieter than a wrong one. Drop device from the dictionary and the fall-through looks identical. But this time there is no WARN anywhere, and the SDK mentions missing attributes only at debug verbosity. Absent isn't false, and absent doesn't log. The gradient of silence: wrong type warns (if you wired logs), wrong name says nothing, missing says nothing. 5. Case sensitivity, now in three places. Part 2 had the case-sensitive VariationKey. Part 3 adds attribute names (Device ≠ device), attribute values (Mobile ≠ mobile; our custom criterion deliberately Trim+lowercases editor input as a courtesy FX won't extend), and the geo header's value (pl resolves to nothing). That last one is also the closing argument for the unification: part 2's hand-rolled parser folded case and would have accepted pl. The native resolver doesn't. Two readers of one header with different tolerances is exactly the divergence class that breaks cross-engine and cross-head consistency: one resolver on the CMS, one written-down contract for the second head. 6. A personalized item doesn't leak to Graph: it ceases to exist. The coexistence section holds the measurement. The dangerous half is that nothing tells you: the sync succeeds, the schema is fine, the array is just empty. If your roadmap says “headless next year”, every CMS Audience you ship today is a block that will silently vanish in the migration. 7. One header steers two engines. AddCmsClientGeolocation is genuinely elegant. And it concentrates trust in a single header that, exposed without an edge to strip client values, both engines will believe. The part-2 caveat, squared. 8. The datafile is still the clock. Editing an audience is a datafile change like any other. This instance picked the fix from edge #1 up in about 75 seconds on the default polling. Not a repeat of part 2's lifecycle section. Just a reminder that audience edits ride the same train, and so does your kill switch. <h2>FAQ, the questions as people actually type them</h2> Can I use Visitor Groups / CMS Audiences with a headless frontend? No. Evaluation needs the CMS runtime, and the measurement here is blunter than the docs: a personalized content-area item isn't filtered for Graph consumers. It is absent from the index entirely. Personalize whole page versions with FX Audiences instead. They evaluate in any SDK. Targeted delivery or A/B test: which one do I want? Deliveries deploy, experiments measure. A delivery produces no Results page at all, so the question is really “do I need to learn anything from this traffic?” If yes, experiment; if you already know and just want control and ramp, delivery. Why does my FX audience never match? In observed order of likelihood: a stray character in the condition value, the wrong value case, the wrong attribute-name case, the wrong value type, the attribute not sent at all. The runbook above walks the diagnostics. The short version: the panel shows what you sent, and the SDK log shows what the evaluator thought of it. Can a delivery run above an experiment? No. The ruleset evaluates experiments first, and the UI encodes that as fixed sections rather than a sortable list. Carve segments out of an experiment with audiences, not with rule order. Do I need ODP to use audiences? No. Everything in this article runs on request-derived attributes. ODP (Real-Time Segments) is the path when targeting needs customer data (past purchases, lifecycle stage) rather than facts about the current request. How fast is the kill switch? One datafile propagation. This instance picked up an audience edit in ~75 seconds on default polling. The guarantee is your polling interval (or webhook latency), not the dashboard click. Does QA and test traffic pollute my results? Dashboard allowlists do: they fire impressions like any decision. This build's ?fx_force deliberately doesn't, and the consent gate has a pleasant side effect: the entire automated suite (hundreds of requests per run) sends zero events, because test traffic never carries a consent cookie. <h2>The take</h2> The model that survives all of the above is short enough to memorize. The CMS owns what: versioned, publishable content variations, plus fragment-level personalization wherever the CMS itself renders. FX rules own who and whether: deterministic assignment, deliveries for rollout, experiments for measurement. Audiences, both kinds, own for whom, and the kind you pick decides where the personalization can exist at all. CMS Audiences see everything and travel nowhere. FX Audiences see only what you send and run everywhere you do. For the business reader who skipped to the end: the mobile personalization in this demo shipped without a deploy, measured itself before an audience of three hundred synthetic visitors, survived a re-platform to a second rendering stack with zero integration code, and can be killed from a dashboard in about the time it takes to refresh a datafile. The block-level personalization shipped too. And it stopped at the CMS's edge, invisible to the headless head, unmeasured by anything but page-view counters. Both behaviors are by design. The architecture decision is choosing which design your roadmap can live with. The fragile parts haven't changed character since part 2: every failure in this article degraded to “someone quietly sees master” or “someone quietly sees too much”, and not one of them threw. The integration is still strings and dictionaries. The engineering is still making the silence loud: a diagnostics panel, an SDK logger, a startup self-check, and tests that assert the rule, not just the arm. Quiet hero, part 3: now it knows who you are. Still quiet, that's still the problem to engineer around. <h2>Glossary</h2> <table style="border-collapse: collapse; width: 100%; margin: 20px 0; font-size: 14px;"> <thead> <tr> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">Term</th> <th style="border: 1px solid #e0e0e0; padding: 8px 12px; text-align: left; background: #f5f5f4;">In one sentence</th> </tr> </thead> <tbody> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;"><a href="https://en.wikipedia.org/wiki/Goodness_of_fit">Chi-square goodness-of-fit test</a></td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Tests whether observed arm counts are consistent with the configured split; χ² = Σ (observed − expected)² / expected.</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;"><a href="https://en.wikipedia.org/wiki/Degrees_of_freedom_(statistics)">Degrees of freedom</a></td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Category counts free to vary; k arms give df = k − 1, so our three arms test at df = 2.</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;"><a href="https://en.wikipedia.org/wiki/Statistical_significance">Significance level α</a></td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">The false-alarm rate the test tolerates; this series uses α = 0.001 so a healthy split almost never red-flags live.</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;"><a href="https://en.wikipedia.org/wiki/Critical_value_(statistics)">Critical value</a></td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">The rejection threshold for the statistic, 13.816 for df = 2 at α = 0.001.</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;"><a href="https://en.wikipedia.org/wiki/Standard_error">Sampling error</a></td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Per-arm share fluctuates by ≈ √(p(1−p)/n), about 2.7 percentage points at n = 300, p = ⅓.</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;"><a href="https://en.wikipedia.org/wiki/MurmurHash">MurmurHash</a></td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">The deterministic hash every FX SDK applies to visitor ID + experiment; the reason parity needs no coordination.</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;"><a href="https://en.wikipedia.org/wiki/Pure_function">Pure function</a></td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Same input, same output, no side effects, FX audience evaluation in one phrase.</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;"><a href="https://en.wikipedia.org/wiki/Predicate_(mathematical_logic)">Predicate</a></td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">A boolean-valued function; both audience kinds are predicates over different inputs.</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;"><a href="https://en.wikipedia.org/wiki/Eventual_consistency">Eventual consistency</a></td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Distributed state converges after a delay, the datafile (~75 s observed) and the Graph index both live here.</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;"><a href="https://docs.developers.optimizely.com/feature-experimentation/docs/run-flag-deliveries">Targeted delivery</a></td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">A rule serving one variation to an audience; deployment, not measurement, no Results page.</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;"><a href="https://docs.developers.optimizely.com/feature-experimentation/docs/manage-config-datafile">Datafile</a></td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Configuration-as-data: the JSON snapshot of flags, rules and audiences every SDK evaluates locally.</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;"><a href="https://samnewman.io/patterns/architectural/bff/">Backend for Frontend</a></td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">The server-side layer that keeps SDK and Graph keys out of the browser on the headless head.</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;"><a href="https://en.wikipedia.org/wiki/Defense_in_depth_(computing)">Defense in depth</a></td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">Layered safeguards: consent gate, no-store, antiforgery, origin checks, none trusted alone.</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;"><a href="https://docs.developers.optimizely.com/feature-experimentation/docs/run-a-b-tests">Allowlist</a></td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">A per-rule list (up to fifty user IDs) pinning specific visitors to specific arms; fires impressions like normal decisions.</td> </tr> <tr> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;"><a href="https://docs.developers.optimizely.com/feature-experimentation/docs/forced-decision-methods-csharp">Forced decision</a></td> <td style="border: 1px solid #e0e0e0; padding: 8px 12px;">An SDK-level override bypassing audiences and allocation; not persistent, it lives and dies with the user context.</td> </tr> </tbody> </table> <h2>Further reading</h2> <ul> <li><a href="https://docs.developers.optimizely.com/content-management-system/v13.0.0-CMS/docs/audiences">Create audiences (CMS 13)</a> · <a href="https://docs.developers.optimizely.com/content-management-system/v13.0.0-CMS/docs/personalize-a-digital-experience-with-audiences">Personalize content with audiences</a></li> <li><a href="https://docs.developers.optimizely.com/content-management-system/v13.0.0-CMS/docs/breaking-changes-in-cms-13">CMS 13 breaking changes</a>, the AddVisitorGroupsMvc().AddVisitorGroupsUI() registration · <a href="https://docs.developers.optimizely.com/content-management-system/v13.0.0-CMS/docs/install-cms13">Install CMS 13</a></li> <li><a href="https://docs.developers.optimizely.com/feature-experimentation/docs/interactions-between-flag-rules">Interactions between flag rules</a>, experiments before deliveries; roll-down vs jump</li> <li><a href="https://docs.developers.optimizely.com/feature-experimentation/docs/run-flag-deliveries">Run flag deliveries</a> · <a href="https://support.optimizely.com/hc/en-us/articles/38816521665933">Define attributes</a></li> <li><a href="https://docs.developers.optimizely.com/feature-experimentation/docs/forced-decision-methods-csharp">Forced decision methods (C#)</a></li> <li><a href="https://docs.developers.optimizely.com/feature-experimentation/docs/upgrade-the-javascript-sdk-from-v5-to-v6">Upgrade the JavaScript SDK from v5 to v6</a>, the explicit eventProcessor</li> <li><a href="https://docs.developers.optimizely.com/feature-experimentation/docs/real-time-audiences-for-feature-experimentation">Real-Time Segments for Feature Experimentation</a>, the ODP path</li> <li>Part 1: <a href="https://pino-labs.com/blog/content-variations-cms-13-quiet-hero/">Content Variations in CMS 13, the quiet hero</a> · Part 2: <a href="/link/06d8f538fc754cb9b4362f2b31071f31.aspx">Unlock Experimentation with Content Variations in CMS 13</a></li> </ul>2026-06-14T17:46:48.0000000Z

Blog post

Hiding Pages in the Optimizely CMS 13 Page TreeWhen working with large Optimizely CMS solutions, the page tree can quickly become one of the biggest sources of editor frustration. This is especially true in multisite installations where many editors share the same platform, but only work with a limited part of the content structure. The access rights may be configured correctly, but the […]2026-06-13T20:54:18.0000000Z

Blog post

Four database surprises when upgrading from CMS 11 to CMS 13<div> <div>We're in the middle of migrating a fairly large site from CMS 11 / .NET Framework to CMS 13 / .NET 10. The code migration is one thing, but the database is where the real surprises live. Everything worked fine against our dev and stage databases — and then we pointed the upgrade at a copy of the production database.</div> <div>Here are four things that bit us. Two of them are reported to Optimizely (one verified as a bug and fixed in the latest release, one in triage), so depending on when you read this you might be spared. The other two are by design in CMS 13 and you could hit them if your solution is old enough.</div> <div> </div> <div> <div> <div>1. NULL values in tblSiteDefinition stop the site from booting</div> <div> </div> <div> <div> <div>CMS 13 replaces `SiteDefinition` with the new `Application` model, and on first boot a schema migration moves your rows from `tblSiteDefinition` to `tblApplication` with a plain `INSERT ... SELECT`. The catch: `Saved` and `SavedBy` are `NOT NULL` in the new table, and in our production database some of the old rows had NULL in those columns. The migration rolls back with an INSERT NULL violation and the site doesn't start at all.</div> <div>The kicker is that our stage databases didn't have this problem — only production did. So if your upgrade rehearsals all run against stage copies, you can sail through every test and still faceplant on go-live night.</div> <div>The fix is a one-off backfill before the first CMS 13 boot:</div> <div> </div> <div> <pre class="language-csharp"><code>UPDATE tblSiteDefinition SET Saved = ISNULL(Saved, GETUTCDATE()), SavedBy = ISNULL(SavedBy, 'system') WHERE Saved IS NULL OR SavedBy IS NULL;</code></pre> <div> <div>2. Tab names must be plain ASCII</div> <div> </div> <div> <div> <div>CMS 13 validates tab definition names at model sync, and it's strict: no non-ASCII characters, no spaces, no hyphens. Being a Swedish project we had tab names like "Sökinställningar", "SEO-Settings" and "Externa länkar" — and the app refused to boot with:</div> <div>```</div> <div>ValidationException: The Name 'X' is not a valid format.</div> <div>```</div> <div>So all tab names need to be plain ASCII identifiers. They're internal keys though — if you want nicer editor-facing labels (or anything with åäö), that's handled with tab translations in your localization files.</div> <div> </div> <div> <div> <div>3. "Content" and "Settings" are reserved tab names</div> <div> </div> <div> <div> <div>This one is sneaky. CMS 13 reserves the tab names `Content` and `Settings` for its built-in tabs, and if you have those exact strings as your own tab names — which we did, in a perfectly innocent-looking GroupNames class — model sync throws a `ConflictingResourceException` against a freshly upgraded database.</div> <div>The confusing part is that `SystemTabNames.Content` isn't the string "Content" at all — it's "Information". And `SystemTabNames.Settings` is "Advanced". So the constants never collide, only the literals do. The fix is simply to point your own constants at `SystemTabNames`:</div> <div> </div> <div> <pre class="language-csharp"><code>public const string Content = SystemTabNames.Content; // "Information" public const string Settings = SystemTabNames.Settings; // "Advanced"</code></pre> </div> </div> </div> </div> </div> <div> </div> </div> </div> </div> </div> </div> </div> <div>  <div> <div>4. NULLs in tblSynchedUser break edit mode for everyone</div> <div> </div> <div> <div> <div>The site authenticates with WS-Federation against an external ADFS, and not every identity comes with `email`, `givenname` or `surname` claims. After user sync those rows end up with NULL in the corresponding columns in `tblSynchedUser` — including one literally named `Metadata`. The columns are nullable, so we assumed that was fine.</div> <div>It isn't. As soon as anyone opens edit mode, the CMS shell tries to subscribe the current user to feature notifications, reads through the user table, and dies:</div> <div> </div> <div> <pre class="language-csharp"><code>System.Data.SqlTypes.SqlNullValueException: Data is Null. at EPiServer.DataAccess.Internal.SynchronizeUsersDB.<FindUsersAsync>g__CreateUser|18_0 ... at FeatureNotificationService.SubscribeAsync</code></pre> </div> </div> </div> <div> </div> <div> <div> <div>A single NULL row anywhere in the table is enough, and it doesn't have to belong to the user logging in. The public site keeps working — only edit mode breaks — which makes it genuinely confusing to troubleshoot.</div> <div>The workaround is backfilling the nullable string columns with empty strings. The good news: we reported this one, Optimizely verified it as a bug, and a fix ships in the latest release. If you're on an earlier 13.x, the backfill is:</div> <div> </div> <div> <pre class="language-csharp"><code>UPDATE tblSynchedUser SET Email = '' WHERE Email IS NULL; UPDATE tblSynchedUser SET GivenName = '' WHERE GivenName IS NULL; UPDATE tblSynchedUser SET LoweredGivenName = '' WHERE LoweredGivenName IS NULL; UPDATE tblSynchedUser SET Surname = '' WHERE Surname IS NULL; UPDATE tblSynchedUser SET LoweredSurname = '' WHERE LoweredSurname IS NULL; UPDATE tblSynchedUser SET Metadata = '' WHERE Metadata IS NULL;</code></pre>   <div> <div>Wrapping up</div> <div> </div> <div> <div> <div>The common thread: none of this shows up on a clean database. It's the years of accumulated production data — old site definitions, legacy users synced before claims were complete, tab names from a more liberal era — that trip the upgrade. So rehearse against a fresh copy of *production*, not stage, before the real cutover.</div> </div> </div> <div> </div> </div> </div> </div> </div> </div> </div> </div> </div> </div>2026-06-12T10:02:44.0000000Z

Blog post

Designing ODP Real-Time Audiences for CMS Personalization and ExperimentationA practical look at when to use ODP Real-Time Audiences, how to build them, and how they fit into CMS personalization and Feature Experimentation.2026-06-11T20:58:07.0000000Z

Blog post