Blogs

Blogs2026-09-01T16:39:41.0000000Zhttps://world.optimizely.com/blogs/ Optimizely World New addon puts the optimization GUI for Optimizely Graph back in the CMSI wanted the Graph UI for Pinned Results and Synonyms inside the CMS, so I created another addon.2026-09-01T16:39:41.0000000Z

Blog post

From CMS Content to AI-Ready Content: A Practical Optimizely CMS 12 ApproachHow structured content can help Optimizely CMS editors prepare content for search and AI-powered experiences Introduction The way users discover information is changing. Traditional search engines return a list of pages. Answer engines provide direct answers, while generative AI experiences can combine information from multiple sources to create responses. This has led to three commonly used terms: SEO, AEO and GEO. SEO, AEO and GEO - What's the Difference? <table class="MsoNormalTable" style="mso-cellspacing: 1.5pt; border: solid windowtext 1.0pt; mso-border-alt: solid windowtext .5pt; mso-yfti-tbllook: 1184; mso-border-insideh: .5pt solid windowtext; mso-border-insidev: .5pt solid windowtext;"> <thead> <tr style="mso-yfti-irow: 0; mso-yfti-firstrow: yes;"> <td style="border: solid windowtext 1.0pt; mso-border-alt: solid windowtext .5pt; padding: .75pt .75pt .75pt .75pt;"> </td> <td style="border: solid windowtext 1.0pt; mso-border-alt: solid windowtext .5pt; padding: .75pt .75pt .75pt .75pt;"> SEO </td> <td style="border: solid windowtext 1.0pt; mso-border-alt: solid windowtext .5pt; padding: .75pt .75pt .75pt .75pt;"> AEO </td> <td style="border: solid windowtext 1.0pt; mso-border-alt: solid windowtext .5pt; padding: .75pt .75pt .75pt .75pt;"> GEO </td> </tr> </thead> <tbody> <tr style="mso-yfti-irow: 1;"> <td style="border: solid windowtext 1.0pt; mso-border-alt: solid windowtext .5pt; padding: .75pt .75pt .75pt .75pt;"> Focus </td> <td style="border: solid windowtext 1.0pt; mso-border-alt: solid windowtext .5pt; padding: .75pt .75pt .75pt .75pt;"> Search engines </td> <td style="border: solid windowtext 1.0pt; mso-border-alt: solid windowtext .5pt; padding: .75pt .75pt .75pt .75pt;"> Answer engines </td> <td style="border: solid windowtext 1.0pt; mso-border-alt: solid windowtext .5pt; padding: .75pt .75pt .75pt .75pt;"> Generative AI </td> </tr> <tr style="mso-yfti-irow: 2;"> <td style="border: solid windowtext 1.0pt; mso-border-alt: solid windowtext .5pt; padding: .75pt .75pt .75pt .75pt;"> Goal </td> <td style="border: solid windowtext 1.0pt; mso-border-alt: solid windowtext .5pt; padding: .75pt .75pt .75pt .75pt;"> Help users discover your content </td> <td style="border: solid windowtext 1.0pt; mso-border-alt: solid windowtext .5pt; padding: .75pt .75pt .75pt .75pt;"> Help systems provide direct answers </td> <td style="border: solid windowtext 1.0pt; mso-border-alt: solid windowtext .5pt; padding: .75pt .75pt .75pt .75pt;"> Help AI understand and use your content </td> </tr> <tr style="mso-yfti-irow: 3;"> <td style="border: solid windowtext 1.0pt; mso-border-alt: solid windowtext .5pt; padding: .75pt .75pt .75pt .75pt;"> Editor focus </td> <td style="border: solid windowtext 1.0pt; mso-border-alt: solid windowtext .5pt; padding: .75pt .75pt .75pt .75pt;"> Useful, relevant content </td> <td style="border: solid windowtext 1.0pt; mso-border-alt: solid windowtext .5pt; padding: .75pt .75pt .75pt .75pt;"> Clear questions and answers </td> <td style="border: solid windowtext 1.0pt; mso-border-alt: solid windowtext .5pt; padding: .75pt .75pt .75pt .75pt;"> Clear structured content </td> </tr> <tr style="mso-yfti-irow: 4; mso-yfti-lastrow: yes;"> <td style="border: solid windowtext 1.0pt; mso-border-alt: solid windowtext .5pt; padding: .75pt .75pt .75pt .75pt;"> Developer focus </td> <td style="border: solid windowtext 1.0pt; mso-border-alt: solid windowtext .5pt; padding: .75pt .75pt .75pt .75pt;"> Technical SEO and metadata </td> <td style="border: solid windowtext 1.0pt; mso-border-alt: solid windowtext .5pt; padding: .75pt .75pt .75pt .75pt;"> Semantic and structured content </td> <td style="border: solid windowtext 1.0pt; mso-border-alt: solid windowtext .5pt; padding: .75pt .75pt .75pt .75pt;"> Structured content and machine-readable data </td> </tr> </tbody> </table> The boundaries between these approaches aren't strict. Many of the same practices support all three. For an Optimizely CMS developer, this leads to an important question: How can we make content easier for machines to understand without making content editors responsible for technical implementation? <div class="MsoNormal" style="margin-bottom: .0001pt; text-align: center; line-height: normal;" align="center"><hr /></div> Start With the CMS Content Model Consider a typical article in Optimizely CMS 12. An editor may manage: <ul> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l3 level1 lfo1; tab-stops: list 36.0pt;">Heading</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l3 level1 lfo1; tab-stops: list 36.0pt;">Introduction</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l3 level1 lfo1; tab-stops: list 36.0pt;">Author</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l3 level1 lfo1; tab-stops: list 36.0pt;">Published date</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l3 level1 lfo1; tab-stops: list 36.0pt;">Modified date</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l3 level1 lfo1; tab-stops: list 36.0pt;">Featured image</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l3 level1 lfo1; tab-stops: list 36.0pt;">Main content</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l3 level1 lfo1; tab-stops: list 36.0pt;">FAQs</li> </ul> These aren't just pieces of text. They have meaning. An author is different from an article heading. A publication date has a different meaning from the main content. An FAQ question has a relationship with its answer. This is where structured content becomes important. Instead of asking the application to interpret everything from rich text, we can model important information explicitly through Optimizely Content Types and Block Types. <div class="MsoNormal" style="margin-bottom: .0001pt; text-align: center; line-height: normal;" align="center"><hr /></div> What Should the Editor See? The editor experience should remain simple. For example, an Article Page in Optimizely Edit Mode could expose: Article <ul> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l1 level1 lfo2; tab-stops: list 36.0pt;">Heading</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l1 level1 lfo2; tab-stops: list 36.0pt;">Author</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l1 level1 lfo2; tab-stops: list 36.0pt;">Published Date</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l1 level1 lfo2; tab-stops: list 36.0pt;">Modified Date</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l1 level1 lfo2; tab-stops: list 36.0pt;">Featured Image</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l1 level1 lfo2; tab-stops: list 36.0pt;">Main Content</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l1 level1 lfo2; tab-stops: list 36.0pt;">FAQ Blocks</li> </ul> The editor simply creates and publishes the content. They shouldn't need to see a large field called "JSON-LD" or understand Schema.org syntax. The principle is: Editors manage content. Developers manage its technical representation. <div class="MsoNormal" style="margin-bottom: .0001pt; text-align: center; line-height: normal;" align="center"><hr /></div> The Architecture A simple architecture can connect the Optimizely content model with structured data: <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">                 OPTIMIZELY CMS 12 <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">                        │ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">                        ▼ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">              Content Types & Blocks <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">                        │ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">                        ▼ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">                Structured Content <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">                        │ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">                        ▼ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">              Structured Data Layer <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">                        │ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">             ┌──────────┼──────────┐ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">             ▼          ▼          ▼ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">          Article      FAQ      Breadcrumb <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">             │          │          │ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">             └──────────┼──────────┘ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">                        ▼ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">                      JSON-LD <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">                        │ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">                 ┌──────┴──────┐ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">                 ▼             ▼ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">              Search           AI The important part is the separation between content management and structured-data generation. <div class="MsoNormal" style="margin-bottom: .0001pt; text-align: center; line-height: normal;" align="center"><hr /></div> Don't Make Editors Write JSON-LD It can be tempting to expose a JSON-LD text field in the CMS and let editors control everything. For most projects, this creates more problems than it solves. Editors shouldn't have to understand: <ul> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l0 level1 lfo3; tab-stops: list 36.0pt;">JSON syntax</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l0 level1 lfo3; tab-stops: list 36.0pt;">Schema.org types</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l0 level1 lfo3; tab-stops: list 36.0pt;">Schema properties</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l0 level1 lfo3; tab-stops: list 36.0pt;">Required relationships</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l0 level1 lfo3; tab-stops: list 36.0pt;">Validation rules</li> </ul> Instead, give editors control over the information, and let the application determine how that information should be represented. For example: <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">Editor <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">  ↓ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">Author = Sanket Mahimkar <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">Published Date = 20 Aug 2026 <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">Featured Image = Article.jpg <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">  <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">              ↓ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">  <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">Application <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">  ↓ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">Article structured data This provides editorial flexibility while maintaining technical governance. <div class="MsoNormal" style="margin-bottom: .0001pt; text-align: center; line-height: normal;" align="center"><hr /></div> Let Optimizely Automate What It Already Knows Not everything needs an editor field. Consider breadcrumbs. Optimizely already knows where a page sits in the content tree: <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">Start Page <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">   └── Technology <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">        └── Optimizely <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">             └── CMS <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">                  └── Article The application can use this hierarchy to generate breadcrumb structured data. The editor doesn't need to maintain the same information twice. This leads to another useful principle: If the CMS already knows the information, don't ask the editor to enter it again. <div class="MsoNormal" style="margin-bottom: .0001pt; text-align: center; line-height: normal;" align="center"><hr /></div> One Source of Truth A structured-content approach also reduces duplication. Without it, we may end up maintaining: <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">CMS Content <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">    + <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">SEO Fields <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">    + <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">JSON-LD These can eventually become inconsistent. Instead: <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">                 CMS Content <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">                      │ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">            ┌─────────┼─────────┐ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">            ▼         ▼         ▼ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">           HTML      SEO      JSON-LD The same underlying content can support multiple experiences. If an editor updates the author, date or image, the generated representations can use the updated CMS content. <div class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; text-align: center; line-height: normal;" align="center"><hr /></div> <h1>What Changes with Optimizely CMS 13?</h1> If you're working with Optimizely CMS 13, this approach becomes even more relevant. CMS 13 introduces built-in Generative Engine Optimization (GEO) capabilities. Optimizely's current CMS 13 tooling includes AI-powered GEO analysis for evaluating content discoverability and can apply JSON-LD schema markup to content. This means the architecture we've discussed is moving from something developers may need to build themselves toward capabilities that are increasingly part of the Optimizely platform. The important distinction is that structured content is still the foundation. Think of the evolution as: <img src="/link/d9520f5ff6e34c68a61813a423fec4c1.aspx" /> CMS 13 also introduces a more modern content and delivery architecture around Optimizely Graph, with Visual Builder and a unified editing experience. So, if you're starting a new CMS 13 implementation, the question is no longer simply: "How do I build JSON-LD generation?" It becomes: "How should I model and govern my content so Optimizely's built-in GEO capabilities can make the best use of it?" That is an important shift for developers. CMS 12 gives us the architectural opportunity. CMS 13 takes many of those capabilities further into the platform. <div class="MsoNormal" style="margin-bottom: .0001pt; text-align: center; line-height: normal;" align="center"><hr /></div> Where Does GEO Fit? Structured data is not GEO by itself, and adding JSON-LD doesn't guarantee that an AI system will cite or recommend a website. Instead, think of AI readiness as a combination of: <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">Clear Content <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">     + <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">Structured CMS Content <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">     + <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">Semantic HTML <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">     + <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">Good Information Architecture <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">     + <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">Accurate Metadata <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">     + <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">Structured Data For Optimizely developers, the opportunity is to make sure the CMS preserves not just the text, but also the meaning and relationships behind the content. An article has an author. An article has a publication date. An FAQ has a question and an answer. A page has a place in the site hierarchy. When this information is structured in the CMS, the application has a much better foundation for creating machine-readable experiences. <div class="MsoNormal" style="margin-bottom: .0001pt; text-align: center; line-height: normal;" align="center"><hr /></div> Start Small You don't need to redesign an entire Optimizely CMS 12 implementation. Start with one content type, such as an Article Page. Then gradually introduce structured representations for: <ul> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l2 level1 lfo4; tab-stops: list 36.0pt;">Articles</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l2 level1 lfo4; tab-stops: list 36.0pt;">FAQs</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l2 level1 lfo4; tab-stops: list 36.0pt;">Breadcrumbs</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l2 level1 lfo4; tab-stops: list 36.0pt;">Products</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l2 level1 lfo4; tab-stops: list 36.0pt;">Events</li> <li class="MsoNormal" style="mso-margin-top-alt: auto; mso-margin-bottom-alt: auto; line-height: normal; mso-list: l2 level1 lfo4; tab-stops: list 36.0pt;">Organizations</li> </ul> The key is to start with content that provides clear business value. <div class="MsoNormal" style="margin-bottom: .0001pt; text-align: center; line-height: normal;" align="center"><hr /></div> Conclusion Making an Optimizely CMS 12 website ready for an increasingly AI-driven web doesn't start with JSON-LD. It starts with how we model content. When content is structured properly in Optimizely, developers can create reusable mechanisms to expose that information to different consumers, while editors continue working with the familiar CMS experience. The architecture is simple: <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">Optimizely Editor <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">       ↓ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">Structured Content <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">       ↓ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">Structured Data <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">       ↓ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">JSON-LD <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">       ↓ <p class="MsoNormal" style="margin-bottom: .0001pt; line-height: normal; tab-stops: 45.8pt 91.6pt 137.4pt 183.2pt 229.0pt 274.8pt 320.6pt 366.4pt 412.2pt 458.0pt 503.8pt 549.6pt 595.4pt 641.2pt 687.0pt 732.8pt;">Search + AI Experiences The principle is even simpler: Let editors manage the meaning of the content. Let developers manage how that meaning is represented technically. Your CMS shouldn't just store content. It should preserve what that content means.  2026-09-01T11:09:45.0000000Z

