Blogs

Blogs2026-08-23T17:38:18.0000000Zhttps://world.optimizely.com/blogs/ Optimizely World Copies vs. Connections: Modeling Content Areas for Multilingual Success<h2>Starting With the Simple Question</h2> Most multilingual content modeling conversations start with a deceptively simple question from a client: <blockquote> "If we set this image once in English, will it show up automatically in French?" </blockquote> It sounds like a yes-or-no question. In Optimizely SaaS CMS, the honest answer is: it depends entirely on how that image was modeled. Before diving into anything complex, here are three quick sanity checks worth running on your own project. If you can answer all three confidently, you are probably in good shape: <ol class="tight"> <li> Open a translated page in your CMS. Change something in the master language. Does the translated version follow, or stay as it was? </li> <li> Look at a Content Area in the editor. Can you tell, at a glance, what each item inside it actually is? </li> <li> Ask a translator to open a page. Do they immediately know which field maps to which part of the design? </li> </ol> If any of those made you pause, this post is written for you. Nothing here is exotic or advanced. It is simply about understanding what the platform stores where, and choosing shapes that match what your editors and translators actually need. This is an area where reasonable teams land on different answers, so treat what follows as a starting point for your own discussion rather than a fixed rule set. <hr /> <h2>Designing for Both the Code and the Editor</h2> One of the genuine strengths of Optimizely SaaS CMS is its code-first, headless approach. Developers define content types directly in TypeScript and push them straight to the CMS, keeping the model in version control alongside the front-end application. But a content model is not only a database schema or a GraphQL query shape. It is also the daily interface for your editorial team. When we model content, we are designing the workspace that authors, content managers, and translators will live in. Model purely for developer convenience and it is easy to hand editors something that is awkward to navigate, fragile across languages, and difficult to translate cleanly. This post focuses on one specific area of that decision space: Content Areas, and how the items inside them behave once you introduce a second language. <hr /> <h2>The Core Building Blocks</h2> There are three primary ways to structure content within a page or experience in Optimizely SaaS CMS. Flat properties are scalar fields defined directly on the content type, such as a string, a contentReference, or a boolean. They are simple, predictable, and the easiest to reason about across languages. Embedded components are nested data structures stored inside the parent page's data as a cohesive group. Their lifecycle is bound to the parent, so publishing the page publishes the component with it. Content arrays are the headless equivalent of a Content Area. They hold a collection of content items, and those items can be one of two kinds: <ul class="tight"> <li> Shared blocks are reusable items that live in the Assets panel with their own publishing workflow and their own locale branches. </li> <li> Inline blocks are created on the fly inside the Content Area. They have no independent identity and their lifecycle is tied entirely to the parent page. </li> </ul> Each of these is a good fit for something. The interesting question is which one fits the requirement in front of you. <hr /> <h2>The SHARED Label: A Signal Worth Teaching</h2> One of the most useful affordances in the CMS editing interface is a small label: SHARED. When an author opens a Content Area, each item inside it is visually marked: <ul class="tight"> <li> Shared blocks show a SHARED badge next to their name. </li> <li> Inline blocks show no badge at all. </li> </ul> This is not decoration. It is a live signal about editorial reach: <blockquote> If you see SHARED, this block is a connected item. Editing it affects every page that references it, and for non-localizable properties it updates all language versions at once. </blockquote> An inline block, by contrast, is a private copy owned by that one page. On screen the two look almost identical. The consequences of editing them are quite different. This is worth five minutes in editor onboarding. It is one of the simplest ways to prevent a well-meaning edit from rippling further than anyone intended. <hr /> <h2>Naming Habits: Small Effort, Large Payoff</h2> When an author creates an inline block inside a Content Area, the CMS offers a Name field. It is optional. Leave it blank and the CMS fills it with the content type name. The code compiles and the API returns everything correctly. But let's look at what actually happens in the editor's workspace on a multilingual site when we don't establish a naming standard. Imagine an editor builds a Modular Landing Page using a Content Area, where they can add a flexible sequence of blocks: a hero banner, three promotional cards, and a call-to-action button. Because a landing page is highly dynamic, a flexible Content Area is exactly the right tool. However, if they leave the optional Name fields blank during block creation, the CMS defaults each name to the block's content type (such as PromoCard or HeroBanner). Here is what the English and French editors see side-by-side in their page editor: <pre class="code-block"><code class="language-text">THE UNNAMED PAIN POINT (What the translator sees) English Page French Page (Copied) Landing Page Landing Page |- HeroBanner |- HeroBanner |- PromoCard |- PromoCard |- PromoCard |- PromoCard |- PromoCard |- PromoCard |- CTABlock |- CTABlock</code></pre> The Problem: The list is completely anonymous. If the French translator wants to translate the text for the "Free Shipping" card vs. the "20% Discount" card, they have no idea which PromoCard is which. They have to click and open every single inline block on both sides of the screen to match them up. This turns a straightforward translation task into a tedious guessing game. <h3>A Convention That Solves It</h3> Now look at the difference when we introduce a simple, structured naming convention. If we instruct authors to prefix their inline blocks with a simple numeric order and a functional marketing label, the translation workspace transforms: <pre class="code-block"><code class="language-text">THE NAMED BEST PRACTICE (Effortless translation) English Page French Page (Copied) Landing Page Landing Page |- 1. Hero - Summer Promo |- 1. Hero - Summer Promo |- 2. Card - Free Shipping |- 2. Card - Free Shipping |- 3. Card - 20% Discount |- 3. Card - 20% Discount |- 4. Card - New Arrivals |- 4. Card - New Arrivals |- 5. CTA - Sign Up |- 5. CTA - Sign Up</code></pre> The Benefit: Because the names are cloned during the copy-to-language flow, the French translator immediately knows the context of each block. They click exactly the card they want, translate the English text to French, and can optionally update the block names if they choose. The page layout remains perfectly clear, organized, and predictable. For shared blocks, a meaningful name is even more critical because that name appears in the global Assets panel where every editor on the project finds, filters, and manages them: <pre class="code-block"><code class="language-text">Assets panel |- Global Blocks |- Homepage Hero Banner (SHARED) |- Q3 Promo CTA (SHARED)</code></pre> Agreeing this convention before the first content entry session is a small investment that keeps paying off as the site grows. <hr /> <h2>The Multilingual Flow: Copies and Connections</h2> Optimizely SaaS CMS makes creating a language variant straightforward. When you add a French version of an English page, the CMS offers to copy content from English, duplicating the structure and cloning the inline block data so translators start from a complete page rather than a blank one. What happens after that copy depends on whether the items are inline or shared. <h3>Inline Blocks: A Snapshot in Time</h3> Inline blocks have no independent key, so they belong entirely to the language version of the page that owns them. Once the copy is made, the two sets of blocks are separate. Update the image in the English block and the French page keeps the one it already had. Fix a typo in English and the French text stays as it was. Add or reorder blocks in English and the French arrangement is unaffected. This is reasonable behaviour, and for some teams it is exactly what they want. It gives regional editors complete freedom to shape their own market's content without a central team overwriting their work. The trade-off is that any master-language change needs to be applied again in each translated version. Where this catches teams out is when the expectation was the opposite. If a client believes they are setting a value once for all markets, this is the moment to talk it through. <h3>Shared Blocks: A Genuine Connection</h3> Shared blocks are content items in their own right, with their own key and their own locale branches. When both the English and French pages reference the same shared block, they are pointing at the same item. For properties marked as non-localizable, the value is held once and served to every language version of that block. Change it in the master language and all languages reflect it. In the editor, those fields appear as read-only when working in a non-master language, with an indicator showing where the value comes from. For properties marked as localizable, each locale branch keeps its own value, exactly as you would expect for translatable text. <hr /> <h2>The Localizable Setting</h2> The SDK exposes a localizable flag on property definitions. Setting it to false means one shared value across languages; setting it to true means a unique value per language version. <pre class="code-block"><code class="language-typescript">export const ImageWithAltCT = contentType({ key: 'ImageWithAlt', baseType: '_component', properties: { image: { type: 'contentReference', allowedTypes: ['_image'], displayName: 'Image', localizable: false, }, altText: { type: 'string', displayName: 'Alt text', localizable: true, }, }, });</code></pre> The CLI maps this to the Unique value per language setting on the property when types are pushed to the CMS. <h3>Where the Setting Creates a Connection</h3> This is the part most worth internalising, because the same setting behaves differently depending on where the property lives. <table style="border-collapse: collapse; width: 100%; border: 1px solid rgb(0, 0, 0);"> <tbody> <tr> <td style="text-align: left; vertical-align: top; background-color: rgb(236, 240, 241); border: 1px solid rgb(0, 0, 0); padding: 10px; width: 20.8323%;"> Where the property lives </td> <td style="text-align: left; vertical-align: top; background-color: rgb(236, 240, 241); border: 1px solid rgb(0, 0, 0); padding: 10px; width: 79.1677%;"> Effect of setting localizable to false </td> </tr> <tr> <td style="text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0); padding: 10px; width: 20.8323%;"> Flat property on a page </td> <td style="text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0); padding: 10px; width: 79.1677%;"> One value shared by every language version of that page. Change it in the master language and all locales reflect it. </td> </tr> <tr> <td style="text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0); padding: 10px; width: 20.8323%;"> Property on a shared block </td> <td style="text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0); padding: 10px; width: 79.1677%;"> One value shared across all locale branches of that block. Both the English and French pages referencing it see the update. </td> </tr> <tr> <td style="text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0); padding: 10px; width: 20.8323%;"> Property inside an inline block </td> <td style="text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0); padding: 10px; width: 79.1677%;"> The setting still governs whether the field is translatable, but there are two separate anonymous copies. A change in the English copy does not reach the French copy. </td> </tr> </tbody> </table> The underlying principle is straightforward once you see it: a shared value needs something stable to attach to. Flat properties and shared blocks both have a stable identity. Inline blocks do not, so there is nothing for the two language versions to share. <hr /> <h2>Pairing Shared Blocks With Localizable Settings</h2> When you need grouped content, such as an image with its alt text, and that group needs to behave sensibly across languages, combining a shared block with selective localizable settings is a clean approach worth considering. Using the definition above as a shared block, referenced from both the English and French pages, gives you this behaviour: <table style="border-collapse: collapse; width: 100%; border: 1px solid rgb(0, 0, 0);"> <tbody> <tr> <td style="background-color: rgb(236, 240, 241); text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0); padding: 10px;"> Action </td> <td style="background-color: rgb(236, 240, 241); text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0); padding: 10px;"> Result </td> </tr> <tr> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> English editor selects a different image </td> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> French page shows the new image, since the property is non-localizable on a shared item </td> </tr> <tr> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> French translator updates the French alt text </td> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> English alt text is unaffected </td> </tr> <tr> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> English editor updates the English alt text </td> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> French alt text is unaffected </td> </tr> </tbody> </table> The result is the split many multilingual projects are reaching for: shared structural assets, independently translated text, enforced by the platform rather than by editorial vigilance. Worth noting honestly: this pattern also means the shared block is genuinely shared. Editing it affects every page referencing it. That is the intent, but it should be a deliberate choice rather than a side effect, and the SHARED badge is what makes it visible to authors. <h3>Choosing Between Flat Properties and Shared Blocks</h3> Both approaches keep languages aligned. The question that usually separates them is whether the content is genuinely reused. <table style="border-collapse: collapse; width: 100%; border: 1px solid rgb(0, 0, 0);"> <tbody> <tr> <td style="background-color: rgb(236, 240, 241); text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0); padding: 10px;"> Scenario </td> <td style="background-color: rgb(236, 240, 241); text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0); padding: 10px;"> Approach worth considering </td> </tr> <tr> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> Image and alt text in one fixed slot on one page </td> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> Flat contentReference set to non-localizable, plus a flat string set to localizable </td> </tr> <tr> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> The same grouped structure appearing on many pages </td> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> A shared block with the image non-localizable and the alt text localizable </td> </tr> <tr> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> Analytics identifiers or configuration values </td> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> A flat string set to non-localizable on the parent type </td> </tr> <tr> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> A centrally managed promo banner or CTA </td> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> A shared block, structural fields non-localizable, headline localizable </td> </tr> </tbody> </table> A reasonable rule of thumb: if nobody can name two pages today where the same instance genuinely needs to update together, starting with flat properties keeps things simple. Moving to a shared block later is a one-time migration. Unwinding a shared block that turned out not to be shared is usually more work. <hr /> <h2>A Practical Example: Analytics Container IDs</h2> Consider a tracking container ID that needs to be present across the site. Placed inside an inline block within a Content Area, it gets copied into each language version when the variant is created. If that ID ever changes, someone needs to open every language version of every page holding it and update the field individually. On a site with ten languages and fifty pages, that is a lot of repetitive edits for a single value. Modeled as a flat property on the parent type with localizable set to false, the same change is made once in the master language and every language version reflects it. The useful distinction here is that a tracking ID is not translatable content at all. It is configuration. Recognising which of your fields are configuration rather than content often makes the modeling choice obvious. <hr /> <h2>What Happens If an Author Deletes a Block</h2> This question comes up on most projects, and the answer is more reassuring than teams often expect. Inline blocks do not appear in the global Trash, because they are not standalone items. Deleting one is closer to clearing a property value on the parent page. However, the parent page's version history does cover them. Every save and publish creates a revision in the Versions gadget, and rolling back to an earlier revision restores the Content Area as it was, including the inline blocks it contained. For everyday accidental deletions, this works well. There are limits worth knowing. The Versions gadget holds a 20-version history, so if a deletion goes unnoticed across many subsequent publishes, the revision containing the block can age out. The documentation is also explicit that content versions are not covered by trash management, meaning a version deleted directly from the gadget is permanently gone. Shared blocks behave differently here in a way that favours them: because they are standalone items, they do go to the Trash and can be restored independently of the pages referencing them. <hr /> <h2>A Decision Matrix to Discuss With Your Team</h2> This is offered as a conversation starter rather than a prescription. Your team's editorial workflow may well justify different choices. <table style="border-collapse: collapse; width: 100%; border: 1px solid rgb(0, 0, 0);"> <tbody> <tr> <td style="background-color: rgb(236, 240, 241); text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0); padding: 10px;"> Requirement </td> <td style="background-color: rgb(236, 240, 241); text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0); padding: 10px;"> Approach worth considering </td> <td style="background-color: rgb(236, 240, 241); text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0); padding: 10px;"> Reasoning </td> </tr> <tr> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> A fixed slot unique to one page </td> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> Flat contentReference and string properties </td> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> Structure stays locked, image can be shared across languages, alt text stays per language </td> </tr> <tr> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> The same grouped structure on many pages </td> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> A shared block with mixed localizable settings </td> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> One instance referenced everywhere, with the SHARED badge making the reach visible </td> </tr> <tr> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> Configuration values identical everywhere </td> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> A flat string set to non-localizable </td> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> One edit updates all languages </td> </tr> <tr> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> Centrally managed reusable content </td> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> A Content Area holding shared blocks </td> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> Managed from the Assets panel, changes propagate to all referencing pages </td> </tr> <tr> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> Genuinely flexible author-composed layouts </td> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> A Content Area holding inline blocks </td> <td style="padding: 10px; border: 1px solid rgb(0, 0, 0);"> Full composition freedom, with the naming convention and language copy flow documented for the team </td> </tr> </tbody> </table> <hr /> <h2>Questions Worth Asking Before You Model</h2> Running through these with your technical and editorial teams tends to surface the right answer quickly. Is the item count fixed by the design? If the layout always calls for exactly three slots, flat properties express that more directly than an array. Should any field update everywhere when the master language changes? If so, a flat property or a shared block will give you that. An inline block will not. Is this content genuinely reused across pages today? If no one can name two specific pages, starting simple is usually the safer bet. Are we planning to use an external translation service? Stable named properties are generally easier for translation tooling to map reliably than nested arrays of anonymous items. This is worth validating with your specific vendor before committing. Have editors been shown what the SHARED badge means? A short walkthrough prevents a lot of surprises. Have we agreed a naming convention? Documenting it before the first content session is far easier than retrofitting it later. <hr /> <h2>Wrapping Up</h2> Optimizely SaaS CMS gives teams a genuinely flexible toolkit here. Flat properties, embedded components, inline blocks, and shared blocks each serve a real purpose, and the localizable setting gives you fine-grained control over which values travel with translations and which stay anchored to one source of truth. If there is one idea worth carrying into your next modeling conversation, it is this: <blockquote> A shared value needs a stable identity to attach to. Flat properties and shared blocks have one. Inline blocks, by design, do not. </blockquote> Everything else tends to follow from that. Decide deliberately, write the decisions down, walk your editors through the SHARED badge, and test the language copy flow on a real page before go-live rather than after. I would genuinely like to hear how other teams are approaching this. Multilingual modeling is one of those areas where the best answer often depends on how a specific editorial team works day to day, and there is a lot to learn from comparing notes. <hr /> How is your team handling Content Areas across languages? <hr /> If you enjoyed this technical breakdown, you’ll like my monthly newsletter, <a class="_4n13zc _1l4j4nae _1q9ygi7 _4ivg92 _12zsz04 _4n13zc" href="https://www.linkedin.com/newsletters/pragmatic-judgement-7487084233719549953/">Pragmatic Judgement</a>. I write about where technical decisions meet real operational constraints for tech and delivery leaders.2026-08-23T17:38:18.0000000Z

