Blogs2026-08-07T02:53:49.0000000Zhttps://world.optimizely.com/blogs/Optimizely WorldOptimizely Commerce 14 Now Supports .NET 10<div>
<p>In my previous post, <a href="/link/d15848f947264cc59c3d86b9c7d55c95.aspx"><em>Optimizely CMS 12 Now Fully Supports .NET 10</em></a>, I noted one remaining limitation: <strong>Commerce 14 (Commerce Connect)</strong> did not yet support .NET 10, and Commerce customers were advised to stay on .NET 8.</p>
<p>I'm happy to report that this gap has now been closed. <strong>Commerce 14 officially supports .NET 10 starting with version 14.46.0. </strong>It's also mentioned in the <a href="https://support.optimizely.com/hc/en-us/articles/23973422587405-2026-Commerce-Connect-release-notes#h_01KECT5AZ1XKGXHK59KB1XF3WT">release notes</a>.</p>
<h2>What's New</h2>
<ul>
<li><strong>EPiServer.Commerce 14.46.0</strong> – adds official .NET 10 support.</li>
<li><strong>EPiServer.Find.Commerce 12.3.0</strong> – supports Commerce 14 running on .NET 10.</li>
</ul>
<p>If you're using <strong>Optimizely Search & Navigation (Find)</strong> with Commerce, upgrade both packages together to ensure full compatibility.</p>
<div class="___1dmoc29 f10pi13n ftgm304 f1enuhaj fdclmfp f1nbblvp fat0sn4 f1ov4xf1 fekwl8i f1lmfglv f1oz7aqm f1abmfm4 f1w619qj f16h0jq8">
<table class="___1vyiefv f1ddd56o f16vktn6 f1ahpp82 f11qra4b f1uinfot fibjyge fvueend f9yszdx f1fu4s3n f3l3pb3 f10ghnd0 f8fmt76 fjvbh62 f1qrqxae f1vw5qpk fc02sbz fxawf59 fymf513 f1aoyrul f1el8yx3 f1pymoxg f1ofu761 fe6itr f7coize f1794535 f1o0pw0q fbjjl9v fk1v6el f16pyhcb f1ixlhx9 f12zef0i flu5r5u f19haqzy f1owmcxx f1oddm8q f1004tna fcoaxci fh0ee9u f15v23i2 f1dmj53 f1r1gcv9 f14z1veh ffufd3x f1ypplot f1660cg">
<tbody>
<tr>
<th>Package</th>
<th>Minimum Version</th>
</tr>
<tr>
<td>EPiServer.Commerce</td>
<td><a href="https://nuget.optimizely.com/packages/episerver.commerce/14.46.0">14.46.0</a></td>
</tr>
<tr>
<td>EPiServer.Find.Commerce</td>
<td><a href="https://nuget.optimizely.com/packages/episerver.find.commerce/12.3.0">12.3.0</a></td>
</tr>
</tbody>
</table>
</div>
<p>This means the full Optimizely stack, including both <strong>CMS 12 and Commerce 14</strong>, can now run on <strong>.NET 10</strong>.</p>
<h2>Why Upgrade?</h2>
<p>With <strong>.NET 8 and .NET 9 reaching end of support on November 10, 2026</strong>, .NET 10 is now the recommended target. As the current LTS release, it provides support through <strong>November 2028</strong>, along with performance improvements, security updates, and a longer support horizon.</p>
<h2>Recommendations</h2>
<ul>
<li>Upgrade <strong>EPiServer.Commerce</strong> to <strong>14.46.0</strong> or later before moving to .NET 10.</li>
<li>Upgrade <strong>EPiServer.Find.Commerce</strong> to <strong>12.3.0</strong> or later if you use Find with Commerce.</li>
<li>Verify that any additional add-ons or integrations are compatible with .NET 10.</li>
</ul>
<p>For upgrade guidance and system requirements, refer to the <a href="https://docs.developers.optimizely.com/content-management-system/docs/system-requirements-for-optimizely">Optimizely Developer Documentation</a> or contact <a href="https://support.optimizely.com/hc/en-us">Optimizely Support</a> for assistance.</p>
</div>2026-08-07T02:53:49.0000000ZBlog postThe Top 10 Things I'm Actually Using AI For<div>
<p>A while back I wrote about ReviewPR, an Azure Function that uses AI to review Azure DevOps pull requests. That was one specific use case, but over the last year AI has become part of my day-to-day workflow in a lot of other ways.</p>
<p>For context, we run Optimizely CMS 12 and Commerce Connect 14 on DXP for a national homebuilder. It's a large platform with a lot of moving parts, years of history, and a relatively small team responsible for keeping everything running.</p>
<p>The biggest thing that changed for me is that I stopped thinking of AI as a coding tool. The real value has been giving it access to the systems I already use every day, then letting it help connect information across them. Logs, telemetry, deployments, databases, source code, configuration, and documentation all tell part of the story. Having something that can look across all of them at once has saved me a surprising amount of time.</p>
<p>Here are the areas where I've gotten the most value from it.</p>
<h2>1. Troubleshooting Production Issues</h2>
<p>This is the one that changed how I work.</p>
<p>Most production incidents aren't caused by a single obvious failure. They show up as symptoms scattered across several systems, and a lot of the effort goes into figuring out which signals actually matter.</p>
<p>One recurring pattern has been discovering that the original assumption was wrong. Problems that looked like database issues turned out to be networking issues. Stability problems ended up being scaling rules watching the wrong metric. Intermittent exceptions came back to application design problems that had been hiding for months. Looking at telemetry, deployments, infrastructure metrics, and source code together tends to surface connections that are easy to miss when you're investigating one system at a time.</p>
<p>Just as importantly, it's been useful for ruling things out. Finding out a theory is wrong in an hour is often more valuable than finding the right answer after three days.</p>
<h2>2. Answering the Questions Nobody Has Time For</h2>
<p>Every long-running Optimizely implementation develops a backlog of questions that never quite make it onto a sprint.</p>
<p>Which scheduled jobs are still needed? Which old integrations can be removed? Are there migrations that never completed correctly? How much data is sitting around because nobody ever cleaned it up?</p>
<p>These are all answerable questions, but they're usually more tedious than difficult. AI has been particularly useful for this kind of investigative work because it can sift through the details much faster than I can manually.</p>
<h2>3. Building Small Projects That Cross Too Many Boundaries</h2>
<p>Some of my favorite uses have been side projects that touch several different technologies at once.</p>
<p>Usually these aren't difficult projects. They just require learning a new API, figuring out an authentication model, understanding an unfamiliar library, and wiring everything together. That's often enough friction to keep a good idea from ever getting finished.</p>
<p>Having AI help bridge those gaps has made it much easier to take an idea from concept to something working without spending days context-switching between documentation sites.</p>
<h2>4. Arguing With My Own Code</h2>
<p>I've gotten into the habit of asking for a deliberately skeptical review before opening a pull request.</p>
<p>Not "does this look okay?" but "explain why this is wrong."</p>
<p>That tends to produce much better feedback. It's caught fixes that only suppressed warnings, tests that weren't actually validating behavior, and assumptions that looked safe until somebody challenged them. Even when I disagree with the feedback, forcing myself to defend the implementation usually improves the final result.</p>
<h2>5. Writing Better Tests</h2>
<p>This is one area where I've learned to be careful.</p>
<p>Left alone, AI tends to write tests around implementation details rather than behavior. Those tests often pass, but they don't necessarily prove anything valuable.</p>
<p>The best results have come from treating it like a partner in test design rather than a test generator. I want help identifying scenarios, edge cases, and requirements. The actual test is much less important than proving the behavior we're trying to protect.</p>
<h2>6. Making Sense of Telemetry</h2>
<p>Modern systems generate more telemetry than most developers can realistically consume.</p>
<p>One thing AI does well is help summarize what changed between two periods of time and identify where an investigation should start. Sometimes the answer is obvious after the fact, but getting to that point can require digging through thousands of events, metrics, and traces.</p>
<p>The biggest value isn't necessarily the answer itself. It's reducing the amount of time spent looking in the wrong place.</p>
<h2>7. Finding the Bugs Nobody Sees</h2>
<p>Some problems are obvious once they're found and almost invisible before that.</p>
<p>I've seen issues caused by a single unexpected character, subtle data inconsistencies, and small assumptions that quietly affected behavior without ever generating an obvious failure.</p>
<p>These are the kinds of things humans can find, but they're also the kinds of things we tend to overlook because we're focused on larger problems. AI is surprisingly good at noticing details that don't stand out during normal troubleshooting.</p>
<h2>8. Capturing Institutional Knowledge</h2>
<p>Every team has information that exists mostly in people's heads.</p>
<p>Environment-specific quirks, deployment lessons, platform limitations, and the odd exceptions that nobody remembers until something breaks.</p>
<p>I've started being much more intentional about documenting those lessons. AI has been useful for organizing and retrieving that information, especially when it spans years of projects and multiple systems.</p>
<h2>9. Hardware Troubleshooting</h2>
<p>The same approach works surprisingly well outside software development.</p>
<p>Most hardware troubleshooting comes down to collecting evidence. Event logs, diagnostics, performance data, firmware versions, and error messages all provide clues, but pulling them together takes time.</p>
<p>Being able to feed in the evidence and get a structured analysis has made the process significantly faster.</p>
<h2>10. Home Networking and Security</h2>
<p>I've also used AI extensively for home networking and security projects.</p>
<p>The biggest value hasn't been creating configurations. It's been reviewing them. Understanding what a rule actually allows, identifying unnecessary exposure, and validating assumptions turns out to be just as useful at home as it is in production systems.</p>
<p>One lesson that carries across both worlds is that asking "what could this reach?" is often more useful than asking "is this secure?"</p>
<h2>A Few Things to Watch</h2>
<p>AI gets things wrong. Regularly.</p>
<p>The failure mode isn't that it doesn't know the answer. The failure mode is that it gives a clean, confident explanation that sounds reasonable and happens to be completely wrong.</p>
<p>That's why I always want to see the underlying evidence. The logs, the query, the deployment, the code, or whatever data led to the conclusion.</p>
<p>I've also found that context matters far more than prompts. The more access it has to the relevant information, the more useful it becomes. A model that can read logs, telemetry, source code, and configuration is a very different tool from one that can only answer questions in a chat window.</p>
<h2>Conclusion</h2>
<p>If I had to summarize where AI has helped me most, it comes down to three things:</p>
<ul>
<li>Investigating problems faster.</li>
<li>Connecting information across systems.</li>
<li>Challenging assumptions before I spend time acting on them.</li>
</ul>
<p>It hasn't replaced experience, judgment, or critical thinking.</p>
<p>Mostly, it's removed a lot of the manual digging that used to sit between noticing a problem and understanding it.</p>
</div>2026-08-05T19:24:01.0000000ZBlog postDrag-and-Drop Reordering for Commerce Media Collection in Optimizely Commerce Connect<p>Optimizely Commerce Connect ships a polished asset editor for the <span style="font-family: 'courier new', courier, monospace;">CommerceMediaCollection </span>property on catalog entries. It lets editors add, remove, and reorder media assets directly in the edit view — a solid baseline for most projects. Reordering is done via "Move Up" and "Move Down" buttons in the grid, which is perfectly fine when you have a handful of assets.</p>
<p>For some projects, though, editors need to manage dozens of images per product — product shots, lifestyle images, detail crops, downloads — and clicking a button 30 times to move an asset to the top becomes a real workflow problem. Drag-and-drop row reordering is the natural solution. This post walks through how to add it by extending the built-in Commerce editor rather than replacing it.</p>
<hr />
<h2>The Property</h2>
<p>The <span style="font-family: 'courier new', courier, monospace;">CommerceMediaCollection </span>property is declared on <span style="font-family: 'courier new', courier, monospace;">EntryContentBase </span>and typed as <span style="font-family: 'courier new', courier, monospace;">ItemCollection<CommerceMedia></span>. Each <span style="font-family: 'courier new', courier, monospace;">CommerceMedia </span>item carries a <span style="font-family: 'courier new', courier, monospace;">SortOrder </span>integer that controls display priority on the front end — carousels, image galleries, download lists. Whatever order the editor sees in the CMS is what the front end is supposed to render.</p>
<pre><code class="language-csharp">[UIHint("commercemediacollection")]
public virtual ItemCollection<CommerceMedia> CommerceMediaCollection { get; set; }
</code></pre>
<p>The built-in editor already renders this as a dgrid with drag-handle affordances — the visual infrastructure for drag-and-drop is present. Wiring it up for internal row reordering and making sure <span style="font-family: 'courier new', courier, monospace;">SortOrder </span>is written correctly afterward is the implementation work.</p>
<hr />
<h2>Approach: Extend, Don't Replace</h2>
<p>Optimizely Commerce Connect Asset Collection's editor descriptor sets up column definitions, thumbnail formatters, item converters, and the dialog flow for adding assets. Rather than reimplementing all of that, the approach is to register a custom descriptor that runs last, inherits everything the Commerce descriptor configured, and only swaps out the client-side widget class.</p>
<p>The widget itself extends <span style="font-family: 'courier new', courier, monospace;">CommerceMediaCollectionEditor </span>and overrides the minimum needed: how the grid's DnD layer is wired, how sort order is written after a drag, and whether columns are user-sortable.</p>
<hr />
<h2>Step 1 — Register a Custom Editor Descriptor</h2>
<p>Optimizely CMS resolves editor descriptors by <span style="font-family: 'courier new', courier, monospace;">(TargetType, UIHint)</span> pair. The <span style="font-family: 'courier new', courier, monospace;">CommerceMediaCollection</span> property carries <span style="font-family: 'courier new', courier, monospace;">[UIHint("commercemediacollection")]</span>, so the custom descriptor must declare the same UIHint. <span style="font-family: 'courier new', courier, monospace;">EditorDescriptorBehavior.PlaceLast</span> ensures it runs after Commerce's built-in descriptor, so all Commerce-specific metadata is already applied before we override just the widget class name.</p>
<pre><code class="language-csharp">using EPiServer.Commerce.SpecializedProperties;
using EPiServer.Shell.ObjectEditing;
using EPiServer.Shell.ObjectEditing.EditorDescriptors;
[EditorDescriptorRegistration(
TargetType = typeof(ItemCollection<CommerceMedia>),
UIHint = "commercemediacollection",
EditorDescriptorBehavior = EditorDescriptorBehavior.PlaceLast)]
public class CommerceMediaDndEditorDescriptor : EditorDescriptor
{
public override void ModifyMetadata(
ExtendedMetadata metadata,
IEnumerable<Attribute> attributes)
{
base.ModifyMetadata(metadata, attributes);
metadata.ClientEditingClass = "myproject/editors/CommerceMediaDndEditor";
}
}
</code></pre>
<hr />
<h2>Step 2 — Create a Protected Shell Module</h2>
<p>The Dojo AMD path <span style="font-family: 'courier new', courier, monospace;">myproject/editors/CommerceMediaDndEditor</span> must resolve to a real file. That means registering a Dojo package called <span style="font-family: 'courier new', courier, monospace;">myproject </span>via a protected shell module.</p>
<p><strong><span style="font-family: 'courier new', courier, monospace;">modules/_protected/MyProject.Commerce.UI/module.config:</span></strong></p>
<pre><code class="language-xml"><?xml version="1.0" encoding="utf-8"?>
<module name="MyProject.Commerce.UI" clientResourceRelativePath="">
<dojo>
<packages>
<add name="myproject" location="ClientResources" />
</packages>
</dojo>
<clientModule>
<moduleDependencies>
<add dependency="CMS" />
<add dependency="Commerce" />
</moduleDependencies>
</clientModule>
</module>
</code></pre>
<p><strong>Source file tracking:</strong> <span style="font-family: 'courier new', courier, monospace;">modules/_protected/ </span>is typically gitignored because NuGet restores add-on packages there. Keep your source in a separate tracked directory (e.g. <span style="font-family: 'courier new', courier, monospace;">ShellModules/_protected/</span>) and copy it at build time:</p>
<pre><code class="language-xml"><ItemGroup>
<ShellModuleSource Include="ShellModules\_protected\**\*" />
<Content Remove="ShellModules\_protected\**\*" />
<Content Include="@(ShellModuleSource)">
<Link>modules\_protected\%(RecursiveDir)%(FileName)%(Extension)</Link>
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
<CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
</Content>
</ItemGroup>
<Target Name="CopyCustomShellModules" BeforeTargets="Build">
<Copy
SourceFiles="@(ShellModuleSource)"
DestinationFolder="$(MSBuildProjectDirectory)\modules\_protected\%(RecursiveDir)"
SkipUnchangedFiles="true" />
</Target>
</code></pre>
<p><strong>Explicit module registration:</strong> EPiServer Shell 12.x auto-discovery matches module directories to assemblies by name. A module named <span style="font-family: 'courier new', courier, monospace;">MyProject.Commerce.UI</span> with no correspondingly-named assembly is skipped. Register it explicitly via <span style="font-family: 'courier new', courier, monospace;">IConfigurableModule</span>:</p>
<pre><code class="language-csharp">using EPiServer.Framework;
using EPiServer.Framework.Initialization;
using EPiServer.ServiceLocation;
using EPiServer.Shell.Modules;
using Microsoft.Extensions.DependencyInjection;
[InitializableModule]
[ModuleDependency(typeof(EPiServer.Shell.UI.InitializationModule))]
public class CommerceUiModuleRegistration : IConfigurableModule
{
public void ConfigureContainer(ServiceConfigurationContext context)
{
context.Services.Configure<ProtectedModuleOptions>(options =>
{
if (options.Items.Any(x => x.Name == "MyProject.Commerce.UI"))
return;
options.Items.Add(new ModuleDetails
{
Name = "MyProject.Commerce.UI"
});
});
}
public void Initialize(InitializationEngine context) { }
public void Uninitialize(InitializationEngine context) { }
}
</code></pre>
<blockquote>
<p><strong>Note:</strong> Do not set <span style="font-family: 'courier new', courier, monospace;">Assemblies </span>in <span style="font-family: 'courier new', courier, monospace;">ModuleDetails </span>to your main web assembly. This module is purely client-side (JavaScript + <span style="font-family: 'courier new', courier, monospace;">module.config</span>) — no C# shell controllers. Pointing <span style="font-family: 'courier new', courier, monospace;">Assemblies</span> at the main project assembly causes EPiServer Shell to re-process it under its own application-part rules, which conflicts with ASP.NET Core's existing registration of that assembly and breaks ViewComponent discovery. Omit <span style="font-family: 'courier new', courier, monospace;">Assemblies </span>for client-only modules.</p>
</blockquote>
<hr />
<h2>Step 3 — The Custom Dojo Widget</h2>
<p>The widget has three jobs:</p>
<ol>
<li>
<p><strong>Enable internal row DnD</strong> — <span style="font-family: 'courier new', courier, monospace;">epi/shell/dnd/Source</span> (the DnD source class used by the grid) does not self-accept by default when <span style="font-family: 'courier new', courier, monospace;">accept</span> type strings are configured. Commerce media items don't carry a recognized <span style="font-family: 'courier new', courier, monospace;">typeIdentifier</span>, so the type-matching check fails for same-source drops. Wrapping <span style="font-family: 'courier new', courier, monospace;">checkAcceptance </span>with <span style="font-family: 'courier new', courier, monospace;">dojo/aspect</span>'s <span style="font-family: 'courier new', courier, monospace;">around </span>restores the standard behaviour for internal drags while leaving external drop handling (adding assets from the DAM) completely unchanged.</p>
</li>
<li>
<p><strong>Write sequential <span style="font-family: 'courier new', courier, monospace;">SortOrder</span> values</strong> — After a drag, every item needs a <span style="font-family: 'courier new', courier, monospace;">SortOrder </span>that matches its new visual position. The custom model override handles the move and renumbers all items 1, 2, 3, … in one atomic update, firing <span style="font-family: 'courier new', courier, monospace;">itemsChanged </span>exactly once with the final correct state.</p>
</li>
<li>
<p><strong>Disable column header sorting</strong> — Clicking a column header in the grid would re-sort rows by that column's data without saving, creating a mismatch between what the editor sees and what is stored. Marking all columns <span style="font-family: 'courier new', courier, monospace;">sortable: false</span> prevents this.</p>
</li>
</ol>
<pre><code class="language-javascript">define([
"dojo/_base/declare",
"dojo/aspect",
"epi-ecf-ui/contentediting/editors/CommerceMediaCollectionEditor",
"epi-ecf-ui/contentediting/editors/model/CommerceMediaCollectionEditorModel",
], function (
declare,
aspect,
CommerceMediaCollectionEditor,
CommerceMediaCollectionEditorModel,
) {
// Extended model: moves the item in the array and assigns sequential
// SortOrder values across all items in a single atomic update.
var ShiftReorderModel = declare([CommerceMediaCollectionEditorModel], {
moveItem: function (item, target, before) {
// Suppress itemsChanged from the first splice (remove)
this._itemsUnchanged = true;
var fromIdx = this._itemModels.indexOf(item);
this._itemModels.splice(fromIdx, 1);
// Suppress itemsChanged from the second splice (insert)
this._itemsUnchanged = true;
var toIdx = this._itemModels.indexOf(target);
toIdx =
toIdx === -1
? this._itemModels.length // dropped past last row → append
: before
? toIdx
: toIdx + 1;
this._itemModels.splice(toIdx, 0, item);
// Renumber: SortOrder 1, 2, 3, … in array order
this._itemModels.forEach(function (m, i) {
m.sortOrder = i + 1;
});
// Fire once with the final correct state
this.emit("itemsChanged", this.get("items"));
},
});
return declare([CommerceMediaCollectionEditor], {
modelType: ShiftReorderModel,
// Disable column header sorting so grid order always reflects stored order
_getGridDefinition: function () {
var columns = this.inherited(arguments);
for (var col in columns) {
if (columns[col]) {
columns[col].sortable = false;
}
}
return columns;
},
// Wire internal DnD and restore self-acceptance for same-source drops
_setupDnD: function () {
this.inherited(arguments);
var dndSrc = this.grid.dndSource;
this.own(
aspect.around(dndSrc, "checkAcceptance", function (original) {
return function (source, nodes) {
// Allow reordering within the same grid
if (source === this) {
return true;
}
return original.apply(this, arguments);
};
}),
);
},
});
});
</code></pre>
<p>Place this at <span style="font-family: 'courier new', courier, monospace;">ShellModules/_protected/MyProject.Commerce.UI/ClientResources/editors/CommerceMediaDndEditor.js</span> (the MSBuild target copies it to <span style="font-family: 'courier new', courier, monospace;">modules/_protected/</span> at build time).</p>
<hr />
<h2>End Result</h2>
<p>Editors open a catalog entry, switch to the Assets tab, and drag rows to reorder media. The grid updates immediately. On save, each asset's <span style="font-family: 'courier new', courier, monospace;">SortOrder </span>reflects its position in the grid — 1 for the first row, 2 for the second, and so on. No separate admin page, no property changes, no base class modifications.</p>
<p>The solution can be applied to any <span style="font-family: 'courier new', courier, monospace;">ItemCollection<CommerceMedia></span> property in the codebase with the correct UIHint.</p>
<hr />
<h2>File Checklist</h2>
<table>
<thead>
<tr>
<th>File</th>
<th>What it does</th>
</tr>
</thead>
<tbody>
<tr>
<td><span style="font-family: 'courier new', courier, monospace;">CommerceMediaDndEditorDescriptor.cs</span></td>
<td>Registers the custom widget for <span style="font-family: 'courier new', courier, monospace;">ItemCollection<CommerceMedia></span></td>
</tr>
<tr>
<td><span style="font-family: 'courier new', courier, monospace;">CommerceUiModuleRegistration.cs</span></td>
<td>Registers the shell module explicitly so auto-discovery doesn't skip it</td>
</tr>
<tr>
<td><span style="font-family: 'courier new', courier, monospace;">ShellModules/_protected/MyProject.Commerce.UI/module.config</span></td>
<td>Declares the <span style="font-family: 'courier new', courier, monospace;">myproject </span>Dojo package</td>
</tr>
<tr>
<td><span style="font-family: 'courier new', courier, monospace;">ShellModules/_protected/MyProject.Commerce.UI/ClientResources/editors/CommerceMediaDndEditor.js</span></td>
<td>The custom editor widget</td>
</tr>
<tr>
<td><span style="font-family: 'courier new', courier, monospace;">MyProject.csproj</span> (MSBuild target)</td>
<td>Copies shell module source to <span style="font-family: 'courier new', courier, monospace;">modules/_protected/ </span>at build time</td>
</tr>
</tbody>
</table>2026-08-05T09:48:55.0000000ZBlog postOrder tabs with drag and drop V2<p>I earlier did a very simple Blazor version to be able to sort tabs with drag and drop.</p>
<p>I wanted to update it a bit and also display how the tabs are actually ordered on the content types to spot inconsistencys or make it easier to fine tune placement by being able to drag and drop in the tab layout directly instead of adjusting in a potential long vertical list.<br /><br />Nothing changes until you hit save. Have som export / import buttons but I havent tested that yet. </p>
<p>You can find the code over at my <a href="https://github.com/PNergard/Nergard.Opti.TabSorter">GitHub</a>.</p>
<p><img src="/link/476714de6566474da9deacd2b66a120d.aspx" alt="" width="759" height="627" /></p>
<p> </p>2026-08-04T09:56:57.0000000ZBlog postOptimizely : Missing Language Manager Gadget Fix in CMS 12 After Upgrading to .NET 10<p>Recently, while upgrading an Optimizely CMS solution to .NET 10, we came across an issue where the Language Manager gadget completely disappeared from CMS Edit...</p>
<p>The post <a href="https://madhuanbalagan.com/optimizely-missing-language-manager-gadget-fix-in-cms-12-after-upgrading-to-net-10">Optimizely : Missing Language Manager Gadget Fix in CMS 12 After Upgrading to .NET 10</a> appeared first on <a href="https://madhuanbalagan.com">Madhu Anbalagan's Blog</a>.</p>
2026-08-02T16:15:41.0000000ZBlog postFlat or Nested? Weighing Your Content Modeling Options in Optimizely SaaS CMS<p>When building a headless site on Optimizely SaaS CMS, one of the earliest and most critical design milestones your team will face is defining your <strong>content model</strong>.</p>
<p>Unlike traditional monolithic setups where visual layout often dictates data structure, headless modeling requires you to design a clear, reusable contract between two very different groups of people: your <strong>content authors</strong> (working in the CMS UI) and your <strong>developers</strong> (writing front-end components).</p>
<p>Because developers are trained to eliminate duplicate code (the "DRY" principle), they often instinctively design highly complex, nested, or consolidated data structures. Authors, on the other hand, require flat, intuitive, and self-explanatory editing interfaces.</p>
<p>When these two instincts collide, tension arises.</p>
<p>Below, we’ll walk through a common, real-world scenario—modeling standard videos versus gated lead-generation videos—and lay out three valid modeling options, complete with their architectural trade-offs, so your team can make a well-informed choice.</p>
<hr />
<h2>The Scenario: One Concept, Two Realities</h2>
<p>Let's say your site needs to support videos in two very different business contexts:</p>
<ol class="tight">
<li>
<p><strong>Standard Video:</strong> An editorial or informational video with autoplay, looping, and visual player controls.</p>
</li>
<li>
<p><strong>Gated Video:</strong> A lead-generation asset that plays a brief preview, pauses at a specific timestamp, and displays an email capture form synced automatically with an external Marketing Automation Platform (MAP).</p>
</li>
</ol>
<table style="border-collapse: collapse; width: 100%; border-width: 1px; border-style: solid;">
<tbody>
<tr>
<td style="padding: 10px; text-align: left; vertical-align: top; border-width: 1px; border-style: solid;">
<p><strong>Feature</strong></p>
</td>
<td style="padding: 10px; text-align: left; vertical-align: top; border-width: 1px; border-style: solid;">
<p><strong>Standard Video</strong></p>
</td>
<td style="padding: 10px; text-align: left; vertical-align: top; border-width: 1px; border-style: solid;">
<p><strong>Gated Video</strong></p>
</td>
</tr>
<tr>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p><strong>Author sets</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Video file, Poster image, Title, Autoplay toggle, Loop toggle, Show controls</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Video file, Poster image, Title</p>
</td>
</tr>
<tr>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p><strong>Sourced from MAP</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Not applicable</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Form ID, Gate Timestamp (seconds to trigger form)</p>
</td>
</tr>
<tr>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p><strong>Front-end behavior</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Continuous playback, native player controls</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Pauses playback at Gate time and overlays lead capture form</p>
</td>
</tr>
</tbody>
</table>
<p>To model this, your team has three distinct structural approaches to consider. Let's look at the trade-offs of each.</p>
<hr />
<h2>Option 1: The Consolidated "Mega-Block" (All Fields in One Type)</h2>
<p>This approach creates a single, highly flexible content type—such as VideoComponent—containing every possible property. You then rely on the author's training (or inline help text) to know which fields to fill.</p>
<pre class="code-block"><code>Consolidated Block: VideoComponent
├── VideoFile
├── PosterImage
├── Title
├── Autoplay (Fill only for Standard)
├── Loop (Fill only for Standard)
├── ShowControls (Fill only for Standard)
├── FormId (Fill only for Gated)
└── GateTimestamp (Fill only for Gated)</code></pre>
<h3>The Trade-Offs</h3>
<ul class="tight">
<li>
<p><strong>Pros:</strong></p>
<ul class="tight">
<li>
<p><strong>Simple Setup:</strong> Only one content type to define, register, and sync to the CMS.</p>
</li>
<li>
<p><strong>Single Component:</strong> Developers maintain just one straightforward React component with simple conditional rendering.</p>
</li>
</ul>
</li>
<li>
<p><strong>Cons:</strong></p>
<ul class="tight">
<li>
<p><strong>Author Cognitive Load:</strong> Authors are forced to look at "dead fields." An editor adding a gated marketing video must mentally ignore Autoplay, Loop, and Controls.</p>
</li>
<li>
<p><strong>Validation Gaps:</strong> You cannot easily make fields like FormId required for gated videos without making them required for standard videos too, risking incomplete data.</p>
</li>
</ul>
</li>
</ul>
<hr />
<h2>Option 2: The Nested "Wrapper Block" (Composition via Content Area)</h2>
<p>This approach seeks to avoid database field duplication by pulling the shared properties (<strong>VideoFile</strong>, <strong>PosterImage</strong>, and <strong>Title</strong>) into a parent <strong>VideoItem </strong>block. This block then contains a nested Content Area where the author inserts a secondary "extension block" containing the specific properties.</p>
<pre class="code-block"><code>Parent Block: VideoItem
├── VideoFile
├── PosterImage
├── Title
└── Content Area (Allows only StandardProperties OR GatedProperties)</code></pre>
<h3>The Trade-Offs</h3>
<ul class="tight">
<li>
<p><strong>Pros:</strong></p>
<ul class="tight">
<li>
<p><strong>Strictly "DRY" Database Schema:</strong> The base fields are declared exactly once, preventing schema duplication.</p>
</li>
<li>
<p><strong>Modularity:</strong> You can reuse the "Standard" or "Gated" property blocks in other components across the system.</p>
</li>
<li>
<p><strong>Configurable guardrails:</strong> Content Areas are not a free-for-all. Built-in validation fields let you constrain them declaratively—<strong>allowedTypes </strong>/ <strong>restrictedTypes </strong>restrict exactly which extension types can be dropped in, and <strong>maxLength: 1</strong> caps the area to a single item—so wrong-type and duplicate insertions are preventable without any custom code.</p>
</li>
</ul>
</li>
<li>
<p><strong>Cons:</strong></p>
<ul class="tight">
<li>
<p><strong>Editing Friction:</strong> Authors must execute a two-step process to build a single video. They fill out the parent, click "Create New Block" inside the Content Area, and then fill out the child block—slower than picking one flat type up front.</p>
</li>
<li>
<p><strong>The "empty wrapper" gap:</strong> While <strong>allowedTypes </strong>and <strong>maxLength </strong>handle type and cardinality, enforcing a strict <em>minimum</em> of one item is not cleanly supported for content areas—so an author can still save an empty wrapper with no extension inside.</p>
</li>
<li>
<p><strong>GraphQL Query Noise:</strong> Even when correctly constrained, every query to fetch a video must navigate a nested fragment structure, increasing the payload and query complexity compared to a flat type.</p>
</li>
</ul>
</li>
</ul>
<hr />
<h2>Option 3: The Split-Type "Symmetrical" Pattern (Recommended)</h2>
<p>This approach splits the concept into two distinct, flat content types: <strong>StandardVideo </strong>and <strong>GatedVideo</strong>. The author's choice of which component to insert in their page layout <em>is</em> the disambiguation.</p>
<p>To keep things clean, we use Optimizely's built-in features to resolve the duplication: <strong>Property Groups</strong> for authors, and <strong>SDK Contracts</strong> for developers.</p>
<pre class="code-block"><code>Standard Video (Type 1)
├── [Video Settings Group] ← via SDK Contract
│ ├── VideoFile
│ ├── PosterImage
│ └── Title
└── [Player Options Group]
├── Autoplay, Loop, ShowControls
Gated Video (Type 2)
├── [Video Settings Group] ← via SDK Contract
│ ├── VideoFile
│ ├── PosterImage
│ └── Title
└── [Lead Capture Group]
├── FormId, GateTimestamp</code></pre>
<h3>The Trade-Offs</h3>
<ul class="tight">
<li>
<p><strong>Pros:</strong></p>
<ul class="tight">
<li>
<p><strong>Excellent Author UX:</strong> Editors see only the fields that are directly relevant to what they are creating. No noise, no confusion, and the choice happens up front in a single step.</p>
</li>
<li>
<p><strong>Precise Validation:</strong> You can make <strong>FormId </strong>strictly required on Gated Videos and <strong>VideoFile </strong>required on both, with no overlaps—and no "empty wrapper" edge case to guard against.</p>
</li>
<li>
<p><strong>Evolvable Schemas:</strong> If you need to add an "External Tracker ID" to Gated Videos later, you add it to the Gated type. The Standard Video type remains completely untouched, preventing regressions.</p>
</li>
<li>
<p><strong>Flat GraphQL queries:</strong> Each type resolves directly, with no nested content-area fragment to traverse.</p>
</li>
</ul>
</li>
<li>
<p><strong>Cons:</strong></p>
<ul class="tight">
<li>
<p><strong>Minor Code Duplication:</strong> In some architectures, this might mean registering two types instead of one (though Optimizely's SDK makes this incredibly clean, as shown below).</p>
</li>
</ul>
</li>
</ul>
<hr />
<h2>Implementing Option 3 Cleanly with the Content JS SDK</h2>
<blockquote>
<p>⚠️ <strong>Implementation Disclaimer:</strong> <em>The following code snippets are illustrative implementations demonstrating the structure and APIs of the </em><strong>@optimizely/cms-sdk</strong><em>. Depending on your active SDK version, environment settings, and target packages, always verify the exact properties, imports, and field parameters in your sandbox prior to deploying content types to production.</em></p>
</blockquote>
<h3>1. Define a Shared Contract in Code</h3>
<p>The SDK's <strong>contract()</strong> function lets you declare the shared fields once. It keeps your codebase DRY, but merges the properties directly into each schema under the hood so authors get a flat, non-nested editor form:</p>
<pre class="code-block"><code class="language-ts">// src/contracts/VideoBaseContract.ts
import { contract } from '@optimizely/cms-sdk';
export const VideoBaseContract = contract({
key: 'VideoBase',
properties: {
videoFile: { type: 'contentReference', allowedTypes: ['_video'], required: true },
posterImage: { type: 'contentReference', allowedTypes: ['_image'], required: true },
title: { type: 'string', required: true },
},
});</code></pre>
<h3>2. Extend the Contract in Your Content Types</h3>
<p>Both content types simply extend our base contract:</p>
<pre class="code-block"><code class="language-ts">// src/components/StandardVideo.ts
export const StandardVideoContentType = contentType({
key: 'StandardVideo',
baseType: '_component',
extends: VideoBaseContract, // <-- Merges shared fields
properties: {
autoplay: { type: 'boolean', group: 'playerOptions' },
loop: { type: 'boolean', group: 'playerOptions' },
showControls: { type: 'boolean', group: 'playerOptions' },
},
});
// src/components/GatedVideo.ts
export const GatedVideoContentType = contentType({
key: 'GatedVideo',
baseType: '_component',
extends: VideoBaseContract, // <-- Merges shared fields
properties: {
formId: { type: 'string', group: 'leadCapture' },
gateTimestamp: { type: 'integer', group: 'leadCapture' },
},
});</code></pre>
<h3>3. Resolve to a Single React Component</h3>
<p>Here is the developer's favorite trick: even though we have two schemas in the CMS, <strong>we can map them both to a single React component.</strong></p>
<p>In our registry setup, we point both type keys to our <strong><VideoItem /></strong> component. The component inspects <strong>__typename</strong> (always supplied by Optimizely Graph) to decide how to render:</p>
<pre class="code-block"><code class="language-ts">// src/app/layout.tsx — Map both keys to the same component
initReactComponentRegistry({
resolver: {
StandardVideo: VideoItem,
GatedVideo: VideoItem,
},
});
// src/components/VideoItem.tsx — One entry, two layouts
export default function VideoItem({ content }: Props) {
if (content.__typename === 'GatedVideo') {
return <GatedVideoView content={content} />; // Typed as GatedVideoProps
}
return <StandardVideoView content={content} />; // Typed as StandardVideoProps
}</code></pre>
<hr />
<h2>Conclusion: Choosing What's Right for Your Team</h2>
<p>There is rarely a single "correct" answer in software architecture—only choices and their consequences.</p>
<ul class="tight">
<li>
<p>If your team is very small, your content needs are highly fluid, and you prioritize a rapid setup above all else, <strong>Option 1 (The Consolidated Block)</strong> might serve you well.</p>
</li>
<li>
<p>If your design system relies heavily on composable, modular sub-assemblies and your editors are comfortable with multi-step nesting, <strong>Option 2 (The Nested Wrapper)</strong> offers high structural reuse.</p>
</li>
<li>
<p>If you prioritize editor productivity, robust validation, and clean GraphQL queries, <strong>Option 3 (The Split-Type Pattern)</strong> combined with the SDK's single component routing gives you the best of both worlds: flat schemas for authors, and type-safe, DRY code for developers.</p>
</li>
</ul>
<p>By laying these options on the table, your team can align on a modeling philosophy that matches your technical maturity and authoring workflows.</p>
<hr />
<p><em>Resources: </em><a href="https://github.com/episerver/content-js-sdk/tree/main/docs"><em>Content JS SDK documentation</em></a><em> · </em><a href="https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/docs/content-modeling-saas"><em>Optimizely content modeling principles</em></a><em> · </em><a href="https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/docs/content-base-types-saas"><em>Content base types</em></a></p>2026-07-31T03:15:37.0000000ZBlog postFrom SDK to Core: Modernizing Optimizely Configured Commerce for .NET 8 and .NET 10<h1><img src="/link/a035a4fbeac940bbbbf3f09b0fb3d14f.aspx" alt="" /><br /><br /></h1>
<p><em>The .NET Framework 4.8 clock is running out for Configured Commerce customizations. Handled well, this deadline is not a chore it is the cleanest opportunity in years to shed technical debt, unlock modern performance, and future-proof your storefront. Here is what the migration really involves, and how an automation-first accelerator turns a months-long rewrite into a managed, low-risk upgrade.</em></p>
<h2>The deadline you cannot keep deferring</h2>
<p>For years, Optimizely Configured Commerce customizations have lived comfortably on the .NET Framework 4.8 SDK. It worked, it was stable, and there was rarely a pressing reason to touch it. That era is ending. Optimizely has set an end-of-support timeline for .NET 4.8 within Configured Commerce and is moving the platform onto modern .NET, and the runway is short.</p>
<p>The wider .NET picture makes the urgency concrete. Microsoft froze .NET Framework as a feature platform years ago there have been no new capabilities since version 4.8.1 in August 2022, and it now ships only as a component of Windows. Meanwhile the modern line moves fast: <strong>.NET 8</strong>, the current long-term-support release many teams are targeting, reaches <strong>end of support on November 10, 2026</strong>, and <strong>.NET 10</strong>, released in November 2025, carries long-term support through November 2028. Standing still is no longer neutral; it is a decision to fall further behind with every passing quarter.</p>
<p>The good news is that this is a well-understood, finite piece of work provided you approach it as an engineering program rather than a scramble. The rest of this article explains what the migration actually entails, why it is trickier than a routine framework bump, and how Royal Cyber compresses the effort and the risk with a purpose-built migration accelerator.</p>
<h2>What “SDK to Core” actually means</h2>
<p>Configured Commerce ships as a managed platform with defined extension points. Your team’s investment does not live in the platform’s own code; it lives in the customization projects layered on top the extensions, custom modules, integrations, and accelerator libraries that make the storefront yours. Historically those projects were built against the .NET Framework 4.8 SDK. “SDK to Core” migration means recompiling and re-shaping that custom code so it runs on modern, cross-platform .NET (the .NET 8.0+ line, the successor to what many still call “.NET Core”).</p>
<p>Crucially, the platform-owned projects are Optimizely’s responsibility and are upgraded through the normal version-upgrade process. Your migration scope is the <strong>custom code you own</strong>. Optimizely’s guidance is to first move to a recent platform build (release 5.2.2508 or newer), set up a modern local development environment, and then migrate your extension projects to .NET 8.0+. The target framework depends on your platform build: releases in the 5.2.2512–5.2.2604 range pair with .NET 8, while 5.2.2605 and later move to .NET 10.</p>
<p>In practice, then, this is a focused, bounded job: take the projects you built, carry them across a genuine framework boundary, and make sure they still behave the same way against the modernized platform. Bounded does not mean trivial as the next section shows.</p>
<h2>The real cost of standing still</h2>
<p>It is tempting to treat an aging framework as a problem for “later.” But the cost of remaining on .NET Framework 4.8 is real and compounding, even while the application appears to run fine.</p>
<ul>
<li><strong>Security exposure.</strong> A frozen framework receives only critical operating-system-level patches. Modern .NET receives active security hardening, and the ecosystem’s newest package versions increasingly target it exclusively.</li>
<li><strong>Performance left on the table.</strong> Each modern .NET release has delivered substantial throughput and memory improvements. Staying on 4.8 means paying for infrastructure to do work that newer runtimes do faster and cheaper.</li>
<li><strong>Innovation lockout.</strong> New Configured Commerce capabilities, language features, and libraries are built for modern .NET. On 4.8 you are increasingly unable to adopt them and unable to take advantage of platform enhancements that assume the new runtime.</li>
<li><strong>A shrinking talent pool.</strong> Engineers want to work on current stacks. Legacy frameworks make hiring harder and slow every future change.</li>
<li><strong>Compounding technical debt.</strong> The longer the gap between your code and the supported platform, the larger and riskier the eventual jump. Deferring does not remove the work; it inflates it.</li>
</ul>
<p>There is also a hard dependency at play: once Optimizely’s support window for .NET 4.8 closes, continued platform upgrades and hotfixes assume you are on the modern runtime. Migration stops being an optimization and becomes a prerequisite for staying current and supported.</p>
<h2>Why this is not a routine framework upgrade</h2>
<p>Teams sometimes assume a framework bump is a matter of changing a target version and rebuilding. For Configured Commerce customizations, several factors make it materially harder.</p>
<h3>A platform boundary you must not cross</h3>
<p>Certain projects are owned by the platform and must never be modified during migration. Editing them breaks upgradeability and support. A safe migration has to positively identify those projects and leave them alone, migrating only the code you own a distinction that is easy to get wrong by hand in a large solution.</p>
<h3>Breaking API and behavior changes</h3>
<p>The move from the old web stack to ASP.NET Core is not a rename. Controller base classes, action-result types, attribute routing, model binding, and dependency-injection patterns all change. Some shifts are mechanical; others are behavioral for example, how a null response is treated, or how optional collection parameters bind. A find-and-replace approach will compile and still be subtly wrong.</p>
<h3>Entity Framework and data access</h3>
<p>Legacy Entity Framework mapping classes must be reshaped into the EF Core pattern. Beyond the mechanical conversion, some query shapes that ran happily before will no longer translate to SQL, and lazy-loading assumptions can quietly change. These need a human eye, not a blind rewrite.</p>
<h3>The NuGet and packaging maze</h3>
<p>Modern platform packages pull in a large graph of dependencies at versions higher than the old direct references, producing downgrade errors. If your repository uses central package management, a naive migration also breaks version resolution. Getting a migrated project to simply restore and build cleanly is often where unaided efforts stall for days.</p>
<h3>Removed features with no drop-in replacement</h3>
<p>Some capabilities are gone in the modern platform. Search rebuild Version 1 is unsupported and must move to Version 2; certain legacy integration endpoints, media-editing features, and admin experiments are removed. These require a plan, not a patch and discovering them late is how projects slip.</p>
<h2>Where the manual approach breaks down</h2>
<p>Handed to a team without tooling, this migration tends to follow a predictable and painful arc. Engineers open project after project, chase compiler errors one at a time, and lose days untangling package conflicts before a single line of business logic is even reviewed. Because the mechanical and the judgment-heavy changes are tackled together, genuinely risky decisions get rushed while trivial edits soak up attention. Worst of all, the work is hard to audit: at the end, no one can say cleanly which changes were safe and automatic versus which ones altered behavior and deserve testing.</p>
<p>The result is slow, inconsistent, and stressful and it scales badly across the dozens of customization projects a mature storefront accumulates. The mechanical majority of the work is exactly the kind of thing software should do; the human minority is exactly the kind of thing software should never guess at. That insight is the foundation of Royal Cyber’s approach.</p>
<h2>A different approach: automate the mechanical, spotlight the judgment</h2>
<p>Royal Cyber built a migration accelerator for exactly this problem. Its guiding principle is a strict separation into two tiers.</p>
<ul>
<li><strong>Automatic.</strong> Changes that are mechanical and semantically safe the routing rewrites, base-class swaps, result-type changes, mapping conversions, and package reconciliations. These are applied for you, consistently, every time.</li>
<li><strong>Review.</strong> Changes that need human judgment behavioral edge cases, queries that may not translate, removed features. These are never auto-“fixed.” They are detected and reported with context, because a wrong automatic fix here is worse than a clear flag.</li>
</ul>
<p>Two design decisions make the accelerator safe to run early and often. First, it is non-destructive by default: it produces upgraded copies of your projects in a separate folder, keeping the original names and namespaces, so your existing codebase is never modified until you choose to adopt the result. Second, it defaults to a preview (dry-run) mode nothing is written to disk until you explicitly approve it. You can see exactly what a migration would do before committing to any of it.</p>
<h2>Inside the accelerator: how it works, end to end</h2>
<p>The tool is a single migration engine offered through several front-ends, so it fits however a team prefers to work a command-line tool for power users and CI pipelines, a browser-based app for a guided click-through, an automated agent for hands-off runs, and an integration that lets AI assistants drive the migration conversationally. Whichever entry point you choose, the underlying process is the same.</p>
<p><strong>1. Scan and select.</strong> The engine reads the solution, inventories every project with its current framework, and automatically locks the platform-owned projects so they cannot be migrated by mistake. You choose which of your customization projects to migrate.</p>
<p><strong>2. Analyze and transform.</strong> It runs Microsoft’s upgrade analysis for a baseline, then applies the full catalog of automatic transforms project-file modernization, namespace and API rewrites, EF Core mapping conversion, dependency and package-management reconciliation to the copies.</p>
<p><strong>3. Build, fix, and repeat.</strong> This is the standout capability. In agent mode the tool builds the migrated project, reads the compiler errors, applies a library of safe fixes, and rebuilds looping automatically until the project compiles. If it cannot finish on its own within a set number of attempts, it pauses and asks whether to continue rather than guessing. The tedious build-error grind that consumes manual migrations is largely automated away.</p>
<p><strong>4. Report everything.</strong> Every run produces a written migration report: what was changed automatically, and what still needs a person, organized by category with file and line references. It is an audit trail and a to-do list in one, and it is what lets a lead scope the remaining human work precisely.</p>
<h2>Automatic versus human: a concrete example</h2>
<p>The difference is easiest to see in code. Below is a typical Web API controller before and after migration. Every change on the right the routing attribute, the base class, the result types, the response attribute, the explicit body binding is applied automatically, because each is mechanical and safe.</p>
<table style="border-collapse: collapse; width: 100%; border: 1px solid #d6dbe0;">
<thead>
<tr>
<th style="background: #003963; color: #ffffff; text-align: left; padding: 8px 12px; border: 1px solid #d6dbe0; width: 50%;">Before .NET Framework 4.8 (SDK)</th>
<th style="background: #003963; color: #ffffff; text-align: left; padding: 8px 12px; border: 1px solid #d6dbe0; width: 50%;">After .NET 8 / .NET 10 (Core)</th>
</tr>
</thead>
<tbody>
<tr>
<td style="vertical-align: top; padding: 0; border: 1px solid #d6dbe0;">
<pre style="margin: 0; background: #f3f5f8; border-left: 4px solid #003963; padding: 12px; font-family: Consolas,Monaco,monospace; font-size: 13px; line-height: 1.5; white-space: pre; overflow: auto;">[RoutePrefix("api/v1/sample")]
public class SampleController
: ApiController
{
[ResponseType(typeof(OrderDto))]
public IHttpActionResult GetOrder(int id)
{ return this.Ok(dto); }
[HttpPost]
public IHttpActionResult CreateOrder(
OrderDto order) { ... }</pre>
</td>
<td style="vertical-align: top; padding: 0; border: 1px solid #d6dbe0;">
<pre style="margin: 0; background: #f3f5f8; border-left: 4px solid #003963; padding: 12px; font-family: Consolas,Monaco,monospace; font-size: 13px; line-height: 1.5; white-space: pre; overflow: auto;">[Route("api/v1/sample")]
public class SampleController
: ControllerBase
{
[ProducesResponseType(typeof(OrderDto),200)]
public IActionResult GetOrder(int id)
{ return this.Ok(dto); }
[HttpPost]
public IActionResult CreateOrder(
[FromBody] OrderDto order) { ... }</pre>
</td>
</tr>
</tbody>
</table>
<p>What the tool will not do silently is change behavior. If that same controller returned a value that might be null, or accepted an optional collection parameter, those are flagged for review because in ASP.NET Core they can behave differently, and only a developer who knows the intent should decide. The table below summarizes how the work divides across the migration.</p>
<table style="border-collapse: collapse; width: 100%; border: 1px solid #d6dbe0;">
<thead>
<tr>
<th style="background: #003963; color: #ffffff; text-align: left; padding: 8px 12px; border: 1px solid #d6dbe0;">Migration area</th>
<th style="background: #003963; color: #ffffff; text-align: left; padding: 8px 12px; border: 1px solid #d6dbe0;">Handled automatically</th>
<th style="background: #003963; color: #ffffff; text-align: left; padding: 8px 12px; border: 1px solid #d6dbe0;">Flagged for a human</th>
</tr>
</thead>
<tbody>
<tr>
<td style="padding: 8px 12px; border: 1px solid #d6dbe0; vertical-align: top;"><strong>Project files</strong></td>
<td style="padding: 8px 12px; border: 1px solid #d6dbe0; vertical-align: top;">Target framework set to a single modern .NET; legacy project format modernized; package references reconciled.</td>
<td style="padding: 8px 12px; border: 1px solid #d6dbe0; vertical-align: top;">Rare custom build targets or Windows-only assembly references.</td>
</tr>
<tr>
<td style="padding: 8px 12px; border: 1px solid #d6dbe0; vertical-align: top;"><strong>Web APIs & routing</strong></td>
<td style="padding: 8px 12px; border: 1px solid #d6dbe0; vertical-align: top;">Old attribute routing, action-result types and controller base classes rewritten to ASP.NET Core equivalents.</td>
<td style="padding: 8px 12px; border: 1px solid #d6dbe0; vertical-align: top;">Behavioral edge cases such as null-response handling and model binding differences.</td>
</tr>
<tr>
<td style="padding: 8px 12px; border: 1px solid #d6dbe0; vertical-align: top;"><strong>Data access</strong></td>
<td style="padding: 8px 12px; border: 1px solid #d6dbe0; vertical-align: top;">Entity Framework mapping classes converted to the EF Core pattern.</td>
<td style="padding: 8px 12px; border: 1px solid #d6dbe0; vertical-align: top;">Complex queries that may not translate to SQL, and lazy-loading assumptions.</td>
</tr>
<tr>
<td style="padding: 8px 12px; border: 1px solid #d6dbe0; vertical-align: top;"><strong>Dependencies (NuGet)</strong></td>
<td style="padding: 8px 12px; border: 1px solid #d6dbe0; vertical-align: top;">Version conflicts and central-package-management wiring resolved so the project restores cleanly.</td>
<td style="padding: 8px 12px; border: 1px solid #d6dbe0; vertical-align: top;">Cases where an intentionally older package version must be kept.</td>
</tr>
<tr>
<td style="padding: 8px 12px; border: 1px solid #d6dbe0; vertical-align: top;"><strong>Removed platform features</strong></td>
<td style="padding: 8px 12px; border: 1px solid #d6dbe0; vertical-align: top;"> </td>
<td style="padding: 8px 12px; border: 1px solid #d6dbe0; vertical-align: top;">Search rebuild to Version 2, dropped legacy integration endpoints, and other features with no drop-in replacement.</td>
</tr>
</tbody>
</table>
<p>This division is the whole point. Engineers stop spending their expensive judgment on mechanical edits, and start spending it only where judgment is actually required with a report that tells them exactly where that is.</p>
<h2>What the numbers look like in practice</h2>
<p>The accelerator is not a theoretical exercise. Run against a real, production Configured Commerce customization solution, it produces results like these:</p>
<div style="border: 1px solid #E87722; border-left: 6px solid #E87722; background: #fbf4ec; padding: 16px 20px;">
<p style="margin: 0 0 8px 0; color: #003963; font-weight: bold;">From one real accelerator codebase</p>
<p style="margin: 0;">Run against a production Configured Commerce customization solution, the tool scanned <strong>207 files</strong> across the custom modules, applied <strong>137 automatic, semantically-safe changes</strong>, and surfaced <strong>184 review items</strong> for an engineer to judge everything from a chatbot integration and a Power BI connector to a Teams module and a B2B accelerator library. The platform’s own projects were never touched.</p>
</div>
<p>The ratio is telling. The large majority of changes were handled automatically and consistently, while the review items the genuine engineering decisions were isolated and documented rather than buried. That is what converts an open-ended rewrite into a scoped, estimable, testable piece of work. It also means the same migration standard is applied identically across every project, instead of varying with whichever engineer happened to touch it.</p>
<h2>Choosing your target: .NET 8 or .NET 10</h2>
<p>A common early question is which modern framework to target. The honest answer is that your platform build largely decides for you, but the support calendar should shape the plan. Targeting <strong>.NET 8</strong> is the right move for platform releases in the 5.2.2512–5.2.2604 range but remember its support ends in November 2026, so it is best treated as a stepping stone rather than a destination. Newer platform builds (5.2.2605+) move to <strong>.NET 10</strong>, which carries long-term support through November 2028 and is the better place to land if your platform version allows it.</p>
<p>The strategic implication is straightforward: align your Configured Commerce version-upgrade roadmap with your framework target so you make the jump once, to a runtime with a long support runway, rather than migrating to .NET 8 now and repeating the exercise a year later. Royal Cyber’s accelerator supports both targets and enforces a single modern framework in the output, so the migrated projects are clean and unambiguous either way.</p>
<h2>A pragmatic migration playbook</h2>
<p>Based on real engagements, a low-drama migration tends to follow this shape:</p>
<ol>
<li><strong>Inventory and align.</strong> Catalog your customization projects and confirm your target platform build and framework. Establish which projects are platform-owned and out of scope.</li>
<li><strong>Preview before you commit.</strong> Run the accelerator in dry-run mode to produce a full report of automatic changes and review items with no risk to the existing codebase and use it to scope the human effort accurately.</li>
<li><strong>Automate the mechanical majority.</strong> Let the tool generate the migrated copies, run the build-fix loop to green, and reconcile packages, so engineers start from a compiling project rather than a wall of errors.</li>
<li><strong>Work the review list deliberately.</strong> Address the flagged items behavior changes, untranslatable queries, removed features such as the search rebuild move to Version 2 with proper testing behind each decision.</li>
<li><strong>Regression-test as a first-class step.</strong> Mechanical migration is not a substitute for testing. Validate the storefront’s critical paths against the modernized platform before you adopt the result.</li>
</ol>
<p>Handled this way, the migration becomes a series of visible, reviewable steps with a clear finish line not an open-ended risk hanging over the roadmap.</p>
<h2>The bottom line</h2>
<p>The end of .NET Framework 4.8 support for Configured Commerce is not a problem to survive; it is an opportunity to modernize on your own terms. The work is real, and parts of it genuinely require experienced judgment. But the mechanical majority the part that historically eats weeks and introduces inconsistency can and should be automated, leaving your engineers to focus only on the decisions that matter and giving your stakeholders a clear, auditable trail of what changed and why.</p>
<p>That is precisely what Royal Cyber’s migration accelerator delivers: automatic where it is safe, transparent where it is not, non-destructive by default, and fast where manual effort stalls. If your Configured Commerce storefront is still on the .NET Framework SDK, the smartest move is to start with a no-risk assessment a dry-run migration report that shows exactly what your modernization will involve, before you commit a single change.</p>
<h3>Ready to see your migration report?</h3>
<p>Royal Cyber’s Optimizely practice can run an assessment against your solution and walk you through the results. Explore our Optimizely services at</p>
<p><a style="color: blue;" href="https://www.royalcyber.com/technologies/optimizely/">https://www.royalcyber.com/technologies/optimizely/</a>, or reach out to start the conversation.</p>
<p> </p>2026-07-29T18:16:57.0000000ZBlog postParallel Development in Optimizely CMS SaaS: Shifting to a Schema Migration Mindset<p> </p>
<p><em>Part 3 of the Parallel Development series.</em></p>
<p>The branch-scoped push script from <a href="/link/60050e9906014446bb28143b0ca1b0c2.aspx">Part 1</a> works. Run it on a feature branch where you've touched a handful of independent content types and it does exactly what it promises — pushes only your changes, leaves your teammate's work untouched, no <strong>--force</strong> required.</p>
<p>For most of your day-to-day work, that's enough. The majority of content type changes are leaf changes: you added a field to a page, you tweaked a block, you updated a template. The script handles all of those cleanly.</p>
<p>But as soon as you start moving past basic, isolated components and build toward a real content model—with custom contracts, shared property groups, and complex validation rules—the landscape changes. The script still works, but running selective push against a full, production-grade schema teaches you a few things worth mapping out before you hit them cold. None of this is a flaw in the selective push approach. These dependency cases exist in any code-first workflow with the CLI, whether you push selectively or all at once. What changes is whether you walk into them knowing what's happening, or whether you spend an afternoon confused at an API rejection.</p>
<p>This post maps the five hidden dependency cases, shows what each looks like in code, and proposes a repo structure plus a reviewable push workflow that makes them more manageable. These are starting points and open questions — not a finished solution. We'd genuinely like to hear how other teams are thinking about this.</p>
<hr />
<h2>First: "Why not just always full push?"</h2>
<p>It's the fair question, and worth answering before anything else — because if full push were always fine, none of this would matter.</p>
<p>Full push is authoritative and safe <em>against a clean, canonical branch</em>. That's exactly why it's the right tool for your CI/CD pipeline pushing from <strong>main</strong>. But on a <strong>shared development instance where several people have unmerged work</strong>, full push is the opposite of safe: it syncs your <em>entire</em> local model, including stale or half-built types, over whatever your teammates have pushed. That's the collision Part 1 set out to solve.</p>
<p>And when the CLI suggests <strong>--force</strong>? That's not a fix. It's the CLI telling you the remote already has changes you're about to overwrite. The correct response is to <strong>sync with your team</strong>, not to force through. Force is how one developer silently clobbers another's content types.</p>
<p>So the real trade-off isn't "selective push (hard) vs full push (easy)." It's:</p>
<ul class="tight">
<li>
<p><strong>Independent leaf changes (the 80%)</strong> — selective push is fully automatic and strictly better. No contest.</p>
</li>
<li>
<p><strong>The five dependency cases</strong> — selective push <em>still</em> beats full push on a shared instance, because a scoped-but-complete push includes what's needed and touches nothing else. The catch is you have to know what "complete" means. That's what this article tries to make knowable.</p>
</li>
<li>
<p><strong>Key renames and deletions</strong> — these genuinely are "stop and coordinate" moments. The honest value here isn't a clever script; it's <em>recognising</em> you're in one, so you sync with the team and run a deliberate full push instead of forcing blindly.</p>
</li>
</ul>
<p>That's the frame for everything below. This isn't about avoiding full push forever — it's about knowing which situation you're in.</p>
<hr />
<h2>The Five Hidden Dependencies</h2>
<p>In Optimizely CMS SaaS, we've identified five distinct cases where a change to one file creates a dependency that requires other files to be pushed in the same payload. Before we look at how to handle them, here is the quick map of the territory:</p>
<ol class="tight">
<li>
<p><strong>Contract changes</strong> — Modifying an interface pulls in all content types implementing it.</p>
</li>
<li>
<p><strong>Property group changes</strong> — Renaming or removing a group key affects every content type assigned to it.</p>
</li>
<li>
<p><strong>Component embeds</strong> — Schema shifts on a component affect any content type using them as typed properties.</p>
</li>
<li>
<p><strong>Validation constraints</strong> — Changes to referenced type keys break <strong>allowedTypes</strong> or <strong>restrictedTypes</strong> in other files.</p>
</li>
<li>
<p><strong>Key renames</strong> — A key value change is a destructive delete-and-create that orphans content and breaks external references.</p>
</li>
</ol>
<p>For each case, the "how to handle it" notes reflect our own thinking and what seems reasonable — not tested playbooks. Your project's structure and conventions will change what actually works.</p>
<hr />
<h2>Case 1 — Contract change → all implementing types</h2>
<p>Contracts define a shared set of properties that multiple content types implement. Add a field to a contract, and every implementing type has a stale resolved schema on the server — because that field is now part of their schema too, whether they declared it explicitly or not.</p>
<p>This is transitive. If Contract A is implemented by Contract B, and Contract B is implemented by five page types, a change to Contract A means all six need to be in the same push.</p>
<h3>Why isolated contract pushes fail</h3>
<p>The temptation is to slice pushes into layers — a "foundation" config that covers contracts, a "types" config that covers pages and blocks. Different concerns, different cadence. The logic is sound.</p>
<p>Then you try it on a live instance where types already implement the contract:</p>
<pre class="code-block"><code class="language-bash"># Fails if any content type already implements the contract on the target instance
npx @optimizely/cms-cli@latest push --config optimizely.config.foundation.mjs</code></pre>
<p>The CLI errors out. The API rejects the payload.</p>
<p>Based on observed behaviour, when a contract changes on the server, the CMS appears to immediately recompile the fully resolved schema of every implementing type. If those types aren't in the same push payload, the API rejects the whole operation rather than leave the instance in a half-compiled state. This is the right call — it's protecting you. But it means contracts and their implementers can't travel separately once the contract is applied.</p>
<p>📖 <a href="https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/docs/create-contracts">Create contracts</a></p>
<blockquote>
<p><strong>Note on code examples:</strong> The JSON and TypeScript shapes shown throughout this article are illustrative of the concepts. Always check the current CLI <strong>--help</strong> output and the <a href="https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/docs/manage-content-types-using-the-rest-api">REST API reference</a> for exact syntax on your version.</p>
</blockquote>
<pre class="code-block"><code class="language-json">// Contract — POST https://api.cms.optimizely.com/v1/contenttypes
{
"key": "categorizable",
"displayName": "Categorizable",
"properties": {
"category": { "type": "string", "displayName": "Category" },
"tags": { "type": "array", "displayName": "Tags", "items": { "type": "string" } }
}
}
// Content type implementing the contract
// Adding a field to 'categorizable' above means this type must be in the same push
{
"key": "articlePage",
"baseType": "_page",
"contracts": ["categorizable"],
"properties": {
"title": { "type": "string", "displayName": "Title" },
"body": { "type": "richText", "displayName": "Body" }
}
}</code></pre>
<blockquote>
<p><strong>One possible approach:</strong> Scan all content-type files for any import or string reference to the changed contract's file name, and include matches in the push set. Whether that works reliably depends on how consistently your codebase names and imports contracts — a loosely structured project may need a more explicit dependency map. We haven't found a clean universal answer here.</p>
</blockquote>
<hr />
<h2>Case 2 — Property group change → all types referencing that group</h2>
<p>Property groups are defined in <strong>optimizely.config.mjs</strong> via <strong>buildConfig</strong> and referenced by <strong>key</strong> inside property definitions. Change or remove that key, and any type that assigns properties to it fails validation.</p>
<p>📖 <a href="https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/docs/property-groups-saas">Property groups</a></p>
<pre class="code-block"><code class="language-javascript">// optimizely.config.mjs
import { buildConfig } from '@optimizely/cms-sdk';
export default buildConfig({
components: ['./src/content-model/**/*.tsx'],
propertyGroups: [
{ key: 'seo', displayName: 'SEO Settings', sortOrder: 10 }
// Rename 'seo' here → every type referencing this key must be re-pushed
]
});</code></pre>
<pre class="code-block"><code class="language-json">// PATCH https://api.cms.optimizely.com/v1/contenttypes/articlePage
{
"key": "articlePage",
"baseType": "_page",
"properties": {
"metaTitle": { "type": "string", "displayName": "Meta Title", "group": "seo" },
"metaDescription": { "type": "string", "displayName": "Meta Description", "group": "seo" }
}
}</code></pre>
<p>Rename the group key without re-pushing <strong>articlePage</strong> and its <strong>metaTitle</strong> / <strong>metaDescription</strong> properties now point to a group that doesn't exist on the instance.</p>
<blockquote>
<p><strong>One possible approach:</strong> Diff <strong>optimizely.config.mjs</strong>, extract changed group keys, and search content-type files for those strings. Since the config change is usually deliberate and visible in review, this might be something you handle at review time rather than automating — though what's right depends entirely on your team's workflow and how often these keys change.</p>
</blockquote>
<hr />
<h2>Case 3 — Component used as a typed property → the embedding type</h2>
<p>A <strong>_component</strong> content type can be declared as a fixed typed property on another content type — not just dropped into a content area at runtime, but <em>declared</em> in the schema as a property of that specific type. Optimizely Graph registers both <strong>TeaserBlock</strong> (standalone) and <strong>TeaserBlockProperty</strong> (when embedded as a schema property) to support this.</p>
<p>When the component's schema changes, the type that embeds it is resolving a shape that has shifted.</p>
<p>📖 <a href="https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/docs/content-modeling-saas-graph">Content modeling — content properties</a> · <a href="https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/docs/content-types-saas">Define content types</a></p>
<pre class="code-block"><code class="language-json">// The component — POST https://api.cms.optimizely.com/v1/contenttypes
{
"key": "teaserBlock",
"baseType": "_component",
"properties": {
"heading": { "type": "string", "displayName": "Heading" },
"image": { "type": "contentReference", "displayName": "Image" }
// Add a new required field here → homePage below must be in the same push
}
}
// A page declaring the component as a typed property
{
"key": "homePage",
"baseType": "_page",
"properties": {
"hero": { "type": "content", "displayName": "Hero Teaser", "contentType": "teaserBlock" }
}
}</code></pre>
<blockquote>
<p><strong>One possible approach:</strong> Scan content-type files for references to the changed component's name or key. The tricky part is distinguishing a typed schema embed from a regular rendering import — a flat folder makes this ambiguous, which is part of why the folder structure below is worth considering.</p>
</blockquote>
<hr />
<h2>Case 4 — allowedTypes / restrictedTypes references → the referencing type</h2>
<p><strong>allowedTypes</strong> and <strong>restrictedTypes</strong> are validation constraints on <strong>content</strong> and <strong>contentReference</strong> properties. They name other types <strong>by their key</strong>. That reference is invisible to a git diff.</p>
<p>📖 <a href="https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/docs/content-property">Content property — allowedTypes</a> · <a href="https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/docs/content-types-saas">Define content types</a></p>
<pre class="code-block"><code class="language-json">// PATCH https://api.cms.optimizely.com/v1/contenttypes/landingPage
{
"key": "landingPage",
"baseType": "_page",
"properties": {
"relatedContent": {
"type": "contentReference",
"displayName": "Related Content",
"allowedTypes": ["articlePage", "blogPage"]
}
}
}
// If 'blogPage' is renamed to 'blogPostPage' —
// git diff shows BlogPage.tsx changed
// git diff does NOT show landingPage.tsx changed
// but landingPage now references a key that doesn't exist</code></pre>
<p>Adding a <em>new</em> type to <strong>allowedTypes</strong> is completely safe — it's in your diff and selective push handles it automatically.</p>
<blockquote>
<p><strong>One possible approach:</strong> A pre-push step that reads all <strong>allowedTypes</strong> / <strong>restrictedTypes</strong> arrays and verifies every key they name still exists in the codebase could act as an early warning. Whether that's worth building depends on how often your model changes and how much a broken shared environment costs your team.</p>
</blockquote>
<hr />
<h2>Case 5 — Key rename: unavoidable sometimes, never trivial</h2>
<blockquote>
<p>⚠️ <strong>Design your keys well upfront and you likely won't face this. But if you do, know exactly what happens.</strong></p>
</blockquote>
<p>The <strong>key</strong> of a content type, contract, or property is its permanent identity on the CMS instance. There is no rename operation — what actually happens is a <strong>delete of the old + create of the new</strong>. The CMS treats them as two completely different entities.</p>
<p>Consequences:</p>
<ul class="tight">
<li>
<p>All content items created under the old key are orphaned</p>
</li>
<li>
<p>Every type that names the old key — in <strong>allowedTypes</strong>, <strong>restrictedTypes</strong>, typed <strong>contentType</strong> properties, <strong>contracts</strong> arrays — is now broken</p>
</li>
<li>
<p>Git diff shows only the file where the key string changed, nothing about files that reference it elsewhere</p>
</li>
</ul>
<p>📖 <a href="https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/docs/manage-content-types-using-the-rest-api">Manage content types — key field</a></p>
<pre class="code-block"><code class="language-json">// BEFORE: 'blogPage' is the live key
{ "key": "blogPage", "baseType": "_page" }
{ "allowedTypes": ["articlePage", "blogPage"] } // another type, referencing it
// AFTER: key renamed to 'blogPostPage'
{ "key": "blogPostPage", "baseType": "_page" } // BlogPage.tsx — in your diff
{ "allowedTypes": ["articlePage", "blogPage"] } // LandingPage.tsx — NOT in your diff, now broken</code></pre>
<p><strong>The realistic minimum when a rename is unavoidable:</strong></p>
<ol class="tight">
<li>
<p>Search the full codebase for the old key string (<strong>grep -r "blogPage" src/</strong> is the starting point)</p>
</li>
<li>
<p>Update every file that references it in the same branch</p>
</li>
<li>
<p>Run a <strong>coordinated full push</strong> — not a selective push</p>
</li>
<li>
<p>Plan content migration separately — existing content under the old key is not auto-migrated</p>
</li>
</ol>
<p><strong>displayName</strong> is free to rename at any time. <strong>key</strong> is permanent the moment it lands on an instance.</p>
<h3>One direction worth exploring: detect the rename at diff time</h3>
<p>Git has the information you need — you can pull the <em>old</em> version of any changed file and compare key values:</p>
<pre class="code-block"><code class="language-bash"># Get the old content of a file as it was on the base branch
git show origin/main:src/content-model/pages/BlogPage.tsx</code></pre>
<p>For each modified content-type file: extract the old <strong>key</strong> and the new <strong>key</strong>. If they differ, search the codebase for the old key and surface every file that still references it. That turns a silent, easy-to-miss breakage into a loud early warning. You still need the coordinated full push — but at least you know why before you push, rather than after.</p>
<p>We haven't battle-tested this in a complex repo. It's a direction that seems worth exploring, not a recommendation.</p>
<h4>The Safe Alternative: The Editorial Deprecation Pattern</h4>
<p>Instead of performing a destructive key rename, the industry-standard best practice is to <strong>deprecate</strong> the old field and introduce the new one alongside it. While CMS SaaS doesn't have a native "deprecated" JSON flag in the schema, you can enforce this through an <strong>editorial convention</strong> in your code:</p>
<ol class="tight">
<li>
<p><strong>Remove constraints:</strong> Set <strong>"required": false</strong> on the old field so editors are never blocked.</p>
</li>
<li>
<p><strong>Warn editors in the UI:</strong> Update its <strong>displayName</strong> to include <strong>(Obsolete)</strong> and use the <strong>description</strong> to point to the new property.</p>
</li>
<li>
<p><strong>Warn developers in the IDE:</strong> Add a JSDoc <strong>@deprecated</strong> comment to the TypeScript interface.</p>
</li>
</ol>
<pre class="code-block"><code class="language-javascript">// src/content-model/components/TeaserBlock.tsx
export interface TeaserBlockType extends ContentType {
heading: string;
/**
* @deprecated Use 'heroImage' instead. This field is scheduled for removal in Q4.
*/
imageLink?: string; // Suffix with ? to make it optional in TS
}
export const TeaserBlockSchema = {
key: 'teaserBlock',
baseType: '_component',
displayName: 'Teaser Block',
properties: {
heading: { type: 'string', displayName: 'Heading', required: true },
imageLink: {
type: 'string',
displayName: 'Image Link (Obsolete)',
description: 'Deprecated. Use the Hero Image property instead.',
required: false, // Must be optional to prevent editor lock-out
},
},
};</code></pre>
<p>This keeps the old schema active, preserves historical data on production, and gives both developers and editors loud warnings. Only after several release cycles (when audit logs confirm no content remains in the old field) do you coordinate with your team to delete the key.</p>
<blockquote>
<p><strong>Our suggested approach:</strong> Treat renames as deliberate, planned events requiring a full codebase audit before any push. The git-blob detection above is a reasonable middle ground — cheap to build, fails loudly. But no script makes a key rename safe on its own.</p>
</blockquote>
<hr />
<h2>The Repo Structure That Makes All of This More Tractable</h2>
<p>Every detection approach above — scanning for contract references, extracting group keys, comparing old and new key values — relies on being able to tell <em>what kind of thing</em> a changed file is from where it lives. In a flat folder where contracts, pages, blocks, and templates all coexist, that falls apart immediately.</p>
<p>A deliberate folder structure is what makes any of this tractable. It won't solve the dependency problem on its own, but it gives your scripts — and your reviewers — something to reason from.</p>
<pre class="code-block"><code>src/
└── content-model/ # Everything the CLI pushes as schema
├── contracts/ # Shared interfaces — Case 1 blast radius
│ ├── Categorizable.ts # category + tags fields shared across types
│ └── IHeroImage.ts # heroImage + heroAlt fields
├── pages/ # _page base type
│ ├── ArticlePage.tsx
│ ├── LandingPage.tsx
│ └── BlogPage.tsx
├── components/ # _component base type (blocks AND elements)
│ ├── TeaserBlock.tsx
│ ├── HeroBlock.tsx
│ ├── HeadingElement.tsx # an "element" is just a component with restricted config
│ └── ParagraphElement.tsx
├── experiences/ # _experience base type
│ └── BlankExperience.tsx
└── sections/ # _section base type
└── BlankSection.tsx
src/
└── templates/ # Display templates — decoupled, own push lane
├── ArticlePage.style.ts # Wide / Narrow display variants for ArticlePage
├── TeaserBlock.style.ts # Card / Banner display variants for TeaserBlock
└── section-grid.style.ts # 1-col / 2-col / 3-col section layout options</code></pre>
<p>A note on <strong>elements</strong>: in the JavaScript SDK, an element is not a separate base type — it's a <strong>_component</strong> with restricted configuration (it's meant to be used as a Visual Builder building block rather than a standalone block). Because it's still a component, it lives in the same folder and behaves identically for push-dependency purposes. Group by base type, not by editorial role.</p>
<p><strong>Property groups</strong> don't get their own files either — they live in <strong>optimizely.config.mjs</strong> as the propertyGroups array. If your config grows large you can split it into an imported module, but the source of truth stays the config file.</p>
<h3>What templates actually are</h3>
<p>A template file registers display variations that editors can apply to content nodes in Visual Builder. They are pure style/visual configuration — they carry no content schema. This is why they can be pushed on their own lane without any dependency scanning.</p>
<p>A display template applies to a content type (or base type, or structural node) and exposes editor-selectable settings:</p>
<pre class="code-block"><code class="language-typescript">// src/templates/TeaserBlock.style.ts
// POST https://api.cms.optimizely.com/v1/displaytemplates
export const teaserBlockCardStyle = {
key: 'TeaserBlockCard',
displayName: 'Card',
contentType: 'teaserBlock', // applies to this specific content type
settings: {
ImagePosition: {
displayName: 'Image Position',
editor: 'select',
choices: {
Left: { displayName: 'Left', sortOrder: 1 },
Right: { displayName: 'Right', sortOrder: 2 },
Top: { displayName: 'Top', sortOrder: 3 }
}
}
}
};</code></pre>
<pre class="code-block"><code class="language-typescript">// src/templates/section-grid.style.ts
// A structural node template — applies to all sections
export const sectionGridStyle = {
key: 'SectionGrid',
displayName: 'Grid',
nodeType: 'section', // applies to all section nodes
settings: {
Columns: {
displayName: 'Columns',
editor: 'select',
choices: {
One: { displayName: '1 column', sortOrder: 1 },
Two: { displayName: '2 columns', sortOrder: 2 },
Three: { displayName: '3 columns', sortOrder: 3 }
}
}
}
};</code></pre>
<p>📖 <a href="https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/docs/configure-visual-builder">Configure Visual Builder</a> · <a href="https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/docs/work-with-styles">Manage styles</a></p>
<h3>The folder pays off in the script</h3>
<p>With this structure, a script can classify a changed file from its path alone:</p>
<ul class="tight">
<li>
<p>A file under <strong>content-model/contracts/</strong> → run the Case 1 scan</p>
</li>
<li>
<p>A file under <strong>content-model/pages/</strong> or <strong>content-model/components/</strong> → run the Case 3 scan</p>
</li>
<li>
<p><strong>optimizely.config.mjs</strong> changed → run the Case 2 check</p>
</li>
<li>
<p>A file under <strong>templates/</strong> → push on the templates lane, no schema scan needed</p>
</li>
</ul>
<p>It also opens the door to something more responsive: a file watcher during development that flags dependency-affecting changes the moment you save, before you ever run a push. We haven't built that — it's a direction the structure makes possible.</p>
<p>The honest caveat: no folder convention survives a team that doesn't follow it. The structure only works if it's agreed, documented, and enforced.</p>
<hr />
<h2>Shifting Our Mindset: Content Modeling as Schema Migration</h2>
<p>When you build on a headless, code-first content platform, your content type files are not just React rendering files. They represent your <strong>live database schema, your API contract, and your editorial UI layout all at once.</strong></p>
<p>In traditional software engineering, we treat database schemas with extreme discipline. You would never let a CI/CD build run a migration that drops database columns containing live customer data. You write versioned migrations, test them locally, and deploy them sequentially.</p>
<p>Content modeling in CMS SaaS requires the exact same engineering discipline.</p>
<p>This realization completely changes how we govern our code-first pipelines and why selective pushes exist:</p>
<ol class="tight">
<li>
<p><strong>Selective push is your local iteration tool.</strong> It is how developers move quickly on a shared sandbox without overwriting other unmerged work.</p>
</li>
<li>
<p><strong>The script is your diagnostic blueprint.</strong> When a build fails or conflicts occur, the branch-diff script is what you run to instantly map out the exact footprint of your changes and see which contracts or components are dragging dependents in.</p>
</li>
<li>
<p><strong>CI/CD is your schema safety gate.</strong> It must run strictly, never forcing, and failing loudly if anything is out of sync.</p>
</li>
</ol>
<p>Let’s look at how to structure your CI/CD pipeline to act as this hard firewall.</p>
<hr />
<h2>CI/CD Guardrails: The "Fail Loudly, Never Force" Principle</h2>
<p>In lower environments (like individual developer sandboxes), selective pushes and the propose-review-push workflow provide rapid feedback loops. But as your code travels up to shared environments, the governance must tighten.</p>
<table style="border-collapse: collapse; border-width: 1px; border-style: solid;">
<tbody>
<tr>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p><strong>Environment</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p><strong>Purpose</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p><strong>Push Strategy</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p><strong>CLI Flags</strong></p>
</td>
</tr>
<tr>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p><strong>Local Sandbox</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Individual dev space</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Scoped / Selective push</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Normal</p>
</td>
</tr>
<tr>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p><strong>Shared QA / Stage</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Team integration & content entry</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Scoped or Full Push</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p><strong>Strictly no --force</strong></p>
</td>
</tr>
<tr>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p><strong>Production</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Live consumer experience</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Authoritative Full Push</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p><strong>Strictly no --force</strong></p>
</td>
</tr>
</tbody>
</table>
<h3>Enforcing the Safety Gate</h3>
<p>The <strong>@optimizely/cms-cli</strong> is designed to fail loudly. If there is a schema conflict — such as a missing implementing type for a modified contract, or an invalid group key reference — the command exits with a non-zero exit code (typically <strong>1</strong>).</p>
<p>Any standard CI/CD engine (GitHub Actions, GitLab CI, Azure DevOps) will intercept this non-zero exit code and immediately fail the build step.</p>
<p>By running your staging and production pipelines <strong>without the --force flag</strong>, you ensure that if a developer checked in a breaking change without coordination, the build halts before a single production schema is modified or live data is orphaned.</p>
<h3>Diagnostic Recovery Workflow</h3>
<p>When the build fails, the team doesn't have to guess what broke. A developer runs the <strong>push-branch-changes.mjs</strong> script locally comparing the release branch to the target base (e.g., <strong>origin/main</strong>):</p>
<pre class="code-block"><code class="language-bash">npm run cms:push:types release/q3 origin/main</code></pre>
<p>The script outputs the precise dependency tree of the changed files. The team can instantly pinpoint: <em>"Ah! Someone updated the contract, which dragged in ArticlePage. But ArticlePage on Stage has custom fields that are still locked in another draft. That's our conflict."</em></p>
<p>It turns a black-box build failure into an actionable, reviewable transaction map.</p>
<hr />
<h2>The Workflow: Propose, Review, Push</h2>
<p>The script below doesn't push for you automatically. It detects, proposes, and hands you a reviewable config. You decide whether to push it.</p>
<p>The loop:</p>
<ol class="tight">
<li>
<p>Run one command against your branch.</p>
</li>
<li>
<p>The script diffs your branch, classifies each changed file by its folder, and runs the relevant dependency scans for Cases 1–3.</p>
</li>
<li>
<p>It <strong>writes a temporary config</strong> listing the proposed push set — your changed files plus every dependent it found — and prints the list.</p>
</li>
<li>
<p>You review the list. Does it look right? Anything surprising, or anything missing you expected? For Cases 4–5 it flags what needs a human decision.</p>
</li>
<li>
<p>If you're satisfied, you run the push command it hands you.</p>
</li>
</ol>
<p>This isn't overhead instead of a solution. It's a gate that makes a scoped push reviewable before it lands on a shared instance — something a blind full push can't give you.</p>
<p>Two commands, split by concern:</p>
<pre class="code-block"><code class="language-json">// package.json
"scripts": {
"cms:push:templates": "npx @optimizely/cms-cli@latest push --config optimizely.config.templates.mjs",
"cms:push:types": "node push-branch-changes.mjs"
}</code></pre>
<p><strong>Templates lane —</strong> display templates and Visual Builder styles. Zero schema risk. No review needed.</p>
<p><strong>Types lane —</strong> content types and contracts together, via the propose-review-push script below.</p>
<hr />
<h2>One Rough Starting Point for the Script</h2>
<p>This extends the script from Part 1 to attempt dependency detection for Cases 1–3. We're sharing it as a concept, not a drop-in solution. It makes simplifying assumptions — consistent folder structure, filename-based detection, flat directory scanning — that won't hold in every project. Treat it as something to adapt, not something to copy.</p>
<p>Cases 4 and 5 (key renames and deletions) are not automatable in any reliable way. The script blocks on file deletions to at least surface the problem. Key value renames it cannot detect at all without the git-blob comparison described in Case 5.</p>
<p>📖 <a href="https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/docs">JavaScript SDK docs</a></p>
<pre class="code-block"><code class="language-javascript">// push-branch-changes.mjs — adapt to your folder structure
import { execSync } from 'child_process';
import fs from 'fs';
import path from 'path';
const baseBranch = process.argv[2] || 'origin/main';
const tempConfig = 'optimizely.config.temp.mjs';
// Match your actual folder structure. Note: elements live under components.
const PAGES_DIR = 'src/content-model/pages';
const COMPONENTS_DIR = 'src/content-model/components';
const CONTRACTS_DIR = 'src/content-model/contracts';
const ALL_TYPES_DIRS = [PAGES_DIR, COMPONENTS_DIR, CONTRACTS_DIR];
try {
console.log(`Diffing against ${baseBranch}...`);
const gitOutput = execSync(`git diff ${baseBranch} --name-only`, { encoding: 'utf8' });
const changedFiles = gitOutput
.split('\n').map(f => f.trim())
.filter(f => f.length > 0 && fs.existsSync(f));
if (changedFiles.length === 0) {
console.log('No changes. Nothing to push.');
process.exit(0);
}
// ── Block on deletions — requires human audit before any push
const deletedFiles = execSync(
`git diff ${baseBranch} --name-only --diff-filter=D`, { encoding: 'utf8' }
).split('\n').map(f => f.trim()).filter(Boolean);
const deletedTypes = deletedFiles.filter(f => ALL_TYPES_DIRS.some(d => f.startsWith(d)));
if (deletedTypes.length > 0) {
console.error('\n[BLOCKED] Deleted content type or contract files:');
deletedTypes.forEach(f => console.error(` - ${f}`));
console.error('\nAudit all referencing files before running a coordinated full push.\n');
process.exit(1);
}
const pushRegistry = new Set();
changedFiles
.filter(f => ALL_TYPES_DIRS.some(d => f.startsWith(d)))
.forEach(f => pushRegistry.add(f));
// All content-model files — used for scanning
const allTypeFiles = ALL_TYPES_DIRS.flatMap(dir =>
fs.existsSync(dir)
? fs.readdirSync(dir, { recursive: true })
.filter(f => f.endsWith('.tsx') || f.endsWith('.ts'))
.map(f => path.join(dir, f))
: []
);
// ── Case 1: Contract changes → scan for implementing types
const changedContracts = changedFiles.filter(f => f.startsWith(CONTRACTS_DIR));
if (changedContracts.length > 0) {
console.log('\n[Case 1] Contract changes — scanning for implementing types...');
const names = changedContracts.map(f => path.basename(f, path.extname(f)));
expandDependents(allTypeFiles, names, pushRegistry, 'implements contract');
}
// ── Case 2: Property group key changes → scan for referencing types
const changedConfig = changedFiles.find(f => f === 'optimizely.config.mjs');
if (changedConfig) {
const src = fs.readFileSync(changedConfig, 'utf8');
const groupKeys = [...src.matchAll(/key:\s*['"](\w[\w-]*)['"]\s*,\s*displayName/g)].map(m => m[1]);
if (groupKeys.length > 0) {
console.log(`\n[Case 2] Property group keys (${groupKeys.join(', ')}) — scanning referencing types...`);
expandDependents(allTypeFiles, groupKeys, pushRegistry, 'references group key');
}
}
// ── Case 3: Component/page changes → scan for types that embed them
const changedComponents = changedFiles.filter(f =>
f.startsWith(COMPONENTS_DIR) || f.startsWith(PAGES_DIR)
);
if (changedComponents.length > 0) {
const names = changedComponents.map(f => path.basename(f, path.extname(f)));
console.log('\n[Case 3] Component/page changes — scanning for embedding types...');
expandDependents(allTypeFiles, names, pushRegistry, 'embeds as typed property');
}
const finalPushList = Array.from(pushRegistry);
if (finalPushList.length === 0) {
console.log('No pushable schema changes found.');
process.exit(0);
}
// ── Propose: write the temp config and print it for review
console.log(`\nProposed push set (${finalPushList.length} files) — review before confirming:`);
finalPushList.forEach(f => console.log(` - ${f}`));
const filePaths = finalPushList.map(f => `'./${f}'`).join(',\n ');
fs.writeFileSync(tempConfig,
`import { buildConfig } from '@optimizely/cms-sdk';
export default buildConfig({ components: [\n ${filePaths}\n ] });
`, 'utf8');
console.log(`\nWrote ${tempConfig}. Review it, then push with:`);
console.log(` npx @optimizely/cms-cli@latest push --config ${tempConfig}\n`);
// The script stops here and hands you the command rather than pushing automatically.
// If you're confident in the detection for your project, you can execSync the push instead.
} catch (err) {
console.error('Failed:', err.message);
if (fs.existsSync(tempConfig)) fs.unlinkSync(tempConfig);
process.exit(1);
}
function expandDependents(allFiles, names, registry, reason) {
for (const filePath of allFiles) {
if (registry.has(filePath)) continue;
const source = fs.readFileSync(filePath, 'utf8');
const matched = names.find(name => source.includes(name));
if (matched) {
console.log(` -> Including ${filePath} (${reason}: '${matched}')`);
registry.add(filePath);
}
}
}</code></pre>
<p><strong>Known limitations worth being honest about:</strong> String scanning produces false positives in loosely structured projects — a rendering import looks identical to a schema embed reference. The property group regex is fragile if your config format differs. Key renames inside a still-present file are invisible to this script entirely. These aren't edge cases to dismiss — they're reasons to test this against your actual project before leaning on it.</p>
<hr />
<h2>Forward Looking: Maturing to a Shared Package</h2>
<p>For larger enterprise projects or teams handling multiple concurrent front-end applications, a final maturity step is to <strong>extract the content model layer into its own npm package</strong> (such as <strong>@yourorg/content-model</strong>).</p>
<p>This moves your schema definitions into their own independent repository with strict versioning and ownership:</p>
<ul class="tight">
<li>
<p><strong>Strict Review Gates:</strong> The package can have its own <strong>package.json</strong>, its own CI validation, and its own <strong>CODEOWNERS</strong> file — meaning no developer can alter a contract or change a schema key without explicit approval from a content architect.</p>
</li>
<li>
<p><strong>Semantic Versioning:</strong> Schema changes are published as versioned releases. A breaking key rename is mapped to a Major version bump, acting as a clear, standard signal to every consuming front-end application.</p>
</li>
<li>
<p><strong>Isolate the Pipeline:</strong> The CI/CD push logic lives with the package that defines the models. The client applications simply consume the published TypeScript interfaces.</p>
</li>
</ul>
<p>While a separate package adds publishing overhead that might be overkill for smaller single-team projects, it represents the logical north star for teams managing Optimizely CMS SaaS at true scale.</p>
<hr />
<h2>Design-Time Guidelines</h2>
<p>The structure and script address what happens. These habits reduce how many cases happen in the first place.</p>
<ul class="tight">
<li>
<p><strong>Treat contracts like a public API.</strong> Get their shape right before multiple types implement them. Every field you add later drags every implementer into the same push. Small, focused contracts are cheaper to change than broad ones.</p>
</li>
<li>
<p><strong>Freeze keys once a type lands on any shared instance.</strong> Key rename = delete + create. Change <strong>displayName</strong> freely — it's cosmetic. Treat <strong>key</strong> as permanent from day one.</p>
</li>
<li>
<p><strong>Prefer additive changes.</strong> Adding a property is safe and localised. Deprecate and add rather than rename or delete.</p>
</li>
<li>
<p><strong>Separate your content-model layer from your app code and templates.</strong> The folder structure is what makes any detection approach tractable.</p>
</li>
<li>
<p><strong>Push in dependency order on fresh environments.</strong> Property groups first, then contracts, then types that implement them.</p>
</li>
<li>
<p><strong>Route true breaking changes through a full push.</strong> Key renames, deletions, dropping a contract — these are coordination events. Merge, let CI/CD do the authoritative full push, plan content migration separately.</p>
</li>
</ul>
<hr />
<h2>Summary</h2>
<table style="border-collapse: collapse; border-width: 1px; border-style: solid; width: 100%;">
<tbody>
<tr>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top; background-color: rgb(206, 212, 217);">
<p><strong>What changed</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top; background-color: rgb(206, 212, 217);">
<p><strong>Dependency created</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top; background-color: rgb(206, 212, 217);">
<p><strong>Direction to explore</strong></p>
</td>
</tr>
<tr>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Field added to a <strong>contract</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>All implementing types (transitive)</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Scan by contract folder + name — reliability varies</p>
</td>
</tr>
<tr>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p><strong>Property group</strong> key changed</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>All types using that group key</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Diff config + scan, or manual review at PR time</p>
</td>
</tr>
<tr>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p><strong>Component</strong> schema changed</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>All types embedding it as a typed property</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Scan by component folder + name</p>
</td>
</tr>
<tr>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Type added to <strong>allowedTypes</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>None — stays in your diff</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>No extra action needed</p>
</td>
</tr>
<tr>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Referenced type key <strong>renamed or deleted</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>All types naming it anywhere</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Git-blob compare to detect + coordinated full push</p>
</td>
</tr>
</tbody>
</table>
<p> </p>
<table style="border-collapse: collapse; border-width: 1px; border-style: solid; width: 100%;">
<tbody>
<tr style="height: 47.6px;">
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top; height: 47.6px; background-color: rgb(206, 212, 217);">
<p><strong>Environment</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top; height: 47.6px; background-color: rgb(206, 212, 217);">
<p><strong>Templates</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top; height: 47.6px; background-color: rgb(206, 212, 217);">
<p><strong>Content types + contracts</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top; height: 47.6px; background-color: rgb(206, 212, 217);">
<p><strong>Key renames</strong></p>
</td>
</tr>
<tr style="height: 47.6px;">
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top; height: 47.6px;">
<p><strong>Developer instances</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top; height: 47.6px;">
<p>Full push of template config</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top; height: 47.6px;">
<p>Propose-review-push (adapted to your project)</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top; height: 47.6px;">
<p>Never selective</p>
</td>
</tr>
<tr style="height: 47.6px;">
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top; height: 47.6px;">
<p><strong>Shared QA / Staging</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top; height: 47.6px;">
<p>Full push on merge</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top; height: 47.6px;">
<p>Full push on merge</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top; height: 47.6px;">
<p>Full push after team coordination</p>
</td>
</tr>
<tr style="height: 67.2px;">
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top; height: 67.2px;">
<p><strong>Production</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top; height: 67.2px;">
<p>CI/CD on release</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top; height: 67.2px;">
<p>CI/CD on release</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top; height: 67.2px;">
<p>Coordinated release + content migration</p>
</td>
</tr>
</tbody>
</table>
<hr />
<h2>The Point</h2>
<p>Part 1 gave you selective push — it works, and it's still the right approach for the vast majority of day-to-day content type changes.</p>
<p>This part maps the cases where it gets more complex: when a single-file change reaches further than the diff suggests. The five cases are real — the CMS validates them this way and you will hit them. The folder structure and propose-review-push workflow are directions we think are worth exploring, not a proven system.</p>
<p>We're publishing this partly because the answer isn't fully settled. If you've solved any of these more cleanly — or found that some of this doesn't hold up in practice — that's exactly the kind of feedback this series is for.</p>
<p>Know the cases. Structure the repo. Let the workflow propose, and you review.</p>
<hr />
<p><em>Have you hit any of these dependency cases on a project? Particularly curious whether the folder-structure approach holds up in practice, and whether anyone has a cleaner answer for the key-rename detection. Comments open below.</em></p>2026-07-25T12:23:05.0000000ZBlog postFrom AI Agents to AI Workflow with Opal<h2 class="article-editor-heading article-editor-content__has-focus">Introduction</h2>
<p class="article-editor-paragraph">In the <a class="article-editor-link article-editor-link" href="/link/b31bb7d003754244a5a025412aca0edd.aspx">first article in this series</a>, we talked about AI agents in Optimizely Opal and walked through the process of creating a specialised agent. In this article we will take the next step and build a workflow agent.</p>
<p class="article-editor-paragraph">As in the first article, we will go through a step–by–step process of creating a workflow agent using a practical example of creating a workflow that performs automated initial review of content draft for brand and tone of voice alignment.</p>
<h2 class="article-editor-heading">Standalone agent vs workflow agent</h2>
<p class="article-editor-paragraph">Before we dive into building a workflow agent, let’s first look at how it differs from a Standalone Agent. “Standalone agent” is not an official term used in Optimizely documentation, but in this article, we will use it to refer to either an existing agent from the Optimizely Agent Directory or a specialised agent you build yourself.</p>
<p class="article-editor-paragraph">A standalone agent already uses context (prompt template, variables, attached files, instructions and the conversation it is in). It can already take actions on its own using tools. What it cannot do is start on its own, coordinate other agents, or run the same workflow on a schedule or every time an event happens. That is what a workflow agent adds: it uses triggers, steps sequence, conditions and loops to combine multiple standalone agents into a multi–step process.</p>
<p class="article-editor-paragraph">Can you just create a specialised agent with a prompt that will make it do the same multi-step process? In theory – yes, but in practice such a complex agent will be very difficult (if not impossible) and expensive (in terms of Opal credits and time spent) to test, debug and maintain. You can refer to the first article – it explains this in more detail.</p>
<p class="article-editor-paragraph">An important consideration to keep in mind: workflow agents typically operate with greater autonomy and less human involvement. A standalone agent is usually invoked by a person, who then reviews its output. A workflow agent, by contrast, often starts automatically and runs unattended, with human review taking place only after the workflow is complete. For this reason, workflow agents (and any standalone agents they use as part of the workflow) need stricter guardrails defining what they can do, what outputs they must produce, and how they should handle errors and edge cases.</p>
<h2 class="article-editor-heading">Building Blocks of a Workflow Agent</h2>
<p class="article-editor-paragraph">A workflow agent consists of 3 building blocks: a trigger that decides when it starts, a series of agents that each perform one step, and the logic that determines how those steps are sequenced.</p>
<p class="article-editor-paragraph is-empty"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQFAGVo8yhATAQ/article-inline_image-shrink_1000_1488/B56Z.KYG2mH4AI-/0/1784733003415?e=1786579200&v=beta&t=hCqpg6pXSyvFyieIdqE7wDKGi6OHElqbitKq8XYHZsM" /></p>
<h3 class="article-editor-heading">Trigger</h3>
<p class="article-editor-paragraph"><a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/39865892823693-Workflow-agent-triggers">Trigger</a> is what starts the workflow agent. It can be one of the following:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Chat</strong> – agent is called from a chat, just like a standalone agent.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Scheduler</strong> – agent is executed on a schedule (every hour, every day at 9AM, etc.).</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Webhook</strong> – Opal listens for an incoming webhook and starts the workflow when an external. system sends an event.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Email</strong> – agent is called when email is sent to the email address that you set as the Trigger Recipient. You can configure additional conditions for sender and subject to avoid accidental email or spam to result in workflow execution</p>
</li>
</ul>
<h3 class="article-editor-heading">Logic</h3>
<p class="article-editor-paragraph">Workflow agent logic is defined using conditions and loops.</p>
<p class="article-editor-paragraph"><a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/43620929090829-Workflow-agent-conditions#h_01KHS15TF8A8X5ZW0N9HKT1GYE">Conditions</a> allow the workflow to follow different paths based on defined criteria. This is your typical “if-then-else” condition that can have multiple “then” parts. Below is an example of having different processing steps for blog article, email or social post.</p>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="/link/cb0c40f167984ffd99605a2f8abe0263.aspx" /></p>
<p class="article-editor-paragraph"> </p>
<p class="article-editor-paragraph">Consider the following best practices when using conditions in workflow:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Use clear criteria and structured data</strong> – base conditions on specific, predictable values. Prefer numeric or pre-defined values such as High, Medium or Low over free-form text.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Keep conditions simple</strong> – split complex logic into smaller decisions.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Avoid overlapping or duplicate rules </strong>– make it clear which path takes priority.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Cover every outcome </strong>– include both matching and fallback paths.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Test edge cases </strong>– check missing, unexpected and boundary values.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Add a safe fallback </strong>– route uncertain cases for human review or end the workflow safely.</p>
</li>
</ul>
<p class="article-editor-paragraph"><a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/43590976293389-Workflow-agent-loops">Loop</a> is handy when you need to perform same step (or set of steps) over multiple items. Below is an example of using loop to do AEO/GEO analysis and provide summary and improvement recommendations for all child pages of a specified page.</p>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQGrafRs4viSMQ/article-inline_image-shrink_1000_1488/B56Z.KYwDcJoAM-/0/1784733172179?e=1786579200&v=beta&t=dt_NwalvU39iQTgUKbkqBTq0zdJH-pOxJKSNXjyCjks" /></p>
<p class="article-editor-paragraph">Some best practices when using loops:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Keep the loop focused</strong> – include only the steps required for each item inside the loop, all other steps should be outside of the loop.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Handle individual failures</strong> – define what should happen when one or more items in the loop cannot be processed.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Test with different list sizes</strong> – plan/check for empty lists, single-item lists and larger collections.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Limit the number of iterations</strong> – large lists can increase workflow execution time and credits consumption.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Avoid excessive nesting</strong> – Optimizely supports up to three nested loops, but simpler workflows are easier to maintain so avoid nested loops unless it’s really necessary.</p>
</li>
</ul>
<h3 class="article-editor-heading">Agents</h3>
<p class="article-editor-paragraph">Each step in the workflow is executed by an agent – it can be out-of-the-box agent from Optimizely Agent Directory or a specialised agent you or someone else from your team created.</p>
<h2 class="article-editor-heading">Creating Workflow Agent</h2>
<p class="article-editor-paragraph">Let’s now create a workflow agent that performs an automated initial review of a content draft for brand and tone-of-voice alignment.</p>
<p class="article-editor-paragraph">In this example we will use combination of Optimizely CMP + Opal. There is a reason this is a very powerful combination – CMP provides the structure, governance and visibility to the process, while Opal adds the creativity, reasoning and judgement needed to accelerate complex tasks that cannot be done by conventional tools, such as creating content briefs and drafts, reviewing and proofreading content.</p>
<p class="article-editor-paragraph">Here is the scenario we will build. A content team is working on content production. Every content production task follows a set of steps, and one of these steps is <strong>Brand review</strong>. Today, a copywriter picks up this step, opens the content, opens the brand guidelines, and checks one against the other. It is necessary work, but most of it is mechanical.</p>
<p class="article-editor-paragraph">With the workflow we will build, when a task reaches the Brand review step, Opal picks it up automatically. It reads the content, fetches the latest brand and tone of voice guidelines, reviews the content against them, and leaves a comment on the task listing any issues it found and suggesting improvements. The task is then assigned to the copywriter, who now starts from a prepared initial review instead of a blank page.</p>
<p class="article-editor-paragraph">Looks simple but even such a simple workflow can save lots of time for a team that has to produce lots of content and is short on resources. Or imagine a situation where a new version of brand guidelines is released and someone needs to re-check 20 most recent articles against updated guidelines. How long would that take if done manually from scratch? As a copywriter, is this a kind of task you’d be excited to work on? As a team manager, is this where you’d want to spend your copywriters’ time?</p>
<h3 class="article-editor-heading">Planning the Workflow</h3>
<p class="article-editor-paragraph">Before jumping into building the agent, it’s first important to understand and plan what exactly you want to the workflow to do, how do you want it to do it.</p>
<p class="article-editor-paragraph">A simple way to do this is to write down workflow steps or (if you’re a visual person) draw it as a sequence diagram. Then look at the workflow and ask yourself these questions:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Is it only covering the happy path, what could go unexpectedly and how should we handle it.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Do you have human review steps at the right place? It’s tempting to have a workflow where AI does just everything and human only reviews the final result but in a complex multi-step workflow you will likely need few human review checkpoints.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">If workflow has a loop in it – is there a risk of it becoming an endless loop or having too many iterations, do you want to put a limit on number of iterations to avoid it from consuming too many credits?</p>
</li>
</ul>
<p class="article-editor-paragraph">Here are the high-level steps in our example workflow:</p>
<ol class="article-editor-ordered-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Content creation task reaches the AI Assisted Brand review step.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Opal gets the task details and extracts the content to be reviewed.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Opal fetches the latest brand and tone of voice guidelines.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">For each content item in the task, Opal identifies the content type, reviews it against the relevant guidelines, and leaves a comment on the task with identified issues and suggested improvements.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Opal moves the task to the next step, Final Brand Review and Approval.</p>
</li>
</ol>
<p class="article-editor-paragraph">Next, we look at these initial steps and ask the questions:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph">What should happen if we cannot get the task details on step 2?</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">What if task status is Completed instead of instead of In Progress – do we still do the review or skip it?</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">What if we get an error fetching latest brand guidelines?</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">On step 4, what content type should be reviewed and what content type should be skipped?</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Do we want to have a limit of content types to review within 1 task?</p>
</li>
</ul>
<p class="article-editor-paragraph">Now we adjust our workflow with these considerations in mind:</p>
<ol class="article-editor-ordered-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Content creation task reaches the AI Assisted Brand review step.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Get task details. If there is an error when getting task details – notify support/ops team via email. If task status is Completed – skip processing and exit.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Get the latest brand and tone of voice guidelines. If there is an error getting them – skip processing, leave comment about this in the task and notify support/ops team via email</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Get content items with content type “article” or “social media post” from the task – these are the only ones we want to cover with the review. If there are no matching content items – skip processing, leave comment about this in the task. If there are more than 5 matching content items found – leave comment that only first 5 will be processed, the rest will be skipped</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Loop over found content items: Review content item against brand guidelines, leave comment in the task with findings and recommendations. Stop after reviewing 5 content items.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Move the task to the next step – Final Brand Review and Approval.</p>
</li>
</ol>
<h3 class="article-editor-heading">Configuring the Workflow</h3>
<h3 class="article-editor-heading">CMP Configuration</h3>
<p class="article-editor-paragraph">CMP will control the overall content production steps. We will not get into the details of CMP configuration in this article but if you’re starting with CMP, you can read about how to <a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/8186091022093-Manage-workflows">configure task workflows</a>.</p>
<h3 class="article-editor-heading">Workflow</h3>
<p class="article-editor-paragraph">Here is how our CMP Task Workflow looks like</p>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQHQ38iuMYP90Q/article-inline_image-shrink_1500_2232/B56Z.KaC6TJoAQ-/0/1784733511531?e=1786579200&v=beta&t=Xxqod8dnRdkMlW4aHhw29eyliyLY88thxtBkO30X7DI" /></p>
<p class="article-editor-paragraph">Note that AI Brand Review has the icon that indicates that it is an external step – this is required to trigger Opal workflow agent from this step.</p>
<p class="article-editor-paragraph">When converting this step to external step you will be required to select external system:</p>
<p class="article-editor-paragraph">We will later use this in Opal agent configuration to distinguish webhook for external step in “Content Production with AI-Assisted Brand Review” CMP workflow vs external step in another CMP workflow.</p>
<h3 class="article-editor-heading"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQFKzpGPJOtgNA/article-inline_image-shrink_1500_2232/B56Z.KaGknKcAQ-/0/1784733526572?e=1786579200&v=beta&t=J6mE4K_5A8cCCa9M79L-j91-VF5-_X08CUipZqoTxD0" /></h3>
<h3 class="article-editor-heading">Configuring webhook to trigger Opal workflow agent</h3>
<p class="article-editor-paragraph">We already have workflow with external step – now we need to create webhook in CMP to notify Opal when our external step “AI Brand Review” is started.</p>
<p class="article-editor-paragraph">This process is describe in details here: <a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/43289384478989-How-to-trigger-workflow-agents-with-Content-Marketing-Platform-webhooks">https://support.optimizely.com/hc/en-us/articles/43289384478989-How-to-trigger-workflow-agents-with-Content-Marketing-Platform-webhooks</a></p>
<p class="article-editor-paragraph">We will only select 1 event for our webhook: <strong>external_sub_step_started</strong></p>
<p class="article-editor-paragraph">Note that when creating webhook you will need to provide callback URL and secret – you get those when you create trigger in Opal – once you get them copy them to webhook settings.</p>
<h3 class="article-editor-heading">Opal Configuration</h3>
<p class="article-editor-paragraph">Here is how our workflow will look like when we’re done</p>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="/link/d7e550844e6e4483a0aeb8ff530e086e.aspx" width="1267" height="693" /></p>
<p class="article-editor-paragraph">Let’s see how we create it step by step.</p>
<h3 class="article-editor-heading">Connect Opal to CMP instance</h3>
<p class="article-editor-paragraph">For Opal agents to be able to use existing CMP tools to get task details, it must be given access to this CMP instance by connecting to it.</p>
<p class="article-editor-paragraph">Note that this connection can only be added by Opal Administrator in your organisation: <a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/36359944449805-Get-started-with-Optimizely-Opal-for-administrators#h_01JTGSVJJ6VYDVXSYEK8MZTQWX">https://support.optimizely.com/hc/en-us/articles/36359944449805-Get-started-with-Optimizely-Opal-for-administrators#h_01JTGSVJJ6VYDVXSYEK8MZTQWX</a></p>
<p class="article-editor-paragraph">As a user, you can check what Optimizely products and instances Opal is connected to by creating a workflow agent, adding a trigger step, clicking on the trigger step and see what products and instances are available in Product Instance drop-down.</p>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQEljT6VHAuhmg/article-inline_image-shrink_1500_2232/B56Z.Kanc7JoAQ-/0/1784733661280?e=1786579200&v=beta&t=C4uJBmOl5wc5HxohrbUycJDDkBrDdOXBTj4SfO2WteQ" /></p>
<h3 class="article-editor-heading">Add Trigger</h3>
<p class="article-editor-paragraph">Once you add a trigger by dragging it from the components section to working area, make sure to select the right product instance and configure auth header as described in the documentation:</p>
<p class="article-editor-paragraph"><a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/43289384478989-How-to-trigger-workflow-agents-with-Content-Marketing-Platform-webhooks">https://support.optimizely.com/hc/en-us/articles/43289384478989-How-to-trigger-workflow-agents-with-Content-Marketing-Platform-webhooks</a></p>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQEqTVINacL5Fg/article-inline_image-shrink_1500_2232/B56Z.KarpOKMAU-/0/1784733678399?e=1786579200&v=beta&t=Ev8Qto4m7v3RD3bRpIg5f-lVXOoXphwjLKOOvS9tLAM" /></p>
<p class="article-editor-paragraph">Copy webhook URL and secret and put them in webhook configuration on CMP side.</p>
<p class="article-editor-paragraph is-empty"> </p>
<h3 class="article-editor-heading">Add check for external system passed in webhook</h3>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQH1HuRYeQjiaA/article-inline_image-shrink_1500_2232/B56Z.KWnOVGQAQ-/0/1784732611703?e=1786579200&v=beta&t=G4z3BvhoHgxHG6vLDrM1bOMEh8E4Wg4UtW8-vyjzLq0" /></p>
<p class="article-editor-paragraph">This is similar to External Step Routing Agent described here: <a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/43289384478989-How-to-trigger-workflow-agents-with-Content-Marketing-Platform-webhooks">https://support.optimizely.com/hc/en-us/articles/43289384478989-How-to-trigger-workflow-agents-with-Content-Marketing-Platform-webhooks</a></p>
<p class="article-editor-paragraph">But instead of agent with external step name specified in prompt, we use an agent that gets value of external step + a condition that checks it. You can re-use this combination in other workflows initiated by a webhook trigger without having to create separate step routing agent with different external system name in prompt.</p>
<p class="article-editor-paragraph">We need to add this check because CMP will call the webhook any time an external sub step of a task is started. It could be an external step of a task in a completely different workflow unrelated to content production.</p>
<h3 class="article-editor-heading">Add agents to get task and step details and check if it’s ready for processing</h3>
<p class="article-editor-paragraph">Next, we need agents that will get task details and check if task is at the right step in the workflow (AI Brand Review).</p>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQGMeGKuGmFOrw/article-inline_image-shrink_1000_1488/B56Z.KbhxNHUAM-/0/1784733900139?e=1786579200&v=beta&t=bgemiz65ENgvYWlT_D7e9GEaz1z1fuVaBWYujVGVkRY" width="815" height="469" /></p>
<p class="article-editor-paragraph">All this could be done with 1 specialised agent, but as we covered before, smaller agents are easier to create and maintain.</p>
<p class="article-editor-paragraph">We already covered details on creating specialised agents in the previous article, so here we’ll focus on what each of these agents will do rather than how they are built.</p>
<p class="article-editor-paragraph"><strong>Get CMP Task Details from Webhook </strong>agent does exactly what the name suggests</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Gets CMP task ID from webhook</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Uses <strong>get_cmp_resource</strong> tool to get task details</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Returns task details</p>
</li>
</ul>
<p class="article-editor-paragraph">You can re-use agent in any other workflow that is initiated by a webhook from CMP Task.</p>
<p class="article-editor-paragraph"><strong> Verify CMP Task and Step </strong>agent gets task details from the previous agent, check the status of the task (should be <strong>In Progress</strong>), and the current step of the task (should be AI Brand Review). If task has the right status and is at the right step – it will return <strong>READY_TO_PROCEED</strong>.</p>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQGgl0LzgLwbxw/article-inline_image-shrink_1000_1488/B56Z.KbrIwG8AI-/0/1784733938544?e=1786579200&v=beta&t=yVsJ8MJg3CRJ7st2edSfPvmJzWIuGE7_FgdWEl01kiM" width="629" height="362" /></p>
<p class="article-editor-paragraph">We then have a condition step that moves workflow to next step (Brand Guardrails retrieval) or stops processing if the CMP task has wrong status or is not at “AI Brand Review” step.</p>
<p class="article-editor-paragraph">We also added a condition to notify Ops team in case Opal fails to get task details from CMP. This is an optional condition and we’re using it as example of how you can make the workflow more robust.</p>
<p class="article-editor-paragraph"> </p>
<h3 class="article-editor-heading">Add agent to get latest brand and tone of voice guidelines</h3>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQFn528yInFL1g/article-inline_image-shrink_1500_2232/B56Z.KbvejGQAU-/0/1784733956347?e=1786579200&v=beta&t=LgddnHyWZI5LG5RzDcu4tIFwit5JydWnt831Th0l39Y" width="617" height="478" /></p>
<p class="article-editor-paragraph">This agent gets the latest version of brand and tone of voice guidelines. Depending on how and where you store these guidelines, it can use tools like browse_web or read_file or a custom tool (if you keep brand guidelines in a system that must be access in a specific way).</p>
<p class="article-editor-paragraph">This agent should also return the status of guidelines retrieval. In this example we return <strong>BRAND_GUIDELINES_READY</strong> if all went well.</p>
<p class="article-editor-paragraph">Here we also have a contingency step to notify Ops team if brand retrieval was not successful.</p>
<h3 class="article-editor-heading">Add agent to get content items from the task</h3>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQGPPfxb9RPhAQ/article-inline_image-shrink_400_744/B56Z.Kb3vRG4AQ-/0/1784733990158?e=1786579200&v=beta&t=jFrVd66DRu1KoFyJClSPFD-Soc1OZ7Gr_ZC9UXs1lxE" /></p>
<p class="article-editor-paragraph">Now that we have the brand guidelines, we need to get content items from the task. This agent goes over list of content items created in the task and filters one with the appropriate type (article, social post, etc). It can get list of content items in task from “Get CMP task details” agent or use tool <strong>get_cmp_resource</strong> to get this information. We can also instruct this agent to:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph">leave comment in the task if there are no content items found in the task and there is nothing to review;</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">only choose first 5 content items from the task if it has too many (to avoid workflow taking forever and consuming too many credits) and leave comment about this in the task.</p>
</li>
</ul>
<p class="article-editor-paragraph"> </p>
<h3 class="article-editor-heading">Use loop to call Brand Review Agent for each content item</h3>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQG6a48UEsVXgQ/article-inline_image-shrink_400_744/B56Z.Kb._XGgAM-/0/1784734019933?e=1786579200&v=beta&t=IQOS6DiuDgUwMsCDM2LQCW3EWa2NahECSkWgfiFSZ10" /></p>
<p class="article-editor-paragraph">Since a task can have multiple content items in it, we use loop to iterate over these content items and call Brand Review Agent for each of them.</p>
<p class="article-editor-paragraph">Brand Review Agent already has access to brand guidelines (passed from “Retrieve Latest Brand Guidelines” agent), uses tool <strong>cmp_retrieve_asset_from_library </strong>to get asset contents, and uses tool <strong>add_comment_on_task_substep </strong>to leave comment with review details.</p>
<h3 class="article-editor-heading">Mark step in task as Completed</h3>
<p class="article-editor-paragraph">To make CMP workflow progress to the next step, we have an agent that uses tool <strong>update_task_substep </strong>to complete the current step (AI Brand Review).</p>
<h3 class="article-editor-heading">Testing and Troubleshooting the Workflow</h3>
<p class="article-editor-paragraph">Just as specialised agents, workflow agents in Opal keep execution log that show details of each step in the workflow, including input, output and processing status.</p>
<figure class="article-editor-figure-image">
<div class="article-editor-inline-image__container article-editor-inline-image__container--resize">
<div class="article-editor-content__element-overlay">
<div class="article-editor-inline-image__buttons">
<div class="resize-image-control-button-tooltip resize-image-control-button-tooltip--hidden">Maximize image</div>
<div class="resize-image-control-button-tooltip resize-image-control-button-tooltip--hidden">Edit image</div>
<div class="resize-image-control-button-tooltip resize-image-control-button-tooltip--hidden">Delete image</div>
</div>
</div>
<img class="article-editor-inline-image__image" src="https://media.licdn.com/dms/image/v2/D5612AQEo6FmSPoucnw/article-inline_image-shrink_1000_1488/B56Z.KcJ_SKAAI-/0/1784734064904?e=1786579200&v=beta&t=jKUmmqtJitOsWqLG2jnV62CqgBRZKqf1og14CvxjxvE" alt="" /></div>
<figcaption class="is-empty"></figcaption>
</figure>
<p class="article-editor-paragraph">To see details of an execution – click on the flow icon</p>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="/link/ff060a4fea194b54a3a6fce1d2812278.aspx" width="1725" height="262" /></p>
<p class="article-editor-paragraph">And from there you can click on each step in the workflow to see its input, output and execution memory.</p>
<p class="article-editor-paragraph">I recommend that you do this testing early in the process and repeat every time you add a new step to the workflow, especially if you are creating a workflow for the first time. Otherwise, it will be difficult to find where it went wrong when you need to troubleshoot across 5-10 steps.</p>
<p class="article-editor-paragraph">As a starting point – make sure CMP trigger actually works:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Create CMP task based on the workflow that includes external step that will trigger the webhook</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Make sure you saved you workflow agent and it’s in Active status</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Move task to the step that triggers the Opal workflow and make sure step is in In Progress state</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Go to Opal agent > View logs – you should see agent execution in the log</p>
</li>
</ul>
<p class="article-editor-paragraph"> </p>
<h3 class="article-editor-heading">Lessons learned</h3>
<p class="article-editor-paragraph">A few principles I would carry into building any workflow like this:</p>
<p class="article-editor-paragraph"><strong>Start small. </strong>One trigger, one review, one comment. A first version that also fixes the content, reassigns the task, and updates three external systems in the process is harder to test and debug. Get one path working end to end before you add the next.</p>
<p class="article-editor-paragraph"><strong>Use a clear trigger. </strong>It should be clear what starts the workflow. If you find yourself adding too many conditions right after the trigger, the trigger is probably too broad.</p>
<p class="article-editor-paragraph"><strong>Keep each agent focused.</strong> The same rule as in the first article applies: an agent should do one thing well. This matters even more inside a workflow than in chat, because agents in a workflow run unattended in a single pass - there is nobody there to answer a clarifying question, so the prompt has to carry everything the agent needs.</p>
<p class="article-editor-paragraph"><strong>Keep a human approval step. </strong>No matter how good the results may look, leave the final step assigned to a person. The workflow's job is to make that person faster, not to replace their decision.</p>
<p class="article-editor-paragraph"><strong>Do not automate irreversible actions early.</strong> Leaving a comment is easy to ignore if it is wrong. Un-publishing content or rejecting a task is not as easy. Keep the workflow on the safe side of that line until you trust it.</p>
<p class="article-editor-paragraph"><strong>Measure the result.</strong> The point of this workflow is less manual effort and better review coverage. Check whether that is actually happening by looking at the measurements available in agent execution log, CMP reports on tasks throughput and most importantly, by talking to people who use the workflow.</p>
<h2 class="article-editor-heading">Wrapping up</h2>
<p class="article-editor-paragraph">In the first article, we built a specialised agent that focuses on one task. In this one, we connected several agents to create to a real content process: a trigger from CMP, context gathered at run time, a loop over content items, an action written back into the task, and a human making the final call.</p>
<p class="article-editor-paragraph">Standalone agents are already valuable, but workflows are where the efficiency gains can multiply. When applied to the right process and designed well, workflows can run consistently whenever they are needed, without relying on someone to initiate each step. As this example shows, that does not mean removing the human from the process. The goal is to reduce the time spent on repetitive, time-consuming tasks so people can focus on review, judgement and final decisions. AI simply expands the range of work that can be treated as routine and automated.</p>2026-07-23T14:48:00.0000000ZBlog postBuilding Your First Optimizely Opal AI Agent: a Hands-On Walkthrough<h2 class="article-editor-heading article-editor-content__has-focus">Introduction</h2>
<p class="article-editor-paragraph">There's a common assumption that building an AI agent is something only engineers or developers can do. It isn't. At the Optimizely ANZ Ai-ccelerate Opal Workshop in Melbourne this May, a room full of marketeers built their own working Opal agents in a single 2-hour session. For some of them it was the first time they’ve seen Optimizely Opal.</p>
<p class="article-editor-paragraph">A specialised agent in Optimizely Opal is, at its core, a set of written instructions and a few settings – there’s no code writing required. The main skill is being able to describe a task clearly: if you can write a clear brief for a colleague, you have most of what you need. Of course, understanding the subject matter is also very important. The rest is understanding few key concepts and some best practices – this is what this article covers.</p>
<p class="article-editor-paragraph">This article is for anyone who has started using Opal and wants to understand how specialised agents are built. You don't need to be technical, and you don't need a developer's background. It's written with marketing managers, content managers, and CRO specialists in mind, but it's just as useful if you're still getting familiar with Opal and want a clear picture of what's going on under the hood before you build anything yourself.</p>
<p class="article-editor-paragraph">To keep it practical, we will use example of building <strong>Answer Readiness Reviewer</strong> agent: you give it a page URL and a question, and it tells you whether an AI assistant (ChatGPT, Claude, Perplexity, and the like) could actually pull the answer to that question off that page. It reads the content, decides whether the answer is explicit, buried, fragmented, or missing, and then suggests what to change so the page is more likely to be the one an AI quotes. Deciding whether a page actually answers a question well enough for an AI assistant to use it is a judgement call, not a straightforward check that can be done by a script, and that's exactly the kind of work an agent is good at. We'll use it as our running example so that every concept has something solid attached to it.</p>
<h2 class="article-editor-heading">What an agent actually is</h2>
<p class="article-editor-paragraph">Let’s start with understanding key concepts used in Opal: <strong>agents</strong>, <strong>tools</strong>, and <strong>skills</strong>.</p>
<p class="article-editor-paragraph">An <strong>agent</strong> is the assistant that completes the task. It follows a set of written instructions to complete it, and it can call on tools to take action along the way. Opal describes agents as intelligent assistants that use natural language prompts and tools to complete tasks on your behalf, with each agent having a specific purpose – generating content, analysing data, or automating a step in a workflow.</p>
<p class="article-editor-paragraph">A <strong>tool</strong> is a single action the agent can take. Opal's own analogy is an attachment on a Swiss Army knife – each one does one specific thing. Examples of tools include searching the web, creating a campaign, generating an image, or fetching the HTML of a web page. The agent decides which tools it needs and calls them; you don't run them by hand. Our example agent will use a tool called browse_web_html. This tool fetches the raw contents of a web page. Agent will use it to read the actual page it's been asked to review, exactly as a browser would see it. Opal has an rich catalogue of tools available out of the box – you can find it here <a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/39340107628429-System-tools-overview">https://support.optimizely.com/hc/en-us/articles/39340107628429-System-tools-overview</a></p>
<p class="article-editor-paragraph">The relationship between the two is simple: the <strong>agent is the worker, the tools are its equipment</strong>. An agent with no tools can only think and write. An agent with the right tools can also do things – read a page, send an email, update a record. You give an agent access to a tool by naming it in the agent's instructions and adding it in the agent's Tools section.</p>
<p class="article-editor-paragraph"><strong>Skills</strong> (which Opal used to call "instructions") are the third piece. Skills are reusable context and guidelines that shape how Opal behaves, like your brand voice, your product descriptions, your target personas, or your formatting rules. The point of skills is that you write them once and reuse them everywhere, instead of repeating "here's our tone of voice" in every single agent. One thing worth knowing: a specialized agent does not automatically pull in your skills. If you want an agent to use one, you reference it explicitly in the agent's instructions. So skills are the shared knowledge your agents use if needed.</p>
<p class="article-editor-paragraph">Put together: an <strong>agent</strong> does a job by following its prompt, using shared <strong>skills</strong> for context, and calling <strong>tools</strong> to take actions.</p>
<h3 class="article-editor-heading">The three types of agents</h3>
<p class="article-editor-paragraph">Opal has three kinds of agents, and knowing the difference saves you from building something that already exists.</p>
<p class="article-editor-paragraph"><strong>Out-of-the-box agents</strong> (also called default agents) live in the <strong>Agent Directory</strong>. Optimizely builds and maintains these, and they're ready to run without any setup. They cover common jobs like reviewing content for tone and style, generating competitive insights, or drafting support responses. Each listing tells you what the agent does, which tools it includes, and what you can configure. If one of these already does what you need – try using it first. They're also worth checking out even when you plan to build your own, because they show you working examples of how an agent is structured. You can see list of available agents if you select Agents from the left frame menu in Opal and then select Agent Directory.</p>
<p class="article-editor-paragraph"><img src="/link/34a8a928b5fe47d7bb163326c549dd1f.aspx" /></p>
<p class="article-editor-paragraph">If you don’t yet have access to Opal, you can find agent directory here: <a class="article-editor-link article-editor-link" href="https://www.optimizely.com/agents/">https://www.optimizely.com/agents/</a></p>
<p class="article-editor-paragraph"><strong>Specialised agents</strong> are the custom agents you build. Specialised agents are the right choice when no default agent covers your task and you want precise control over the inputs, the output, and the behaviour.</p>
<p class="article-editor-paragraph"><strong>Workflow agents</strong> are the third type, and they're more advanced. A workflow agent chains several default and specialised agents together into a multi-step process, with the output of one feeding into the next. Think of it as assembling a small team where each member does their part and hands off to the next.</p>
<p class="article-editor-paragraph">This article focuses on building Specialised agents, we’ll cover Workflow agents in another article.</p>
<h3 class="article-editor-heading">Before you start: the prerequisites</h3>
<p class="article-editor-paragraph">A few things need to be in place before you can create a specialised agent.</p>
<p class="article-editor-paragraph"><strong>Opal license that supports creating specialised agents.</strong> If you're unsure what your Opal license covers, your Customer Success Manager can confirm.</p>
<p class="article-editor-paragraph"><strong>The right role assigned to your user.</strong> The roles that can create agents are <em>Agent Builder</em>, <em>Opal Administrator</em> or any custom role that's been given the "<em>Add, edit, and install specialized agents</em>" permission. If you can see the Agents page but the Add Agent button isn't there, you most likely have Opal User role that lets you use Opal but does not allow to create or edit agents.</p>
<p class="article-editor-paragraph"><img src="/link/f15f4e13f7eb4e479f7bc75a2a23252d.aspx" /></p>
<h3 class="article-editor-heading">Best practices: keep each agent small</h3>
<p class="article-editor-paragraph">Before proceed with agent configuration, you need to plan what you want this agent to do and what part of the overall workflow it will handle. There is an important best practice worth remembering when doing the planning: give each agent one job, keep agents simple.</p>
<p class="article-editor-paragraph">You may be tempted to build one big agent that does everything – fetches the pages, analyses them, rewrites the content, and emails a report. Avoid doing this. Big agents are hard to maintain. They are slower and more expensive to test, because each run does more work and consumes more Opal credits. They are harder to troubleshoot, because when the result is wrong, it's not always obvious which part failed. And they are harder to improve, because any change you make carries a higher risk of breaking something that was working.</p>
<p class="article-editor-paragraph">Better approach is to break a process into individual steps and for each step decide who will handle it – a person, an external system, an existing tool, out-of-the-box Opal agent or a specialised Opal agent. Our example is a good illustration. The broad goal is "make our content perform well with AI assistants," which is a big task. But the Answer Readiness Reviewer doesn't try to own all of it. It does exactly one thing: given one page and one question, decide whether an AI could extract the answer, and suggest what would make it better. It doesn't crawl your whole site, it doesn't pick which questions matter, and it doesn't rewrite the page for you. Such agent is easy to describe, easy to test, and easy to reuse – including as one step inside a bigger workflow later.</p>
<p class="article-editor-paragraph">If this principle sounds familiar, it's because it isn't new. This is one of the things I liked about Linux when I started learning it: the idea that each program should do one thing well, and that you chain small programs together to do complex work.</p>
<p class="article-editor-paragraph">A few related habits that come from the same principle:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Define the job in 1-2 sentences before you build.</strong> If you can't, the scope could be too big and you may need to break it down further. Our example's sentence: "Given a page and a question, judge whether an AI could extract the answer, and suggest how to improve the page's chances of being cited."</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Be clear about the output.</strong> Decide upfront what the agent should return as result – plain text, a table, a file, or structured data like JSON (to pass to another agent or tool) and how that output will be used. Our example returns a short text summary a person can act on: a rating, the evidence behind it, and a list of suggested fixes.</p>
</li>
</ul>
<p class="article-editor-paragraph">Know which tools it will need. List only the tools required for that one job. Our example needs to read one web page, so it gets one tool: browse_web_html.</p>
<h2 class="article-editor-heading">Getting started</h2>
<p class="article-editor-paragraph">You can build a specialised agent completely from scratch. But there's usually a faster path, especially if you are new to this: find the existing agent that's closest to what you want and use it as a starting point. A close-enough agent already has a sensible structure – a prompt laid out in steps, the right kind of tools selected, an output format chosen. You can keep this structure and change the details, instead of trying to think of everything from scratch. The default agents in the Agent Directory are good candidates for this, and so is any agent your team has already built.</p>
<p class="article-editor-paragraph">In our example, we will use FAQ Creation agent as starting point.</p>
<p class="article-editor-paragraph">Use Duplicate Agent from the context menu to create a copy of an existing agent.</p>
<h3 class="article-editor-heading"><img src="/link/332e08be77b341c7ae715873dfa45673.aspx" /></h3>
<h3 class="article-editor-heading">Agent Configuration</h3>
<p class="article-editor-paragraph">Now that we've started creating the agent, let's look at what it's made up of.</p>
<h3 class="article-editor-heading">Name, Id, and Description</h3>
<p class="article-editor-paragraph"><strong><img src="/link/16bbe41dad80403d949075df0cb94106.aspx" width="1135" height="544" /></strong></p>
<p class="article-editor-paragraph"><strong>Name</strong> is for you and your team to understand what agent does and find it.</p>
<p class="article-editor-paragraph"><strong>Id</strong> is how the agent gets invoked — it's prefixed with @, so you'd call this one with something like <strong>@answer_readiness_reviewer</strong>. This Id must be unique, Opal checks that the Id is available and suggests alternatives if it's taken.</p>
<p class="article-editor-paragraph"><strong>Description</strong> explains what the agent does and when to use it. It's a required field. Treat it as documentation for the next person who has to maintain, troubleshoot, or reuse the agent - and this could be a future you who hasn't looked at it in six months :). A clear description also makes it easier to find the right agent when your library grows and someone needs to choose between several similar ones.</p>
<h3 class="article-editor-heading">Interaction mode</h3>
<p class="article-editor-paragraph"><strong><img src="/link/aa9afbc78ff34b0d8bf2d8f47b08fd9f.aspx" width="424" height="181" /></strong></p>
<p class="article-editor-paragraph"><strong>Support multi-turn conversation </strong>is off by default, which means the agent runs in single-shot mode: you provide the inputs, it runs once and returns a final result. There is no back-and-forth. This is the right choice for most specialised agents that handle tasks that are well-defined enough that a single run with clear inputs produces a usable output. It's also suitable for agents that are going to perform a step in a multi-step workflow. Multi-turn mode keeps the agent active in Opal Chat for continued conversation, which is better suited to tasks where you expect to refine the output through follow-up such as content draft you want to iterate on.</p>
<p class="article-editor-paragraph"><strong>Trigger from Chat</strong> controls whether people can invoke the agent directly in Opal Chat.</p>
<h3 class="article-editor-heading">Input</h3>
<p class="article-editor-paragraph"><strong>Variables.</strong> Variables are the inputs the agent collects before it runs, and they're what make an agent reusable instead of hard-coded. Each variable has a type, a name, a description, and a flag for whether it's required.</p>
<p class="article-editor-paragraph">In our example we have 2 variables – URL and Question and both are required.</p>
<p class="article-editor-paragraph is-empty"><img src="/link/ccb4b8e72cec43898f7848739ecb9edf.aspx" width="660" height="207" /></p>
<p class="article-editor-paragraph"><strong>Tools.</strong> This is where you give the agent its equipment. You can let Opal predict and add relevant tools automatically or add them manually by selecting from the tools available in your instance.</p>
<p class="article-editor-paragraph"><img src="/link/a9465742661c4650adb01ba608a46420.aspx" width="946" height="214" /></p>
<p class="article-editor-paragraph">In our example we only need one tool – <code>browse_web_html</code>. It will be used to fetch the page so agent can read page content.</p>
<p class="article-editor-paragraph"><strong>Inference level.</strong> This controls how hard Opal thinks before answering. Higher levels improve quality on complex, multi-step reasoning but take longer to run and cost more (in terms of Opal credits). You match the level to the task. In our example, I will set it to Complex, because deciding whether an answer is explicit, buried, fragmented, or missing is genuine reasoning as the agent has to understand the question, comprehend the page, and judge the relationship between them.</p>
<p class="article-editor-paragraph"><strong>Model Provider. </strong>As of June 2026, Opal allows selecting between Google Gemini or Antropic Claude as AI model provider for specialised agents. </p>
<p class="article-editor-paragraph"><strong>Files (optional).</strong> You can attach files the agent should reference every time it runs. This can be used when you have guidelines already documented in a file. Going to keep this empty for our example as all the instructions will be in the prompt.</p>
<h3 class="article-editor-heading">Writing the prompt</h3>
<p class="article-editor-paragraph">The prompt (Opal calls it the <strong>prompt template</strong>) is the agent's standing instructions, the brief it follows every single time it runs. This is where most of your effort goes, and what defines how good your agent will be.</p>
<p class="article-editor-paragraph">Optimizely guidance for prompts is very straightforward, and it matches how you'd brief a capable teammate:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Write in clear, direct language.</strong> Say what you want done, not what to "consider."</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Build a clear hierarchy.</strong> Use headers, bold text, and lists so the structure of the task is obvious.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Break the work into explicit steps.</strong> Number them. An agent following "Step 1, Step 2, Step 3" is better than unstructured wall of text.</p>
</li>
</ul>
<p class="article-editor-paragraph">A few additional prompt-writing techniques that are worth mentioning:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Reference variables and tools explicitly. In the prompt, variables are written in double square brackets like <code>[[PAGE_URL]]</code> and <code>[[QUESTION]]</code>, and tools are written in backticks like <code>browse_web_html</code>. This is how you wire the prompt to the inputs and equipment you configured in the other sections. <br />Spelling out when and how to use a tool rather than just making it available produces far more consistent results.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Define what to do when things go wrong.</strong> A robust prompt tells the agent how to handle not just the happy path, but also negative scenarios and edge cases. <br />In our example it could be some of these: a page that won't load (empty or returns an error), a page behind a login, content is presented as picture rather than text, a question that doesn't really relate to the page at all or a questions that is not a question but a statement.</p>
</li>
</ul>
<p class="article-editor-paragraph">If you want to get better at writing these prompts or just needs an inspiration, you can always check out prompts used in the out-of-the-box agents or check the recommendations here: <a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/39300056376717-Prompts-for-specialized-agents">https://support.optimizely.com/hc/en-us/articles/39300056376717-Prompts-for-specialized-agents</a></p>
<p class="article-editor-paragraph">And another tip - you can use Opal or your favourite LLM (ChatGPT, Claude) to generate prompt for your agent or improve existing prompt - they are all quite good at writing and can give ideas for some instruction points or directions you didn't think about. Just make sure to always review the result before you use it.</p>
<p class="article-editor-paragraph">Prompt for our example agent is too big to put here but you can find it at <a class="article-editor-link article-editor-link" href="https://gist.github.com/igor-safonov/696c1a07e93e8e4f3aa446cc63348f60">https://gist.github.com/igor-safonov/696c1a07e93e8e4f3aa446cc63348f60</a></p>
<h3 class="article-editor-heading">Output</h3>
<p class="article-editor-paragraph">You select an <strong>Output Data Type</strong> from a list and you can optionally add a brief <strong>Description</strong> of what the output is.</p>
<p class="article-editor-paragraph"><img src="/link/1afe59a09e7c46e88c62a669995a720e.aspx" width="697" height="232" /></p>
<p class="article-editor-paragraph">Two important things to keep in mind:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>The detailed shape of the output is defined in the prompt, not here.</strong> Whether the response uses a table, what columns it has, what the four ratings are - all of that lives in your prompt template. The Output section just tells Opal what kind of data the response is and (optionally) describes it at a high level.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>What the Description field is for.</strong> It's a short, plain-language summary of what the agent returns. It's most useful when the agent is later used as a step inside a workflow agent, because the next step in the workflow needs to know what shape of result it's getting. If the agent only ever runs on its own, the description is less critical, but it's still good documentation for your teammates.</p>
</li>
</ul>
<p class="article-editor-paragraph">The choice of data type usually comes down to who or what is going to consume the output. If the result will be passed to another agent or to an automated step in a workflow, <strong>JSON</strong> is the better choice - it's structured and machine-readable, and you can pin down the exact shape with an Output Schema. If the result is meant for a person to read and act on, <strong>Text</strong> is the right choice.</p>
<p class="article-editor-paragraph">In our example, the output is meant for a person, so we'll set:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Output Data Type</strong>: Text</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Description</strong>: "A markdown response containing the answer-readiness rating (Explicit, Buried, Fragmented, or Missing), evidence from the page that supports the rating, and a short list of concrete suggested improvements. Returns an error template instead if the question is invalid, the page can't be read, or the question is off-topic for the page."</p>
</li>
</ul>
<p class="article-editor-paragraph">One more practice worth mentioning, even though it isn't part of the Output section itself: <strong>preferred outputs</strong>. After you've run the agent a few times, you can mark a particularly good result as a <em>preferred output</em>. Opal can then use it as an example to guide future runs, which helps tune the agent toward the style and quality you want. This is done from the agent's execution logs after the fact, not configured upfront - so you'll come back to it once the agent is built and you've seen a few real results. More details available at <a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/43244850788109-Preferred-output-examples">https://support.optimizely.com/hc/en-us/articles/43244850788109-Preferred-output-examples</a></p>
<h3 class="article-editor-heading">Testing and improving the agent</h3>
<p class="article-editor-paragraph">Building the agent is the first draft, not the finished product. You will then need to do a few rounds of testing and adjustment until you’re happy with the result.</p>
<p class="article-editor-paragraph"><strong>Run a test.</strong> Save the agent and use <strong>Test Run</strong> to try it with real inputs. For our example, that means a real page URL and a real question – ideally start with cases where you already know the answer, so you can tell whether the agent got it right.</p>
<p class="article-editor-paragraph"><strong>Build yourself a small set of known cases to test every time you make some big changes to the agent.</strong> This way you can check if baseline still works well or recent change made things worse.</p>
<p class="article-editor-paragraph"><strong>Look at what the agent did, not just what it returned.</strong> Opal keeps execution logs that show the steps the agent took and the tools it called. If the result is not what you expected, the log can help you see where it went wrong.</p>
<p class="article-editor-paragraph"><strong>Adjust one thing at a time.</strong> When something's off, the fix is usually adjusting the prompt: a rule that wasn't explicit enough, a step that needed splitting, an edge case you didn't mention. Change one thing, test it again, compare.</p>
<p class="article-editor-paragraph">Do not forget the settings can play a part too – if adjusting prompt gets you nowhere, check if inference level as well as output instructions and examples.</p>
<p class="article-editor-paragraph"><strong>Save versions as you go.</strong> Opal keeps versions of specialised agents, so you can make changes confidently and go back to a previous version anytime.</p>
<p class="article-editor-paragraph"><img src="/link/36774809d97a4a4ab7845b26e5197665.aspx" width="855" height="366" /></p>
<p class="article-editor-paragraph">Or you can just test it by calling it from Opal chat. Let's give our example agent a try and see how it goes:</p>
<p class="article-editor-paragraph"><img src="/link/0503efff9b324830a57ab9a2583afce8.aspx" width="853" height="793" /></p>
<p class="article-editor-paragraph">Looks pretty good to me :)</p>
<p class="article-editor-paragraph">And if you're worried you'll consume too many Opal credits with your agent - there is a very simple way to check how many tokens each run consumes - from agent editor go to Logs tab and it's all there.</p>
<p class="article-editor-paragraph"><img src="/link/7a75638925da4c3aa379c04553d38074.aspx" width="1247" height="463" /></p>
<p class="article-editor-paragraph">As you see, the amount of credits consumed by our agent is very reasonable which is another reminder that small agents focused on one task are easier to maintain and more cost efficient that complex do-it-all agents.</p>
<h2 class="article-editor-heading">Conclusion</h2>
<p class="article-editor-paragraph">If there's one thing to take from this, it's that building an Opal agent is mostly clear thinking written down and knowing some best practices. You define a job, describe it in clear direct language with steps by step instructions, give the agent the inputs and the tools it needs, and then test and tune it until it's reliable. The Answer Readiness Reviewer we used as example is straightforward under the hood – two main inputs, one tool, a well-structured but simple prompt. And yet it does something quite useful and something that a generic script cannot do.</p>
<p class="article-editor-paragraph">For now, the best next step is a simple one: open Opal, find the agent closest to something you'd find useful, duplicate it, and start changing it. You learn this far faster by building than by reading.</p>2026-07-23T14:34:13.0000000ZBlog postAdvanced Task Manager Gets a Big Update<p>One of the things I keep coming back to with Optimizely's content approval workflow is that it's solid at the individual level - you know a piece of content needs approving, you click through, done. But the moment you're managing a site with dozens or hundreds of items in the queue, the interface starts to feel a bit like doing surgery with oven mitts.</p>
<p>This release is largely the result of that frustration. Each feature below started as something I (or someone using the tool) wanted to do that took too many clicks, too much scrolling, or just wasn't possible at all. Here's what changed, and why.</p>
<hr />
<h2>Advanced Filtering</h2>
<p>Before this update, the only way to narrow down the task list was by language. That's fine if your queue is short, but not if you're staring at 200 tasks and trying to find everything that's a block, or everything from a specific site, or that one page whose name you only half remember.</p>
<p>There's now a proper filter bar above the list with four independent dimensions:</p>
<ul>
<li><strong>Status</strong> - <em>In Review</em> (the default) or <em>Ready to Publish</em>, useful for finding things that are approved but haven't gone live yet.</li>
<li><strong>Type</strong> - narrow to Pages, Blocks, or Assets/Media only.</li>
<li><strong>Site</strong> - in multi-site setups, limits the list to one site. Hidden on single-site installs.</li>
<li><strong>Content search</strong> - type a content ID (integer) or part of the name to find a specific item.</li>
</ul>
<p>Every filter combination updates the URL, so you can bookmark a view or send a link to a colleague.</p>
<p style="background:#e8f0ff; border-left:3px solid #1a56e8; padding:12px 16px; border-radius:0 4px 4px 0;">Active filters show up as dismissible badge pills below the filter bar. Each badge removes just that one filter when clicked. A <strong>Clear all</strong> link removes everything at once.</p>
<hr />
<h2>Select All Across Pages</h2>
<p>The existing checkbox in the table header selects everything visible on the current page. Which is fine, until you realise there are 12 more pages of results and you need to approve the lot.</p>
<p>When you check that header checkbox and there are more results than the current page can show, a small banner appears:</p>
<p style="background:#e8f0ff; border-left:3px solid #1a56e8; padding:12px 16px; border-radius:0 4px 4px 0;"><em>All 30 items on this page are selected.</em> <strong>Select all 412 items matching current filters.</strong></p>
<p>Clicking that link fetches every matching approval ID across all pages and loads them into the current selection. The approval action then covers the complete set - one click, one comment, done. A <strong>Clear selection</strong> link sits in the same banner if you want to start over.</p>
<p>The "all items" fetch respects every active filter, so you're not accidentally bulk-approving things you didn't intend to include.</p>
<hr />
<h2>Scheduled Publishing</h2>
<p>Publishing right after approval is the common path, but it's not the only one. Launches, campaigns, news embargoes - there are plenty of reasons to approve content today and want it to go live at a specific future moment without someone having to remember to click Publish at 8 AM on a Tuesday.</p>
<p>When you check the <em>Publish selected content after approval</em> option in the approval modal, a second checkbox appears: <em>Schedule publishing for a specific date and time.</em> Enabling it reveals a date/time picker.</p>
<p>The chosen datetime is passed along with the approval request. Optimizely handles the rest by setting <code>IVersionable.StartPublish</code> to that value, so the standard CMS scheduled-publish mechanism kicks in with no custom job needed.</p>
<hr />
<h2>Approve Blocks & Media on a Page</h2>
<p>This is the one I'm most glad made it into this release. Here's the scenario: a page has gone through its approval sequence and is ready, but it references a dozen blocks and a handful of media files that are all sitting in their own approval queues. The page can't go live until those are cleared too. Hunting them down individually is tedious.</p>
<p>The <strong>Approve Page Dependencies</strong> button in the filter bar opens a modal where you can pick any page in the site and approve all of its pending block and media dependencies in one action.</p>
<p>Here's how it works:</p>
<ol>
<li>Click <strong>Approve Page Dependencies</strong> in the filter bar.</li>
<li>Navigate the <strong>page hierarchy tree</strong> to find the target page. The tree lazy-loads child pages as you expand nodes. In multi-site setups, each configured site appears as a top-level node.</li>
<li>If you know the content ID, type it directly into the number input above the tree instead. Picking from the tree clears the input; typing a number clears the tree selection.</li>
<li>Select one or more <strong>language branches</strong> to process.</li>
<li>Optionally add an approval comment and check <strong>Publish approved content</strong> to publish the dependencies immediately after approval.</li>
<li>Click <strong>Approve Dependencies</strong>. A spinner shows while the request runs.</li>
</ol>
<p>Behind the scenes the system reads every <code>ContentArea</code> and <code>ContentReference</code> property on the selected page, collects all referenced blocks and media, and approves any that currently have a pending approval step for the chosen languages. The number of items approved is shown inline, and if anything was approved the task list refreshes automatically after a short pause.</p>
<p style="background:#e8f0ff; border-left:3px solid #1a56e8; padding:12px 16px; border-radius:0 4px 4px 0;"><strong>Note:</strong> This only approves dependencies - blocks and media that the page references. It does not approve the page itself. That separation is intentional: the page's own approval workflow stays under normal editorial control.</p>
<hr />
<h2>Task Ordering</h2>
<p>The task list columns are now sortable. Click a column header to sort ascending, click again to sort descending. You can order by name, content type, task type, submission date, who started the review, or deadline (if you're using the deadline property).</p>
<p>It sounds small, but being able to sort by submission date newest-first, or by deadline to see what's most urgent, changes how you triage a long queue.</p>
<hr />
<h2>Site Column (Multi-site)</h2>
<p>If your Optimizely installation runs multiple sites, the task list now shows a <strong>Site</strong> column alongside each item so you can see at a glance where things belong. On a single-site installation the column stays hidden.</p>
<p>This pairs naturally with the Site filter: use the column to notice that most of your queue is from one site, then use the filter to focus on it.</p>
<hr />
<h2>A note on CMS versions</h2>
<p>All of the above is available in <strong>version 4.1.0</strong> on Optimizely CMS 13 / .NET 10, and as <strong>version 3.1.0</strong> on the CMS 12 branch for teams still on .NET 6. Change Approval support is CMS 12 only for now, since the <code>EPiServer.ChangeApproval</code> package doesn't yet have a CMS 13-compatible release.</p>
<p>To install or update:</p>
<pre style="background:#f1f5fb; border:1px solid #dce6f8; border-radius:6px; padding:14px 18px; overflow-x:auto; font-size:14px;"><code>dotnet add package AdvancedTaskManager</code></pre>
<p>Source, changelog, and issue tracker are on <a href="https://github.com/adnanzameer/optimizely-advancedtaskmanager">GitHub</a>. If any of these features behave unexpectedly in your setup, or there's something you'd like to see that isn't here yet, open an issue - the backlog is public and feature requests are genuinely read.</p>2026-07-21T14:43:20.0000000ZBlog postParallel Development in Optimizely CMS SaaS: A Smarter Way to Register Components<p><strong>📌 A note before you read:</strong> The approach described in this article is not a replacement for Optimizely’s recommended out-of-the-box component registration pattern — which is clean, explicit, and exactly right for most projects. This is written for teams of <strong>4 or more developers</strong> working on <strong>parallel feature branches</strong> who are finding that a shared registry file is becoming a source of repeated, low-value merge conflicts. If that’s not your situation yet, file this away for when it is.</p>
<hr />
<p>When Optimizely introduced code-first content modeling for CMS SaaS, they solved one of the biggest headaches in modern CMS development. Being able to define your content types in standard <strong>.tsx</strong> files and push them via the CLI is a massive developer experience win.</p>
<p>But modeling is only half the equation. On the frontend, you must map those content types to actual React components so the SDK can resolve and render them.</p>
<p>The standard approach uses a central registration file — typically in your Next.js layout or a dedicated registry file — where you manually import every single component and content type, registering them with <strong>initContentTypeRegistry</strong> and <strong>initReactComponentRegistry</strong>:</p>
<pre class="code-block"><code class="language-typescript">// The classic static registration (e.g., src/components/registry.ts)
import { initContentTypeRegistry } from '@optimizely/cms-sdk';
import { initReactComponentRegistry } from '@optimizely/cms-sdk/react/server';
import HeroBanner, { HeroBannerContentType } from './HeroBanner';
import ArticlePage, { ArticlePageContentType } from './ArticlePage';
import GridContainer, { GridContainerContentType } from './GridContainer';
export function registerComponents() {
initContentTypeRegistry([
HeroBannerContentType,
ArticlePageContentType,
GridContainerContentType,
]);
initReactComponentRegistry({
resolver: {
HeroBanner,
ArticlePage,
GridContainer,
},
});
}</code></pre>
<p>This explicit registration is an excellent default design. It's clean, type-safe, and self-documenting.</p>
<p>But as your engineering team grows from one developer to five, ten, or twenty working in parallel, this central registry file starts to feel a bit crowded.</p>
<p>Let's talk about the friction this creates — and how a small shift in thinking can clean up your git history forever.</p>
<hr />
<h2>The Tragedy of the Common Registry File</h2>
<p>Imagine a typical day on an enterprise development team.</p>
<ul class="tight">
<li>
<p><strong>Developer A</strong> is on a feature branch building a new <strong>PromoCard</strong> component.</p>
</li>
<li>
<p><strong>Developer B</strong> is on a separate branch creating an <strong>AuthorBio</strong> content type.</p>
</li>
<li>
<p><strong>Developer C</strong> is refactoring the <strong>NavigationMenu</strong>.</p>
</li>
</ul>
<p>Each developer creates their standalone component file. But to make it work in their respective sandbox environments, they <em>all</em> have to touch the exact same central file — <strong>src/components/registry.ts</strong> — to import and register their work.</p>
<p>Everything works beautifully in isolation. The local tests pass, and the PRs are opened.</p>
<p>But when the time comes to merge these branches back into <strong>main</strong>, Git grinds to a halt. There's a merge conflict in <strong>registry.ts</strong>. Because everyone modified the exact same import list on the exact same lines, the automated merge fails.</p>
<p>Dealing with merge conflicts on actual code logic is a normal part of engineering. Dealing with merge conflicts on a <em>list of import statements</em> is just tax. It slows down your CI/CD pipelines, frustrates developers, and adds zero business value.</p>
<hr />
<h2>The Mind Shift: Static Imports vs. Runtime Discovery</h2>
<p>The default behavior of manually importing components in a static file is excellent for small projects or stable schemas. It provides absolute certainty about what is being loaded — Optimizely's design here is intentional and solid.</p>
<p>But as you scale parallel development, the question changes: <em>"Do we really need to declare what files exist when our file system already knows?"</em></p>
<p>This is the mental model shift: <strong>move from manual, static registration to automated, runtime discovery.</strong></p>
<p>If a developer places a valid component — with its matching <strong>contentType</strong> definition — inside the <strong>src/components</strong> folder, the project should automatically detect and register it. Your folder structure is the source of truth; your registry file should simply reflect that truth dynamically at build time.</p>
<p>By generating this registry file automatically, we preserve all the power, safety, and type-safety of Optimizely's SDK while eliminating manual list maintenance — and the inevitable merge conflicts that come with it — entirely.</p>
<p>The question for your team to consider: is the overhead of manually maintaining the registry file appropriate for the size and pace of your team? For a solo developer or a two-person squad, the static approach is perfect. For five or more developers running parallel feature tracks, automation becomes the right call.</p>
<hr />
<h2>Implementing Registry Generation</h2>
<p>Instead of writing complex dynamic imports that can sometimes complicate React server-side rendering or bundle splitting, the most robust approach is a lightweight pre-build <strong>codegen script</strong> that automatically compiles your <strong>registry.ts</strong> file right before your app starts or builds.</p>
<p>This is a well-established industry pattern that works perfectly with standard Next.js and React environments.</p>
<h3>1. The Registry Generator Script</h3>
<p>Create a native Node.js script in your project root: <strong>generate-registry.mjs</strong>. It recursively scans <strong>src/components</strong>, finds every component file, and writes a fully-resolved <strong>registry.ts</strong>.</p>
<pre class="code-block"><code class="language-javascript">// generate-registry.mjs
import fs from 'fs';
import path from 'path';
const COMPONENTS_DIR = './src/components';
const OUTPUT_FILE = './src/components/registry.ts';
function getComponentFiles(dir, filesList = []) {
if (!fs.existsSync(dir)) return filesList;
const items = fs.readdirSync(dir);
for (const item of items) {
const fullPath = path.join(dir, item);
const stat = fs.statSync(fullPath);
if (stat.isDirectory()) {
getComponentFiles(fullPath, filesList);
} else if ((item.endsWith('.tsx') || item.endsWith('.ts')) && !item.includes('registry')) {
// Expects each file to export a default component + a named ContentType
// e.g. export const HeroBannerContentType = contentType(...)
filesList.push(fullPath);
}
}
return filesList;
}
try {
console.log('[Optimizely Registry] Scanning components...');
const files = getComponentFiles(COMPONENTS_DIR);
const imports = [];
const contentTypes = [];
const resolvers = [];
files.forEach((file) => {
const relativePath = './' + path.relative(path.dirname(OUTPUT_FILE), file)
.replace(/\\/g, '/')
.replace(/\.tsx?$/, '');
const componentName = path.basename(file, path.extname(file));
const contentTypeConst = `${componentName}ContentType`;
imports.push(`import ${componentName}, { ${contentTypeConst} } from '${relativePath}';`);
contentTypes.push(` ${contentTypeConst}`);
resolvers.push(` ${componentName}`);
});
const output = `// ==========================================================================
// AUTO-GENERATED — do not edit manually. Changes will be overwritten.
// Run: node generate-registry.mjs | Source: generate-registry.mjs
// ==========================================================================
import { initContentTypeRegistry } from '@optimizely/cms-sdk';
import { initReactComponentRegistry } from '@optimizely/cms-sdk/react/server';
${imports.join('\n')}
export function registerComponents() {
initContentTypeRegistry([
${contentTypes.join(',\n')},
]);
initReactComponentRegistry({
resolver: {
${resolvers.join(',\n')},
},
});
}
`;
fs.writeFileSync(OUTPUT_FILE, output, 'utf8');
console.log(`[Optimizely Registry] Done — ${files.length} component(s) registered.`);
} catch (err) {
console.error('[Optimizely Registry] Generation failed:', err.message);
process.exit(1);
}</code></pre>
<h3>2. Wire It Into Your Lifecycle</h3>
<p>Hook the script into your <strong>package.json</strong> using npm's built-in <strong>pre</strong> hooks. It runs automatically before both <strong>dev</strong> and <strong>build</strong> — no manual step required.</p>
<pre class="code-block"><code class="language-json">"scripts": {
"predev": "node generate-registry.mjs",
"prebuild": "node generate-registry.mjs",
"dev": "next dev",
"build": "next build",
"start": "next start"
}</code></pre>
<p>Then add the generated file to <strong>.gitignore</strong>, since it is a build artifact:</p>
<pre class="code-block"><code class="language-bash"># .gitignore
src/components/registry.ts</code></pre>
<p>From this point on, no developer ever touches <strong>registry.ts</strong> again. It is generated fresh on every <strong>npm run dev</strong> and every CI/CD build run.</p>
<hr />
<h2>Why This Works on Local and CI/CD Alike</h2>
<p>Because the generator runs as part of the standard dev/build lifecycle, it scales flawlessly across all stages without any developer intervention.</p>
<table style="border-collapse: collapse; border-width: 1px; border-style: solid;">
<tbody>
<tr>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p><strong>Scenario</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p><strong>Static Registry</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p><strong>Generated Registry</strong></p>
</td>
</tr>
<tr>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p><strong>Local Sandbox</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Developers must manually add imports every time they create a component.</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Creating a <strong>.tsx</strong> file and running <strong>npm run dev</strong> registers it automatically.</p>
</td>
</tr>
<tr>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p><strong>Feature Branch</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Every branch modifies the shared <strong>registry.ts</strong>, creating Git conflicts on merge.</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Branches only contain the component file itself. <strong>registry.ts</strong> is Git-ignored. Merges are 100% clean.</p>
</td>
</tr>
<tr>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p><strong>CI/CD Pipeline</strong></p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>Static imports are read as-is. A missed import causes a silent runtime failure.</p>
</td>
<td style="border-width: 1px; padding: 10px; border-style: solid; text-align: left; vertical-align: top;">
<p>The generator scans the actual workspace. If the file exists in the repo, it gets registered.</p>
</td>
</tr>
</tbody>
</table>
<hr />
<h2>Is This the Right Move for Your Team?</h2>
<p>Runtime registry generation isn't a universal answer — it's a tool for the right context. Here's how to think about it:</p>
<p><strong>Stick with the static registry if:</strong></p>
<ul class="tight">
<li>
<p>Your team is small (one to three developers)</p>
</li>
<li>
<p>Your schema is stable and rarely changes</p>
</li>
<li>
<p>You value absolute explicitness and prefer to control every import</p>
</li>
</ul>
<p><strong>Consider dynamic generation if:</strong></p>
<ul class="tight">
<li>
<p>You have four or more developers working on parallel feature branches</p>
</li>
<li>
<p>You're frequently hitting merge conflicts on a single registration file</p>
</li>
<li>
<p>You want your CI/CD pipeline to be self-healing rather than dependent on human memory</p>
</li>
</ul>
<p>Neither approach is wrong. The static model is exactly what Optimizely recommends out of the box — and for good reason. The generated model is a team-scale evolution of that same idea, where automation takes on the maintenance burden.</p>
<hr />
<h2>Wrapping Up</h2>
<p>Optimizely's SDK gives you a clean, type-safe, and explicit way to map content types to React components. That design is intentional and it's solid.</p>
<p>But as teams grow, automation should replace manual list-keeping. By shifting your mental model toward dynamic registry generation, you get the best of both worlds: the reliability and structure of Optimizely's component resolution, paired with a conflict-free, scalable parallel development workflow.</p>
<p>It's a simple script with a meaningful impact on your daily developer experience. Give it a try on your next feature sprint and let the filesystem do the organizing.</p>
<hr />
<p><em>Are you running into registry conflicts on your Optimizely CMS SaaS projects? Have you found other ways to automate the component wiring? Share what's working for your team in the comments — we'd love to hear it.</em></p>2026-07-21T05:42:00.0000000ZBlog postHow I Deployed My Optimizely Content JS SDK Next.js App on Vercel (Hello Opti World)📌 Scope: This post covers Optimizely CMS (SaaS) only, using the official content-js-sdk with Next.js 15 deployed to Vercel. This is a practitioner walkthrough — not official documentation. ⚠️ No official Vercel deployment guide exists for the content-js-sdk at the time of writing. This is what I figured out building my first app — Hello […]2026-07-21T04:02:15.0000000ZBlog postFinding Thomas Part 5 - The Closed Loop<p class="font-claude-response-body break-words whitespace-normal">Five weeks. Five layers. One Thomas.</p>
<p class="font-claude-response-body break-words whitespace-normal">If you've followed this series from the start — thank you. If you're just landing here, the short version: Thomas is the returning visitor who reads everything, opens every email, converts on nothing, and one day quietly stops coming back. No warning. No signal. Just gone.</p>
<p class="font-claude-response-body break-words whitespace-normal">Over the last four posts we traced exactly how that happens — and how to stop it. The <span style="color: rgb(35, 111, 161);"><strong><a style="color: rgb(35, 111, 161);" href="https://www.linkedin.com/pulse/finding-thomas-part-1-observation-post-ritu-madan-8kkwe">CMS</a></strong></span> watching Thomas's behavior as it unfolds. <strong><span style="color: rgb(35, 111, 161);"><a style="color: rgb(35, 111, 161);" href="https://www.linkedin.com/pulse/finding-thomas-part-2-recognition-engine-ritu-madan-wq2ef">ODP</a></span></strong> turning that behavior into a persistent, scorable profile. <strong><span style="color: rgb(35, 111, 161);"><a style="color: rgb(35, 111, 161);" href="https://www.linkedin.com/pulse/finding-thomas-part-3-moment-recognition-ritu-madan-5hvwe">Personalization</a></span></strong> making him feel seen for the first time. <strong><span style="color: rgb(35, 111, 161);"><a style="color: rgb(35, 111, 161);" href="https://www.linkedin.com/pulse/finding-thomas-part-4-intelligence-layer-ritu-madan-tgvgc">Opal</a></span></strong> scaling that recognition to every Thomas in your audience without a human bottleneck.</p>
<p class="font-claude-response-body break-words whitespace-normal">Part 5 is the final part where all four connect.</p>
<p class="font-claude-response-body break-words whitespace-normal">Not as adjacent tools. Not as a martech stack. As a single, continuous loop — one that finds Thomas while he's still Drifting, responds before he reaches At Risk, and gets smarter with every intervention it makes.</p>
<p class="font-claude-response-body break-words whitespace-normal">It also ends where the whole series began. With Thomas. And with the question worth asking honestly of any Optimizely implementation that has been live for more than a year:</p>
<p class="font-claude-response-body break-words whitespace-normal">Is your platform pointed at finding Thomas — or is it still primarily pointed at bringing new visitors through the door?</p>
<p class="font-claude-response-body break-words whitespace-normal">Read the full story <strong><span style="color: rgb(35, 111, 161);"><a style="color: rgb(35, 111, 161);" href="https://www.linkedin.com/pulse/finding-thomas-part-5-closed-loop-ritu-madan-pmkoc/">here</a></span></strong>.</p>2026-07-20T14:34:06.0000000ZBlog postExtending the Optimizely Product Recommendations Feed to Include Custom Product TypesA practical way to extend the Optimizely Product Recommendations catalog feed so the export scheduled job also includes custom catalog types, like bundles, that are skipped by default.2026-07-20T14:20:00.0000000ZBlog postParallel Development in Optimizely CMS SaaS: A Smarter Way to Push Content Models<p>When Optimizely shipped the JavaScript SDK and CLI for CMS SaaS, they gave developers something pretty cool — a code-first workflow for content modeling. Define your content types in <strong>.tsx</strong> files, run <strong>npx @optimizely/cms-cli@latest push</strong>, and your content models land in the CMS instance via the REST API.</p>
<p>Clean. Fast. Developer-friendly.</p>
<p>But here's the thing about developer tools — the moment you hand them to a <em>team</em>, the dynamics shift. And that's not a flaw in the tooling. It's just what happens when multiple people start pushing content models to the same environment at the same time.</p>
<p>Let's talk about that.</p>
<hr />
<h2>The Reality of Parallel Development</h2>
<p>Picture this: you're on a feature branch, building out a <strong>HeroBanner</strong> component. Your teammate is on a separate branch, refining the <strong>ArticlePage</strong> schema. Both of you are pointing your CLI at the same non-production CMS instance.</p>
<p>You run <strong>push</strong>. The CLI reads your <strong>optimizely.config.mjs</strong>, scans the entire <strong>src/components/</strong> directory, and attempts to sync <em>everything</em> it finds — your changes, your teammate's changes, and every other content type definition sitting in the codebase.</p>
<p>Now, if your local branch doesn't have your teammate's latest work (because they haven't merged yet), the CLI sees a mismatch. It flags a conflict. You get an error.</p>
<p>This is actually <em>good behavior</em>. The CLI is protecting you from accidentally overwriting someone else's work. Optimizely built in a <strong>--force</strong> flag for exactly this reason — when you know what you're doing and want to push regardless, you can.</p>
<p>But here's where the mental model needs to shift.</p>
<hr />
<h2>The Force Flag Solves the Wrong Problem (For This Scenario)</h2>
<p>Let's be clear — the <strong>--force</strong> option is a legitimate and useful tool. It exists because there are real scenarios where you need to override what's on the remote instance. Schema migrations, breaking changes, cleanup operations — force is the right call.</p>
<p>But in a parallel development workflow, the question isn't <em>"how do I push harder?"</em> — it's <em>"why am I pushing things I didn't change?"</em></p>
<p>Think about it. If you only modified <strong>HeroBanner.tsx</strong>, why should the CLI even <em>look</em> at <strong>ArticlePage.tsx</strong>? Why should it care about 47 other component files that you never touched?</p>
<p>The problem isn't conflict resolution. The problem is <strong>scope</strong>.</p>
<hr />
<h2>A Different Way to Think About It</h2>
<p>Here's the mental shift: instead of treating the CLI push as a <em>full sync</em> operation, treat it as a <em>deployment of your changes</em>.</p>
<p>This is how we already think about code deployments. Your CI/CD pipeline doesn't redeploy every microservice when you change one. Your database migration tool doesn't re-run every migration from the beginning. You deploy <em>what changed</em>.</p>
<p>Content model pushes should work the same way.</p>
<p>The good news? The CLI already supports this. The <strong>optimizely.config.mjs</strong> file controls <em>which components the CLI processes</em>. If you narrow the <strong>components</strong> array to only the files you've changed, the CLI will only push those content types. No conflicts with your teammate's work. No force flags needed. No wasted API calls.</p>
<p>The trick is doing this <em>dynamically</em> — based on your actual Git branch changes.</p>
<hr />
<h2>Git as Your Scope Engine</h2>
<p>Your version control system already knows exactly what you changed. A simple <strong>git diff</strong> against your base branch gives you the precise list of modified <strong>.tsx</strong> files. From there, it's straightforward to generate a temporary config file, push only those components, and clean up.</p>
<p>Here's a Node.js script that handles the entire flow:</p>
<pre class="code-block"><code class="language-js">// push-branch-changes.mjs
import { execSync } from 'child_process';
import fs from 'fs';
import path from 'path';
const baseBranch = process.argv[2] || 'origin/main';
const tempConfig = 'optimizely.config.temp.mjs';
try {
console.log(`Checking changes against ${baseBranch}...`);
const gitOutput = execSync(
`git diff ${baseBranch} --name-only -- "src/components/**/*.tsx"`,
{ encoding: 'utf8' }
);
const changedFiles = gitOutput
.split('\n')
.map(f => f.trim())
.filter(f => f.length > 0 && fs.existsSync(f));
if (changedFiles.length === 0) {
console.log('No component changes on this branch. Nothing to push.');
process.exit(0);
}
console.log(`\nPushing ${changedFiles.length} changed component(s):`);
changedFiles.forEach(f => console.log(` - ${f}`));
// Generate a temporary config scoped to changed files only
const paths = changedFiles.map(f => `'./${f}'`).join(',\n ');
const config = `import { buildConfig } from '@optimizely/cms-sdk';
export default buildConfig({
components: [
${paths}
],
});
`;
fs.writeFileSync(path.resolve(tempConfig), config, 'utf8');
// Push using the scoped config
execSync(`npx @optimizely/cms-cli@latest push --config ${tempConfig}`, {
stdio: 'inherit',
});
// Cleanup
fs.unlinkSync(tempConfig);
console.log('Done. Only your branch changes were pushed.');
} catch (err) {
console.error('Push failed:', err.message);
if (fs.existsSync(tempConfig)) fs.unlinkSync(tempConfig);
process.exit(1);
}</code></pre>
<p>Wire it up in your <strong>package.json</strong>:</p>
<pre class="code-block"><code class="language-json">"scripts": {
"cms:push-branch": "node push-branch-changes.mjs"
}</code></pre>
<p>And run it:</p>
<pre class="code-block"><code class="language-bash"># Compare against origin/main (default)
npm run cms:push-branch
# Or compare against a different base
npm run cms:push-branch origin/develop</code></pre>
<p>That's it. The script diffs your branch, generates a scoped config, pushes only your changes, and cleans up after itself.</p>
<hr />
<h2>What This Actually Gets You</h2>
<p><strong>Speed.</strong> Instead of the CLI parsing and validating every content type in your project, it processes only the handful you touched. On larger codebases with dozens of content types, the difference is noticeable.</p>
<p><strong>Safety.</strong> You literally cannot overwrite a teammate's content type because the CLI never sees it. There's no conflict to resolve, no force flag to debate, no Slack message asking <em>"did someone just push over my changes?"</em></p>
<p><strong>Focus.</strong> Your push operation maps 1:1 to your pull request. What you changed in code is what gets pushed to the CMS. Nothing more, nothing less. That's easier to review, easier to debug, and easier to roll back.</p>
<hr />
<h2>Where This Fits in a Bigger Picture</h2>
<p>This approach pairs well with a structured environment strategy. Consider this setup:</p>
<table style="border-collapse: collapse; border-width: 1px; border-style: solid;">
<tbody>
<tr>
<td style="padding: 10px; text-align: left; vertical-align: top; border-width: 1px; border-style: solid;">
<p><strong>Environment</strong></p>
</td>
<td style="padding: 10px; text-align: left; vertical-align: top; border-width: 1px; border-style: solid;">
<p><strong>Who Pushes</strong></p>
</td>
<td style="padding: 10px; text-align: left; vertical-align: top; border-width: 1px; border-style: solid;">
<p><strong>How</strong></p>
</td>
</tr>
<tr>
<td style="padding: 10px; text-align: left; vertical-align: top; border-width: 1px; border-style: solid;">
<p>Developer instances</p>
</td>
<td style="padding: 10px; text-align: left; vertical-align: top; border-width: 1px; border-style: solid;">
<p>Individual devs</p>
</td>
<td style="padding: 10px; text-align: left; vertical-align: top; border-width: 1px; border-style: solid;">
<p>Branch-scoped push (this script)</p>
</td>
</tr>
<tr>
<td style="padding: 10px; text-align: left; vertical-align: top; border-width: 1px; border-style: solid;">
<p>Shared QA/Staging</p>
</td>
<td style="padding: 10px; text-align: left; vertical-align: top; border-width: 1px; border-style: solid;">
<p>CI/CD pipeline</p>
</td>
<td style="padding: 10px; text-align: left; vertical-align: top; border-width: 1px; border-style: solid;">
<p>Full push on merge to main</p>
</td>
</tr>
<tr>
<td style="padding: 10px; text-align: left; vertical-align: top; border-width: 1px; border-style: solid;">
<p>Production</p>
</td>
<td style="padding: 10px; text-align: left; vertical-align: top; border-width: 1px; border-style: solid;">
<p>CI/CD pipeline</p>
</td>
<td style="padding: 10px; text-align: left; vertical-align: top; border-width: 1px; border-style: solid;">
<p>Full push on release</p>
</td>
</tr>
</tbody>
</table>
<p>Developers get fast, isolated feedback loops on their own instances. The shared environments only receive content models that have been reviewed and merged. Production stays locked down behind your release process.</p>
<p>The Optimizely CLI's full push behavior is <em>exactly right</em> for CI/CD — you want a complete sync when deploying from a merged, canonical branch. The branch-scoped approach fills the gap for the development phase, where speed and isolation matter more than completeness.</p>
<hr />
<h2>Wrapping Up</h2>
<p>The Optimizely CMS SaaS CLI is a solid tool. The force option exists for a reason and handles real conflicts well. But parallel development introduces a different kind of challenge — not <em>"how do I resolve conflicts"</em> but <em>"how do I avoid creating them in the first place?"</em></p>
<p>By scoping your pushes to only the content types you've actually changed, you sidestep the problem entirely. Your Git branch becomes the source of truth for what gets pushed, and everyone on the team stays out of each other's way.</p>
<p>It's a small script with a big impact on your daily workflow. Give it a try on your next feature branch.</p>
<hr />
<p><em>Have you tried a similar approach or found other ways to streamline parallel development with Optimizely CMS SaaS? We'd love to hear what's working for your team.</em></p>2026-07-20T09:04:26.0000000ZBlog postFixing index_not_found_exception After Purging External Data in Optimizely Graph<h3>The Scenario: Indexing External Data</h3>
<p>When working with Optimizely Content Graph, indexing external data is a straightforward process. <a href="https://docs.developers.optimizely.com/platform-optimizely/docs/sync-content-data">Synchronize custom data sources with Optimizely Graph</a></p>
<p>Followed by setting up a GraphQL schema to push an external content type called <strong>Article </strong>into a specific source src1</p>
<p>Here is the initial schema definition using the V3 API:</p>
<p><!----><!----><!----><!----><!----><!----><!----><!----></p>
<div class="code-block ng-tns-c2171817996-27 ng-animate-disabled ng-trigger ng-trigger-codeBlockRevealAnimation"><!---->
<div class="formatted-code-block-internal-container ng-tns-c2171817996-27">
<div class="animated-opacity ng-tns-c2171817996-27"><!---->
<pre class="ng-tns-c2171817996-27"><code class="code-container formatted ng-tns-c2171817996-27">curl --location --request PUT <span class="hljs-string">'https://cg.optimizely.com/api/content/v3/types?id=src1'</span> \
--header <span class="hljs-string">'Content-Type: application/json'</span> \
--header <span class="hljs-string">'Authorization: Basic BASE64_ENCODED_CREDENTIALS'</span> \
--data <span class="hljs-string">'{
"languages": ["en-US"],
"contentTypes":{
"Article": {
"contentType": [],
"properties": {
"Id": { "type": "Int" },
"Keywords": { "type": "String", "searchable": true },
"Language": { "type": "String" },
"Comment": { "type": "String" },
"Body": { "type": "String", "searchable": true },
"Summary": { "type": "String", "searchable": true },
"CreatedTime": { "type": "Date" }
}
}
}
}'</span>
</code></pre>
<!----></div>
</div>
</div>
<p><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----></p>
<p>After registering the schema, I successfully synced the content using Post request via a scheduled job. The data was indexed and queryable.<code>POST /api/content/v2/data?id=src1</code> </p>
<h3>The Problem: A Silent Failure Post-Purge</h3>
<p>To clean up the index and start fresh, I executed a purge operation using the API: <code>DELETE /api/content/v2/data?id=src1</code></p>
<p>While the purge succeeded and cleared the results, a major issue occurred when my scheduled job tried to sync new data. The Post request returned a successful response with a journalId, but queries still returned zero items.</p>
<p>Upon checking the journal stream details in Postman I found the culprit: a failed status throwing an <strong>index_not_found_exception</strong> <code>https://cg.optimizely.com/journal/stream/journalId</code></p>
<p><img src="/link/12ce3b2d0ae34c59b8981d2f360438db.aspx" alt="" width="1065" height="294" /></p>
<h3>The Root Cause: Management Layer vs. Storage Layer</h3>
<p>Why did the API return a success response if the index didn't exist? The answer lies in how Optimizely Content Graph separates data configuration:</p>
<ol>
<li>
<p><strong>The Management Layer (Schema Registry):</strong> When you check for your schema, the API looks at its registry. The blueprint for <strong>Article</strong> is still there, so the ingestion gateway assumes everything is fine and accepts your data stream (giving you a success response and a journalId).</p>
</li>
<li>
<p><strong>The Storage Layer (Elasticsearch Cluster):</strong> This is where the physical data buckets live. When you performed the purge, it completely wiped the physical storage bucket to free up cloud resources.</p>
</li>
</ol>
<p>When the background worker attempts to write your new data to the physical storage layer, it panics and throws the <strong>index_not_found_exception </strong>because the actual bucket no longer exists.</p>
<p>According to the Optimizely development team, the legacy DELETE /api/content/v2/data and the newer DELETE /api/content/v3/sources?mode=data endpoints delete <em>all</em> data, <strong>including the underlying indices</strong>. Because this is an <strong><em>external content type</em></strong>, the system doesn't automatically rebuild the physical container upon receiving new data.</p>
<h3>The Current Solution</h3>
<p>If you expect a purge to solely remove records while keeping the underlying physical container intact, you will run into this error. As the purge inherently drops the Elasticsearch index, you must manually recreate it.</p>
<p><strong>To resolve this, you must re-push your schema before indexing new documents.</strong></p>
<ol>
<li>
<p><strong>Purge the data:</strong> <code>DELETE /api/content/v2/data?id=src1</code></p>
</li>
<li>
<p><strong>Recreate the Schema:</strong> Resend your original PUT request to o rebuild the physical storage index. <code>PUT /api/content/v3/types?id=src1</code></p>
</li>
<li>
<p><strong>Sync the Content:</strong> Execute your Post request to index the new documents.</p>
</li>
</ol>
<p>By pushing the schema again after every purge, you ensure the underlying Elasticsearch container is recreated and ready to accept your external content data streams.</p>
<h3>Support the Feature Request</h3>
<p>While the workaround above successfully resolves the issue, the ideal behavior would be for the purge operation to delete only the content records, leaving the underlying physical container and schema intact so background syncs don't fail.</p>
<p>I have submitted a feedback request to the Optimizely support to address this behavior. If you have run into this same issue, please upvote and support the request here:</p>
<p><strong><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><!----><a class="ng-star-inserted" href="https://feedback.optimizely.com/forums/964785-cms-saas-content-management-system/suggestions/51482671-sync-external-content-data-purge-deletes-content-a">Vote here: Sync External Content Data - Purge Deletes Content and Schema</a></strong></p>2026-07-16T08:20:17.0000000ZBlog postFinding Thomas Part 4 - The Intelligence Layer<p class="font-claude-response-body break-words whitespace-normal">I've been finding Thomas for a couple weeks now. Bear with me — we're almost at the full picture.</p>
<p class="font-claude-response-body break-words whitespace-normal">Quick catch-up : Thomas is the returning visitor who reads everything, opens every email, converts on nothing — and one day quietly stops coming back. No warning. No signal. Just gone.</p>
<p class="font-claude-response-body break-words whitespace-normal">In Parts 1 through 3 we built the foundation — the <a href="https://www.linkedin.com/pulse/finding-thomas-part-1-observation-post-ritu-madan-8kkwe/"><strong>CMS</strong></a> watching him, <a href="https://www.linkedin.com/pulse/finding-thomas-part-2-recognition-engine-ritu-madan-wq2ef/"><strong>ODP</strong></a> profiling him, <a href="https://www.linkedin.com/pulse/finding-thomas-part-3-moment-recognition-ritu-madan-5hvwe/"><strong>Personalization</strong></a> making him feel seen for the first time.</p>
<p class="font-claude-response-body break-words whitespace-normal">Part 4 is where it gets interesting.</p>
<p class="font-claude-response-body break-words whitespace-normal">Because everything we've built so far has a ceiling. Someone still has to hypothesize the Thomas profile, build the segment manually, monitor the scores, and make judgment calls. At the scale of a real content ecosystem, that human dependency is the bottleneck.</p>
<p class="font-claude-response-body break-words whitespace-normal">Opal removes the ceiling.</p>
<p class="font-claude-response-body break-words whitespace-normal">It doesn't guess what Thomas looks like. It learns what Thomas looks like — from the behavior of every visitor who eventually stopped coming back. Then it scales that recognition to thousands of Thomas-profile users without manual intervention.</p>
<p class="font-claude-response-body break-words whitespace-normal">There's also a productive paradox at the heart of this one: the answer to AI displacing your site traffic is AI deployed inside your own ecosystem. Part 4 makes that case. Read it <span style="color: rgb(35, 111, 161);"><strong><a style="color: rgb(35, 111, 161);" href="https://www.linkedin.com/pulse/finding-thomas-part-4-intelligence-layer-ritu-madan-tgvgc">here</a></strong></span>.</p>2026-07-14T19:01:56.0000000ZBlog postThe Silent Success: When Your Optimizely SaaS CMS Config Push Succeeds with "0" Changes<p> </p>
<p>Picture this frustratingly common scenario in headless, code-first development with Optimizely SaaS CMS:</p>
<p>You’ve defined a brilliant new element, block, or page type in your React codebase. You trigger your local push command. The console works its magic, spinning up green indicators and a clean finish:</p>
<pre class="code-block"><code>📤 Pushing content types...
✓ Configuration file uploaded
✅ Push succeeded.</code></pre>
<p>But when you open the Optimizely CMS UI, navigate to <strong>Settings > Content Types</strong>, and look for your new type... there is absolutely, crushing nothingness.</p>
<p>You immediately jump into emergency triage mode. You double-check your <strong>.env</strong> keys. You check permissions. Everything is correct. So why did the CLI say "Success" while doing absolutely nothing?</p>
<p>This is the <strong>CLI Silent Empty Push</strong> — and to debug it, you have to work through a specific hierarchy of checks. Let's trace the journey from the most obvious suspects down to the real, silent culprit.</p>
<hr />
<h2>The "Everything Looks Correct" Checklist</h2>
<p>Before tear-downs and code reviews, developers usually start with the obvious infrastructure questions. Here is the checklist of things you likely already verified:</p>
<h3>🔍 Check 1: Client ID & Client Secret</h3>
<ul class="tight">
<li>
<p><strong>The Question:</strong> Are your credentials expired or invalid?</p>
</li>
<li>
<p><strong>How to verify:</strong> Run <strong>npx @optimizely/cms-cli@latest login</strong>. If the connection is broken, the CLI will throw an authentication error immediately. If it says "Authentication complete," your credentials are functional.</p>
</li>
</ul>
<h3>🔍 Check 2: API Permissions & Impersonation Scopes</h3>
<ul class="tight">
<li>
<p><strong>The Question:</strong> Does your API Key have the rights to actually write schemas?</p>
</li>
<li>
<p><strong>How to verify:</strong> Check <strong>Settings > API Keys</strong> in the CMS UI. Ensure the key is active and possesses write scopes. If your key lacks permissions, a push would trigger a stark <strong>403 Forbidden</strong> or <strong>401 Unauthorized</strong> error in your terminal.</p>
</li>
</ul>
<h3>🔍 Check 3: The Target Environment URL</h3>
<ul class="tight">
<li>
<p><strong>The Question:</strong> Are you accidentally pushing to the wrong sandbox or staging instance?</p>
</li>
<li>
<p><strong>How to verify:</strong> Inspect your <strong>OPTIMIZELY_CMS_API_URL</strong> environment variable. If you pushed to a different instance, the schemas would exist, just on the wrong server.</p>
</li>
</ul>
<hr />
<h3>If all of those are green, why is the CMS still empty?</h3>
<p>If credentials, permissions, and host URLs are completely correct, and the terminal prints a successful <strong>200 OK</strong>, you have officially bypassed standard configuration errors.</p>
<p>The issue isn't security or network-related. It is a silent, 12-character path resolution discrepancy.</p>
<hr />
<h2>What the Official Documentation Says</h2>
<p>The official Optimizely <a href="https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/docs/configure-javascript-sdk"><em>Configure JavaScript SDK</em></a> guide is explicit about where the configuration file should live. Step 4 reads:</p>
<blockquote>
<p>*"Create an <strong>optimizely.config.mjs</strong> file in the <strong>root of your project</strong>."</p>
</blockquote>
<p>The official project structure diagram reinforces this:</p>
<pre class="code-block"><code>.
├── src/
│ └── components/
├── .env
├── optimizely.config.mjs ← root level, explicitly
└── ...</code></pre>
<p>The documentation does not cover what happens when you move this file into a subdirectory — <strong>because it assumes you won't.</strong> Developers following natural project organisation instincts — a clean root, a monorepo structure, a dedicated <strong>config/</strong> folder for multiple environment files — deviate from this guidance without realising there is a hidden consequence.</p>
<p>The CLI works perfectly when the file is at the root. The moment it moves into a subdirectory, globs silently resolve against the wrong base path, and the push uploads nothing.</p>
<hr />
<h2>The Real Culprit: The Glob Resolution Trap</h2>
<p>In clean, modern JavaScript monorepos or well-structured project hierarchies, developers rarely leave configuration files floating in the root directory. To keep things tidy, we often organize configurations into subdirectories like <strong>.optimizely/</strong> or <strong>config/</strong>.</p>
<p>For instance, you might move your CMS configuration to:</p>
<pre><strong>config/optimizely.config.mjs</strong></pre>
<p>And inside that nested configuration file, you write your relative component search paths:</p>
<pre class="code-block"><code class="language-javascript">import { buildConfig } from '@optimizely/cms-sdk';
export default buildConfig({
components: ['./src/content-types/**/*.ts'],
});</code></pre>
<p>This is where the silent trap springs. Here is the golden rule of the Optimizely CMS CLI:</p>
<blockquote>
<p>⚠️ <strong>The CLI resolves glob patterns inside a configuration file relative to the location of the configuration file itself, not relative to the root directory where you ran the CLI command.</strong></p>
</blockquote>
<p>Because the configuration file lives inside the <strong>config/</strong> subdirectory, the CLI reads <strong>./src/content-types/...</strong> as relative to <strong>config/</strong>. It starts searching for your schemas here:</p>
<p><strong>config/src/content-types/**/*.ts</strong></p>
<p>That subdirectory path does not exist. The CLI scans the folder, matches <strong>0 files</strong>, and finds exactly <strong>0 schemas</strong> to process.</p>
<h3>Why did the CLI report success?</h3>
<p>The Optimizely CLI is highly permissive. If a glob pattern matches zero files, it does not throw an error or fail the build. It assumes you just have a clean configuration slate, packs up an empty schema payload, and uploads it.</p>
<p>The CMS API receives a valid, perfectly formed (but empty) configuration payload, updates nothing, and returns an <strong>HTTP 200 OK</strong>. The CLI reports <strong>Configuration file uploaded</strong> because the upload itself <em>did</em> succeed.</p>
<p>The result: a completely silent, completely successful push of nothing.</p>
<hr />
<h2>The Fix</h2>
<p>The simplest fix is to follow the official documentation — keep your configuration file at the <strong>project root</strong> where the CLI expects it:</p>
<pre class="code-block"><code class="language-bash"># ❌ Nested (globs resolve relative to config/ — finds nothing)
npx @optimizely/cms-cli config push config/optimizely.config.mjs
# ✅ Root level (globs resolve relative to root — finds your files)
npx @optimizely/cms-cli config push optimizely.config.mjs</code></pre>
<p>If you have a strong reason to keep the config file inside a subdirectory — such as a monorepo setup or managing multiple environment configurations — you can adjust the glob paths inside the config to step up one level:</p>
<pre class="code-block"><code class="language-javascript">import { buildConfig } from '@optimizely/cms-sdk';
export default buildConfig({
// ../ steps up from config/ back to the project root
components: ['../src/content-types/**/*.ts'],
});</code></pre>
<p>Both approaches work. The root-level approach aligns with official documentation and is the least error-prone for single-app projects. The <strong>../</strong> prefix approach is useful for monorepos or multi-environment setups where nesting is intentional.</p>
<hr />
<h2>Reusable Debugging Checklist for Teams</h2>
<p>Bookmark this order-of-operations checklist for the next time a developer on your team runs into missing content types after a successful-looking push:</p>
<ol class="tight">
<li>
<p><strong>CLI Authentication Test</strong> — Run <strong>npx @optimizely/cms-cli@latest login</strong> to rule out expired credentials.</p>
</li>
<li>
<p><strong>API Key Scope Verification</strong> — Confirm your key has write access under <strong>Settings > API Keys</strong> in the CMS.</p>
</li>
<li>
<p><strong>Environment URL Check</strong> — Verify <strong>OPTIMIZELY_CMS_API_URL</strong> points to the instance you are currently viewing.</p>
</li>
<li>
<p><strong>Config File Location Audit</strong> — Is your <strong>optimizely.config.mjs</strong> (or any dynamically generated config) in the project root? If it is nested in a subdirectory, check whether the glob paths inside use <strong>../</strong> to compensate.</p>
</li>
<li>
<p><strong>Glob Match Validation</strong> — Test whether your glob patterns actually match any files before pushing:</p>
<pre class="code-block"><code class="language-typescript">import { globSync } from 'fast-glob';
const matched = globSync('./src/content-types/**/*.ts');
if (matched.length === 0) {
console.error('❌ Zero files matched. Config push will be empty.');
}</code></pre>
</li>
<li>
<p><strong>Visual Builder Composition</strong> — If your type appears in <strong>Settings > Content Types</strong> but not in the Visual Builder editor, go to that type's <strong>Settings</strong> tab and enable <strong>"Available for composition in Visual Builder"</strong>.</p>
</li>
</ol>
<hr />
<h2>Key Takeaway</h2>
<p>The Optimizely developer documentation is clear: <strong>optimizely.config.mjs</strong> belongs at the root of your project. When it lives there, everything works exactly as expected. When it moves — even for completely legitimate reasons — the CLI's glob resolution silently breaks, the push uploads an empty payload, and the CMS returns a perfectly polite <strong>200 OK</strong>.</p>
<p>The fix is simple. The behaviour, however, is not documented — which is precisely what makes it one of the most confusing silent failures in a SaaS CMS headless setup.</p>
<p>One line change. Types appear instantly.</p>
<hr />
<p><em>Have you run into other silent failure modes when working with Optimizely SaaS CMS content type workflows? Share your experience in the comments — this kind of institutional knowledge keeps teams shipping faster.</em></p>2026-07-13T07:32:17.0000000ZBlog postArchitecting an Enterprise-Grade Development Pipeline in Optimizely SaaS CMS<p>Most enterprise teams show up to Optimizely SaaS CMS with a clear roadmap for their release pipeline: DEV → QA → Stage → Prod. Four logical environments to manage active coding, quality assurance, business sign-off, and live operations.</p>
<p>When setting up your initial cloud-native topology, the question immediately arises: how do we align this 4-stage pipeline with our SaaS CMS instances in a way that is automated, secure, and team-safe?</p>
<p>This is a practical guide for every dev lead, architect, and project manager looking to design a high-velocity, team-safe development workflow. We've mapped out the key architectural strategies, branching patterns, and deployment automation tactics to make your Optimizely SaaS CMS pipeline production-ready.</p>
<hr />
<h2>First, Let's Talk About What "Separate Applications" Can and Can't Do</h2>
<p>Before we dive into environment mapping, it's critical to understand how Optimizely SaaS CMS handles resource isolation: <strong>applications and environments are not the same thing.</strong></p>
<p>Within a single CMS SaaS instance, you can create multiple <strong>Applications</strong> — each with its own:</p>
<ul class="tight">
<li>
<p>Content tree and start page hierarchy</p>
</li>
<li>
<p>Preview URLs and hostname configuration</p>
</li>
<li>
<p>Routing and application root settings</p>
</li>
</ul>
<p>This is incredibly powerful for multi-site and multi-brand strategies. But here is the architectural boundary: <strong>content types are scoped to the instance, not the application.</strong> When a developer pushes a new content type or modifies an existing schema, that change is immediately live across every application on that instance. There is no branching, draft mode, or per-application isolation for schemas.</p>
<p>Because schemas are instance-wide, a shared development or testing instance requires a deliberate promotion strategy to ensure that active development doesn't disrupt running QA or staging cycles.</p>
<hr />
<h2>Analyzing the Topologies: Pros and Cons of Environment Sharing</h2>
<p>If your initial setup is configured with three physical SaaS instances, achieving a 4-stage pipeline requires pairing two of your logical phases onto a single instance. There are three primary ways to design this topology, each with distinct architectural consequences.</p>
<hr />
<h3>Topology 1: Shared DEV & QA (The Schema Bottleneck Pattern)</h3>
<p><strong>Overall Assessment: Not recommended for parallel development teams</strong></p>
<p>In this pattern, the first instance is shared by developers and QA testers, while Staging and Production remain fully isolated.</p>
<ul class="tight">
<li>
<p><strong>The Problem:</strong> Developers iterate constantly. Every new feature requires adding content types, modifying properties, or updating validation rules. In a shared setup, these schema changes land on the instance immediately.</p>
</li>
<li>
<p><strong>The Impact on QA:</strong> If a developer pushes an unverified or breaking schema change mid-sprint, it can instantly destabilize the testing environment, blocking QA automation runs and invalidating manual test cycles.</p>
</li>
<li>
<p><strong>Verdict:</strong> While workable for small, highly coordinated teams (1-2 developers), this pattern quickly becomes a bottleneck for larger teams working on parallel streams.</p>
</li>
</ul>
<hr />
<h3>Topology 2: DEV | Shared QA & Stage (The Recommended Pattern)</h3>
<p><strong>Overall Assessment: The gold standard for velocity and stability</strong></p>
<p>This pattern keeps your DEV environment fully isolated, while QA testing and User Acceptance Testing (UAT/Staging) share the middle instance.</p>
<ul class="tight">
<li>
<p><strong>Why it works:</strong> Developers have complete freedom to experiment, iterate, and break things on the DEV instance. Schemas are promoted to the QA+Stage instance only through a controlled, automated deployment gate.</p>
</li>
<li>
<p><strong>Managing the Share:</strong> Because QA and UAT/Staging are typically <strong>sequential, not simultaneous</strong>, they rarely require different schema versions at the same time. You complete functional QA, sign off on the release branch, and then hand over to business stakeholders for UAT on the same schema.</p>
</li>
<li>
<p><strong>How Separate Applications Help:</strong> By creating two separate <strong>Applications</strong> within this single instance, you cleanly isolate your content and preview layers:</p>
<ul class="tight">
<li>
<p><strong>QA Application:</strong> Points to your QA frontend deployment, using QA-specific content and automated test trees.</p>
</li>
<li>
<p><strong>UAT Application:</strong> Points to your Staging/UAT frontend deployment, showcasing pristine demo content for business stakeholders.</p>
</li>
</ul>
</li>
<li>
<p><strong>Verdict:</strong> This is the most robust topology for a 3-instance setup. It completely protects developer velocity and ensures production-level safety.</p>
</li>
</ul>
<hr />
<h3>Topology 3: DEV | QA | Shared Stage & Production (The High-Risk Pattern)</h3>
<p><strong>Overall Assessment: Avoid entirely</strong></p>
<p>In this pattern, DEV and QA are fully isolated, but business sign-off (Staging/UAT) happens on the production instance.</p>
<ul class="tight">
<li>
<p><strong>The Danger:</strong> Even with separate CMS applications isolating your live content tree from your draft UAT tree, <strong>schemas are still instance-wide</strong>.</p>
</li>
<li>
<p><strong>The Impact:</strong> Any content type modification or configuration change made during UAT is immediately live on production. A single configuration oversight during a stakeholder review session can trigger an immediate production incident.</p>
</li>
<li>
<p><strong>Verdict:</strong> Production stability is non-negotiable. This topology should never be used.</p>
</li>
</ul>
<hr />
<h2>The Pipeline Comparison Matrix</h2>
<table>
<tbody>
<tr>
<td style="border-style: solid; border-width: 1px;">
<p>Pipeline Strategy</p>
</td>
<td style="border-style: solid; border-width: 1px;">
<p>DEV+QA Shared / Stage / Prod</p>
</td>
<td style="border-style: solid; border-width: 1px;">
<p>DEV / QA+Stage Shared / Prod (Recommended)</p>
</td>
<td style="border-style: solid; border-width: 1px;">
<p>DEV / QA / Stage+Prod Shared</p>
</td>
</tr>
<tr>
<td style="border-style: solid; border-width: 1px;">
<p>Developer Freedom</p>
</td>
<td style="border-style: solid; border-width: 1px;">
<p>❌ Constrained</p>
</td>
<td style="border-style: solid; border-width: 1px;">
<p>✅ Full</p>
</td>
<td style="border-style: solid; border-width: 1px;">
<p>✅ Full</p>
</td>
</tr>
<tr>
<td style="border-style: solid; border-width: 1px;">
<p>QA Schema Stability</p>
</td>
<td style="border-style: solid; border-width: 1px;">
<p>❌ Unstable</p>
</td>
<td style="border-style: solid; border-width: 1px;">
<p>✅ Stable</p>
</td>
<td style="border-style: solid; border-width: 1px;">
<p>✅ Stable</p>
</td>
</tr>
<tr>
<td style="border-style: solid; border-width: 1px;">
<p>UAT/Stakeholder Experience</p>
</td>
<td style="border-style: solid; border-width: 1px;">
<p>✅ Clean</p>
</td>
<td style="border-style: solid; border-width: 1px;">
<p>⚠️ Shares with QA</p>
</td>
<td style="border-style: solid; border-width: 1px;">
<p>❌ Shares with Prod</p>
</td>
</tr>
<tr>
<td style="border-style: solid; border-width: 1px;">
<p>Production Safety</p>
</td>
<td style="border-style: solid; border-width: 1px;">
<p>✅ Safe</p>
</td>
<td style="border-style: solid; border-width: 1px;">
<p>✅ Safe</p>
</td>
<td style="border-style: solid; border-width: 1px;">
<p>❌ Dangerous</p>
</td>
</tr>
<tr>
<td style="border-style: solid; border-width: 1px;">
<p>Application Isolation Helps?</p>
</td>
<td style="border-style: solid; border-width: 1px;">
<p>⚠️ Minimally</p>
</td>
<td style="border-style: solid; border-width: 1px;">
<p>✅ Meaningfully</p>
</td>
<td style="border-style: solid; border-width: 1px;">
<p>⚠️ Not enough</p>
</td>
</tr>
<tr>
<td style="border-style: solid; border-width: 1px;">
<p>Large Team Suitability</p>
</td>
<td style="border-style: solid; border-width: 1px;">
<p>🔴 Poor</p>
</td>
<td style="border-style: solid; border-width: 1px;">
<p>🟢 Excellent</p>
</td>
<td style="border-style: solid; border-width: 1px;">
<p>🔴 Unacceptable</p>
</td>
</tr>
</tbody>
</table>
<hr />
<h2>Implementing Automated Schema Promotion</h2>
<p>To make this pipeline robust, you should eliminate manual schema management. The recommended approach is to define all content types in code — inside your frontend components (e.g., .tsx files) — and let the <strong>Optimizely CMS CLI</strong> handle promotion programmatically.</p>
<h3>1. Integrate CLI Sync into Your CI/CD Build</h3>
<p>Your Git branch is the source of truth, and your CI/CD pipeline is the gate. Configure separate API credentials for each CMS instance in your pipeline's environment variables:</p>
<pre class="code-block"><code class="language-bash"># In your CI/CD pipeline (e.g., GitHub Actions, Azure DevOps)
# On deploy to the staging environment:
OPTIMIZELY_CMS_CLIENT_ID=${{ secrets.QA_CMS_CLIENT_ID }}
OPTIMIZELY_CMS_CLIENT_SECRET=${{ secrets.QA_CMS_CLIENT_SECRET }}
npx @optimizely/cms-cli@latest sync</code></pre>
<p>This ensures that schema changes only land on your QA+Stage instance when code is merged and deployed to your release branch — completely insulating testers from mid-sprint developer changes.</p>
<blockquote>
<p><strong>Technical Note:</strong> The CLI operates as a one-way push, reading content definitions from code and synchronizing them to the target CMS instance. This reinforces the best practice that schemas should always be version-controlled in Git.</p>
</blockquote>
<h3>2. Map Git Branches directly to CMS Instances</h3>
<p>Establishing a clear one-to-one relationship between your repository branches and your CMS targets ensures a seamless release flow:</p>
<table style="border-collapse: collapse; border-width: 1px; border-style: solid;">
<tbody>
<tr>
<td style="border-width: 1px; text-align: left; vertical-align: top; border-style: solid;">
<p><strong>Git Branch</strong></p>
</td>
<td style="border-width: 1px; text-align: left; vertical-align: top; border-style: solid;">
<p><strong>Target Frontend</strong></p>
</td>
<td style="border-width: 1px; text-align: left; vertical-align: top; border-style: solid;">
<p><strong>CLI target (CMS Instance)</strong></p>
</td>
</tr>
<tr>
<td style="border-width: 1px; text-align: left; vertical-align: top; border-style: solid;">
<p>feature/*</p>
</td>
<td style="border-width: 1px; text-align: left; vertical-align: top; border-style: solid;">
<p>Local / DEV Deploy</p>
</td>
<td style="border-width: 1px; text-align: left; vertical-align: top; border-style: solid;">
<p>DEV Instance</p>
</td>
</tr>
<tr>
<td style="border-width: 1px; text-align: left; vertical-align: top; border-style: solid;">
<p>release/* or main</p>
</td>
<td style="border-width: 1px; text-align: left; vertical-align: top; border-style: solid;">
<p>QA & Stage Deploys</p>
</td>
<td style="border-width: 1px; text-align: left; vertical-align: top; border-style: solid;">
<p>QA+Stage Shared Instance</p>
</td>
</tr>
<tr>
<td style="border-width: 1px; text-align: left; vertical-align: top; border-style: solid;">
<p>production</p>
</td>
<td style="border-width: 1px; text-align: left; vertical-align: top; border-style: solid;">
<p>Live Production Deploy</p>
</td>
<td style="border-width: 1px; text-align: left; vertical-align: top; border-style: solid;">
<p>Prod Instance</p>
</td>
</tr>
</tbody>
</table>
<hr />
<h2>Aligning SaaS Architecture with Team Requirements</h2>
<p>This approach reflects the cloud-native, headless architecture of modern SaaS platforms: the CMS backend is tightly integrated with global content APIs, real-time preview engines, and the Optimizely Graph layer.</p>
<p>By utilizing branch-gated CI/CD pipelines and native CMS Applications, teams can deliver enterprise-grade release management that feels fast, automated, and safe.</p>
<p>For large global organizations where a strictly isolated 4-environment physical topology is required by compliance or parallel testing tracks, we recommend discussing your roadmap early with your Optimizely account team. Additional non-production instances can easily be provisioned, and framing the discussion around team velocity and schema-gated testing ensures a highly collaborative path forward.</p>
<hr />
<h2>Summary of Best Practices</h2>
<ul class="tight">
<li>
<p><strong>Differentiate applications from environments:</strong> Use separate Applications to isolate content trees, but remember schemas are instance-wide.</p>
</li>
<li>
<p><strong>Isolate development first:</strong> Keep your DEV instance fully separated so developers have complete freedom to innovate and experiment.</p>
</li>
<li>
<p><strong>Automate schema delivery:</strong> Define content types in code and use the <strong>Optimizely CMS CLI</strong> to synchronize schemas at build time.</p>
</li>
<li>
<p><strong>Gate with Git:</strong> Align your branching strategy directly with your CMS targets to turn your pipeline into a hands-free, automated release gate.</p>
</li>
</ul>
<hr />
<p><em>How has your team structured its headless deployment pipeline? Share your architecture tips and lessons learned in the comments below!</em></p>2026-07-12T02:38:20.0000000ZBlog post