Blog post

Serving Heavy Multilingual Content Efficiently with Optimizely SaaS CMSWhen building enterprise-grade applications on modern headless stacks, performance is governed by payload efficiency. Optimizely SaaS CMS and Optimizely Graph provide a fast, flexible foundation for omnichannel digital experiences. As projects grow and complex content requirements emerge — such as multi-locale video transcripts, technical specifications, or localized legal disclosures — architects face a challenge that applies to any headless platform and any frontend channel: How do we store rich, multi-locale data within a content item without bloating delivery payloads or inflating content item counts? The good news is that Optimizely SaaS CMS provides native architectural levers — granular Graph indexing modes, inline component lists, and SDK query synthesis — that allow teams to solve this challenge elegantly across any channel. This article walks through how to configure these capabilities into a high-performance, cost-efficient omnichannel architecture. <hr /> <h2>What This Article Covers</h2> This guide is for solution architects and senior developers building enterprise digital experiences with Optimizely SaaS CMS, Optimizely Graph, and the Optimizely Content JS SDK. The patterns apply equally to any frontend channel — Next.js, mobile apps, Vue/Nuxt, SvelteKit, Astro, or embedded displays. It connects key platform capabilities into a unified architectural pattern: <table style="border-collapse: collapse; width: 100%; border: 1px solid rgb(0, 0, 0);"> <tbody> <tr> <td style="padding: 10px; text-align: left; vertical-align: top; background-color: rgb(236, 240, 241); border: 1px solid rgb(0, 0, 0);"> Platform Capability </td> <td style="padding: 10px; text-align: left; vertical-align: top; background-color: rgb(236, 240, 241); border: 1px solid rgb(0, 0, 0);"> Architectural Purpose </td> </tr> <tr> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Inline Component List Properties </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Attach structured multi-locale data to a page without creating standalone items that count toward subscription quotas </td> </tr> <tr> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Granular Graph Indexing Modes </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Use Default vs. Queryable indexing to protect schema quotas and avoid silent data loss </td> </tr> <tr> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Content JS SDK Query Synthesis </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Control which properties are fetched on initial page render by managing registered TypeScript models </td> </tr> <tr> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Two-Way GraphQL Operations </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Target specific language entries on demand and enable catalog-level discovery filtering </td> </tr> <tr> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Structured Editorial UX </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Give content authors clean, form-based input fields grouped logically in dedicated tabs </td> </tr> </tbody> </table> <hr /> <h2>What You Will Achieve</h2> A production-ready blueprint for storing large, optional multilingual content inside a single Optimizely CMS page item, serving it lazily per locale on demand across any channel, and managing it reliably in the CMS — all while maintaining optimal page performance and zero licensing overhead. <hr /> <h2>Architecture at a Glance</h2> The pattern spans four layers, each leveraging a native Optimizely capability: <ol class="tight"> <li> Storage Layer (SaaS CMS): Define a reusable component content type — a language code and a content body — attached as a list property to the page. Entries are versioned inline as part of the page item, not as standalone objects. </li> <li> Indexing Layer (Optimizely Graph): Set the language code to Queryable (enabling catalog-level filters) and the text body to Default (stored and returned for delivery, bypassing full-text search limits and minimizing schema field usage). </li> <li> Fetching Boundary (Content JS SDK): Omit the list property from the frontend model registered with initContentTypeRegistry. The SDK's dynamic runtime query builder fetches only what is declared in your model, keeping initial payloads light. </li> <li> Delivery Layer (On-Demand Fetching): Retrieve the content asynchronously via a targeted GraphQL query only when the user actively requests it — on any channel, from any client. </li> </ol> <hr /> <h2>The Headless Payload Tradeoff</h2> In high-performance web and mobile applications, initial payloads should contain only what is immediately visible. A 15-minute video transcript across multiple languages can easily exceed 200KB of raw text. Without intentional architecture, three problems emerge: <ul class="tight"> <li> Initial payload bloat: Returning all language transcripts on standard content queries bloats the response and slows Time to First Byte regardless of the rendering framework. </li> <li> Content item proliferation: Creating a standalone shared block per language per video multiplies content items across environments. Optimizely licensing is tied to item counts across all environments in an instance, so this compounds quickly. </li> <li> Translation dependencies: Language-specific properties require a translated page version to exist before auxiliary data can be stored — a hard dependency that rarely matches how transcription pipelines or workflows actually operate. </li> </ul> By configuring Optimizely SaaS CMS correctly, all three challenges are resolved simultaneously. <hr /> <h2>Step 1: Model the Component as an Inline List Property</h2> First, define a reusable component content type holding two properties: an identifier for the language code and the transcript body. <h3>The Component Definition (VideoTranscript)</h3> <pre class="code-block"><code class="language-json">{ "key": "VideoTranscript", "baseType": "_component", "displayName": "Video Transcript", "properties": { "langCode": { "type": "string", "displayName": "Language Code", "description": "IETF locale tag, lowercase — for example en-us or de-de", "indexingType": "queryable" }, "content": { "type": "string", "displayName": "Transcript Text" } } }</code></pre> With the component defined, attach it to your page type as an array of inline components ("type": "component"). In Optimizely SaaS CMS, the component property type indicates an inline-only composition, ensuring that entries are embedded directly within the parent page's storage and lifecycle rather than creating standalone referenced entities. <h3>The Page Type (VideoPage)</h3> <pre class="code-block"><code class="language-json">{ "key": "VideoPage", "baseType": "_page", "displayName": "Video Page", "properties": { "title": { "type": "string", "displayName": "Title", "localized": true }, "videoUrl": { "type": "string", "displayName": "Video URL", "localized": true }, "transcripts": { "type": "array", "displayName": "Transcripts", "description": "One entry per language. Shared across all locale versions of this page.", "localized": false, "items": { "type": "component", "contentType": "VideoTranscript" } } } }</code></pre> Setting localized: false on the list means all language transcripts live on the master locale version of the page. Automated pipelines can populate translations immediately without waiting for localized page versions to exist. <h3>Architectural Tradeoff: component vs. content Property Types</h3> While array properties in Optimizely SaaS CMS can hold primitive types (strings, numbers, booleans) or complex structures, arrays of structured data typically choose between component and content as their item type: <ul class="tight"> <li> "type": "component" (used in this pattern): Inline-only. Entries are permanently embedded within the parent page and cannot be extracted or referenced as standalone blocks. This is the safer choice when keeping item counts flat is a priority. </li> <li> "type": "content" (alternative): Inline or referenced. Provides a future migration path if transcripts ever need to be reused across multiple items — but editors can also unintentionally author entries as standalone shared blocks, which increases repository item counts and can affect licensing costs. </li> </ul> <hr /> <h2>Step 2: Choose the Right Indexing Type for Each Property</h2> Optimizely SaaS CMS gives developers per-property control over how content is indexed in Optimizely Graph: <table style="border-collapse: collapse; width: 100%; border: 1px solid rgb(0, 0, 0);"> <tbody> <tr> <td style="padding: 10px; text-align: left; vertical-align: top; background-color: rgb(236, 240, 241); border: 1px solid rgb(0, 0, 0);"> Indexing Type </td> <td style="padding: 10px; text-align: left; vertical-align: top; background-color: rgb(236, 240, 241); border: 1px solid rgb(0, 0, 0);"> Returned in GraphQL </td> <td style="padding: 10px; text-align: left; vertical-align: top; background-color: rgb(236, 240, 241); border: 1px solid rgb(0, 0, 0);"> Usable in where Filters </td> <td style="padding: 10px; text-align: left; vertical-align: top; background-color: rgb(236, 240, 241); border: 1px solid rgb(0, 0, 0);"> Full-Text Searchable </td> <td style="padding: 10px; text-align: left; vertical-align: top; background-color: rgb(236, 240, 241); border: 1px solid rgb(0, 0, 0);"> Key Consideration </td> </tr> <tr> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Default </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Yes </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> No </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> No </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Ideal for large display text. Bypasses search term limits and minimizes schema field consumption </td> </tr> <tr> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Queryable </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Yes </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Yes </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> No </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Ideal for codes and identifiers. Enables structured filtering without text tokenization </td> </tr> <tr> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Searchable </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Yes </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Yes </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Yes </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Enables full-text search. Subject to Elasticsearch's 8,191-byte per-term limit </td> </tr> <tr> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Disabled </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> No </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> No </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> No </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Excluded from the Graph schema entirely </td> </tr> </tbody> </table> For this pattern: <ul class="tight"> <li> langCode set to Queryable: A short string with negligible indexing cost. Being filterable enables queries such as "return every video that has a German transcript" without fetching transcript bodies. </li> <li> content set to Default: The full transcript is stored in Optimizely Graph and returned when queried, but it is excluded from full-text indexing. Strings marked as Searchable that exceed 8,191 bytes are silently dropped from the index with no error at publish time. Default sidesteps this entirely and consumes fewer fields against the instance's 100,000-field schema quota. </li> </ul> <hr /> <h2>Step 3: Decouple the Frontend Model from the SDK Query Builder</h2> When using automatic routing or calling getContentByPath(), the Optimizely Content JS SDK inspects the models registered in your application and synthesizes a GraphQL query containing every property declared in them. That behavior is the control point: a property absent from the registered model is never requested. <pre class="code-block"><code class="language-typescript">// src/models/VideoPage.ts // Registered with the SDK. // transcripts is deliberately absent so the runtime query builder excludes it. export interface VideoPage { _metadata: ContentMetadata; title: string; videoUrl: string; } // Used only by the on-demand query. export interface TranscriptEntry { langCode: string; content: string; } export interface VideoPageTranscripts { transcripts?: TranscriptEntry[]; }</code></pre> Register only the core model at application bootstrap: <pre class="code-block"><code class="language-typescript">// src/app/layout.tsx import { initContentTypeRegistry } from '@optimizely/cms-sdk'; import { VideoPage } from './models/VideoPage'; initContentTypeRegistry([ { type: 'VideoPage', model: VideoPage } ]);</code></pre> Splitting the interfaces makes accidental inclusion of the heavy field a compile error rather than a silent payload regression. The property remains fully queryable through dedicated operations because it exists in the Graph schema. <hr /> <h2>Step 4: Two-Way Querying via Optimizely Graph</h2> Defining langCode as a structured, Queryable property unlocks a powerful two-way querying synergy in Optimizely Graph: targeted on-demand retrieval for a single item, and catalog-level discovery filtering across your entire content repository. <h3>Direction 1: Targeted Transcript Retrieval (Item → Language)</h3> When a user on a specific video page clicks "Show Transcript" or selects a subtitle language on any client (web, mobile app, or smart display), your application fires a targeted GraphQL query retrieving only the transcripts property for that specific content ID: <pre class="code-block"><code class="language-graphql">query GetVideoTranscript($id: String!) { VideoPage(where: { _metadata: { key: { eq: $id } } }) { items { transcripts { langCode content } } } }</code></pre> Your client (or a lightweight server route / API handler) executes this query against Optimizely Graph, resolves the matching langCode entry in memory, and caches the response. Initial page rendering remains instant because zero transcript bytes were fetched upfront. <h3>Direction 2: Catalog Discovery Filtering (Language → Items)</h3> In reverse, you can query across your entire video catalog to discover every video that offers a transcript in a specific language — without fetching any transcript text: <pre class="code-block"><code class="language-graphql">query VideosWithGermanTranscripts { VideoPage(where: { transcripts: { langCode: { eq: "de-de" } } }) { items { _metadata { key displayName } title videoUrl } } }</code></pre> This unlocks listing and search capabilities (e.g., "Show only videos with German subtitles") while keeping query execution fast and lightweight. <hr /> <h2>Editorial Experience</h2> A structured component list gives content authors form fields — a language code input and a text area per entry — rather than a raw text box holding serialized data. Entries can be added, reordered, and removed through the standard list interface in the CMS editor. Two configuration refinements are worth applying: <ul class="tight"> <li> Group the transcripts property into a dedicated tab (Metadata, or similar) in the content type settings, so the primary editing surface stays focused on the content editors work with most. </li> <li> Standardize language codes as lowercase IETF tags and document the convention in the property's help text. Your application's locale fallback logic depends on predictable casing. </li> </ul> <hr /> <h2>Omnichannel Applicability</h2> This pattern is not specific to any frontend framework. The storage and indexing decisions live entirely within Optimizely SaaS CMS and Optimizely Graph. Any channel consuming content through the Graph API can apply the same approach: <ul class="tight"> <li> A mobile app (iOS, Android, React Native, Flutter) fetches core content on screen load and requests transcripts via a separate API call when the user opens the subtitle panel. </li> <li> A Next.js, Nuxt, or SvelteKit application fetches core content during page render and fetches transcripts lazily on user interaction. </li> <li> A kiosk or digital signage display requests transcripts only when the user activates accessibility mode. </li> </ul> The boundary between what is fetched by default and what is fetched on demand is defined by the component model and the SDK registration — not by the channel. <hr /> <h2>What This Pattern Delivers</h2> <table style="border-collapse: collapse; width: 100%; border: 1px solid rgb(0, 0, 0);"> <tbody> <tr> <td style="padding: 10px; text-align: left; vertical-align: top; background-color: rgb(236, 240, 241); border: 1px solid rgb(0, 0, 0);"> Dimension </td> <td style="padding: 10px; text-align: left; vertical-align: top; background-color: rgb(236, 240, 241); border: 1px solid rgb(0, 0, 0);"> Fetching everything by default </td> <td style="padding: 10px; text-align: left; vertical-align: top; background-color: rgb(236, 240, 241); border: 1px solid rgb(0, 0, 0);"> Selective loading with a component list </td> </tr> <tr> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Initial payload </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Includes all language content on every render </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> No transcript bytes during initial load </td> </tr> <tr> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Page and screen performance </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Slower TTFB and delayed first render </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Payload proportional to visible content </td> </tr> <tr> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Content item count </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Multiplies per language when using shared blocks </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Unchanged — entries are stored inline </td> </tr> <tr> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Graph field usage </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Higher when properties are searchable </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> One Queryable field, one Default field </td> </tr> <tr> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Byte-limit exposure </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Silent index drops above 8,191 bytes </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Avoided by using the Default indexing type </td> </tr> <tr> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Translation dependency </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Blocked until the page is translated </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Decoupled — entries live on the master locale </td> </tr> <tr> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Data integrity </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Errors surface at render time </td> <td style="padding: 10px; text-align: left; vertical-align: top; border: 1px solid rgb(0, 0, 0);"> Validated at the API boundary on write </td> </tr> </tbody> </table>   The underlying principle applies well beyond transcripts. Any property that is large, optional, and consumed by a subset of users — specification sheets, legal text, changelogs, structured FAQ data — benefits from the same separation between what the CMS stores and what any given channel requests by default. <hr /> The code samples in this article illustrate the pattern rather than serving as a drop-in implementation.2026-08-31T10:22:16.0000000Z