Blog post

Content Transfer coming to Optimizely SaaS CMSBack in June I released <a style="color: rgb(224, 62, 45);" href="/link/9ad65182172c47689f5e21a8f01f781b.aspx">Content Transfer</a> on the Optimizely nuget feed – today I’m <a style="color: rgb(224, 62, 45);" href="https://nuget.optimizely.com/packages/mp.dxpcontenttransfer/">releasing version 1.0</a>, because we’ve had it running out in the wild for a while now and nobody has shouted that it’s done anything other than work as expected and hasn’t destroyed any content. So, I’m a happy boy. Related to this news, I’ve spent some of the last month porting a lot of that work over to Optimizely SaaS, working on the new OCP UI extension framework that’s being released later this year.  Content Transfer SaaS allows you to move content that you've authored in one enviroment easily to one of your other environments, without the need of Admin's Export and Import tools. It works in almost exactly the same way as the PaaS tool – albeit with a few extra bells and whistles for the SaaS experience – in that you set your environments up (in the Connect Platform, as opposed to CMS settings), then wherever you are viewing content (experiences, pages, blocks, images...) in the CMS you have the option to send it to one of your other configured environments. Easy peasy. You’ll hopefully have roughly the same tree across environments and so a like for like transfer will be possible, but if you don’t then Content Transfer will do its best to locate where the content is supposed to land, and if it gets it wrong (or right), it offers you the option to re-position your content into a completely different place if needed.  <img src="/link/ef28d5111496493c8e319ca932aaceaa.aspx" width="194" height="316" border="0" /> As for bells and whistles, you can now transfer locales, content types, property groups and display templates as well as content! All in all, I've been quite impressed with the SaaS OCP UI extensions, and it has been remarkable easy to get my PaaS extension over into SaaS, and looking forwards to it being available on the OCP UI ecosystem - so now we must wait patiently for Optimizely to release SaaS OCP UI extensions to the public (presumably around Opticon?) and hope that their pricing model for custom extensions isn't too eye watering. 2026-08-23T15:04:53.0000000Z

Blog post

Improving Optimizely Product Information in LLM ToolsTools like Claude Code can be great for working with Optimizely CMS, but when they index outdated or incomplete information about developing a website, it can lead to wasted time and money. Building a custom documentation skill can help LLM tools return correct answers about Optimizely products without constant course correction from the developer.2026-08-21T18:33:22.0000000Z

Blog post

How to Get a Bacpac Out of DXP (And Never Do It By Hand Again)Every Optimizely DXP project eventually runs into the same task: getting production data onto a local machine so you can actually troubleshoot something. Real content. Real catalog data. Real edge cases that no seed script ever thinks to include. At first, most teams handle it the same way. Someone logs into the portal, downloads a couple of multi-gigabyte files, runs SqlPackage from memory, and hopes nothing goes sideways. After doing that enough times myself, I automated the process by teaching an AI coding agent the entire workflow and packaging it as a Claude Code skill. This post walks through where bacpacs actually come from in DXP, how we retrieve them, and what the skill does once it has them. <h2>Why bother with real data locally at all?</h2> The case for it Seed data lies to you. It's clean, it's small, and it never contains the malformed catalog entry or orphaned content reference that's sitting in production right now waiting to expose a problem you haven't seen yet. Restoring epicms and epicommerce from an actual DXP export gives you the real shape of the data: actual row counts, weird nulls, years-old content nobody has touched, and all the other surprises that come with a live system. The only downside is that the process is tedious enough that most teams don't do it nearly as often as they should. That's the part worth automating. This also turned out to be a great use case for an AI coding agent because the process is mostly orchestration. None of the individual steps are difficult, but there are enough of them that it's easy to miss one when you're doing it manually. <h2>Where do bacpacs actually come from on DXP?</h2> <h3>1. The portal, by hand</h3> DXP's PaaS portal has a Troubleshoot page for each project where you can request and download a database export directly. This is where most teams start: log in, select an environment, wait for the export, and download it. It works. It's also the slowest option because every step requires manual interaction. <h3>2. The morning export, automated</h3> On our project, a separate Azure DevOps release pipeline already generates fresh epicms and epicommerce bacpacs every morning and writes them into a DXP blob storage container. That container has a container-scoped SAS token stored in the release definition variables with read and list permissions. As long as the token is refreshed periodically, grabbing the latest backups is as simple as: <pre><code class="language-powershell">./tools/get-dxp-backups.ps1 # -OutDir <dir> optional; defaults to Downloads</code></pre> No Entra ID login. No portal navigation. No API credentials. The script lists the container, finds the newest epicms* and epicommerce* blobs, and downloads both. If your project already has a similar nightly export pipeline, it's worth looking through the release variables. You may already have everything you need. <h3>3. A fresh export, on demand</h3> Sometimes the overnight export isn't fresh enough. Maybe you're trying to verify whether today's deployment already ran, or you need data that changed recently. In those cases, the EpiCloud PowerShell module can trigger a brand-new export directly from a DXP environment: <pre><code class="language-powershell">Import-Module EpiCloud $ctx = @{ ClientKey = $key ClientSecret = $secret ProjectId = $projectId } $export = Start-EpiDatabaseExport ` @ctx ` -Environment 'Production' ` -DatabaseName 'epicms' ` -RetentionHours 24 # Poll Get-EpiDatabaseExport until status is 'Succeeded', # then download $status.downloadLink</code></pre> This approach requires DXP API credentials created under Project → Settings → API in the DXP portal. It also takes longer. A production-sized export can take 10 to 30 minutes before a file is even available to download. I generally only use this option when the nightly export isn't fresh enough. <h2>So what does the skill actually do?</h2> Once it has a .bacpac for each database, the skill follows the same workflow every time: <ol> <li>Download the newest pair of bacpacs and display their filenames, sizes, and timestamps.</li> <li>Display the plan before making any changes, including which databases will be affected, which mode will be used, and what will be dropped.</li> <li>Request confirmation when the planned action is destructive.</li> <li>Drop the target databases when running in replacement mode.</li> <li>Import both databases in parallel using SqlPackage /Action:Import.</li> <li>Verify the results using index health checks and sanity row counts against known tables, including tblContent for CMS and CatalogEntry for Commerce.</li> <li>Report freshness information using the source bacpac timestamps so you know exactly how current the restored data is.</li> <li>Clean up the multi-gigabyte bacpac files after the imports have been confirmed successful.</li> </ol> Running the imports in parallel usually means the total time is roughly equal to whichever database takes longer instead of the combined time of both imports. <h2>What can I tell it to do differently?</h2> The skill accepts plain-language instructions and maps them to four independent decisions. <h3>Scope</h3> Restore both databases by default, or restore only: <ul> <li style="font-weight: bold;">cms-only</li> <li style="font-weight: bold;">commerce-only</li> </ul> <h3>Mode</h3> Replace (default) This drops the existing epicms and epicommerce databases and restores into those same database names. Nothing else in your local configuration has to change. Additional, also called keep or side-by-side This imports the bacpacs into new timestamped database names and leaves your existing databases untouched. It's useful when you're in the middle of something and don't want to disrupt whatever you're currently working on. <h3>Source</h3> blob (default) This uses the automated morning export from blob storage. fresh-export This generates a new export directly from DXP, optionally from Production, Preproduction, Integration, or another environment. <h3>Confirmation</h3> Destructive operations always request confirmation unless you explicitly say something like: <ul> <li><q>just do it</q></li> <li><q>force</q></li> <li><q>don't wait for confirmation</q></li> </ul> So a request like: <blockquote> Refresh my local databases. </blockquote> runs the full default workflow. While: <blockquote> Restore commerce only from Preproduction and don't ask. </blockquote> does exactly that. Same skill. Same guardrails. Different scope. <h2>How fast is this, really?</h2> A production-sized import is still a heavy operation. Every index gets disabled before the bulk load and rebuilt afterward. The biggest performance improvements come from a few places. <h3>Run both restores in parallel</h3> This is already the default behavior. The CMS and Commerce imports run at the same time, so the total duration is based mostly on whichever import takes longer. <h3>Tune SQL Server once</h3> A few local SQL Server configuration changes can help every subsequent restore: <ul> <li>Configure the model database with simple recovery and appropriately sized files so new databases don't immediately run into autogrow stalls.</li> <li>Pre-size tempdb to avoid unnecessary growth during the index rebuild phase.</li> <li>Increase max degree of parallelism so index rebuild operations can use the available CPU resources.</li> </ul> <h3>Monitor progress</h3> Instead of staring at a blank terminal window, the bundled progress watcher follows the import logs and displays progress by phase: <ul> <li>Download</li> <li>Data import</li> <li>Index rebuild</li> </ul> That doesn't turn a multi-gigabyte restore into a five-minute operation. It does mean the twenty-something minutes it takes no longer require constant supervision. <h2>Worth stealing for your own project?</h2> None of this is particularly Optimizely-specific. Under the covers, it's a blob storage container, an Azure DevOps pipeline variable, and a PowerShell wrapper around SqlPackage. What makes it worthwhile on a DXP project is that almost every team already has this process. The problem is that it's often tribal knowledge. One person knows where the exports live. Another remembers the right SqlPackage switches. Everybody else ends up asking the same questions every few months. Turning <q>How do I get fresh production data locally?</q> into a reusable skill means that knowledge lives in the repository instead of in somebody's head. Anyone on the team can use it, and the process stays consistent every time. If your project already has a nightly export pipeline, go check the release variables before building anything from scratch. There's a decent chance you've already got most of what you need.2026-08-20T20:59:49.0000000Z