Blog post

The Under-Documented Optimizely Caching API I Somehow MissedI recently discovered some useful, but poorly documented, caching features in Optimizely CMS. Here’s how ReadThrough, ReadStrategy.Wait and master keys can prevent cache stampedes and invalidate custom cached data when Optimizely content changes.2026-08-31T09:18:39.0000000Z

Blog post

Beyond [Authorize]: Function-Level Permissions in OptimizelyWhy basic role checks fall short and how Permissions to Functions unlock audience-based access control <h3>The Problem with Basic Authorization</h3> ASP.NET Core's [Authorize] attribute is the right starting point for access control. It answers a simple question: is this user allowed into the application at all? For many endpoints, that is enough. But as business rules grow more specific, [Authorize] starts to show its limits: <ul> <li>It only checks whether the user is authenticated or belongs to a role or policy</li> <li>It does not easily support dynamic business rules</li> <li>It is not ideal for audience-based or context-based permissions</li> <li>It becomes hard to manage when access depends on function-level rules</li> </ul> A familiar scenario A user may be fully authenticated and even hold a valid CMS role yet still should not be allowed to perform a specific action. Some features need access for a specific audience, not just a role name baked into code. That gap is where many Optimizely implementations start looking for a better pattern. <h3>The Limitation of Built-In Permission Checks Alone</h3> Optimizely exposes <a style="color: rgb(0, 0, 238);" href="https://docs.developers.optimizely.com/content-management-system/docs/permissions-to-functions">Permissions to Functions</a> through PermissionType and PermissionService. That is a strong foundation: permissions are discoverable in the admin UI and can be assigned to users and roles. However, relying only on the built-in authorization path has a gap of its own: <ul> <li style="color: rgb(45, 194, 107);">Role and group assignment works well</li> <li style="color: rgb(186, 55, 42);">Visitor group / audience-based evaluation is not wired into a simple declarative attribute out of the box</li> <li style="color: rgb(230, 126, 35);">Controllers end up with duplicated authorization logic, or hard-coded role lists that drift from CMS configuration</li> </ul> The result is often a mix of [Authorize(Roles = "...")] strings scattered across controllers, difficult to audit and painful to change when the business audience evolves. <h2>The Solution: AuthorizePermission with Permissions to Functions</h2> Instead of relying only on [Authorize], use a custom authorization attribute backed by Optimizely's Permissions to Functions model. This approach lets you: <ul> <li>Control access at the function level</li> <li>Evaluate business rules dynamically</li> <li>Support audience-based permission checks (users, roles, and visitor groups)</li> <li>Keep authorization logic reusable and centralized</li> </ul> Key difference at a glance <table style="border-collapse: collapse; width: 65.4292%; border-spacing: 5px; border: 1px solid rgb(126, 140, 141); height: 55.7499px;"> <tbody> <tr style="height: 16.5833px;"> <td style="border-width: 1px; padding: 5px; border-color: rgb(126, 140, 141); height: 16.5833px;">Approach</td> <td style="border-width: 1px; padding: 5px; border-color: rgb(126, 140, 141); height: 16.5833px;">What it checks</td> <td style="border-width: 1px; padding: 5px; border-color: rgb(126, 140, 141); height: 16.5833px;"> Best for</td> </tr> <tr style="height: 19.5833px;"> <td style="border-width: 1px; padding: 5px; border-color: rgb(126, 140, 141); height: 19.5833px;">[Authorize]</td> <td style="border-width: 1px; padding: 5px; border-color: rgb(126, 140, 141); height: 19.5833px;">Authentication, roles, policies</td> <td style="border-width: 1px; padding: 5px; border-color: rgb(126, 140, 141); height: 19.5833px;">App-level and coarse-grained access</td> </tr> <tr style="height: 19.5833px;"> <td style="border-width: 1px; padding: 5px; border-color: rgb(126, 140, 141); height: 19.5833px;">Permissions to Functions</td> <td style="border-width: 1px; padding: 5px; border-color: rgb(126, 140, 141); height: 19.5833px;">CMS-managed audience per permission</td> <td style="border-width: 1px; padding: 5px; border-color: rgb(126, 140, 141); height: 19.5833px;">Function-level, business-aligned access</td> </tr> </tbody> </table>   [Authorize] = basic, framework-level access control CustomAuthorizePermission = custom, function-level permission control <h2>How It Works in Practice</h2> The pattern has three parts: <ul> <li>Define permission types - discovered by Optimizely and shown under Config → Permissions to functions</li> <li>Register virtual roles (optional) - map permissions to virtual roles for broader CMS integration</li> <li>Apply a custom filter attribute - evaluate the current user against the permission audience at request time</li> </ul> Step 1: Define permission types Create a static class decorated with [PermissionTypes]. Each PermissionType represents a function your application exposes, for example, viewing reports, managing settings, or accessing an admin area. <pre><code class="language-csharp">[PermissionTypes] public static class AppPermissions { public const string GroupName = "MyApplication"; static AppPermissions() { ViewReports = new PermissionType(GroupName, nameof(ViewReports)); ManageSettings = new PermissionType(GroupName, nameof(ManageSettings)); AccessAdmin = new PermissionType(GroupName, nameof(AccessAdmin)); } public static PermissionType ViewReports { get; private set; } public static PermissionType ManageSettings { get; private set; } public static PermissionType AccessAdmin { get; private set; } }</code></pre> Once deployed, these permissions appear in the Optimizely admin UI (CMS --> Settings --> Permissions for Functions). Admins can assign users and roles to each function without redeploying code. Add localization so friendly names and descriptions appear in  Permissions for functions instead of raw type names. Create or update a language XML file (for example Resources/Localization/Views_en.xml): <pre><code class="language-xml"><?xml version="1.0" encoding="utf-8" standalone="yes"?> <languages> <language name="English" id="en"> <admin> <permissiontype> <groups> <AppPermissions> <description>Functions in the application</description> <permissions> <ViewReports>Allows users to view reports</ViewReports> <ManageSettings>Allows users to manage application settings</ManageSettings> <AccessAdmin>Allows users to access the admin area</AccessAdmin> </permissions> </AppPermissions> </groups> </permissiontype> </admin> </language> </languages></code></pre> Step 2: Register virtual roles (optional) If you need permissions to participate in Optimizely's role system, for example, in content access rules or visitor group criteria, register a virtual role for each permission: <pre><code class="language-csharp"> [InitializableModule] [ModuleDependency(typeof(EPiServer.Web.InitializationModule))] public class AppVirtualRoleInitialization : IInitializableModule {     public void Initialize(InitializationEngine context)     {         var virtualRoleRepository = context.Locate.Advanced             .GetInstance();         virtualRoleRepository.Register("ViewReportsVirtualRole", new PermissionRole         {             Permission = AppPermissions.ViewReports         });         virtualRoleRepository.Register("ManageSettingsVirtualRole", new PermissionRole         {             Permission = AppPermissions.ManageSettings         });         // Register additional permissions as needed     }     public void Uninitialize(InitializationEngine context) { } } </code></pre> This step is optional. Skip it if you only need controller-level authorization via a custom attribute. Step 3: Apply a custom authorization attribute Create an IAsyncAuthorizationFilter that resolves the permission audience at request time. A typical implementation supports two evaluation paths: By PermissionType - calls PermissionService.IsPermitted for direct function-level checks against users and roles assigned in the CMS By PermissionName - resolves visitor groups assigned to the permission via PermissionRepository and evaluates them with IVisitorGroupRole.IsMatch <pre><code class="language-csharp"> namespace MyApplication.Attributes { using System; using System.Linq; using System.Threading.Tasks; using EPiServer.DataAbstraction; using EPiServer.Find.Helpers.Text; using EPiServer.Personalization.VisitorGroups; using EPiServer.Security; using Microsoft.AspNetCore.Mvc; using Microsoft.AspNetCore.Mvc.Filters; using Microsoft.Extensions.DependencyInjection; using MyApplication.Infrastructure.Security; [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true)] public class AuthorizePermissionAttribute : ActionFilterAttribute, IAsyncAuthorizationFilter { public string PermissionName { get; set; } public PermissionType? PermissionType { get; set; } public AuthorizePermissionAttribute() { } public AuthorizePermissionAttribute(string name) { this.PermissionName = name; } public AuthorizePermissionAttribute(string groupName, string name) { this.PermissionType = new PermissionType(groupName, name); } public async Task OnAuthorizationAsync(AuthorizationFilterContext filterContext) { if (this.PermissionType == null && this.PermissionName.IsNullOrEmpty()) { return; } if (this.PermissionName.IsNotNullOrEmpty()) { await this.AuthorizeByPermissionNameAsync(filterContext); return; } this.AuthorizeByPermissionType(filterContext); } private async Task AuthorizeByPermissionNameAsync(AuthorizationFilterContext filterContext) { var httpContext = filterContext.HttpContext; var user = httpContext.User; var permissionRepository = httpContext.RequestServices.GetRequiredService(); var visitorGroupRoleRepository = httpContext.RequestServices.GetRequiredService(); var permissionType = GetPermissionType(this.PermissionName); var audiences = await permissionRepository.GetPermissionsAsync(permissionType); var visitorGroupNames = audiences .Where(x => x.EntityType == SecurityEntityType.VisitorGroup) .Select(x => x.Name) .Distinct(StringComparer.OrdinalIgnoreCase) .ToList(); foreach (var visitorGroupName in visitorGroupNames) { var hasRole = visitorGroupRoleRepository.TryGetRole(visitorGroupName, out var visitorGroupRole); if (!hasRole) { continue; } var isMatch = visitorGroupRole.IsMatch(user, httpContext); if (isMatch) { return; } } filterContext.Result = new ChallengeResult(); } private void AuthorizeByPermissionType(AuthorizationFilterContext filterContext) { var httpContext = filterContext.HttpContext; var user = httpContext.User; var permissionService = httpContext.RequestServices.GetRequiredService(); var isPermitted = permissionService.IsPermitted(user, this.PermissionType); if (isPermitted) { return; } var isAuthenticated = user.Identity != null && user.Identity.IsAuthenticated; filterContext.Result = GetUnauthorizedResult(isAuthenticated); } private static IActionResult GetUnauthorizedResult(bool isAuthenticated) { if (!isAuthenticated) { return new ChallengeResult(); } return new ForbidResult(); } private static PermissionType? GetPermissionType(string permissionName) { switch (permissionName) { case nameof(AppPermissions.ViewReports): return AppPermissions.ViewReports; case nameof(AppPermissions.ManageSettings): return AppPermissions.ManageSettings; case nameof(AppPermissions.AccessAdmin): return AppPermissions.AccessAdmin; default: return null; } } } } </code></pre> Apply the attribute on any controller or action that should be gated by a CMS-managed audience: <pre><code class="language-csharp"> // By permission name evaluates visitor groups assigned to the permission [AuthorizePermission(nameof(AppPermissions.ViewReports))] public class ReportsController : Controller { // Only users matching the ViewReports visitor group audience can access this } // By permission type evaluates users and roles via PermissionService [AuthorizePermission("AppPermissions", nameof(AppPermissions.ManageSettings))] public class SettingsController : Controller { // Only users in the ManageSettings permission audience can access this } </code></pre> The permission group name and function name must match what you defined in Step 1. The audience users, roles, and optionally visitor groups is managed entirely in the Optimizely admin UI.   When to Use Each Approach <table style="border-collapse: collapse; width: 59.4105%; height: 117.5px; border-spacing: 5px; border: 1px solid rgb(126, 140, 141);"> <tbody> <tr style="height: 19.5833px;"> <td style="height: 19.5833px; width: 47.6037%; border-width: 1px; padding: 5px; border-color: rgb(126, 140, 141);">Scenario</td> <td style="height: 19.5833px; width: 52.3118%; border-width: 1px; padding: 5px; border-color: rgb(126, 140, 141);">Recommended approach</td> </tr> <tr style="height: 19.5833px;"> <td style="height: 19.5833px; width: 47.6037%; border-width: 1px; padding: 5px; border-color: rgb(126, 140, 141);">Public or anonymous endpoints</td> <td style="width: 52.3118%; border-width: 1px; padding: 5px; border-color: rgb(126, 140, 141);"> [Authorize] </td> </tr> <tr style="height: 19.5833px;"> <td style="height: 19.5833px; width: 47.6037%; border-width: 1px; padding: 5px; border-color: rgb(126, 140, 141);">Any authenticated CMS user</td> <td style="width: 52.3118%; border-width: 1px; padding: 5px; border-color: rgb(126, 140, 141);"> [Authorize(Roles = "...")] </td> </tr> <tr style="height: 19.5833px;"> <td style="width: 47.6037%; border-width: 1px; padding: 5px; border-color: rgb(126, 140, 141);"> Fixed role-based access with no CMS audience </td> <td style="width: 52.3118%; border-width: 1px; padding: 5px; border-color: rgb(126, 140, 141);"> AuthorizePermission + PermissionTypes </td> </tr> <tr style="height: 19.5833px;"> <td style="width: 47.6037%; border-width: 1px; padding: 5px; border-color: rgb(126, 140, 141);"> Function-level access managed in Optimizely admin </td> <td style="width: 52.3118%; border-width: 1px; padding: 5px; border-color: rgb(126, 140, 141);"> AuthorizePermission with permission name resolution </td> </tr> <tr style="height: 19.5833px;"> <td style="width: 47.6037%; border-width: 1px; padding: 5px; border-color: rgb(126, 140, 141);"> Audience includes visitor groups </td> <td style="width: 52.3118%; border-width: 1px; padding: 5px; border-color: rgb(126, 140, 141);"> Custom attribute + hybrid auth filter </td> </tr> </tbody> </table> <h3>Benefits</h3> More flexible than [Authorize] Roles and policies are static contracts. Permissions to Functions are business contracts managed in the CMS and mapped to real audiences. Easier to scale As new features ship, add a PermissionType and an attribute. No more hunting through controllers for magic role strings. Better alignment with business needs Marketing, operations, and support teams can reason about who can access Orders or who can change organization context through the admin UI not through source code. Cleaner separation of concerns <ul> <li>Authentication establishes identity</li> <li>Authorization evaluates function-level audience membership</li> <li>Controllers stay focused on business logic</li> </ul>2026-08-28T16:32:40.0000000Z

Blog post

Insights from upgrading Optimizely CMS 12 to CMS 13Optimizely CMS 13 has been here a while now, so I wanted to share some insights from a few of the migrations that has been done. The framework and package upgrade itself was fairly straightforward, but there were a number of API changes, older CMS 12 patterns and a few runtime issues that only showed […]2026-08-28T11:29:38.0000000Z

Blog post

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