Blog post

Error FK_tblContentSoftlink_tblPropertyDefinition in CMSExample Error : <div> Microsoft.Data.SqlClient.SqlException (0x80131904): The DELETE statement conflicted with the REFERENCE constraint "FK_tblContentSoftlink_tblPropertyDefinition". The conflict occurred in database "XYZ-epicms", table "dbo.tblContentSoftlink", column 'fkOwnerPropertyDefinitionID'.</div>   Description: This is happening because you’re attempting to remove a property definition, and during model sync on initialization, it tries to delete that row from tblPropertyDefinition. However, there are still rows in tblContentSoftlink that reference this property definition.   First, I will ask you to try "Restart one instance at a time" from the "Troubleshoot" tab of the PAAS Portal and check again.   If the issue continues, this query will give you all property definitions that have rows in tblContentSoftlink, along with their property definition type: <pre><code>SELECT * FROM tblPropertyDefinition pd INNER JOIN tblPropertyDefinitionType pdtype ON pdtype.pkid = pd.fkPropertyDefinitionTypeID WHERE EXISTS ( SELECT 1 FROM tblContentSoftlink cs WHERE cs.fkOwnerPropertyDefinitionID = pd.pkid );</code></pre> Once you know the property definition to remove, you can delete the dependent softlink rows first (replace <code>X</code> with the <code>pkid</code> of the property definition): <pre><code>DELETE FROM tblContentSoftlink WHERE fkOwnerPropertyDefinitionID = X;</code></pre>   After that, the modelsync should be able to remove the property definition.   I’d recommend testing this locally first, using a copy of the preproduction database, to ensure it behaves as expected.2026-08-20T11:58:26.0000000Z

Blog post

Get count of pages, blocks , Assets from the CMS.The following queries retrieve details from the CMS database. Make sure to try these queries locally first.    Step 1 — Discover your content type bases first: <pre><code>``` SELECT Base, COUNT(*) AS TypeCount FROM tblContentType GROUP BY Base ORDER BY TypeCount DESC; ```</code></pre> Step 2 — Count all content grouped by base type (single query): <pre><code>``` SELECT ct.Base AS ContentBase, ct.Name AS ContentTypeName, COUNT(c.pkID) AS ContentCount FROM tblContent c INNER JOIN tblContentType ct ON c.fkContentTypeID = ct.pkID GROUP BY ct.Base, ct.Name ORDER BY ct.Base, ContentCount DESC; ```</code></pre> Step 3 — Individual counts per category: <pre><code>``` -- Pages SELECT COUNT(*) AS PageCount FROM tblContent c INNER JOIN tblContentType ct ON c.fkContentTypeID = ct.pkID WHERE ct.Base = 'Page'; -- Blocks SELECT COUNT(*) AS BlockCount FROM tblContent c INNER JOIN tblContentType ct ON c.fkContentTypeID = ct.pkID WHERE ct.Base = 'Block'; -- Images (adjust base value based on Step 1 results) SELECT COUNT(*) AS ImageCount FROM tblContent c INNER JOIN tblContentType ct ON c.fkContentTypeID = ct.pkID WHERE ct.Base = 'Image'; -- Documents / Files SELECT COUNT(*) AS DocumentCount FROM tblContent c INNER JOIN tblContentType ct ON c.fkContentTypeID = ct.pkID WHERE ct.Base IN ('File', 'Video', 'Media'); ```</code></pre>2026-08-20T11:52:59.0000000Z

Blog post

Optimizely CMP Login Failure After Enabling SSO – The Certificate Mismatch That Locked Everyone OutRecently, our team faced a production issue where users suddenly lost access to Optimizely CMP, Opti ID Admin Center, and the Optimizely Support Portal. The... The post <a href="https://madhuanbalagan.com/optimizely-cmp-login-failure-after-enabling-sso-the-certificate-mismatch-that-locked-everyone-out">Optimizely CMP Login Failure After Enabling SSO – The Certificate Mismatch That Locked Everyone Out</a> appeared first on <a href="https://madhuanbalagan.com">Madhu Anbalagan's Blog</a>. 2026-08-19T01:45:00.0000000Z

Blog post

Upgrade Optimizely CMS 12 to .NET 10If you are still running CMS 12 on .NET 8, it's time to upgrade!2026-08-17T11:57:17.0000000Z

Blog post

What Your Optimizely DXP Is Serving to AI Crawlers - and the Three Levers You Actually HaveUnblocked bot traffic on Optimizely DXP is a billable page view, and the Cloudflare zone in front of your site is not yours to configure. Three levers remain: robots.txt, Optimizely Support, and bringing your own Cloudflare zone (Orange-to-Orange) for AI Crawl Control. Plus the trap in Cloudflare's July 2026 change, where blocking Training also blocks Googlebot, Applebot and BingBot.2026-08-17T00:00:00.0000000Z

Blog post

Migrating from AEM to Optimizely SaaS CMS: Solving the Architectural HurdlesMigrating a digital footprint from Adobe Experience Manager (AEM) to Optimizely SaaS CMS is a major milestone for any enterprise modernizing its digital experience platform. When you are dealing with years of accumulated legacy content spanning a large number of pages, it is tempting to treat this purely as a volume problem. In reality, bulk loading data is the easy part. The real challenge lies in the architectural differences between how AEM and Optimizely SaaS CMS represent content structure, localization, and identity. In this article, we will bypass the generic advice and focus on the high-stakes architectural hurdles you will encounter during an AEM-to-Optimizely migration — and how to solve them programmatically using the Optimizely SaaS CMS REST API. <hr /> <h2>The Sanity Checks: Start Simple</h2> Before writing migration scripts or converting templates, always begin with a few basic sanity checks on your source JCR (Java Content Repository) data. Running these early prevents major pipeline failures later: <ol class="tight"> <li> Clean up the ROT: Run an analysis in AEM to find Redundant, Outdated, and Trivial content. Look for pages with zero traffic over the last 12 months, expired pages (where offTime is in the past), or duplicate assets. Retiring this content before migrating saves significant engineering, QA, and content-review effort. </li> <li> Verify target locales: Make sure all languages used in your AEM tree are explicitly registered in your Optimizely SaaS CMS instance before pushing content. Attempting to load localized content into an unregistered locale will cause API errors. </li> </ol> Once your basic environment is ready, you can tackle the primary architectural shifts. <hr /> <h2>Architectural Hurdle 1: Parallel Trees vs. The Single-Node Localization Model</h2> One of the deepest conceptual mismatches between AEM and Optimizely is how they handle multi-language websites. <h3>The Problem</h3> AEM organizes languages using parallel folder trees. Under /content/mysite, you might have /en for English and /fr for French. These are completely separate nodes in the JCR, linked together externally via Multi-Site Manager (MSM) or Language Copy. If a French page exists under /content/mysite/fr/about but has no English equivalent under /content/mysite/en/about, AEM is perfectly happy. Optimizely SaaS CMS uses a single-node localization model. A content item is represented by a single unique key. That single node has a primaryLocale — the master language — established permanently at creation. Any additional languages (such as French) exist as locale branches hanging off that same single node. If your client's stated intent is that English must be the master language, but your discovery analysis reveals that a meaningful portion of regional pages or folders have no English equivalent, you have a structural conflict. You cannot create a French translation branch in Optimizely if the master English node does not exist. <h3>The Solution: The Unpublished English Draft Shell</h3> To keep a consistent English-master model without publishing placeholder or machine-translated English content that regional teams never requested, use the Unpublished English Draft Shell pattern. When your migration pipeline encounters a French page with no English sibling, the loader should: <ol class="tight"> <li> Create the content item with English (en) set as the master locale, carrying only non-localized properties and a fallback display name. Keep this version as an unpublished draft. </li> <li> Create the French version (fr) as a translation branch on that same key and publish it. </li> </ol> Here is the two-step API flow: <h4>Step 1: Create the master item in English (Unpublished Draft)</h4> <pre class="code-block"><code class="language-json">POST https://api.cms.optimizely.com/v1/content Content-Type: application/json { "key": "5f2b9c1e-4a7d-4b8e-9c0d-1a2b3c4d5e6f", "contentType": "standardPage", "container": "parent-container-guid", "initialVersion": { "displayName": "About Us (FR Source — Master Shell)", "locale": "en", "properties": { "heading": { "value": "Placeholder English Title" } } } }</code></pre> <h4>Step 2: Post the real French version to the same key</h4> <pre class="code-block"><code class="language-json">POST https://api.cms.optimizely.com/v1/content/5f2b9c1e-4a7d-4b8e-9c0d-1a2b3c4d5e6f/versions Content-Type: application/json { "displayName": "À propos", "locale": "fr", "properties": { "heading": { "value": "À propos de nous" } } }</code></pre> After verifying the version was created, publish it: <pre class="code-block"><code class="language-http">POST https://api.cms.optimizely.com/v1/content/5f2b9c1e-4a7d-4b8e-9c0d-1a2b3c4d5e6f/versions/1:publish</code></pre> This ensures your public-facing site remains clean, while maintaining a consistent and governable data model behind the scenes. Editors will see an empty English draft in the CMS — make sure your editorial team is briefed on this pattern so it does not cause confusion post-migration. <hr /> <h2>Architectural Hurdle 2: Making the Migration Re-runnable with Deterministic Keys</h2> Migrations are rarely a one-and-done big bang. You will run dry runs, test waves, and delta syncs. <h3>The Problem</h3> If your migration loader relies on the target CMS to auto-generate random IDs upon creation, you lose idempotency immediately. If a script fails halfway through, running it again will result in duplicate pages, orphaned assets, and broken references. Maintaining a large lookup table mapping old AEM paths to new random GUIDs is fragile and prone to synchronization errors across environments. <h3>The Solution: Deterministic Key Generation (UUID v5)</h3> Optimizely SaaS CMS allows you to supply your own key (a valid UUID/GUID format) inside the request body when creating content. You can exploit this by generating a deterministic UUID v5. UUID v5 uses a SHA-1 hash combining a fixed namespace UUID with a unique input string. In your migration pipeline, use AEM's highly stable jcr:uuid as the input name: <pre class="code-block"><code>optimizely_key = uuidv5(MIGRATION_NAMESPACE_UUID, aem_jcr_uuid)</code></pre> Because jcr:uuid is unique and survives page moves or renames inside AEM, your migration pipeline will generate the exact same Optimizely key every single time it processes a given item — on any machine, in any environment, with no coordination required. This gives you native idempotency: <ul class="tight"> <li> If the item already exists in Optimizely, your script performs a PATCH update. </li> <li> If it does not exist, it performs a POST to create it. </li> <li> If you need to roll back a wave, your script knows exactly which keys to target for hard deletion. </li> </ul> <hr /> <h2>Architectural Hurdle 3: Content Type Immutability and the "Reparent & Swap" Pattern</h2> During discovery, you classify AEM pages into Optimizely content types — some remain Pages, others (such as Experience Fragments or non-routed pages) become Shared Blocks. <h3>The Problem</h3> What happens if you load an item as a Page, and the editorial team identifies during UAT that it should have been a Shared Block? In Optimizely, an item's contentType is immutable once created. You cannot change a Page to a Block because they inherit from different base classes and are stored differently by the platform — Pages have URL routing and hierarchy placement, Blocks do not. There is no API endpoint that converts one to the other. Furthermore, if that incorrectly typed item is a parent container with a large number of correct children sitting beneath it, a hard delete of the parent will cascade and destroy all those child nodes. <h3>The Solution: The "Reparent & Swap" Pattern</h3> Rather than destroying and rebuilding the entire child hierarchy, execute an architectural swap via the REST API: <ol class="tight"> <li> Create a temporary holding folder elsewhere in your content tree. </li> <li> Move all children by updating each child's container property via a PATCH request to point to the temporary holder. </li> <li> Hard-delete the now-empty parent, passing the special cms-permanent-delete header to release the key immediately rather than moving it to the Trash: </li> </ol> <pre class="code-block"><code class="language-http">DELETE https://api.cms.optimizely.com/v1/content/bad-parent-guid cms-permanent-delete: true</code></pre> <ol class="tight"> <li> Recreate the parent using the exact same GUID key, this time supplying the correct contentType. </li> <li> Move the children back by patching each child's container to point to the original GUID. </li> <li> Hard-delete the temporary folder to leave no trace. </li> </ol> This pattern preserves every child's GUID, version history, regional locale branches, and any inbound content references from other pages — because none of that data was touched. <hr /> <h2>Architectural Hurdle 4: Applying the Swap Pattern to Language Versions</h2> The Reparent & Swap concept extends naturally to localization issues, and this is where it becomes especially powerful during large migrations. There are two distinct language-version scenarios you are likely to encounter. <h3>Scenario A: The "Locale Swap" — Changing the Master Language of a GUID</h3> The primaryLocale of a content item is structurally immutable in Optimizely. If you created a page with English as the master, you cannot call an API to change it to French. However, if the business requires a specific GUID to have French as its master language, you can execute a Locale Swap using a temporary item — preserving the original GUID so all inbound links remain intact. <h4>The Process</h4> <pre class="code-block"><code>[Original: GUID_A] [Temp: GUID_T] [Restored: GUID_A] Master: EN Master: FR (copy) Master: FR Branch: FR Branch: EN (copy) Branch: EN │ ▲ ▲ └── Read all properties ────────┘ │ └── Hard-delete GUID_A │ └── Recreate GUID_A with FR as master ─────────────────────┘ └── Hard-delete GUID_T</code></pre> <h4>The API Steps</h4> Step 1 — Read all version properties for both en and fr from the original item and hold them in your script. Step 2 — Create a temporary item with French as the primaryLocale: <pre class="code-block"><code class="language-json">POST https://api.cms.optimizely.com/v1/content { "key": "temp-guid", "contentType": "standardPage", "container": "temp-holding-folder-guid", "initialVersion": { "displayName": "Temp Shell", "locale": "fr" } }</code></pre> Step 3 — Hard-delete the original item to release GUID_A: <pre class="code-block"><code class="language-http">DELETE https://api.cms.optimizely.com/v1/content/GUID_A cms-permanent-delete: true</code></pre> Step 4 — Recreate GUID_A with French as the master locale and all original French content restored. Step 5 — Create the English translation branch on GUID_A with the original English content. Step 6 — Publish according to the original publication state. Step 7 — Hard-delete the temporary item. The result: GUID_A now has French as its primaryLocale, English as its translation branch, and every page in the system that referenced GUID_A is completely unaware that anything changed. <hr /> <h3>Scenario B: The "Branch Swap" — Moving a Translation to the Correct Parent</h3> In large migrations, AEM's parallel language trees can be misaligned during the bulk load — the French version of Page X ends up attached to Page Y as a locale branch instead. Since locale branches are bound to a specific GUID, you cannot directly reparent them. You must use a Read-Write-Delete approach. <h4>The API Steps</h4> Assume French (fr) is incorrectly sitting on Page_A but belongs on Page_B. Step 1 — Read the French version's full property data from Page_A: <pre class="code-block"><code class="language-http">GET https://api.cms.optimizely.com/v1/content/Page_A/versions?locale=fr</code></pre> Step 2 — Create a new French version branch on Page_B using the properties retrieved in Step 1: <pre class="code-block"><code class="language-json">POST https://api.cms.optimizely.com/v1/content/Page_B/versions Content-Type: application/json { "displayName": "French Title", "locale": "fr", "properties": { ... } }</code></pre> Step 3 — Publish the new French branch on Page_B if the original was published: <pre class="code-block"><code class="language-http">POST https://api.cms.optimizely.com/v1/content/Page_B/versions/{newVersionId}:publish</code></pre> Step 4 — Delete the incorrect French locale branch from Page_A. Locale branch deletion is immediate and irreversible — it does not go to Trash — which is exactly the behavior you need here: <pre class="code-block"><code class="language-http">DELETE https://api.cms.optimizely.com/v1/content/Page_A/locales/fr</code></pre> <blockquote> Important note on locale deletion: Because deleting a locale branch is permanent with no recovery path, always verify that Step 2 and Step 3 have succeeded and the content is correctly visible in the target before executing Step 4. Build a mandatory verification check into your migration script before it fires the delete. </blockquote> <hr /> <h2>Building These Patterns into Your Migration Toolbox</h2> All four patterns described above share a common foundation: <ul class="tight"> <li> A Migration State Database that tracks every AEM node's original jcr:uuid, its deterministic Optimizely key, its content archetype, and its load status. </li> <li> A purge/rollback mode in your loader that can fire cms-permanent-delete against a wave's key set — gated behind an explicit flag and environment check so it can never be accidentally pointed at production. </li> <li> Structured logging with a run ID on every API call, so any partial failure can be diagnosed and resumed rather than restarted. </li> </ul> When these utility scripts exist from day one of your migration build, structural corrections that would otherwise cost days of manual recovery become a 20-minute scripted operation. <hr /> <h2>Conclusion</h2> The architectural gap between AEM and Optimizely SaaS CMS is real, but it is entirely solvable with deliberate engineering. By designing your localization strategy around a consistent master language model, generating deterministic UUIDs to make your pipeline re-runnable, treating content type immutability as a design constraint rather than a blocker, and having the Locale Swap and Branch Swap patterns ready as operational utilities, you give your migration the resilience it needs to handle edge cases without unplanned rework. Have you encountered similar structural challenges during platform migrations? Drop your experience in the comments below — the community would love to hear how you approached them. <hr /> If you enjoyed this technical breakdown, you’ll like my monthly newsletter, <a class="_4n13zc _1l4j4nae _1q9ygi7 _4ivg92 _12zsz04 _4n13zc" href="https://www.linkedin.com/newsletters/pragmatic-judgement-7487084233719549953/">Pragmatic Judgement</a>. I write about where technical decisions meet real operational constraints for tech and delivery leaders.2026-08-16T04:25:04.0000000Z

Blog post

You’re not headless. You’re hybrid — and that’s the CMS 12 default.For CMS 12 / Commerce teams with a React (or similar) storefront who keep hearing “just go headless” or “just move to Graph.” This is Part 1 of Find → Graph: the hybrid storefront. Optimizely CMS 12 sites that look “headless” in the browser are usually hybrid. Editors still work in the CMS. Catalog still lives in Commerce. Preview and on-page edit still need a server-rendered page. React (or similar) is a storefront shell, not the system of record. If you skip that, CMS 13 + Optimizely Graph feels like a frontend rewrite. It isn’t. Graph replaces Search & Navigation (Find) as the query/index layer. It does not replace: <ul> <li>Content types and <code>IContentRepository</code></li> <li>Commerce catalog, pricing, and cart</li> <li>Edit mode and preview</li> <li>Your React / SSR host</li> </ul> <h2>Three layers people mix up</h2> <table> <thead> <tr> <th>Layer</th> <th>CMS 12 today</th> <th>After Graph / CMS 13</th> </tr> </thead> <tbody> <tr> <td>Authoring</td> <td>CMS UI, content types</td> <td>Still CMS</td> </tr> <tr> <td>Storefront</td> <td>Razor + React / Content Delivery API</td> <td>Same hybrid, or more CDA</td> </tr> <tr> <td>Search and listings</td> <td>Find (<code>IClient</code>, facets, conventions)</td> <td>Optimizely Graph</td> </tr> </tbody> </table> Content Delivery API is content over HTTP. Find/Graph is query, facet, rank, and index. Using CDA as your product-listing search is how teams paint themselves into a corner. <h2>A hybrid shape that survives Graph</h2> <ol> <li>CMS/Commerce owns content and catalog.</li> <li>A thin .NET host does auth, cart, preview, and first paint (SSR).</li> <li>React hydrates listing / PDP / checkout islands.</li> <li>Listings talk to a query module (<code>IProductSearch</code>, <code>IPageSearch</code>) — not <code>IClient</code> in 40 controllers.</li> </ol> That last point is the migration. Find behind a port → Graph is an adapter. Find in every controller → Graph is a rewrite. <pre><code>public interface IProductSearch { Task<ProductSearchResult> SearchAsync( ProductSearchRequest request, CancellationToken cancellationToken); } // CMS 12: Find adapter implements this. // CMS 13: Graph adapter implements this. // Controllers and React never take a dependency on IClient. </code></pre> <h2>Do this before</h2> <ul> <li>Draw the line: CDA vs Find vs <code>IContentLoader</code>.</li> <li>Put Find behind interfaces (search, facets, paging).</li> <li>Don’t let React own search URLs the server doesn’t know.</li> <li>Measure three numbers: time from publish until the listing shows the new item in Find; listing p95; percent of searches with zero hits.</li> </ul> This is Part 1 of Find → Graph: the hybrid storefront. Next: typed Find query builders, facets, and <code>GetContentResultAsync</code> — so a Graph adapter can sit beside them later.2026-08-13T14:38:03.0000000Z

Blog post

Stott Security for Optimizely SaaS CMS<h2>Introduction</h2> <a href="https://www.stott.pro/article/getting-started-with-stott-security">Stott Security</a> has been helping developers and editors manage Content Security Policies and security headers on Optimizely PaaS CMS for several years. Today I am pleased to share an early access release of Stott Security for Optimizely SaaS CMS: a complete rebuild designed for Optimizely’s composable platform, built on the Optimizely Connect Platform (OCP) and rendered inside the CMS using CMS UI Extensions. <h2>A Complete Rebuild</h2> Optimizely SaaS CMS does not give you a web server to install a NuGet package into, so the add-on model that has served the PaaS version so well simply does not exist there. Instead, extensions are built as apps on the Optimizely Connect Platform and surface their interfaces inside the CMS using CMS UI Extensions. Stott Security for SaaS is exactly that: an OCP app that adds a full-page security console to your CMS and serves your compiled headers to your site’s front end from a public endpoint. Everything about this implementation lives in OCP, and the data belongs to your installation. Entity Framework and SQL Server are gone; configuration is now held in OCP’s key value storage. This is a much simpler data store, and it does mean some functional changes — relational features of the PaaS version such as the audit history and per-page policies have not carried across. I have set out an honest comparison in the feature parity table below. What has carried across is the engine. The header compilation engine is a faithful TypeScript port of the C# engine that powers the PaaS add-on, cross-validated against the original so that both products produce the same output. That includes the automatic optimisation and splitting of oversized Content Security Policies across multiple headers so that your policy stays within browser and webserver limits. The rebuild was also an opportunity to add something the PaaS version has never had: a draft and publish workflow. Changes are saved as a draft, and nothing reaches your site until you press Publish. Publishing compiles your configuration once and stores the result, so the endpoint your front end calls is a single fast read with no compilation on the hot path. The console always shows you when the live configuration went live and whether unpublished changes exist. <h2>What You Get Today</h2> The console is split into four tabs: Response headers, Content Security Policy, Preview and Tools. The Response headers tab covers eight standard security headers — including X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Strict-Transport-Security and the Cross-Origin family — each with a plain-English description, a behaviour of Add, Remove or Disabled, and a preview of exactly what will be emitted. You can also add your own custom headers. <img src="https://www.stott.pro/assets/stott-security-saas-response-headers-screen.png" alt="The Response headers tab of Stott Security for Optimizely SaaS CMS, showing standard security headers with behaviour, value and preview options." /> The Content Security Policy tab uses the same source-first model as the PaaS version: you manage a list of sources — domains, schemes, keywords, hashes and the 'nonce-random' placeholder — and grant each source the directives it needs. The Settings section lets you run the policy in report-only mode, upgrade insecure requests and send violation reports to an external collector, while the Sandbox section provides switches for the fifteen sandbox permissions. <img src="https://www.stott.pro/assets/stott-security-saas-csp-sources-screen.png" alt="The Content Security Policy Sources tab of Stott Security for Optimizely SaaS CMS, showing sources and the directives granted to each." /> The Preview tab shows your headers in three views: Pending shows what publishing your current draft would produce, Live shows what your site’s head is being served right now, and Integration provides the endpoint for your installation together with a worked example of applying the headers. A diagnostics panel also sits above the console, warning you when a policy is approaching size limits, has been split, or has been dropped entirely. <img src="https://www.stott.pro/assets/stott-security-saas-preview-screen.png" alt="The Preview tab of Stott Security for Optimizely SaaS CMS, showing the live headers currently being served to the site head." /> Finally, the Tools tab provides import and export of the complete configuration as JSON. This matters more on SaaS than it ever did on PaaS: the configuration is held by the app installation, so uninstalling the app deletes it. Keep an exported copy somewhere outside of Optimizely. <img src="https://www.stott.pro/assets/stott-security-saas-tools-screen.png" alt="The Tools tab of Stott Security for Optimizely SaaS CMS, showing the export of the complete configuration as JSON." /> <h2>Feature Parity</h2> A complete rebuild on a much simpler data store means this is not a feature-for-feature copy of the PaaS add-on. Some features have not carried across, some are on the roadmap, and a couple of things are new to the SaaS product. <table> <thead> <tr> <th>Feature</th> <th>PaaS</th> <th>SaaS</th> <th>SaaS Roadmap</th> </tr> </thead> <tbody> <tr> <td>CSP sources & directives</td> <td>✔</td> <td>✔</td> <td>-</td> </tr> <tr> <td>CSP Keyword, scheme, hash & nonce sources</td> <td>✔</td> <td>✔</td> <td>-</td> </tr> <tr> <td>CSP Report-only mode & upgrade insecure requests</td> <td>✔</td> <td>✔</td> <td>-</td> </tr> <tr> <td>CSP sandbox</td> <td>✔</td> <td>✔</td> <td>-</td> </tr> <tr> <td>CSP Automatic policy splitting & optimisation</td> <td>✔</td> <td>✔</td> <td>-</td> </tr> <tr> <td>External violation reporting</td> <td>✔</td> <td>✔</td> <td>-</td> </tr> <tr> <td>Internal violation reporting (Violations tab)</td> <td>✔</td> <td>✘</td> <td>No current plans</td> </tr> <tr> <td>Remote CSP Allow List</td> <td>✔</td> <td>✘</td> <td>No current plans</td> </tr> <tr> <td>Per-page CSP sources</td> <td>✔</td> <td>✘</td> <td>No current plans</td> </tr> <tr> <td>Standard & custom response headers</td> <td>✔</td> <td>✔</td> <td>-</td> </tr> <tr> <td>CORS settings</td> <td>✔</td> <td>✘</td> <td>No current plans</td> </tr> <tr> <td>Permissions Policy</td> <td>✔</td> <td>✘</td> <td>Planned</td> </tr> <tr> <td>Security.txt files</td> <td>✔</td> <td>✘</td> <td>No current plans</td> </tr> <tr> <td>Global / Application / Host contexts</td> <td>✔</td> <td>Global only</td> <td>Planned</td> </tr> <tr> <td>Header preview</td> <td>✔</td> <td>✔</td> <td>-</td> </tr> <tr> <td>Draft & publish workflow</td> <td>✘</td> <td>✔</td> <td>-</td> </tr> <tr> <td>Audit history</td> <td>✔</td> <td>✘</td> <td>No current plans</td> </tr> <tr> <td>Import & export</td> <td>✔</td> <td>✔</td> <td>-</td> </tr> <tr> <td>Headless headers API</td> <td>✔</td> <td>✔</td> <td>-</td> </tr> <tr> <td>Headless middleware for your head</td> <td>Build your own</td> <td>Build your own</td> <td>Planned package</td> </tr> </tbody> </table>   The biggest omissions follow directly from the storage model: without relational data there is no audit trail, and violation reports are sent to an external collector rather than being stored and summarised inside the CMS. The draft and publish workflow, together with the export tooling, are the counterweights — you can always see what is live and when it went live, and you can keep copies of your configuration outside the platform. On the roadmap, Application and Host level contexts are a firm commitment — the storage model was designed for them from day one — alongside Permissions Policy management and a distributable middleware package for your front end. <h2>Plugging It Into Your Headless Solution</h2> Every Optimizely SaaS CMS solution is a headless solution, so applying the headers is always the responsibility of your front end. Your head requests the compiled headers from the endpoint shown on the Integration view of the Preview tab and applies them to its responses.  An example response looks like this: <pre><code class="language-JSON">{ "headers": [ { "key": "Content-Security-Policy", "value": "default-src 'self';...", "isRemoval": false, "isReplacement": false }, { "key": "X-Content-Type-Options", "value": "nosniff", "isRemoval": false, "isReplacement": true }, { "key": "server", "value": "", "isRemoval": true, "isReplacement": false } ], "publishedAt": "2026-08-12T00:06:28.000Z", "cacheSeconds": 300 } </code></pre> Each entry in the headers collection uses the same structure as the PaaS Header Listing API, so a consumer only needs to implement three behaviours: <ul> <li>When isRemoval is true: remove the header from your response.</li> <li>When isReplacement is true: set the header, replacing any existing value.</li> <li>Otherwise: append the header to your response. The Content Security Policy is served this way because a large policy may legitimately be split across multiple headers.</li> </ul> Your front end has two further responsibilities: replace the 'nonce-random' placeholder with a fresh value on every request, and add the nonce="random" attribute to script and style elements. If you want to see what this looks like in practice, <a href="https://www.linkedin.com/in/minesh-shah-dev/">Minesh</a> has written an excellent walkthrough of building exactly this middleware in Next.js for the PaaS version of Stott Security: <a href="/link/27bc4af218b148caac6aab1e14871b00.aspx">Dynamic CSP Management for Headless and Hybrid Optimizely CMS with Next.js</a>. Because the header structure is identical, the same middleware approach carries straight over to the SaaS product. The only difference is the envelope: the PaaS API returns a bare array while the SaaS endpoint wraps the array in an object, so a one-line check such as Array.isArray(body) ? body : body.headers allows a single middleware implementation to serve both products. <h2>Get Involved</h2> Stott Security for Optimizely SaaS CMS is in early access, and this is exactly the right time to influence its direction. I would love to hear how you would plug this into your own SaaS headless solution: which framework does your head run on, would the planned middleware package be useful to you, and which of the missing features matter most to your builds? Like the PaaS add-on, Stott Security for SaaS is free and open source under the MIT licence. If you would like to try it against your own Optimizely SaaS CMS instance then <a href="https://github.com/GeekInTheNorth/Stott.Security.Optimizely.SaaS/discussions/1">join the Discussion</a>. If you want to help shape what comes next, please <a href="https://github.com/GeekInTheNorth/Stott.Security.Optimizely.SaaS">raise an issue on the Stott Security for SaaS GitHub repository</a> — feature requests, integration questions and early access requests are all welcome there. <hr /> I'm a Platinum Optimizely MVP and the maintainer of two open source add-ons: Stott Security for <a href="https://github.com/GeekInTheNorth/Stott.Security.Optimizely.SaaS">SaaS CMS</a> and <a href="https://github.com/GeekInTheNorth/Stott.Security.Optimizely">PaaS CMS 12 & 13</a>, and <a href="https://github.com/GeekInTheNorth/Stott.Optimizely.RobotsHandler">Stott Robots Handler</a> for PaaS CMS 12 & 13. All of my writing is collated at <a href="https://www.stott.pro/">https://www.stott.pro</a>.2026-08-13T13:29:29.0000000Z

Blog post

Optimizely XML Resource Builder: A Visual Studio Extension for Language Resource Files Anyone who has worked on a larger Optimizely solution will know the feeling. You add or update a page type, block type, or shared base class,2026-08-13T09:34:42.0000000Z

Blog post

Optimizely SaaS CMS Management API: The Write Side of HeadlessEverything I’ve written in this series so far has been about reading content — Optimizely Graph, webhooks, ISR, caching layers. But at some point you need to actually write content programmatically. Maybe you’re migrating 500 blog posts from WordPress. Maybe you want a seed script that spins up demo content on every fresh CMS instance. […]2026-08-12T21:22:01.0000000Z

Blog post

Assistants, Instructions and StatisticsWe are introducing three new features for AI Assistant in Optimizely CMS. They make it easier to reuse AI expertise, work faster and understand how AI is being used across your website. 2026-08-11T15:46:49.0000000Z

Blog post

Optimizely Commerce 14 Now Supports .NET 10<div> In my previous post, <a href="/link/d15848f947264cc59c3d86b9c7d55c95.aspx">Optimizely CMS 12 Now Fully Supports .NET 10</a>, I noted one remaining limitation: Commerce 14 (Commerce Connect) did not yet support .NET 10, and Commerce customers were advised to stay on .NET 8. I'm happy to report that this gap has now been closed. Commerce 14 officially supports .NET 10 starting with version 14.46.0. 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>. <h2>What's New</h2> <ul> <li>EPiServer.Commerce 14.46.0 – adds official .NET 10 support.</li> <li>EPiServer.Find.Commerce 12.3.0 – supports Commerce 14 running on .NET 10.</li> </ul> If you're using Optimizely Search & Navigation (Find) with Commerce, upgrade both packages together to ensure full compatibility. <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> This means the full Optimizely stack, including both CMS 12 and Commerce 14, can now run on .NET 10. <h2>Why Upgrade?</h2> With .NET 8 and .NET 9 reaching end of support on November 10, 2026, .NET 10 is now the recommended target. As the current LTS release, it provides support through November 2028, along with performance improvements, security updates, and a longer support horizon. <h2>Recommendations</h2> <ul> <li>Upgrade EPiServer.Commerce to 14.46.0 or later before moving to .NET 10.</li> <li>Upgrade EPiServer.Find.Commerce to 12.3.0 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> 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. </div>2026-08-07T02:53:49.0000000Z

Blog post

The Top 10 Things I'm Actually Using AI For<div> 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. 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. 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. Here are the areas where I've gotten the most value from it. <h2>1. Troubleshooting Production Issues</h2> This is the one that changed how I work. 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. 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. 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. <h2>2. Answering the Questions Nobody Has Time For</h2> Every long-running Optimizely implementation develops a backlog of questions that never quite make it onto a sprint. 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? 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. <h2>3. Building Small Projects That Cross Too Many Boundaries</h2> Some of my favorite uses have been side projects that touch several different technologies at once. 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. 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. <h2>4. Arguing With My Own Code</h2> I've gotten into the habit of asking for a deliberately skeptical review before opening a pull request. Not "does this look okay?" but "explain why this is wrong." 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. <h2>5. Writing Better Tests</h2> This is one area where I've learned to be careful. 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. 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. <h2>6. Making Sense of Telemetry</h2> Modern systems generate more telemetry than most developers can realistically consume. 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. The biggest value isn't necessarily the answer itself. It's reducing the amount of time spent looking in the wrong place. <h2>7. Finding the Bugs Nobody Sees</h2> Some problems are obvious once they're found and almost invisible before that. 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. 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. <h2>8. Capturing Institutional Knowledge</h2> Every team has information that exists mostly in people's heads. Environment-specific quirks, deployment lessons, platform limitations, and the odd exceptions that nobody remembers until something breaks. 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. <h2>9. Hardware Troubleshooting</h2> The same approach works surprisingly well outside software development. 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. Being able to feed in the evidence and get a structured analysis has made the process significantly faster. <h2>10. Home Networking and Security</h2> I've also used AI extensively for home networking and security projects. 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. One lesson that carries across both worlds is that asking "what could this reach?" is often more useful than asking "is this secure?" <h2>A Few Things to Watch</h2> AI gets things wrong. Regularly. 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. 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. 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. <h2>Conclusion</h2> If I had to summarize where AI has helped me most, it comes down to three things: <ul> <li>Investigating problems faster.</li> <li>Connecting information across systems.</li> <li>Challenging assumptions before I spend time acting on them.</li> </ul> It hasn't replaced experience, judgment, or critical thinking. Mostly, it's removed a lot of the manual digging that used to sit between noticing a problem and understanding it. </div>2026-08-05T19:24:01.0000000Z

Blog post

Drag-and-Drop Reordering for Commerce Media Collection in Optimizely Commerce ConnectOptimizely Commerce Connect ships a polished asset editor for the CommerceMediaCollection 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. 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. <hr /> <h2>The Property</h2> The CommerceMediaCollection property is declared on EntryContentBase and typed as ItemCollection<CommerceMedia>. Each CommerceMedia item carries a SortOrder 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. <pre><code class="language-csharp">[UIHint("commercemediacollection")] public virtual ItemCollection<CommerceMedia> CommerceMediaCollection { get; set; } </code></pre> 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 SortOrder is written correctly afterward is the implementation work. <hr /> <h2>Approach: Extend, Don't Replace</h2> 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. The widget itself extends CommerceMediaCollectionEditor 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. <hr /> <h2>Step 1 — Register a Custom Editor Descriptor</h2> Optimizely CMS resolves editor descriptors by (TargetType, UIHint) pair. The CommerceMediaCollection property carries [UIHint("commercemediacollection")], so the custom descriptor must declare the same UIHint. EditorDescriptorBehavior.PlaceLast 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. <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> The Dojo AMD path myproject/editors/CommerceMediaDndEditor must resolve to a real file. That means registering a Dojo package called myproject via a protected shell module. modules/_protected/MyProject.Commerce.UI/module.config: <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> Source file tracking: modules/_protected/ is typically gitignored because NuGet restores add-on packages there. Keep your source in a separate tracked directory (e.g. ShellModules/_protected/) and copy it at build time: <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> Explicit module registration: EPiServer Shell 12.x auto-discovery matches module directories to assemblies by name. A module named MyProject.Commerce.UI with no correspondingly-named assembly is skipped. Register it explicitly via IConfigurableModule: <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> Note: Do not set Assemblies in ModuleDetails to your main web assembly. This module is purely client-side (JavaScript + module.config) — no C# shell controllers. Pointing Assemblies 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 Assemblies for client-only modules. </blockquote> <hr /> <h2>Step 3 — The Custom Dojo Widget</h2> The widget has three jobs: <ol> <li> Enable internal row DnD — epi/shell/dnd/Source (the DnD source class used by the grid) does not self-accept by default when accept type strings are configured. Commerce media items don't carry a recognized typeIdentifier, so the type-matching check fails for same-source drops. Wrapping checkAcceptance with dojo/aspect's around restores the standard behaviour for internal drags while leaving external drop handling (adding assets from the DAM) completely unchanged. </li> <li> Write sequential SortOrder values — After a drag, every item needs a SortOrder 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 itemsChanged exactly once with the final correct state. </li> <li> Disable column header sorting — 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 sortable: false prevents this. </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> Place this at ShellModules/_protected/MyProject.Commerce.UI/ClientResources/editors/CommerceMediaDndEditor.js (the MSBuild target copies it to modules/_protected/ at build time). <hr /> <h2>End Result</h2> 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 SortOrder 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. The solution can be applied to any ItemCollection<CommerceMedia> property in the codebase with the correct UIHint. <hr /> <h2>File Checklist</h2> <table> <thead> <tr> <th>File</th> <th>What it does</th> </tr> </thead> <tbody> <tr> <td>CommerceMediaDndEditorDescriptor.cs</td> <td>Registers the custom widget for ItemCollection<CommerceMedia></td> </tr> <tr> <td>CommerceUiModuleRegistration.cs</td> <td>Registers the shell module explicitly so auto-discovery doesn't skip it</td> </tr> <tr> <td>ShellModules/_protected/MyProject.Commerce.UI/module.config</td> <td>Declares the myproject Dojo package</td> </tr> <tr> <td>ShellModules/_protected/MyProject.Commerce.UI/ClientResources/editors/CommerceMediaDndEditor.js</td> <td>The custom editor widget</td> </tr> <tr> <td>MyProject.csproj (MSBuild target)</td> <td>Copies shell module source to modules/_protected/ at build time</td> </tr> </tbody> </table>2026-08-05T09:48:55.0000000Z

Blog post

Order tabs with drag and drop V2I earlier did a very simple Blazor version to be able to sort tabs with drag and drop. 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. Nothing changes until you hit save. Have som export / import buttons but I havent tested that yet.  You can find the code over at my <a href="https://github.com/PNergard/Nergard.Opti.TabSorter">GitHub</a>. <img src="/link/476714de6566474da9deacd2b66a120d.aspx" alt="" width="759" height="627" />  2026-08-04T09:56:57.0000000Z

Blog post

Optimizely : Missing Language Manager Gadget Fix in CMS 12 After Upgrading to .NET 10Recently, while upgrading an Optimizely CMS solution to .NET 10, we came across an issue where the Language Manager gadget completely disappeared from CMS Edit... 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>. 2026-08-02T16:15:41.0000000Z

Blog post