Blog posts by Minesh Shah

Virtual Teammates in Optimizely Mark: a hands-on first look

2026-10-27T09:44:35.0000000Z

Virtual Teammates are the most interesting thing Optimizely has shipped on its agent platform this year, and the hardest to evaluate from a demo. They are not another agent. They are persistent AI workers with their own login, mailbox, memory and job description, and they keep working when you close the tab.

The Optimizely MVP organisation has just been given access, so I spent a day taking them apart: reading the docs, walking every screen in the directory, and enabling the SEO & AI Search Analyst against a real site with real Google Analytics 4 and Search Console data. Every screenshot below is from that session, unedited apart from cropping. This post covers what they are, how they are configured end to end, what my teammate actually found, where I think they earn their keep, and the gotchas I hit on the way.

A quick note on naming, because it will trip you up. Opal is now the Optimizely Agent Platform, and the assistant and app you work in are called Mark. The UI says Mark, the docs mostly say Mark, and some help articles and the release notes page still say Opal. They are the same product. Virtual Teammates were released on 25/08/2026 with five roles. The Web Manager and Content Marketer arrived on 13/10/2026, and a Translation Specialist is now in the directory too.

Teammate, not agent

The difference is persistence and identity. An agent runs when you invoke it and forgets you when it finishes. A Virtual Teammate is hired once, given a job, and then runs that job on a schedule or in response to events, building up memory as it goes.

Optimizely describes four layers, and they map neatly onto things you already know in Mark:

Tools. Connectors to systems like GA4, Search Console, Semrush, HubSpot or Slack. The same connectors your agents already use.
Agents and workflows. Packaged tasks the teammate runs from Mark, with your permission.
Jobs. Workflows the teammate runs on its own, on a schedule or an event. This is the bit that makes it a teammate.
Teammate layer. A persistent identity, memory, personality and job description wrapped around the rest.

The identity part is more literal than I expected. Each teammate gets its own Opti ID account, login and email address, flagged as a virtual user. It does not consume a product seat. It inherits nothing from the person who hired it, so you grant it access exactly as you would a new starter. Inside Optimizely products it acts as itself. Outside them it acts through accounts a human connects on its behalf, because a teammate cannot complete an OAuth consent itself.

You work with it through Team Messages, a Slack-style messaging layer inside Mark with direct messages, groups and channels. Teammates can message each other too, and can join Teams and Slack meetings to share summaries. The default autonomy model is sensible: the teammate drafts and proposes, you approve or redirect in Team Messages, and you widen what it can do unattended as trust builds.

The directory: eight teammates

The MVP organisation's directory lists eight teammates. Each has a CV-style card ("Why hire me", "Experience", "Tools used") and a set of jobs you can switch on or off when enabling it. All jobs are on by default.

The Virtual Teammates directory in Mark. Each card is a "resume" with the jobs it does and the tools it works with.

The table below is taken from the enable screens in the MVP instance on 27/10/2026.

Teammate	Jobs	Connectors it asks for
SEO & AI Search Analyst	Audit AEO readiness (daily), Research industry trends, Monitor performance (SEO and GEO anomaly scan), Research keywords (daily, from Conductor and Search Console)	GA4, Search Console at enablement. Conductor and Semrush at hire.
Marketing Analyst	Traffic and acquisition pulse (weekly), Content performance (weekly), Conversion summary (monthly), Anomaly detection (daily), Marketing Analyst actions, Self evaluation	GA4, Search Console, Tag Manager
CRO Manager	Generate experimentation roadmap (PIE scored), Write test plans, Monitor experiment portfolio (daily SRM and stat sig checks), Analyse and report results, Configure experiments	GA4. Works natively in Web Experimentation.
Personalization Strategist	Identify opportunities, Design campaign plan, Build campaign, Monitor performance, Impact overview	GA4, Search Console, Salesforce, Google Ads, Figma
Content Marketer	Monitor industry trends (daily), Track competitor content (weekly), Surface pipeline gaps (weekly, from Salesforce), Self evaluation	Salesforce
Web Manager	Perform audit compliance, Manage site health, Manage website updates, Audit report actions	None. Works natively in CMS.
Translation Specialist	Create translations, Audit translations	None. Works natively in CMS.
Chief of Staff	Daily brief, Weekly brief, Meeting prep, Meeting recap, Competitive intel	Teams, Outlook mail and calendar, OneDrive and SharePoint, or Gmail, Drive and Google Calendar. Plus Salesforce.

Two things stand out. First, the Marketing Analyst and Content Marketer both ship a Self evaluation job that scores each run against expected results and logs what worked. That is the memory story in practice, and it is the job I would watch most closely. Second, the Web Manager and Translation Specialist need no third-party connectors at all. For CMS-heavy clients they are the lowest-friction place to start.

Configuration, end to end

Setup happens in two halves: an admin enables a teammate for the organisation, then any permitted user hires their own copy of it. It touches four places: Mark, Connect Platform (the old ODP app directory), Opti ID, and the third-party tool itself. Here is the full path I took, in order.

1. Before you start: email domain (admin)

Check Settings > Email Domain in Mark. Every teammate gets a mailbox on your Mark email domain, so this must be configured and verified first. In the MVP org it already was.

Settings > Email Domain. The verified domain is where each teammate's mailbox lives.

2. Enable the teammate and choose its jobs (admin)

Go to Directory > Virtual Teammates, or Grow your team > Browse the directory from the empty Teammates page, and select Details on a card. This drops you straight into the enable wizard, where every job is on by default. Turn off any you don't want offered. Once a teammate is enabled, the same list lives under the cog on its card as Manage jobs, next to Freeze hiring.

The SEO & AI Search Analyst's four jobs. Admins can switch any of them off for the whole organisation.

After enablement the card shows "1 hired" and a Hire button. The cog holds the organisation-level controls.

3. Install the connectors (admin)

Select Set up connectors. The wizard lists the third-party tools the teammate needs, with a tick for anything already installed and Add connector for anything missing. This example is the Marketing Analyst, where GA4 and Search Console were already in place and Tag Manager was not.

The connector step of the enable wizard.

Add connector opens the connector's app in Connect Platform in a new tab. GA4 showed as installed when the tab opened; Search Console needed Install App. Installing accepts the third-party add-on terms.

The Search Console connector is an app in Connect Platform's App Directory.

4. Configure GA4 in Connect Platform (admin)

Search Console needs no org-level configuration because each user authenticates with OAuth. GA4 does. Open the GA4 app's Settings tab and you get four sections.

The GA4 Mark app settings. The instance-level OAuth toggle is off by default, so each person uses their own Google login.

Under GA4 Properties, add the property ID (from GA4 under Admin > Property details) and an optional nickname. I added realyield.co.uk.

The property ID in Google Analytics, under Admin > Property details.

The property registered in the connector, with its nickname.

Global Filter lets you pin every standard report to one hostname. It is always applied and Mark cannot override it, which is useful when one GA4 property tracks several sites. It does not apply to realtime reports.

The optional hostname filter.

Finally, under Add to Mark, select Add to Mark to register the tools with your Mark account. The spinner gave no feedback and reverted, but it had worked: about a minute later the row showed a tick with Remove from Mark and Sync, and the Mark Connectors page had flipped from "Add connector" to "Connect".

Registered. Do the same for the Search Console app.

The Connectors page in Mark once both Google connectors were registered.

Back in the wizard, select Enable teammate. The card in the directory now says Hire.

5. Hire your teammate (any permitted user)

Hiring is a four-screen wizard:

Name it. Select Hire and give it a name. Mine is Rankin. A name with no spaces keeps the email address clean. You can change the avatar here too.
Choose where it works. Pick the product and instance. The MVP org offered cms and oa. I left it unset, as realyield does not run on Optimizely. The screen is honest that this only tells it where to work. It does not grant access.
Connect its tools. Under Day one essentials, select Connect for each tool. This opens a Google OAuth pop-up that a human must complete, because the teammate cannot consent for itself. Conductor and Semrush appear here too, but as "Set up its tools on the Connectors page first".
Start working together. Once both show Connected, select Start working together, then Go to your teammate. You land in a Team Messages DM.

The hire wizard, from naming to connected tools.

6. Grant access inside Optimizely products (Opti ID admin)

If the teammate will work inside Optimizely products, give its Opti ID user a role on each instance in the Opti ID Admin Center. For CMS 13 and CMS SaaS, also add it under Settings > Set Access Rights with only the rights its jobs need (Read, Create, Change, Delete, Publish or Administer). I skipped this, as Rankin only needed Google data.

Managing a teammate

Every hired teammate appears under Virtual Teammates > Teammates with its own email address, managers, status and start date.

Rankin on the Teammates list, with its own address on the Mark email domain.

Each teammate has two areas. Supervise shows Activity (upcoming and completed job runs, with status, priority and trigger) and Work (everything it has produced).

Activity. The four scheduled jobs are queued, with Audit AEO readiness next up.

Settings covers Identity, Tools, Product Connections and Permissions. Identity holds the basics and a personality, which shapes how it writes and reasons. There are four templates, or you can build your own.

Identity: name, email and start date.

The personality templates: the tastemaker, the hype machine, the pragmatist and the stress tester.

Tools shows what it can reach. Connections you own can be disconnected here; anything an admin has not set up shows as "Contact Admin".

Rankin's tools. GA4 and Search Console are connected; Semrush and Conductor need an admin.

Permissions is where the governance lives. Roles set who manages the teammate and which other people can message it.

Roles. Managers get full access; teammates only what you allow.

Conversation guardrails set what it shares with each audience: managers, named teammates, and anyone in the organisation.

Conversation guardrails per audience.

Jobs can be reordered, switched off, or added. Add job offers Create job or Install from catalog, so you are not limited to the defaults.

Jobs, with the Add job menu open.

Interactions lists the channels it listens on. By default that is instant messaging, and the description shows the tool set it uses to read and reply in Team Messages. Deactivation sits at the bottom and is permanent.

Interactions and deactivation.

Hands-on: what Rankin found on realyield.co.uk

Rankin found a likely GA4 tracking break on its first run, and that alone made the setup worthwhile. realyield.co.uk is a UK buy-to-let analysis side project of mine. It is a small site, which makes it a good test: there is not much data to hide behind.

The onboarding interview

The first message was not a report. It was six questions: domain, competitors, business goals and how SEO contributes to each, priority content areas, keyword focus, and which actions it may take without approval.

Rankin's opening message in Team Messages.

I answered in one message and told it to propose everything first. It played the configuration back, flagged that I had not given a fixed keyword list, and said it had no data yet so would not invent findings.

My answers, and Rankin's confirmation of its working configuration.

The first snapshot

I asked for the last 28 days against the previous 28. The reply came six minutes later, clearly labelled as proposals with nothing actioned. The headline was not a ranking problem at all:

GA4 Organic Search sessions fell 59% (164 against 398) while Search Console clicks fell only 17% (209 against 251).
Every GA4 channel dropped together: 381 sessions against 934 in total, with Direct, Organic Social and AI Assistant traffic all falling at once.
Organic sessions ran at 12 to 20 a day until 1 October, then 1 to 7 a day from 2 October. Search Console clicks show no such step. The GA4-to-GSC ratio went from 1.6x to 0.5x overnight.
It concluded this is probably a tag or consent change around 1 to 2 October, marked it as an unconfirmed hypothesis, and told me to treat GA4 page-level data as unreliable until it is checked.

The first half of the snapshot: the tracking flag and the Search Console scoreboard.

That is exactly the cross-source reasoning a human analyst should do and usually doesn't. The raw data backs it up. GA4's traffic acquisition report shows every channel falling off a cliff at the start of October:

GA4 traffic acquisition for realyield.co.uk, last 90 days. Every channel steps down at the start of October.

Search Console over the same period shows no such step in clicks:

Search Console performance for realyield.co.uk, last three months. Clicks hold steady through October.

The Search Console analysis was just as specific. Clicks were within one standard deviation of the daily mean since 1 July (8.7 a day, SD 3.8, against 7.5 now). 41% of the impression loss was a single query, "rent vs buy calculator", spiking to 6,536 impressions and falling back to 41. The real drift was position: impression-weighted average position went from 16.0 to 21.7 over four weeks, with desktop slipping from 16.6 to 22.4 while mobile improved from 15.4 to 13.6.

It then broke down top pages and found the anomalies worth acting on:

/tools/personal-vs-ltd-company lost 45% of the total click loss on its own. Position held and impressions fell only 9%, so CTR halved from 3.7% to 1.9%. A CTR problem, not a ranking one.
Location pages: 270 URLs with impressions (5,053 impressions, 29 clicks), and 90% of them with no clicks at all. "average rent in" queries had 381 impressions at position 9.7 and no clicks.
The core net yield calculator sits at position 55.7 with no clicks.
Housekeeping: the login subdomain appears in search and should be noindex.

Top pages, top queries and the other anomalies.

The action plan

Five prioritised proposals, each with a first step: fix GA4 tracking and add calculator completion as a key event; rework the core calculator page for "rental yield calculator" and "net yield calculator"; pilot a new location page template on six named cities and read CTR after four weeks; recover CTR on the page that halved; and build a manual AI-citation baseline of about 20 questions because no citation tool is connected. It then listed two further opportunities outside my stated priorities and asked for a steer rather than assuming.

AI visibility, the five proposed actions, and the questions it wanted answered.

Where it fell short

It was honest about it. With no Conductor, Semrush or AI-citation connector, it could not report competitor rankings or citation share, which is half of the "AI Search" in its job title. It also could not find a Team Messages channel to post into, so it put everything in our DM. And at the time of writing none of its four scheduled jobs had run yet, so the daily cadence, memory and self-improvement claims are still untested. I'll follow up once it has a fortnight of runs behind it.

Where they earn their keep

The pattern that fits is recurring, data-heavy work that nobody owns and everybody means to do. Teammates are weakest where the work is a one-off, and strongest where the value comes from turning up every day. Here is where I would start with clients, roughly in order of effort.

Search and AEO monitoring for marketing teams without an SEO. The SEO & AI Search Analyst gives a daily AEO readiness audit, a keyword digest and anomaly alerts off GA4 and Search Console. For mid-market Optimizely clients who rely on an agency retainer for this, it is a real change in cadence.
Weekly reporting that people actually read. The Marketing Analyst replaces the Monday GA4 export. Its 15% channel-movement threshold and "content win of the week" are opinionated defaults, which is what you want from a report.
Content governance on CMS 13 and SaaS. The Web Manager scans content at publish time for brand, legal, style and accessibility issues and stages fixes for approval. Pair it with the Translation Specialist for multi-locale sites. Neither needs a third-party connector, so the only real setup is CMS access rights.
Experimentation hygiene. The CRO Manager's daily SRM, zero-conversion and overrun checks are the boring safety net most programmes lack. Its test plans include sample size and runtime, and it stages experiments in Web Experimentation as drafts for QA.
Personalisation programmes that stall after launch. The Personalization Strategist runs the whole loop from opportunity to campaign build to impact overview, all staged for review.
Leadership admin. The Chief of Staff does daily and weekly briefs, meeting prep and recaps across Microsoft 365 or Google Workspace. Useful, but it competes with Copilot and Gemini, which most clients already pay for.

For partners there is a second angle. A teammate is a packaged, governed role you can hand a client in week one of a build, before their own team is in place. That changes the shape of a launch: the site goes live with an always-on analyst and a content governance check already running.

Governance, credits and gotchas

The governance model is the strongest part of the design. Teammates are real Opti ID users, so access is granted, audited and revoked like any starter's. Managers get full access; other teammates see only what conversation guardrails allow; jobs can be switched off per teammate by its manager, or per organisation by an admin, who can also freeze hiring. Pausing keeps history. Deactivating is permanent and deletes the teammate's memory and context, so pause unless you mean it.

Credits are the open question. Mark uses pooled credits across eligible products, and Scott Reed's October state of play notes that scheduled, webhook and email triggers bill to whoever created the trigger, at an average of 2 credits for chat up to 200 for an XL agent run. The Virtual Teammates docs do not yet say how a teammate's daily jobs are metered or who pays. A teammate running four daily jobs could be a meaningful line item, so model it before you put one in front of a client.

The gotchas I hit:

Org-level data, personal teammate. GA4 property IDs are registered on the connector app for the whole organisation, so everyone in the org sees the list. Data access still runs through each person's own Google OAuth by default, so the exposure is the property name and ID, not the data. That changes if an admin turns on the app's instance-level OAuth option. Think about both before listing client properties in a shared partner sandbox.
No feedback on registration. "Add to Mark" in Connect Platform spins, then silently reverts. It had worked; the Mark Connectors page just took a minute to catch up. The enable wizard also does not refresh connector status until you reload it.
Tool lists disagree. The SEO card shows four tools, but enablement asks for only GA4 and Search Console. Conductor and Semrush then appear at hire time as "Set up its tools on the Connectors page first", and on the teammate's Tools page as "Contact Admin", even though Semrush shows as installed on the Connectors page.
Choosing an instance is not access. The UI says so clearly, but it is still an extra trip to the Opti ID Admin Center, and for CMS a second trip to Set Access Rights.
OAuth needs a human. Every third-party connection is a pop-up a person must complete. Plan this into onboarding sessions with clients rather than assuming an admin can do it alone.
Three names, one product. Opal, Agent Platform and Mark all appear in the UI, docs and connector descriptions. Brief clients on this up front.

Verdict

Virtual Teammates are worth taking seriously, and worth piloting now on one narrow job. The identity and governance model is properly thought through, the onboarding interview is better than most agency kick-offs, and the first piece of analysis I got back was specific, cautious and correct about the thing that mattered most.

The weak spots are setup friction and cost visibility. Enablement spans Mark, Connect Platform, Opti ID and the CMS, with status that lags and tool lists that disagree. And until Optimizely documents how a teammate's scheduled jobs consume credits, I would not promise a client a monthly figure.

My recommendation for partners: pick one client with a clear recurring gap, usually search monitoring or content governance, hire one teammate with propose-only permissions, and review its output weekly for a month before widening its autonomy. That is how you would onboard a junior hire, and it is the right mental model here too.

Sources

Virtual Teammates overview, Optimizely docs
Enable Virtual Teammates, Optimizely docs
Hire a Virtual Teammate, Optimizely support
Manage your Virtual Teammate, Optimizely support
Manage Virtual Teammates for your organization, Optimizely support
2026 release notes, Optimizely docs
Virtual Teammates vs AI agents, Optimizely Field Notes
Optimizely Agent Platform: October state of play, Scott Reed
Optimizely retires DXP label, bets everything on agent platform, CMSWire

Categories have landed in Optimizely SaaS CMS: structure, translate, tag and query

2026-10-19T14:37:13.0000000Z

Categories arrived in Optimizely SaaS CMS at the end of August, with Graph support alongside. I have wanted a proper taxonomy in SaaS since the first build I did on it. Until now we have been faking it with select lists, string arrays or a folder of "tag" blocks. None of those are great. They are hard for editors to maintain, they do not translate cleanly and they make filtering in Graph clumsy.

So I spent an afternoon putting the new feature through its paces on our sandbox instance. This post walks through the whole flow with screenshots: building a category structure, translating it, tagging pages and then querying it all in Optimizely Graph. There are a couple of gotchas in the Graph section that are worth knowing before you start building filters.

Where to find it

Categories live under Settings > Taxonomy > Categories. On a fresh instance you get an empty grid with a locale switcher, a search box and a Create button. Ours already had a single test category in it.

The grid shows Display name, Key, Description, Visible, Selectable, Usage and the usual audit columns. It is wide, so on a laptop you will be scrolling sideways to reach the actions menu at the end of each row.

Creating a structure

I went with a typical B2B example: an Industry parent, three sectors under it, and a third level under Financial Services. I prefixed everything with "Demo" so it is easy to clean up later.

Click Create and you get a row-based dialog.

Each category has these fields:

Field	Notes
Display name	What editors see. Up to 255 characters. Translatable.
Key	The identifier you use in code and Graph. Up to 100 characters, unique, not translatable. It auto-fills from the display name with spaces swapped for underscores.
Description	Optional, up to 500 characters. Translatable.
Parent	Read only. It is set by where you start the create action.
Visible	Whether the category shows in the editor's picker.
Selectable	Whether editors can assign it to content.
Usage	Public or Internal.

The key is the field to get right first time. It is what your front end will depend on, so agree a naming convention with the team before anyone starts typing. The auto-generated value is fine for most cases, but I would not leave it to chance on a real project.

To add children, open the ... menu at the end of a row and choose Create child.

The nice touch here is the + button at the end of each row. You can add several categories in one go rather than opening the dialog for each one. The Parent column is pre-filled and locked.

I repeated that on Financial Services to add Banking and Insurance as a third level.

The result is an expandable tree.

A few things from the documentation that are worth calling out, because they will bite you if you do not plan for them:

You cannot move a category to a different parent after it is created. You have to delete it and recreate it. Get the hierarchy agreed before you load it.
Optimizely recommend keeping trees to three or four levels. I agree. Deeper than that and editors stop being able to find anything.
Visible and Selectable do not cascade. Hiding a parent does not hide its children. This is useful, though. Clearing both flags deprecates a category without deleting it. Leaving Visible on and clearing Selectable gives you a "historic" category that still shows on old content but cannot be applied to anything new.
Usage is metadata only. Marking a category as Internal does not stop it being indexed or returned by Graph. It is a hint for your front end to filter on, not a security control. You also cannot create a Public child under an Internal parent.

My advice: deprecate rather than delete. Deleting a category removes it from every piece of content it was tagged on.

Translating categories

The Locale dropdown at the top of the grid lists the languages enabled for CMS content. Our instance has English as the master, plus Chinese, Spanish and Swedish.

Switch to another language and anything without a translation falls back to the master value. It is shown in italics with a small EN badge so you can see at a glance what still needs doing. This fallback behaviour came in with a fix on 7 October. Before that, untranslated rows just showed blank.

Open ... > Edit on a row and you get an "Edit español translation" dialog. The master values appear as placeholder text. That placeholder is never saved as a translation, so you will not end up with English silently copied into your Spanish data. The key is greyed out because it is shared across all languages.

Once translated, the tree shows the Spanish names. I translated the whole Demo Industry branch. Note that the grid re-sorts by the translated display name, so rows move about as you work through them.

Translation is one row at a time for now. Fine for a demo. For a real taxonomy of a few hundred terms across several languages, I would want a bulk option, or I would script it. The 22 September release also lets you ask Mark, the Agent Platform assistant, to create and update categories for you if you have CMS admin rights. I have not tried that for translations yet.

Tagging pages with categories

This is the part that surprised me. There is no Category property to add to your content types. I went looking under Add Property on our Blog post type and there is nothing taxonomy related in the list. Categories are built in.

Open any page in the editor and a Category field is already there. Start typing and it searches across the whole tree, showing the full path for each match. That path matters when you have two terms with similar names in different branches.

Tick as many as you need. Each one becomes a removable chip.

Only categories that are both Visible and Selectable show up here, which is exactly what you want for the deprecated and historic cases above.

Two behaviours from the docs to be aware of. Categories are assigned in the master language, and the localised names appear on translated versions automatically. Categories are also versioned with the content, so a change on a draft only goes live when that draft is published.

Our Blog post type still has an old "Topic" select list from before this feature existed. If you have something similar, I would plan to migrate it. One managed taxonomy beats a dozen hard-coded option lists scattered across content types.

Querying categories in Optimizely Graph

I published the demo page and moved over to Settings > GraphiQL. The documentation for this part is thin right now, so everything below comes from introspecting the schema and testing queries.

Querying the category tree

Categories are indexed as their own items under a new root query: _TaxonomyTerm.

query CategoryTree {
  _TaxonomyTerm(
    locale: en
    where: { _metadata: { taxonomy: { eq: "categories" } } }
    orderBy: { _metadata: { displayName: ASC } }
  ) {
    total
    items {
      _metadata {
        key
        displayName
        parent
        usage
      }
    }
  }
}

The useful fields on _metadata are key, displayName, description, parent, usage, locale, status and taxonomy. parent holds the parent's key, or null for a root category. That gives you everything you need to rebuild the tree on the front end.

taxonomy returns "categories" for everything today. My guess is that it is there so Optimizely can add more than one taxonomy later. Filtering on it now costs nothing and saves a refactor if that happens.

To get the direct children of a term, filter on parent:

query ChildrenOfIndustry {
  _TaxonomyTerm(
    locale: en
    where: { _metadata: { parent: { eq: "Demo_Industry" } } }
  ) {
    items {
      _metadata {
        key
        displayName
      }
    }
  }
}

Localised category names

Pass a locale and you get the translated values back:

query LocalisedCategory {
  _TaxonomyTerm(
    locale: sv
    where: { _metadata: { key: { eq: "Demo_Industry" } } }
  ) {
    items {
      _metadata {
        key
        displayName
        description
        locale
      }
    }
  }
}

Two gotchas here.

First, the master language fallback you see in the CMS does not apply in Graph. I translated the display name into Swedish but left the description empty. The CMS shows the English description in italics. Graph returns null. If you need a fallback, you have to build it yourself, either with a second query on the master locale or in your front-end mapping.

Second, my Spanish translations never appeared in Graph. Querying with locale: es fails validation because es is not in the schema's Locales enum.

On our instance the only languages in the enum are en, sv and zh. Those are the languages we already have content in. Spanish is enabled in the CMS, but nothing else on the site is published in Spanish. Swedish translations, on the other hand, showed up within ten seconds of saving.

My working theory is that a language has to exist in Graph's index before category translations in that language are picked up. I have not confirmed that with Optimizely, so treat it as an observation rather than documented behaviour. If your translated categories are not coming through, check the Locales enum in GraphiQL first.

Querying content by category

This is the bit you will use most, and it is not where I expected it to be. Categories are not on the usual _metadata field. They are on a separate field called _itemMetadata, which exists on every content type in the schema.

The values are URIs rather than plain keys, in the format cms://taxonomy/categories/<Key>:

"_itemMetadata": {
  "categories": [
    "cms://taxonomy/categories/Retail",
    "cms://taxonomy/categories/Banking"
  ]
}

So to find every blog post tagged with Banking or Insurance, and get facet counts back at the same time:

query PagesByCategory {
  BlogPostPage(
    where: {
      _itemMetadata: {
        categories: {
          in: [
            "cms://taxonomy/categories/Banking"
            "cms://taxonomy/categories/Insurance"
          ]
        }
      }
    }
  ) {
    total
    items {
      Heading
      _metadata {
        url {
          default
        }
      }
      _itemMetadata {
        categories
      }
    }
    facets {
      _itemMetadata {
        categories {
          name
          count
        }
      }
    }
  }
}

eq, in, startsWith and exist all worked as you would expect on a string array. Swap BlogPostPage for _Content and the same filter works across every content type, which is handy for a site-wide "everything tagged Banking" listing.

The facets come back keyed by URI, so your front end needs to strip the prefix and join to the _TaxonomyTerm results to get display names. Something like this does the job:

const keyFromUri = (uri: string) => uri.split("/").pop() ?? uri;

No roll-up through the hierarchy

This is the gotcha most likely to catch people out. Filtering on a parent does not return content tagged with its children. The demo page is tagged Banking, which sits under Financial Services. Filtering on cms://taxonomy/categories/Financial_Services returns zero results.

The hierarchy exists in the taxonomy, but content only knows about the exact terms it was tagged with. If you want "show me everything in Financial Services", you need to:

Query _TaxonomyTerm to collect the keys of the parent and all its descendants.
Turn them into URIs.
Pass the list to an in filter on _itemMetadata.categories.

Two round trips, but both are cheap and the taxonomy query caches well. Build it once as a helper and reuse it everywhere.

Final thoughts

This is a good first release. The admin UI is quick to work with, the multi-row create saves real time, and having categories built into every content item removes a pile of modelling work we used to do by hand. The Graph side gives you everything you need. It just needs a bit of plumbing.

What I would like to see next:

Graph docs that cover _TaxonomyTerm and _itemMetadata, including the URI format.
An option to roll content up through the hierarchy in Graph.
Master language fallback in Graph to match the CMS.
Bulk import and export of categories and translations.
The ability to change a category's parent without deleting it.

If you are starting a new SaaS build, I would use categories from day one rather than rolling your own taxonomy. If you have an existing build with select-list or block-based tagging, it is worth planning the migration now, before the content volume makes it painful.

Personalisation in CMS 13 when you go headless: variations in the CMS, decisions in Experimentation

2026-09-24T13:48:00.0000000Z

Back in February I wrote about personalisation in CMS 13 using Audiences. Everything in that post still holds, with one condition I should have made louder: it only works when the CMS renders the page. The moment your front end is a separate application reading content from Optimizely Graph, Audiences stop doing anything.

This post covers why that is, and how I would approach personalisation on a headless (or hybrid) CMS 13 build instead. The content still lives in the CMS, but the decision about who sees which content moves to Optimizely's experimentation and personalisation products.

Why Audiences do not work on a headless build

Audiences (Visitor Groups, as they were) are evaluated inside the CMS process, on each request. When a content area renders, the CMS looks at the current visitor (their referrer, the pages they have viewed in this session, their geography and so on), checks each item's audience settings, and leaves out the items that do not match. The personalised HTML is the output of that render.

Audiences are evaluated when the CMS renders the content area, which is why they only apply to in-process sites.

On a headless build there is no render in the CMS. Content is published and synchronised into Optimizely Graph once, for everybody, and your Next.js (or other) front end queries Graph when a visitor arrives. Graph never sees the visitor, and the CMS is not in the request path at all, so there is nothing to evaluate the audience against.

Optimizely's own CMS 13 documentation is explicit about this:

"Audiences work only on traditional (in-process) sites, where CMS manages both content authoring and frontend rendering."
(source: Create audiences for personalization)

The CMS 13 technical Q&A adds that Visitor Groups and Audiences "are not indexed to Graph", and recommends "the new Variations support for content and Experimentation for personalization" for Graph-based delivery (source: CMS 13 technical webinar Q&A). The "View as audience" preview is also unavailable on decoupled front ends.

So if your build is headed MVC, carry on with Audiences; the February post still applies. If it is headless or hybrid, read on.

The new split: content in the CMS, the decision in Experimentation

The recommended model separates two jobs that Audiences used to do together.

The content. Editors author each version of a page in the CMS as a content variation. It gets drafted, reviewed, approved and published like any other content, and it is indexed to Graph.
The decision. An experimentation or personalisation engine decides which variation a given visitor should see, and the front end fetches that variation from Graph.

The two are joined by a single string: the variation name. If the engine says "WinterCampaign", the front end asks Graph for the "WinterCampaign" variation of the page. If that variation does not exist, it falls back to the original.

I think this is a better model than it first appears. Content stays in one place, under the CMS's workflow and version history, rather than being pasted into a testing tool's visual editor. The engine that decides is also the one that measures, so every personalised experience can be tested against the original.

Content variations in CMS 13

A content variation is a second (or third, or tenth) published version of the same content item, in the same language. Each variation has its own version history and publishing lifecycle, and only stores the properties you actually change (source: Create content variations in CMS 13).

Creating one from the editor:

Select the page in the content tree.
Choose Variations > Add variation.
Give it a name, for example WinterCampaign. It cannot start with a number or contain spaces.
Select Add variation. The variation opens in Visual Builder and appears in the Variations dropdown.
Make your changes, then Publish > Publish changes.

You can also copy a new variation from an existing one using Copy from, and if a variation wins, Copy changes to Original promotes it to become the new default.

Two things worth knowing before your editors start:

Name variations for what they are, and treat the name as a contract. The name is what the experimentation side will ask for, and it is case sensitive. Rename a variation in the CMS and the front end will quietly serve the original to everyone while the experiment keeps counting visitors.
Check which properties can vary on your version. At the time of writing, variations only vary localisable properties. Treat that as release-specific and re-check it on the version you ship.

Fetching a variation from Graph

By default, Graph queries only return original content, so existing queries are unaffected. To ask for a variation, add the variation argument and keep the original in the response as the fallback (source: Query content variations in Optimizely Graph):

query LandingPage($variation: [String!]) {
  _Content(
    where: { _metadata: { url: { default: { eq: "/winter-offers/" } } } }
    variation: { include: SOME, value: $variation, includeOriginal: true }
  ) {
    items {
      _metadata { key displayName variation }
      ... on LandingPage { Heading MainBody { html } }
    }
  }
}

const requested = items.find((i) => i._metadata?.variation === variationKey);
const original = items.find((i) => !i._metadata?.variation);
const page = requested ?? original;

That fallback is what makes the whole approach safe. If the engine is switched off, returns nothing, or asks for a variation that does not exist, the visitor gets the original page.

Route 1: Feature Experimentation (server-side, the native route)

This is the route Optimizely documents today, and the one I would reach for first on a headless build (source: Configure the Optimizely CMS (SaaS) integration; Piotr Nowak's Unlock Experimentation with Content Variations in CMS 13 walks through the same pattern for CMS 13 with both an MVC and a Next.js head).

In Feature Experimentation:

Create a flag, for example winter_landing_page.
Add variations whose keys match the CMS variation names exactly (WinterCampaign, SummerCampaign). The documented SaaS integration also adds a string variable carrying the name, which is a good idea because it lets you change the mapping without renaming the variation.
Add a rule.
- An A/B test rule splits traffic across the variations and measures them against a metric.
- A targeted delivery rule with an audience serves one variation to everyone who matches, for example visitors in the UK, logged-in members, or a segment you pass in as an attribute. This is where personalisation happens.

In the front end, decide on the server and fetch the matching variation:

import { createInstance, OptimizelyDecideOption } from '@optimizely/optimizely-sdk';

const optimizely = createInstance({
  sdkKey: process.env.OPTIMIZELY_FX_SDK_KEY!,
  datafileOptions: { autoUpdate: true, updateInterval: 60_000 },
});

export async function getVariationKey(visitorId: string, attributes: Record<string, unknown>) {
  await optimizely.onReady();
  const user = optimizely.createUserContext(visitorId, attributes);
  const decision = user?.decide('winter_landing_page', [OptimizelyDecideOption.INCLUDE_REASONS]);
  return decision?.enabled ? decision.variationKey : null;
}

A few things I would build in from the start:

A stable visitor id. Bucketing hashes on the user id, so anonymous visitors need a first-party cookie set in middleware, or they will flip between variations.
Keep the datafile fresh. Without autoUpdate, the JavaScript SDK fetches the datafile once, so rule changes in the dashboard do not reach a long-running server.
Caching. A page that varies by visitor cannot be served from one shared cache entry. Either mark decided responses as uncacheable, or cache per variation (the variation name makes a sensible cache key when the number of variations is small).
Attributes only come from you. Feature Experimentation audiences evaluate the attributes your code passes in. If you want to target on a CRM segment or a logged-in state, the front end has to supply it.

Because the decision happens on the server, there is no flicker and the personalised content is in the first HTML response.

Route 2: Web Experimentation and Personalization (client-side)

The other half of Optimizely's engine is Web Experimentation and its sibling, Optimizely Personalization. Personalization adds campaigns made of experiences, each targeted at an audience, and can use real-time segments from Optimizely Data Platform where you have it (source: Optimizely Personalization overview). Marketers own these audiences and campaigns in the Optimizely UI, which is often exactly what a marketing team wants.

The trap here is the visual editor. It makes it easy to change a heading or swap an image directly in the browser, and when you do that the personalised content lives in Web Experimentation, not in the CMS. It is unversioned by the CMS, invisible to editors, and it breaks the moment the page markup changes.

The better pattern keeps the content in the CMS and uses the campaign only to choose the variation:

Name each Web Experimentation variation or Personalization experience after the CMS variation it should show.
In the front end, read the visitor's active decisions from the snippet's state API and fetch the matching CMS variation from Graph.

function getCmsVariationName(): string | null {
  const state = (window as any).optimizely?.get?.('state');
  if (!state) return null;
  const active = state.getCampaignStates({ isActive: true });
  for (const campaign of Object.values<any>(active)) {
    const name = campaign.variation?.name;
    if (name && /^[A-Za-z][A-Za-z0-9]*$/.test(name)) return name;
  }
  return null;
}

getCampaignStates returns both experiments and personalisation campaigns (source: Get state). Check the returned shape against your own snippet version before relying on it.

This is a pattern rather than an out-of-the-box integration. Optimizely documents the Feature Experimentation route; I have not found a documented Web Experimentation equivalent, so treat this as something you build and own. The trade-offs are the usual client-side ones: the decision happens after the page loads, so either the personalised region is fetched late (reserve its space to avoid layout shift) or you hide it until the decision arrives. I would keep personalised regions out of the largest above-the-fold element for that reason.

Which route should you use?

	Feature Experimentation	Web Experimentation / Personalization
Where the decision happens	Your server or edge	The visitor's browser
Flicker and layout shift	None	Needs designing for
Who owns audiences	Developers pass attributes; audiences built in FX	Marketers, in the Optimizely UI, including ODP real-time segments
Content lives in	The CMS	The CMS, if you use the pattern above
Documented by Optimizely for CMS variations	Yes	Not yet; build it as a pattern

My default on a headless or hybrid CMS 13 build is Feature Experimentation for anything above the fold or on key journeys, with Personalization campaigns where marketers need to own and change audiences without a developer. Both can sit on the same content variations, because the only thing either needs from the CMS is the name.

What about headed sites?

Nothing changes. Audiences still work on in-process CMS 13 sites and remain the simplest option for rules-based personalisation. Content variations work there too, so a headed site can use the same Feature Experimentation pattern with the .NET SDK and IContentLoader when you want proper testing rather than show-and-hide rules.

Optimizely has said deeper integration between the CMS and Experimentation is on the roadmap, without a date. I will update this post if that changes the picture.

Shareable stakeholder previews for Optimizely SaaS CMS

2026-09-14T13:52:54.0000000Z

In August, Nikki Punjabi wrote about a gap in Optimizely SaaS CMS: there is no out-of-the-box way to share a draft page with someone outside the CMS. The editor preview is session-bound. If a legal reviewer or brand owner without a CMS account needs to approve a page, you have to build that yourself.

The post set out a design. The link should be a signed "permission slip" rather than a credential: it grants access to one draft page until an expiry date. Links should be internal-only by default, with external sharing an explicit choice. No database should be needed, CMS keys should stay on the server, and drafts should be hidden from search engines.

We built that design as a CMS UI Extension on the Optimizely Connect Platform (OCP). This post covers how.

Why a CMS UI Extension

Authors should create the link next to the page they are editing, not in a separate admin tool. That is what CMS UI Extensions do: an OCP app can register a sidebar panel inside the editing view. The panel is told which content item is open (key, version, locale) and updates as the editor moves between pages.

The same app also carries its backend functions, a settings screen and storage, so the whole feature ships as one unit. The manifest declares everything:

functions:
  cms_extension:
    entry_point: CmsUiExtension
    accepts: cms_ui_extension     # callable only from the panel
  preview:
    entry_point: Preview
    accepts: http                 # public, reviewer-facing endpoint

ui_extensions:
  sidebar:
    - name: share-preview
      entry_point: SharePreview
      display_name: Share preview

The panel is a React component registered through @optimizely/cms-extensibility-sdk:

register((context) => (
  <AxiomProvider>
    <SharePreviewPanel context={context} />
  </AxiomProvider>
));

context.content.subscribe() gives the panel the open page; context.extension.invokeFunction() calls the app's backend. We built the UI with Optiaxiom, Optimizely's component library, so the panel matches the rest of the CMS.

That is the full setup: a manifest, a React entry point, a backend class, and ocp app prepare --publish to deploy to all regions.

The link

The link contains an HMAC-SHA256 signed token over six fields:

{ contentKey, version, locale, scope, iat, exp }

There are no credentials in it and no session behind it. When a reviewer opens the link, the server recomputes the signature, checks the expiry against its own clock and enforces the scope. Editing the URL to extend the expiry or change the scope breaks the signature.

Internal links only open from configured office or VPN IP ranges. If no ranges are configured, they refuse rather than falling back to shareable behaviour. Shareable is a per-link choice and the panel warns you what it means.

The other guardrails from Nikki's design are all present: noindex via meta tag and X-Robots-Tag, no-store caching, read-only rendering, a clear page for expired links, and a hard refusal when the app is unconfigured. If the page has been published since the link was created, the link redirects to the live page.

Rendering the real page

A metadata summary of the draft is not enough; stakeholders want the page as designed, and in a headless setup only the front end can render it.

Our first attempt was to mint Optimizely Graph tokens from the app, both self-signed with the Graph secret and via an OAuth exchange. Graph rejected both. The documentation is clear once you read it properly: bearer tokens must come from an OIDC authorisation server.

The working approach came from Optimizely's own SaaS demo site, which includes a route at /.well-known/optimizely/preview-psk for exactly this purpose. You send key, ver and loc plus an HMAC signature over those parameters, keyed with a pre-shared token the head already holds. The head validates the signature, fetches the draft with its own server-side Graph credentials, and renders it with its real components. No CMS or Graph credential ever reaches the browser.

That stock route has one problem for this use case: the signature never expires, so the URL a reviewer lands on works forever. We added a sibling route that includes an exp timestamp in the signed data and refuses once it has passed. Our app issues those redirects freshly signed on each visit, valid for ten minutes. The link the author shares remains the single entry point where expiry, scope and revocation are checked.

The key-value store

The first iteration stored nothing, as the original design suggested. Two requirements changed that: authors wanted to see a page's existing links after a refresh, and to revoke one.

OCP apps have a key-value store with atomic read-modify-write and per-row TTL. We keep one row per content item. Each write prunes expired entries and resets the row's TTL to the furthest expiry, so the platform deletes the row once the last link dies. The panel filters by expiry on read, so expired links drop out of the list immediately.

Two details are worth copying:

The KV store documentation says not to store tokens, and our URLs contain one. HMAC tokens are deterministic, so the registry stores only metadata (id, version, locale, scope, issued and expiry times) and the app re-signs the URL when listing. No sensitive value is ever stored.
Revoking moves a link's entry to a deny-list in the same row. The public preview function checks the incoming token's payload against that list. The token format is unchanged, so earlier links are revocable too. A revoke that hits a storage error fails loudly; a viewer request that cannot read the registry fails closed.

Configuration

Everything above is driven by install-time settings, and OCP generates the settings screen for you. The fields are declared in a YAML form definition in the app (forms/settings.yml); a lifecycle hook validates and saves them into the app's settings store, which is the right home for credentials, unlike the key-value store. The app never needs its own admin UI.

The settings map directly to the decisions Nikki's post said to make before building:

Signing secret: leave it blank and the app generates one on save. Rotating it voids every link.
Optimizely Graph credentials: used by the server to fetch drafts.
Front-end preview route and pre-shared key: for rendering the real page.
Live site base URL: published pages redirect here.
Internal network ranges: defines what "internal" means.
Default link expiry: used when the author doesn't pick one.

What it offers

For authors: a panel next to the page with an audience choice (Internal by default, Shareable deliberately), an expiry choice (1, 3 or 7 days), one click to create, copy and send. The table of active links survives refreshes, shows which draft version each link was pinned to, and revokes per row with a confirm step.

For reviewers: a link that opens without an account or login, showing the real page rendered by the front end. Expired and revoked links get clear explanations.

For the organisation: link creation and revocation are logged with content key, version, scope and expiry. Rotating the signing secret voids every link at once. CMS and Graph credentials never leave the server.

Closing

External preview links are a small feature that touches security, caching, indexing and publishing policy, and a SaaS CMS UI Extension handled all of it in one deployable app. If your editors need something the CMS does not ship, this is a good route to it.

Thanks to Nikki Punjabi for the original design.

Personalisation in CMS 13 Using Audiences

2026-02-12T09:00:01.0000000Z

One of the common questions around CMS 13 is whether it still supports personalisation without requiring additional products. The short answer is yes.

CMS 13 includes built in personalisation using what were previously known as Visitor Groups. In CMS 13 these have been renamed to Audiences (Correction they changed to Audiences in latter versions of CMS12 which somehow I missed, Thanks Scott for pointing this out), but the core concept remains the same. You can define audiences based on visitor behaviour and use them to tailor content across your site.

Audiences are managed directly within the CMS interface. For example, you might create an audience made up of visitors who have viewed pages with a specific category more than a set number of times. Once an audience is defined, it can be used to control how content is displayed.

Personalisation is applied at the content level using standard content areas. Editors can choose to show or hide individual components such as a hero or jumbotron based on the selected audience. This allows targeted experiences without introducing additional complexity for editors.

CMS 13 also supports previewing content as a specific audience. This makes it easy to validate personalisation rules and understand exactly what different users will see before changes are published.

This approach provides traditional, rules based personalisation out of the box and offers a clear path to more advanced personalisation in the future if needed. For many organisations, it delivers exactly the right level of capability from day one.

A short video walkthrough is included below to demonstrate this in action.

Experimentation at Speed Using Optimizely Opal and Web Experimentation

2026-01-30T10:24:02.0000000Z

If you are working in experimentation, you will know that speed matters. The quicker you can go from idea to implementation, the faster you can learn, optimise, and deliver impact.

In this short video, I demonstrate just how quick and easy it is to use Optimizely Opal alongside Optimizely Web Experimentation to create and execute an experiment at pace. What normally takes multiple manual steps can be dramatically accelerated, with Opal helping to streamline the entire workflow.

The scenario: make a quick change and run an experiment

The goal of the demo is simple. I want to make a small change to a website and show how fast I can turn that into a working experiment using Opal.

Rather than spending time manually setting everything up, Opal can assist with the process and help generate what you need, quickly and efficiently.

Why this matters: speed and experimentation velocity

The real value here is the speed.

Using Optimizely Opal with Web Experimentation means you can:

reduce time spent on setup
increase experimentation throughput
test more ideas more frequently
accelerate learning cycles across your digital estate

It is genuinely exciting to see experimentation becoming this efficient, and it opens up huge potential for teams who want to move faster without compromising quality.

Final thoughts

Using Optimizely Opal and Web Experimentation together is an absolute dream. The speed in which you can execute experiments, and have Opal support so much of the process for you, is truly impressive.

If you are exploring ways to increase experimentation velocity, this is well worth looking at.

Thank you for watching.

Building an Agent Replicator for Optimizely Opal

2026-01-21T11:46:47.0000000Z

Introduction

A couple of months ago, my team and I took part in the Opal Innovation Challenge (Which we proudly won). We decided to create an agentic AI experience that brings audience insight directly into content workflows, the Virtual Focus Group. By simulating real customer segments and offering instant, nuanced feedback on messaging, this solution helps teams validate messaging in minutes rather than weeks, reduces costly research cycles, and captures behavioural insights that traditional analytics often miss.

To learn more about exactly what we delivered, please find further information here: Virtual Focus Group by Netcel.

However, whilst building the Virtual Focus Group, we quickly discovered that creating and managing multiple specialised agents through the Opal user interface became time consuming and repetitive. Each customer segment needed its own agent with specific configurations, and manually creating dozens of agents was not scalable. This led to the development of the Agent Replicator, a comprehensive toolkit that enables programmatic agent creation, management, and execution following the official Opal Agent JSON Schema specification.

Whilst the Opal API does not yet support programmatic agent creation, this implementation is production ready and can be immediately integrated once Optimizely opens those endpoints. The system includes full CRUD operations, parameter validation, prompt template processing, and request context propagation, everything needed to dynamically create and orchestrate AI agents at scale.

What the Agent Replicator is in practice

In practice, the Agent Replicator is an Opal tool that enables users to create new Virtual Focus Group persona agents quickly and consistently, without leaving Opal.

Once an Opal administrator has registered the Agent Replicator tool endpoint, the capability becomes available in Opal Chat and Opal Workflows. A user can provide a persona scenario and empathy map, and the tool generates a new specialised persona agent, including a tailored prompt template and the parameters needed to run it. That persona agent can then be used by the Virtual Focus Group to review content from a specific audience perspective.

This shifts persona creation from a manual, repetitive task into a fast, repeatable workflow that teams can run whenever new customer segments are needed. It also keeps persona definitions consistent by generating them in a schema aligned format, which makes them easier to manage and evolve over time.

How it works

At a high level, the implementation follows a simple flow.

You deploy the Agent Replicator as a small web service.
The service exposes Opal compatible tool endpoints.
An Opal administrator registers the endpoint inside Opal, which makes the tools available in Chat and Workflows.
Users call the tool to generate persona agents, and then use those persona agents as part of the Virtual Focus Group experience.

The core implementation

The Agent Replicator is built around three pieces:

Schema aligned agent models that match the Opal Agent JSON Schema
Opal tool methods that create and retrieve agent definitions
A small host application that exposes tool endpoints for Opal to register

The sections below show the key parts of the implementation.

1. Adding the Opal tools package

This project references the Optimizely.Opal.Tools package, which provides the infrastructure for exposing tools in a way that Opal can discover and invoke.

<ItemGroup>
  <PackageReference Include="Optimizely.Opal.Tools" Version="0.4.0" />
</ItemGroup>

2. Hosting the tools and exposing endpoints for Opal

This is the important wiring in Program.cs.

It registers the Opal tool service, registers your tool class, and maps the tool endpoints. Once deployed, the mapped routes are what an Opal administrator registers inside Opal.

// Register Opal Tool Service and Tools
builder.Services.AddOpalToolService();

// Register Agent Management Tools
builder.Services.AddOpalTool<AgentManagementTools>();

// ...

app.MapOpalTools();

3. Creating the tool that generates a new persona agent

The Agent Replicator tool methods live in AgentManagementTools.cs. Each method that Opal can call is decorated with [OpalTool] and has a description that Opal can surface in the interface.

The method below creates a new agent definition that matches the Opal Agent JSON Schema fields, stores it for the proof of concept, and returns the created agent back to Opal.

[OpalTool(Name = "create-opal-agent")]
[Description("Creates a new Opal agent within the virtual focus group. This agent can be assigned specific roles, tools, and a prompt template that defines its behavior.")]
public Task<object> CreateOpalAgent(CreateAgentParameters parameters)
{
    var agentId = Guid.NewGuid().ToString();

    var agent = new AgentDefinition
    {
        // Internal tracking fields
        Id = agentId,
        DisplayName = parameters.DisplayName,
        Role = parameters.Role,
        CreatedAt = DateTime.UtcNow,
        UpdatedAt = DateTime.UtcNow,

        // Opal schema fields
        SchemaVersion = "1.0",
        AgentId = parameters.AgentId,
        AgentType = parameters.AgentType,
        Name = parameters.DisplayName,
        Description = parameters.Description,
        Version = parameters.Version,
        PromptTemplate = parameters.PromptTemplate,
        Parameters = parameters.Parameters ?? new List<AgentParameterDefinition>(),
        EnabledTools = parameters.EnabledTools ?? new List<string>(),
        Creativity = parameters.Creativity,
        InferenceType = parameters.InferenceType,
        Output = parameters.Output ?? new AgentOutputDefinition(),
        FileUrls = parameters.FileUrls ?? new List<string>(),
        AgentMetadata = parameters.AgentMetadata,
        IsActive = true,
        IsDeleted = false,
        InternalVersion = 1
    };

    if (!_agents.TryAdd(agentId, agent))
    {
        return Task.FromResult<object>(new
        {
            IsSuccess = false,
            Message = "Failed to create agent due to ID collision. Please try again."
        });
    }

    return Task.FromResult<object>(new
    {
        IsSuccess = true,
        Message = $"Successfully created agent '{parameters.DisplayName}' with agent_id '{parameters.AgentId}'.",
        Agent = agent
    });
}

4. Listing persona agents inside Opal

Once users start generating persona agents, it is useful to list what exists. This tool method returns all agents that have not been deleted, ordered by creation date. This aligns with the experience of listing agents from within Opal.

[OpalTool(Name = "list-opal-agents")]
[Description("Lists all available Opal agents in the virtual focus group (excluding deleted agents).")]
public Task<object> ListOpalAgents(ListAgentParameters parameters)
{
    var agents = _agents.Values
        .Where(a => !a.IsDeleted)
        .OrderByDescending(a => a.CreatedAt)
        .ToList();

    return Task.FromResult<object>(new
    {
        IsSuccess = true,
        Message = $"Found {agents.Count} agent(s).",
        TotalAgents = agents.Count,
        Agents = agents
    });
}

5. Retrieving an agent and its prompt template

To support review and reuse, the next tool fetches a specific agent. This is the foundation for showing an agent’s prompt template inside Opal, which helps teams understand exactly how the persona will evaluate content.

[OpalTool(Name = "get-opal-agent")]
[Description("Retrieves details of a specific Opal agent by ID or agent_id.")]
public Task<object> GetOpalAgent(GetAgentParameters parameters)
{
    var agent = _agents.Values.FirstOrDefault(a =>
        a.Id == parameters.AgentId ||
        a.AgentId.Equals(parameters.AgentId, StringComparison.OrdinalIgnoreCase));

    if (agent == null)
    {
        return Task.FromResult<object>(new
        {
            IsSuccess = false,
            Message = $"Agent '{parameters.AgentId}' not found."
        });
    }

    return Task.FromResult<object>(new
    {
        IsSuccess = true,
        Message = $"Successfully retrieved agent '{agent.DisplayName}'.",
        Agent = agent
    });
}

6. Defining tool parameters so Opal can guide users

Tool parameter models use [Required] and [Description] attributes. This makes the tool self describing, helps validation, and helps Opal present a clear input contract when the tool is used in Chat or Workflows.

public class CreateAgentParameters
{
    [Required]
    [Description("Human-friendly name of the new agent.")]
    public string DisplayName { get; set; } = string.Empty;

    [Required]
    [Description("What this agent does and when to use it.")]
    public string Description { get; set; } = string.Empty;

    [Required]
    [Description("Unique identifier for the agent (e.g., 'brand_lp_research'). Use lowercase with underscores.")]
    public string AgentId { get; set; } = string.Empty;

    [Description("Type of agent: 'specialized', 'workflow', or 'autonomous'. Default is 'specialized'.")]
    public string AgentType { get; set; } = "specialized";

    [Required]
    [Description("Prompt template with agent's instructions. Use [[parameter_name]] syntax for parameters.")]
    public string PromptTemplate { get; set; } = string.Empty;

    [Description("Agent parameters that can be passed at execution time.")]
    public List<AgentParameterDefinition>? Parameters { get; set; }

    [Description("List of tool names the agent can call (e.g., 'browse_web', 'search_web').")]
    public List<string>? EnabledTools { get; set; }

    [Description("Creativity level from 0.0 (deterministic) to 1.0 (creative). Default is 0.5.")]
    public double Creativity { get; set; } = 0.5;

    [Description("Inference type: 'simple' or 'complex'. Default is 'complex'.")]
    public string InferenceType { get; set; } = "complex";

    [Description("Agent version (e.g., '1.0.0'). Default is '1.0.0'.")]
    public string Version { get; set; } = "1.0.0";
}

Registering the Agent Replicator in Opal

Once the service is deployed, an Opal administrator registers the tool provider inside Opal using the URL exposed by MapOpalTools().

After registration, the tools become available within Opal:

In Opal Chat, a user can invoke the tool to generate a new persona agent.
In Opal Workflows, a step can call the same tool to create personas dynamically as part of a workflow.
The newly created persona agents can then be used by the Virtual Focus Group experience to evaluate content from a specific audience perspective.

Conclusion

The Agent Replicator makes it practical to scale Virtual Focus Group personas directly within Opal.

By deploying a small tool service and registering it in Opal, teams can generate persona agents quickly and consistently, inspect the prompt templates those agents use, and reuse the agents across Workflows and Chat. This reduces the manual effort of building and maintaining dozens of audience segments and provides a stable foundation for future integration when Optimizely opens official agent creation endpoints.

Cleaning Up Content Graph Webhooks in PaaS CMS: Scheduled Job

2025-12-17T12:42:30.0000000Z

The Problem

Bit of a niche issue, but we are building a headless solution where the presentation layer is hosted on Netlify, when in a regular delivery cycle and work has to be tested a deployment preview is generated with a unique url, as part of the frontend deployment a new Web Hook is registered in Optimizely Content Graph so when content is published the frontend cache can be invalidated. The problem here is that with so many deployments occuring the list of web hooks can become quite long. While we could have configured deployment previews to skip webhook registration, that would have meant cached content on those environments, preventing proper testing of real-time content updates.

The Solution

Instead of compromising our testing workflow, we built an automated cleanup solution using Optimizely's Scheduled Jobs feature. This job periodically scans all registered webhooks and removes any that don't belong to our production environments, keeping the list clean and manageable.

Implementation

using EPiServer.PlugIn;
using EPiServer.Scheduler;
using RestSharp;
using System.Text;
using System.Text.Json;

namespace Client.Cms.Infrastructure.Jobs
{
    [ScheduledPlugIn(DisplayName = "Clear Graph Webhooks", GUID = "D4F5A6B7-C8D9-4E0F-AB12-3456789ABCDE")]
    public class ClearGraphWebhooksJob : ScheduledJobBase
    {
        private readonly IConfiguration _configuration;
        private readonly IContentLoader _contentLoader;
        private bool _stopSignaled;

        public ClearGraphWebhooksJob(IConfiguration configuration, IContentLoader contentLoader)
        {
            _configuration = configuration;
            _contentLoader = contentLoader;
            IsStoppable = true;
        }

        public override string Execute()
        {
            try
            {
                // Fetch Content Graph Gateway Address, AppKey and Secret from appSettings
                var gatewayAddress = _configuration["Optimizely:ContentGraph:GatewayAddress"];
                var appKey = _configuration["Optimizely:ContentGraph:AppKey"];
                var appSecret = _configuration["Optimizely:ContentGraph:Secret"];

                if (string.IsNullOrEmpty(gatewayAddress) || string.IsNullOrEmpty(appKey) || string.IsNullOrEmpty(appSecret))
                {
                    return "Failed: Missing configuration values for ContentGraph";
                }

                var auth = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{appKey}:{appSecret}"));
                var baseUrl = $"{gatewayAddress}/api/webhooks";

                var client = new RestClient(new RestClientOptions(baseUrl));
                var request = new RestRequest();
                request.AddHeader("Accept", "application/json");
                request.AddHeader("Authorization", $"Basic {auth}");

                var response = client.GetAsync(request).GetAwaiter().GetResult();

                if (!response.IsSuccessful)
                {
                    OnStatusChanged($"Failed to fetch webhooks: {response.StatusCode} {response.ErrorMessage}");
                    return $"Failed: {response.StatusCode} - {response.ErrorMessage}";
                }

                var json = response.Content;
                var webhooks = JsonSerializer.Deserialize<List<WebhookItem>>(json, new JsonSerializerOptions
                {
                    PropertyNameCaseInsensitive = true
                });

                if (webhooks == null || webhooks.Count == 0)
                {
                    OnStatusChanged("No webhooks found or failed to deserialize response.");
                    return "Success: No webhooks to process";
                }

                int deletedCount = 0;
                int skippedCount = 0;

                foreach (var webhook in webhooks)
                {
                    if (_stopSignaled)
                    {
                        return $"Stopped: Processed {deletedCount} deletions, {skippedCount} skipped";
                    }

                    var urls = GetUrls().ToList();
                    if (urls.Any(url => webhook.Request.Url.Contains(url)))
                    {
                        OnStatusChanged($"Skipping webhook {webhook.Id} with URL {webhook.Request.Url}");
                        skippedCount++;
                        continue;
                    }

                    DeleteWebhook(webhook.Id.ToString(), auth, baseUrl);
                    deletedCount++;
                }

                return $"Success: Deleted {deletedCount} webhooks, skipped {skippedCount}";
            }
            catch (Exception ex)
            {
                OnStatusChanged($"Error: {ex.Message}");
                return $"Failed: {ex.Message}";
            }
        }

        public override void Stop()
        {
            _stopSignaled = true;
            base.Stop();
        }

        private void DeleteWebhook(string id, string auth, string baseUrl)
        {
            var client = new RestClient(new RestClientOptions($"{baseUrl}/{id}"));
            var request = new RestRequest();
            request.AddHeader("Authorization", $"Basic {auth}");

            var response = client.DeleteAsync(request).GetAwaiter().GetResult();

            if (!response.IsSuccessful)
            {
                OnStatusChanged($"Failed to delete webhook {id}: {response.StatusCode} {response.ErrorMessage}");
            }
            else
            {
                OnStatusChanged($"Deleted webhook {id}");
            }
        }

        // Fetch URLs from Site Config Block
        private IEnumerable<string> GetUrls()
        {
            var globalSettingsBlock = _contentLoader
                .GetChildren<OptimizelySettingsBlock>(ContentReference.GlobalBlockFolder)
                .FirstOrDefault();

            return globalSettingsBlock?.FrontendUrls ?? Enumerable.Empty<string>;
        }
    }

    public class WebhookRequest
    {
        public string Url { get; set; }
        public string Method { get; set; }
        public Dictionary<string, string> Headers { get; set; }
    }

    public class WebhookItem
    {
        public Guid Id { get; set; }
        public WebhookRequest Request { get; set; }
        public string Preset { get; set; }
    }
}

How It Works

Authentication: The job authenticates with Content Graph using your AppKey and Secret from configuration
Fetch Webhooks: It retrieves all registered webhooks via the Content Graph API
Filter by URL: The job checks each webhook URL against a configurable list of production URLs stored in a global settings block
Smart Deletion: Webhooks matching production URLs are preserved; all others are deleted
Progress Tracking: The job reports its progress and provides a summary of deletions and skips

Key Features

Content-Driven Configuration: Production URLs are stored in an Optimizely block, making them editable by content editors without code changes
Stoppable: The job implements IsStoppable = true and properly handles stop signals for graceful cancellation
Comprehensive Logging: Uses OnStatusChanged() to provide detailed progress updates visible in the Scheduled Jobs interface
Error Handling: Robust try-catch blocks and validation ensure the job fails gracefully with meaningful error messages

Benefits

Deployment previews can register webhooks and test real-time content updates
The webhook list stays clean through automated maintenance
No manual intervention required
Content editors control which URLs to preserve through the CMS interface

Conclusion

By leveraging Optimizely's Scheduled Jobs framework, we've created an automated solution that maintains a clean webhook registry while preserving full functionality across all environments. This approach is far more maintainable than manually managing webhooks or compromising testing capabilities on deployment previews.

The scheduled job can run daily, weekly, or at any interval that suits your deployment frequency, ensuring your Content Graph webhook list remains lean and manageable.

Building a Lightweight Optimizely SaaS CMS Solution with 11ty

2025-12-03T10:59:17.0000000Z

Modern web development often requires striking a difficult balance between site performance and the flexibility needed by content editors. To address this, myself and fellow Optimizely OMVP Graham Carr embarked on a Proof of Concept (POC) to build a solution that prioritises speed and simplicity, while fully leveraging the powerful capabilities of the Optimizely SaaS CMS.

The Challenge: Performance vs. Preview

Our Frontend Architect / Lead, Allyn Thomas, set a clear challenge: find a solution with minimal bloat that is statically generated but still fully compatible with the CMS's live preview capabilities. While frameworks like Next.js are popular, they often come with a significant amount of client-side JavaScript (hydration) that isn't always necessary for content-heavy sites. We wanted something leaner.

The goal was to build a site that is:

Statically Generated: For blazing-fast load times and security.
Lightweight: Avoiding the "hydration tax" of heavier frameworks.
Editor-Friendly: Allowing editors to see live previews of their content in the Optimizely Visual Builder before publishing.

The Solution: 11ty Meets Optimizely SaaS CMS

We chose 11ty (Eleventy) as our Static Site Generator (SSG). 11ty is renowned for its simplicity and flexibility. Unlike other frameworks that force you into a specific client-side architecture, 11ty gives you full control over the output. It generates pure HTML, which is exactly what we needed to keep the bloat to a minimum.

To connect 11ty with Optimizely, we utilised the Optimizely SaaS CMS and the Content JS SDK.

Optimizely SaaS CMS & Content Graph

Our solution centers on the Optimizely SaaS CMS as the headless content repository. We use Optimizely Content Graph, a high-performance GraphQL API, to fetch content. This lets us query exactly what we need, when we need it, keeping our build process efficient.

The Content JS SDK

The Content JS SDK was essential to our architecture. It allowed us to define our content models directly in code using a type-safe builder pattern.

For example, defining a "Button Block" becomes a straightforward TypeScript definition:

import { contentType } from '@optimizely/cms-sdk';

export const ButtonBlock = contentType({
  key: 'ButtonBlock',
  baseType: '_block',
  displayName: 'Button Block',
  properties: {
    Text: { type: 'string', displayName: 'Text' },
    Url: { type: 'url', displayName: 'Url' },
  },
});

This approach ensures that our codebase stays in sync with our content models, providing excellent developer ergonomics and reducing runtime errors.

Structured for Scalability

To maintain sanity as the project grows, we adopted a strict directory structure that mirrors both our content strategy and modern component design principles.

The Models Folder

Our src/models directory is the source of truth for all content definitions. We organized it to reflect the different types of content in the CMS:

src/models/pages/: Definitions for full pages (e.g., ArticlePage, LandingPage).
src/models/experiences/: Composition-based content types used in the Visual Builder.
src/models/components/: Reusable content blocks (e.g., ButtonBlock, TextBlock).

Atomic Component Library

For the frontend implementation, we embraced Atomic Design. This methodology breaks the UI down into its smallest fundamental units, ensuring consistency and reusability across the site.

Our src/components directory is structured as follows:

atoms/: Basic building blocks like buttons, inputs, and text blocks.
molecules/: Groups of atoms working together (e.g., a search form).
organisms/: Complex UI sections like headers, footers, and hero banners.
templates/: Page-level layouts that stitch everything together.

This clear separation of concerns allows developers to work on individual components in isolation while ensuring they fit perfectly into the larger system. It also naturally encourages adherence to the Single Responsibility Principle, as each atom, molecule, or organism has a distinct and focused purpose.

Dynamic Routing with 11ty Pagination

One of the challenges with a static site generator is mapping dynamic content from a CMS to static routes. 11ty handles this elegantly through its pagination feature. We treat our entire content repository as a single "paginated" data set, where each item becomes a page.

First, we fetch all routable content in a global data file, src/_data/routes.js:

// src/_data/routes.js

module.exports = async function () {
  // ... client setup ...

  // Fetch all content items that have a URL
  const query = getRoutePagesQuery(blockFragments);
  const data = await client.request(query);

  // Filter out items without a default URL
  const pages = data._Content.items.filter(item =>
    item._metadata &&
    item._metadata.url &&
    item._metadata.url.default
  );

  return pages;
};

Then, we create a single template, src/pages.11ty.ts, that iterates over this data. By setting size: 1, 11ty generates a separate HTML file for each item in the routes array. The permalink function ensures the file is saved to the correct path as defined in the CMS.

// src/pages.11ty.ts

export const data = {
  pagination: {
    data: 'routes',
    size: 1,
    alias: 'contentItem',
    addAllPagesToCollections: true,
  },
  layout: 'base.11ty.ts',
  permalink: (data: any) => {
    const item = data.pagination.items[0];
    return item._metadata.url.default;
  },
  // ...
};

export function render(data: any): string {
  const item = data.pagination.items[0];
  return ComponentFactory(item);
}

This pattern is incredibly powerful. It means we don't need to manually configure routes or create separate templates for every page type. As editors add new pages in Optimizely, 11ty automatically discovers them and builds the corresponding static pages.

The Component Factory

To handle the diverse range of content types returned by the CMS, we implemented a Component Factory. This function acts as a dispatcher, inspecting the __typename or content type of each item and rendering the appropriate component.

// src/components/ComponentFactory.ts

export function ComponentFactory(content: ContentItem): string {
  // Handle CompositionComponentNode wrapper
  if (content.component) {
    return ComponentFactory(content.component);
  }

  const types = content._metadata?.types || [];
  const typename = content.__typename || '';

  // Dynamic component lookup from registry
  const ComponentView = getView(typename);
  if (ComponentView) {
    return ComponentView(content);
  }

  // Fallback for unknown types
  return `
    <div class="unknown-component" data-epi-block-id="${content._metadata?.key}">
      <h3>${content.Title || content._metadata?.displayName || 'Unknown'}</h3>
      <p>Unknown component type: ${typename}</p>
    </div>
  `;
}

This architecture adheres to the Open/Closed Principle. We can add new component types to our registry without modifying the core routing or rendering logic.

Enabling Live Previews

The most critical part of this POC was ensuring that 11ty's static nature didn't hinder the editing experience. We implemented a dedicated Express Preview Server that runs alongside our 11ty build.

This server acts as a dynamic bridge between the Optimizely Visual Builder and our static templates.

The Express Server Implementation

We chose Express for its robustness and ease of use. The server handles several key responsibilities:

HMAC Authentication: Securely fetches draft content using preview tokens.
Context Awareness: Toggles between "Edit Mode" (injecting data-epi-* attributes) and "Preview Mode".
Real-time Updates: Listens for webhooks to trigger 11ty rebuilds when content is published.

Here is a glimpse of how we handle preview requests in src/preview/server.ts:

// src/preview/server.ts

app.get('/preview/:contentKey', async (req: Request, res: Response) => {
  const { contentKey } = req.params;
  const { preview_token, ctx } = req.query;

  try {
    // 1. Set context mode for Visual Builder (edit vs preview)
    const contextMode =
      ctx === 'edit' ? 'edit' :
      ctx === 'preview' ? 'preview' :
      null;
    setContextMode(contextMode);

    // 2. Set preview token to enable access to draft content
    if (preview_token && typeof preview_token === 'string') {
      previewClient.setPreviewToken(preview_token);
    }

    // 3. Fetch content dynamically
    const content = await previewClient.getContentByKey(contentKey);

    if (!content) {
      return res.status(404).send(renderNotFound(contentKey));
    }

    // 4. Render using the same shared templates as 11ty
    const html = renderContent(content);
    res.send(html);
  } catch (error) {
    res.status(500).send(renderError('Server Error', String(error)));
  }
});

Handling Webhooks

To keep the static site in sync with published content, we also exposed a webhook endpoint. When an editor publishes a page, Optimizely notifies our server, which triggers a debounced rebuild of the 11ty site.

// src/preview/server.ts

app.post('/webhook/content-published', (req: Request, res: Response) => {
  // ... validation ...

  // Debounce rebuilds to handle rapid updates efficiently
  if (rebuildTimeout) {
    clearTimeout(rebuildTimeout);
  }

  rebuildTimeout = setTimeout(() => {
    triggerRebuild();
  }, REBUILD_DEBOUNCE_MS);

  res.json({ status: 'ok', message: 'Rebuild scheduled' });
});

This dual approach gives us the best of both worlds: a static site for production visitors and a dynamic, interactive preview for editors.

Why 11ty Over Next.js?

While Next.js is a fantastic framework, for this specific use case, 11ty offered distinct advantages:

Zero Client-Side JS by Default: 11ty doesn't assume you want a Single Page Application (SPA). It serves HTML. If you want JavaScript, you add it. This results in significantly smaller bundle sizes and faster Time to Interactive (TTI).
Build Speed: 11ty is incredibly fast at building static pages, which is crucial when scaling to thousands of pages.
Simplicity: The learning curve is gentler, and the architecture is easier to reason about. There is no complex hydration logic to debug.

Conclusion

This POC has demonstrated that you don't need a heavy JavaScript framework to build a modern, dynamic, and editor-friendly website with Optimizely SaaS CMS. By combining the raw power and simplicity of 11ty with the robust APIs of Optimizely, we have delivered a solution that delights both developers and content editors.

We have achieved the best of both worlds: the performance of a static site with the dynamic editing capabilities of a CMS-driven application.

You can view the final result here: 11ty-netcel-saas.netlify.app

The full source code is available on GitHub: github.com/MineshS/11ty (Currently a private repo but please do reach out with Git Username so can add)

Extending Application Insights in an Optimizely PaaS CMS Solution

2025-09-24T23:19:07.0000000Z

As part of a recent Optimizely DXP project, I needed richer telemetry from the Content Delivery API than the default Application Insights integration provides. The aim was to capture custom properties such as content IDs and cache status so that we could slice and query API performance in more detail. Here is the approach I took.

Creating a Custom Telemetry Processor

The first step was to create a custom 'ITelemetryProcessor' implementation to enrich telemetry for Content Delivery API requests. This processor inspects each telemetry item, checks whether it relates to the Content Delivery API, and then adds custom properties such as 'ApiType', 'IsOptimizelyApi', and the extracted 'ContentId'.

public class ContentDeliveryApiTelemetryProcessor(ITelemetryProcessor next) : ITelemetryProcessor
{
    private readonly ITelemetryProcessor _next = next;

    public void Process(ITelemetry item)
    {
        if (item is RequestTelemetry requestTelemetry &&
            IsContentDeliveryApiRequest(requestTelemetry.Name))
        {
            requestTelemetry.Properties["ApiType"] = "ContentDeliveryApi";
            requestTelemetry.Properties["IsOptimizelyApi"] = "true";

            var contentId = ExtractContentIdFromUrl(requestTelemetry.Url?.ToString());
            if (!string.IsNullOrEmpty(contentId))
            {
                requestTelemetry.Properties["ContentId"] = contentId;
            }
        }

        _next.Process(item);
    }

    // Helper methods to identify API requests and extract IDs omitted for brevity
}

Register the processor with Application Insights in 'startup.cs' or the Program configuration so that it runs for every request.

Adding Request and Response Logging Middleware

To go further, I introduced a middleware component to log the full request and response cycle for API calls. This middleware captures request and response bodies, headers, and timing, and sends a single 'RequestTelementry' entry to Application Insights with custom properties such as cache status.

Below is a reduced example focusing on adding custom properties to a tracked request:

public class RequestResponseLoggingMiddleware(RequestDelegate next, TelemetryClient telemetryClient)
{
    private readonly RequestDelegate _next = next;
    private readonly TelemetryClient _telemetryClient = telemetryClient;

    public async Task InvokeAsync(HttpContext context)
    {
        // … capture request/response details …

        var telemetry = new RequestTelemetry
        {
            Name = $"{context.Request.Method} {context.Request.Path}",
            Url = new Uri($"{context.Request.Scheme}://{context.Request.Host}{context.Request.Path}{context.Request.QueryString}"),
            Duration = stopwatch.Elapsed,
            ResponseCode = context.Response.StatusCode.ToString(),
            Success = context.Response.StatusCode < 400
        };

        telemetry.Properties["ApiType"] = "ContentDeliveryApi";
        telemetry.Properties["IsOptimizelyApi"] = "true";
        telemetry.Properties["CacheStatus"] = cacheStatus;
        telemetry.Properties["RequestHeader_UserAgent"] = context.Request.Headers["User-Agent"];

        _telemetryClient.TrackRequest(telemetry);
    }
}

app.UseMiddleware<RequestResponseLoggingMiddleware>();

And configure logging levels in 'appSettings.json:

"Logging": {
  "LogLevel": {
    "Default": "Warning",
    "Cms.Infrastructure.Middleware.RequestResponseLoggingMiddleware": "Information"
  },
  "ApplicationInsights": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

This approach provides structured, queryable telemetry for each Content Delivery API call.

Example Output

Benefits of Extended Telemetry

Extending telemetry offers several practical advantages:

Deeper diagnostics: You can quickly isolate performance bottlenecks, such as slow content retrieval or cache misses.
Better observability: Custom properties allow you to group or filter requests by content item, making it easier to identify patterns.
Operational insight: Logging cache status and request headers reveals how your CDN, edge caching, and client applications interact with the CMS.

In large Optimizely solutions, where API calls power multiple front ends, this level of detail is invaluable for proactive monitoring.

Dynamic CSP Management for Headless and Hybrid Optimizely CMS with Next.js

2025-09-08T09:43:10.0000000Z

In the evolving realm of web security, Content Security Policy (CSP) is essential for defending against XSS and injection attacks. Traditional approaches often fall short because policies are embedded in code and hard to coordinate across environments.

Optimizely CMS supports dynamic CSP in a headed setup, where the CMS renders pages. This is straightforward with third-party modules such as the Stott Security Optimizely module. Installation is simple, configuration is clear, and the headers flow with the response.

Headless and hybrid architectures introduce a gap. The frontend is separate, so CSP headers often end up fixed in the application tier. That limits agility for security and content teams.

By combining the Stott Security module with Next.js middleware, dynamic CSP becomes possible in headless and hybrid environments. Policies remain CMS-managed, even when the site is delivered through a decoupled frontend.

What we’re solving

Policy changes without releases: Update CSP in CMS and apply instantly.
Environment variations: Manage dev, staging, and production policies centrally.
Cross-team flow: Security and marketing can adjust policies without blocking frontend teams.

Headed vs headless

In headed Optimizely CMS, dynamic CSP is native to the page response. This remains a solid and current pattern. In headless and hybrid setups, the CMS serves content APIs while a separate frontend handles rendering. Without a bridge, CSP is usually hardcoded in that frontend. The approach below restores the same dynamic control you expect in headed.

Architecture

User Request → Next.js Middleware → Stott Security API → Optimizely CMS → Dynamic CSP Headers

The user requests a page from the Next.js app.
Middleware intercepts the request.
Middleware calls the Stott Security endpoint to retrieve current headers.
Headers are applied to the response before it is returned.

Implementation in Next.js middleware

The example below removes development-only branches. It always sources headers from CMS for consistency.

import { NextRequest } from "next/server";

export async function middleware(request: NextRequest) {
  const baseCmsUrl = process.env.DXP_URL || "https://localhost:5000";
  const headersUrl = `${baseCmsUrl}/stott.security.optimizely/api/compiled-headers/list/`;

  // Create or reuse a Response object from your app logic prior to this point.
  // For illustration we assume you already have a 'response' to enrich.
  let response = new Response();

  try {
    const cmsResponse = await fetch(headersUrl, {
      headers: { "Content-Type": "application/json" },
      // Consider short caching and timeouts at edge to keep latency tight
    });

    if (!cmsResponse.ok) {
      // Replace with your logger
      console.error({
        status: cmsResponse.status,
        statusText: cmsResponse.statusText,
        url: headersUrl,
        path: request.nextUrl.pathname,
        context: "middleware - security headers fetch failed"
      });
      return response; // graceful fallback
    }

    const securityHeaders: Array<{ key: string; value: string }> = await cmsResponse.json();

    securityHeaders.forEach(h => response.headers.set(h.key, h.value));

    return response;
  } catch (error) {
    // Replace with your logger
    console.error({
      error,
      url: headersUrl,
      path: request.nextUrl.pathname,
      context: "middleware - security headers processing error"
    });
    return response; // fail safely
  }
}

In your production app, you’ll attach these headers to the actual page or asset response you are returning from Next.js. Keep the fetch lean, and prefer edge runtime where possible.

Key benefits

CMS-managed security: Update CSP without code changes. See the effect immediately.
Environment flexibility: Dev can be relaxed, staging can mirror production with test tools, production can stay strict.
Operational speed: Emergency updates and new integrations go live from CMS.
Resilience: If the CMS API is unavailable, the site continues with safe defaults.
Developer experience: Clear separation of concerns. No more per-environment hardcoding.

Practical considerations

Performance

Enable caching at the CMS endpoint for short periods.
Return compact JSON from the Stott Security module.
Use edge middleware for minimal latency.

Security

Rely on the module’s validation to prevent invalid CSP syntax.
Keep an audit trail of edits to support compliance.

Workflow

Document your policy structure in CMS.
Align environments through content, not code.
Test policy variations in staging, then promote.

Why the Stott Security module

Comfortable CMS UI for policy editing.
Validation before changes go live.
CSP violation reporting integration.
Support for multiple sites and additional security headers.

Explore the module on GitHub: GeekInTheNorth/Stott.Security.Optimizely.

Conclusion

Headed Optimizely CMS already delivers dynamic CSP with ease. The approach above brings the same control to headless and hybrid builds. Policies stay in CMS, the frontend stays decoupled, and security remains responsive to change.

With Next.js middleware, Optimizely CMS, and the Stott Security module, CSP moves from static configuration to a manageable, collaborative capability. It works with the speed of your teams and the realities of modern delivery.

Resources

The Sweet Spot: Hybrid Headless Architecture

2025-09-04T10:54:45.0000000Z

When it comes to content management architecture, the pendulum often swings between tightly coupled “headed” CMS setups and the flexibility of fully headless. In reality, many organizations are finding the sweet spot in between: hybrid headless. Pair that with Optimizely PaaS CMS and GraphQL, and you get an architecture that balances agility, scalability, and most importantly, content editor empowerment.

The Three Approaches: Headed, Headless, and Hybrid

Traditional headed CMS
CMS and presentation are tightly coupled. It is easy for content editors and fast for classic web builds, but it struggles to expand into multi-channel experiences.
Fully headless CMS
The CMS acts purely as a content repository, serving JSON via APIs. Front-ends can be built with any technology, but editors lose in-context previewing, and development teams bear additional complexity.
Hybrid headless CMS
With Optimizely, you retain in-context editing while exposing content via APIs. Add GraphQL, and your content architecture gains flexibility, typing, and API efficiency, all while keeping the editorial experience intact.

Why Hybrid Headless with Optimizely PaaS + GraphQL Wins

1. Editor-first without compromise

Editors stay in their familiar Optimizely interface, including on-page preview, content workflows, and drag-and-drop editing, without workarounds required in fully headless setups.

2. Developer agility with GraphQL

GraphQL gives developers precise, efficient data access in a single request. It is strongly typed, self-documenting, and accelerates onboarding as well as development velocity.

3. Why Optimizely PaaS CMS

One of the main advantages of running on PaaS rather than SaaS is the additional control it gives development teams. With PaaS, you are not limited to purely configuration-driven approaches. You can implement bespoke functionality, advanced business logic, and integrations that go beyond what SaaS-only solutions allow.

PaaS also provides deeper control over GraphQL and custom properties, which can be crucial when modelling complex content or delivering advanced omnichannel experiences. This level of flexibility ensures you can tailor the platform to your unique business needs rather than shaping your requirements around the platform.

For organizations with more sophisticated demands, this makes PaaS the better fit. You get the stability and scalability of Optimizely’s managed environment while still retaining the freedom to innovate and customize.

4. Scale baked in with Optimizely One

Optimizely’s DXP handles infrastructure, scaling, uptime, and resilience. Crucially, infrastructure is managed directly by Optimizely, so your team does not need to worry about patching servers or handling traffic spikes.

What is new is that you now also have the option to host your decoupled presentation layer on Optimizely. This means you can run your React, Next.js, or other modern front-end applications side by side with your CMS in a fully managed environment. Optimizely takes care of hosting, CDN, and security, the same way it already does for your CMS (If PaaS CMS, inhouse engineering team will need to handle upgrades, SaaS CMS is fully managed by Optimizely). This makes hybrid headless even more compelling, since both your content layer and your front-end layer can be managed under one roof. For more background, see my earlier take on Frontend Hosting (early thoughts and key questions).

5. Reduced complexity vs. fully headless

Going fully headless often means every template, component, and preview experience has to be engineered from scratch. While that gives developers maximum flexibility, it also creates a lot of operational overhead.

Hybrid headless takes a more balanced approach. Editors retain control over templates, layouts, and content structures directly in the CMS, without needing to wait on engineering teams for every change. This lets marketing teams spin up new landing pages, adjust layouts, or test different content formats on their own, while still benefiting from in-context previewing.

When it comes to personalization, hybrid headless works hand in hand with Optimizely’s Personalization Platform and Web Experimentation Platform. Editors and marketers can create personalized variants or run experiments without relying heavily on developers to rewire the front end. The CMS ensures content and templates are structured in a way that these platforms can easily consume, so experimentation and targeting become smoother across channels.

The result is less engineering effort, faster time to market, and greater autonomy for editors and marketers to deliver tailored customer experiences.

6. Personalization and future-proofing

Optimizely’s personalization and experimentation capabilities extend naturally in a hybrid model. Using the Optimizely Personalization Platform and Web Experimentation Platform, marketing teams can deliver tailored content and run experiments across websites, apps, and other channels.

Because the CMS provides structured content and GraphQL enables efficient delivery, these platforms can target the right segments without requiring heavy developer involvement. As new channels like AR or VR, wearables, or AI-driven assistants emerge, the same approach applies: structured content from the CMS, flexible delivery via GraphQL, and personalization layered on top through Optimizely’s dedicated platforms.

Where Opal and the JS SDK Fit In

Opal: Generative AI capabilities embedded in the CMS help editors query content, generate ideas, and streamline content-to-experience workflows.
Content JS SDK: The Content JS SDK abstracts GraphQL wiring, giving front-end developers a clean, easy-to-use interface for consuming CMS content. This cuts boilerplate and speeds up delivery.

Conclusion: The Sweet Spot

Editors stay empowered
Developers get modern flexibility
Optimizely manages infrastructure, including the option to host your decoupled front-end alongside your CMS
Future personalization and multi-channel strategies remain fully open

It is not about swinging to one extreme. It is about choosing an architecture that enables speed now and adaptability tomorrow. With GraphQL, Opal, the Content JS SDK, and the ability to host both CMS and presentation layer on Optimizely, hybrid headless is the architecture that delivers the sweet spot.

Optimizely Frontend Hosting Beta – Early Thoughts and Key Questions

2025-04-23T13:43:24.0000000Z

Optimizely has opened the waitlist for its new Frontend Hosting capability. I’m part of the beta programme, but my invite isn’t due until May, while I haven’t had hands-on access yet, I’ve already been digging into what I’ll be looking for once it lands.

What is Frontend Hosting?

This new offering is designed to simplify how frontend apps are deployed and managed alongside Optimizely CMS. It’s available as an add-on to both CMS SaaS and PaaS, and brings together:

Hosting for headless frontend applications
A built-in delivery network
Web Application Firewall (WAF)
Managed services for build, deploy and performance

This could offer a tighter, more integrated experience for those already using a headless CMS setup.

If you’re after background on other frontend hosting options, I covered related topics in these earlier blog posts:

What I’ll Be Exploring in the Beta

Environment & Compatibility

Will it work cleanly across CMS SaaS and CMS PaaS?
What frameworks will be supported out of the box (e.g. Next.js, Astro)?
Will it handle different build strategies?
- Static
- Dynamic
- Incremental builds
Are serverless functions on the roadmap (Lambda, Edge functions)?
Is there a CDN and WAF already in place?
Are preview environments supported (e.g. URLs for pull requests)?

Developer Experience

Any limits around build minutes, concurrent builds?
Built-in CI/CD or integrations with GitHub/GitLab?
How is secret management handled? (Environment Variables)
What kind of logging and observability is available?
Will it help surface key metrics (e.g. Core Web Vitals, SEO signals)?
Can I get alerts if a deploy fails or performance drops?

Access & Security

Can access be restricted (IP allow lists, password protection)?
Is traffic control through WAF configurable?
Can we apply rate limits?

Commercial Considerations

How will pricing work?
- Bandwidth
- Seats
- Execution time for serverless
Multi-project or multi-site support — all under one roof?

Why It’s Interesting

For teams running hybrid headless setups, this could remove a fair bit of friction. No need to spin up hosting separately or stitch things together manually, this could mean fewer moving parts, more predictable deployment workflows, and a clearer support model.

And being Optimizely-native, it should also mean closer alignment with the rest of the platform ecosystem.

Discovery & Early Access

I was part of an early discovery interview with the team last year, which gave me a first look at the thinking behind this product. Here’s part of the follow-up I received:

"As you may recall, you participated in a discovery interview with us about CMS frontend hosting last year. Your feedback back then was extremely helpful! I wanted to let you know that we are now in a beta testing phase of frontend hosting!"

I’ve also some early preview screenshots from the discovery. I’ll include a few of those in this post to give a sense of what might be coming.

Note: The screenshots shown here are from early design mockups shared during the initial discovery phase. The UI and features in the current beta release may differ significantly as the product has continued to evolve.

Get Involved

Optimizely is actively inviting feedback to help shape this feature before full release. If this looks like something you’d want to test, you can still register via the waitlist.

I’ll post more as soon as I’m hands-on in May — including walkthroughs, findings, and observations from real use cases.

Stay tuned.

Experimentation strategies with Optimizely: Web, Edge, and Feature Experimentation

2025-04-05T12:24:37.0000000Z

Experimentation is a cornerstone of data-driven decision-making, and Optimizely offers multiple ways to run experiments across your digital experiences. Whether you are optimising a website, personalising a user journey, or testing new features, choosing the right experimentation strategy can have a significant impact on both user experience and performance.

In this post, we’ll explore three key experimentation approaches in Optimizely: Web Experimentation, Edge Experimentation, and Feature Experimentation—highlighting their strengths, trade-offs, and performance considerations.

Web Experimentation: Client-Side Testing

Optimizely Web Experimentation is the most commonly known form of A/B testing, where experiments are executed client-side via JavaScript. This means that changes are applied dynamically in the browser after the page has loaded.

Benefits of Web Experimentation

Fast iteration: Non-technical teams (e.g. marketers, designers) can quickly create and deploy experiments without engineering support.
Rich visual editing: The WYSIWYG editor enables easy modification of elements without touching code.
Wide experimentation scope: Ideal for A/B testing landing pages, copy variations, UI elements, and other front-end components.

For more information, refer to the official Optimizely Web Experimentation documentation: Optimizely Web Experimentation Introduction

Performance considerations

Flickering effect: Since changes are applied after the page loads, some users may briefly see the original content before the variation is applied.
JavaScript overhead: As the number of experiments grow, the required JavaScript also increases, which may affect page load times.
Execution time: Performance can vary depending on the complexity of the variation and network conditions.

Despite these considerations, Web Experimentation remains a powerful tool for non-technical teams looking to optimise experiences without needing backend development effort.

Edge Experimentation: Server-side, high-performance testing

Edge Experimentation moves the execution of experiments from the browser to the edge layer, where content delivery happens closer to the user (e.g. via a CDN or middleware). This approach ensures experiments are applied before the page reaches the end user.

Benefits of Edge Experimentation

Near-zero performance impact: Since variations are applied before the response reaches the client, there’s no flickering or delay.
More reliable data: Eliminates client-side inconsistencies, ensuring accurate measurement of experiment results.
Faster experimentation for global users: Leveraging CDNs and edge computing reduces latency, making experiences smoother for users worldwide.

For more information, refer to the official Optimizely Performance Edge documentation: Optimizely Performance Edge Overview

Use cases

Edge Experimentation is ideal for personalisation at scale, content experiments, and changes that impact performance-sensitive areas such as eCommerce checkout flows and high-traffic landing pages.

Feature Experimentation: Server-side testing for feature rollouts

Feature Experimentation allows teams to test and control feature rollouts via feature flags at the server or middleware level. Unlike Web Experimentation, which focuses on front-end changes, this method is geared towards testing new functionalities before full deployment.

Benefits of Feature Experimentation

No performance trade-offs: Since variations are applied server-side, users receive the final content without delay.
Safe feature rollouts: Teams can progressively roll out features to a subset of users before full release.
Deeper experimentation possibilities: Beyond UI tests, Feature Experimentation enables testing changes in logic, APIs, and infrastructure.

For more information, refer to the official Optimizely Feature Experimentation documentation: Optimizely Feature Experimentation Introduction

Use cases

This approach is perfect for testing new functionalities, backend optimizations, and product feature toggles while minimising risks.

Choosing the right experimentation strategy

When deciding between Web, Edge, and Feature Experimentation, consider the following:

Factor	Web Experimentation	Edge Experimentation	Feature Experimentation
Performance	Can introduce flickering and JavaScript overhead	Near-instant, no flickering	No client-side impact
Experiment Scope	Front-end UI elements	Content and UI changes at the edge layer	Feature toggles, backend logic
Execution Location	Client-side (browser)	CDN/Edge layer	Server-side or middleware
Implementation Effort	Low (no engineering needed)	Medium (requires setup)	High (involves development)
Best For	Marketing, UI tweaks, messaging tests	Performance-critical content changes	Feature rollouts, backend logic experiments

Final thoughts

Each experimentation approach in Optimizely has its place. Web Experimentation remains a powerful tool for marketers and teams that need agility, despite its minor performance trade-offs. Edge and Feature Experimentation, on the other hand, offer superior performance and scalability by shifting execution away from the client.

Ultimately, leveraging a combination of these approaches based on your goals, performance requirements, and team capabilities will lead to the most effective experimentation strategy.

Exploring Optimizely SaaS CMS – What’s New & How to Accelerate your Build

2025-02-27T11:00:25.0000000Z

In my latest video, I take a fresh look at Optimizely SaaS CMS, covering some of the recent improvements aimed at enhancing the editor experience. Plus, I dive into the fantastic work Remko has done with his helper packages and starter solutions, making development even more seamless.

🔹 Learn how to effortlessly create an Element in the UI and scaffold it in the frontend.
🔹 See how you can generate a new element directly in the frontend and push it to the CMS.

If you're working with Optimizely or just curious about headless CMS solutions, this one's for you!

📺 Watch here: https://youtu.be/m8zvDgdYmpk

Links I used in the video:

Remkos Git Repository: https://github.com/remkoj
Optimizely Mosey Demo: https://github.com/episerver/cms-saas-vercel-demo

Let me know your thoughts in the comments!

SaaS CMS - Pages and Blocks get the Visual Builder Treatment

2024-12-17T16:27:43.0000000Z

I’m thrilled to see that Optimizely has now enabled Visual Builder for OG Pages and Blocks within SaaS CMS, and I’m guessing this will become standard for CMS13. Previously, Visual Builder was only available for Experiences, forcing us to revert to traditional on-page editing which was somewhat clunky or use the "All Properties" view, which didn’t provide a great preview experience.

With Visual Builder, we now get the best of both worlds: an intuitive editor experience combined with the ability to preview our changes in real time. I haven’t taken this for a proper spin yet, but the early signs are very promising.

When editing structured pages, the new interface looks like this:

As shown above, updates can be made in the left panel, and they are instantly reflected in the main preview panel.

In contrast, the old on-page editing view looked like this and was never as responsive:

Additionally, Visual Builder is now available for Blocks as well. The interface for Blocks is similar to Pages, and it looks like this:

Although my templates aren’t perfect, this is entirely within our control via the frontend presentation layer (Next.js).

This is just a quick post to share my initial impressions, but I’ll provide more updates as I integrate this into my own templates.

SaaS CMS - Self-hosting Presentation Layer with Coolify

2024-09-23T19:00:11.0000000Z

Introduction

In my previous post, I explored the hosting options for the Hybrid Headless/Fully Headless presentation layer (frontend) using Netlify and Vercel. These platforms are my top recommendations due to their ease of use and feature-rich offerings. However, there are situations where they may not entirely meet your needs, or their pricing models might pose challenges.

If you're looking for more control over your hosting costs, self-hosting is a viable third option, whether on physical servers or virtual private servers (VPS). To make the self-hosting process more manageable, I’ve created a proof of concept using Coolify. Coolify is an open-source project that simplifies server configuration for hosting your frontends with minimal effort. It offers many of the same features as Vercel and Netlify, but without the associated costs.

Here are some of Coolify's standout features:

Language Agnostic: Supports a wide range of programming languages and frameworks, including Next.js.
Flexible Deployment: Can be deployed on any resource, including your own servers, VPS, EC2, and DigitalOcean—all you need is an SSH connection.
Push to Deploy: Easily deploy by pointing to any Git repository.

PR/Commit Deployments: Automatically deploy new commits and pull requests.

Additional Features:

SSL certificates
Automatic backups
Webhooks
API-first approach
Collaboration tools
Monitoring and notifications

Azure Example

Coolify offers flexible installation and configuration options, allowing deployment on virtually any environment. For full documentation, you can refer to Coolify's official guide.

For this example, I chose to test Coolify on a Linux (Ubuntu 24.04) Virtual Machine. The setup process in Azure is straightforward, so I won't dive into each setup step, but here’s a quick overview of my configuration below:

I also had to open a few ports to allow for communication to and from the virtual machine. This was for both setup purposes and public site access (I was adding these as and when required).

Port 22 for SSH Access
Port 8000 for initial Coolify server Access
Port 80 for Public HTTP Access
Port 443 for Public HTTPS Access

Once my virtual machine was configured, I made an SSH connection. You can connect either via the Azure Portal or using your favorite terminal.

Install and Configure Coolify

Once connected via SSH, the installation of Coolify was simple. Running the following command started the process:

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

This installs Docker and runs the Coolify image. The entire process took about 5 minutes. After installation, Coolify provides a URL to complete the configuration. Once I registered, I was taken to the Coolify dashboard, ready to create a new project.

Domain Configuration

To make access easier, I connected a domain to my server. I used an existing domain from Fasthosts and made simple DNS changes by adding two A Records (@ and *), pointing them to my server’s public IP address.

In Coolify’s settings, I configured the domain name for the control panel at http://coolify.chillicrunch.co.uk. I also set up Wildcard Subdomains to allow deployments to URLs like https://<my-project-name>.chilicrunch.co.uk/, similar to how Netlify and Vercel manage deployments.

This was done by navigating to Servers > General and adjusting the settings.

Connecting to Git Hub Repo

To enable continuous deployment, I connected Coolify to my private GitHub repository. Coolify supports several Git sources, but for this example, I used GitHub. You can add your GitHub repo by navigating to Sources and clicking Add. The process requires setting up Client ID, Secret, and Webhook Secret, which are generated during the setup.

Adding a new Project

With the Git connection established, I was able to add my first project. In the Projects section, I clicked New, provided a name and description, then selected the Git repo I wanted to deploy.

The deployment process took about 3 minutes. Thanks to the wildcard subdomains setup, the subdomain was automatically configured. I also added the necessary environment variables for my project. You can find more details on this process in this video.

With everything in place, my website was live: https://saas-cms-visual-builder.chilicrunch.co.uk/

Conclusion

Setting up Coolify on an Azure Virtual Machine was smooth and straightforward. As you can see, it's easy to get Coolify up and running on your private servers with minimal effort, making it a cost-effective alternative to traditional hosting platforms like Vercel and Netlify.

Frontend Hosting for SaaS CMS Solutions

2024-07-20T00:21:31.0000000Z

Introduction

Now that CMS SaaS Core has gone into general availability, it is a good time to start discussing where to host the head. SaaS Core is natively a Headless CMS, and regardless of whether you plan to use it in a "Pure Headless" or "Hybrid Headless" manner, the presentation layer (Head/Frontend) needs to be hosted somewhere.

Cloud Native Providers: Vercel and Netlify

Optimizely has partnered with Vercel and Netlify, both of which offer fantastic services for hosting the frontend of your application. Both platforms support a variety of frontend frameworks and static site generators, making them versatile choices for a project's hosting needs.

They provide a seamless experience for developers with continuous deployments, user-friendly CLI tools, unlimited deployment environments, and highly efficient build processes. Every time a pull request is raised, or a commit has been made to a branch, both services automatically build a preview with a unique URL. Like a staging environment for every PR or branch, previews are perfect for testing and collaboration.

To ensure the frontend is fast and scalable, both platforms offer a CDN to serve requests and support edge or serverless functions to execute any business logic. Serverless functions are a way to deploy server-side code as API endpoints. These will spin up automatically when triggered by an event, handle and process server ran code, and then spin down until the next event. Edge Functions are similar to serverless functions that are generally more efficient and faster than traditional Serverless compute, since they operate within a much leaner runtime. Deployed globally by default, Edge Functions run in the region closest to the request for the lowest latency possible.

Commercial Models

Vercel and Netlify are designed to simplify the deployment and management of your website’s frontend, ensuring reliability, speed, and ease of use. Their commercial models are quite similar; both offer customizable enterprise pricing based on the specific needs of the organization. Pricing typically includes multiple developer seats, high bandwidth limits with additional costs for overage, and extensive usage of serverless and edge functions with charges for higher usage. Both platforms provide enterprise-grade support, including dedicated account management and service level agreements (SLAs) to ensure high availability and priority issue resolution.

Demonstration

Here is a quick video demonstrating the deployment of the Mosey Template to Vercel: Watch the video.

A similar process was replicated on Netlify with very few changes to the frontend code or configuration.

Conclusion

By leveraging the robust hosting capabilities of Vercel and Netlify, you can ensure that the frontend of your application is performant, scalable, and easy to manage. Whether you choose Vercel or Netlify, both platforms offer the tools and support needed to seamlessly deploy and maintain your website.

But Wait

... Oh and for a bit of fun I also looked at self hosting either on prem or on a VPS using Coolify, surprisingly this was also very easy and in less than an hour I had this : https://saas-cms-visual-builder.chilicrunch.co.uk

Hopefully have a demo on this early next week :)

Exploring SaaS CMS: API Clients and Content Management APIs

2024-03-06T20:29:56.0000000Z

Introduction

In continuation of my previous post on leveraging the Content Management API and OpenID Connect Authentication on the PaaS-based Optimizely CMS, I delve into the delivery mechanisms within the SaaS-based CMS Platform. Surprisingly, the majority of functionalities are readily available and seamlessly integrated into the system. In this article, I provide a quick preview of the available features and guide on configuring the exposed API for definition and content management.

Note: It's essential to bear in mind that while I explore these features, the SaaS platform is still in its BETA phase, and APIs are currently at version 0.5. Changes might occur as the SaaS CMS transitions into general availability.

Configuring the API Client (Equivalent to OpenID Connect Package)

The API client functionality comes pre-installed in the SaaS CMS, and the setup is near identical to what we found on the PaaS platform with the Open ID Connect package. The tool can be found within Settings and the Access Rights section as highligted in the image below.

Once on the API Client interface we can create a Client ID, the Client Secret is automatically generated please store this safely as there is no way of retrieving once you leave the page. The option to "Allow the client to impersonate users" is self-explanatory; enabling this allows the client to function as another user within the CMS.

Using the credentials

I'll demonstrate how to utilize these credentials using Postman to retrieve a JWT token for subsequent API calls. To obtain a Bearer Auth Token, a GET call needs to be made to the designated URL:

https://app-xxxprod.cms.optimizely.com/_cms/v0.5/oauth/token

Sending the required parameters along with the request, including grant_type, client_id, client_secret, and optionally act_as, will result in the generation of a token for future requests. Notably, this token expires automatically after 300 seconds.

Example:

Authorisation to API using the Bearer Token

With the Bearer Token generated, subsequent API requests can now be authenticated by passing this token as the "Authorization" Header parameter.

Example:

Content Definitions API

Now armed with the bearer token, we can interact with the Content and Definitions API. The first API we explore is the Content Definitions API. Detailed API reference can be found here.

Get Content Types

A simple GET request to the following URL provides a list of all content types within the CMS:

https://app-xxxprod.cms.optimizely.com/_cms/v0.5/contenttypes

Example:

To only get the details of a certain known type we pass in the definition name (key) to the URL:

https://app- xxxprod.cms.optimizely.com/_cms/v0.5/contenttypes/articlepage

Create Content Type

To create a content type, a POST request is made to the same URL, passing in the necessary parameters.

Example:

Content {Delivery} API

The API reference to the Content API can be found here : Create content (optimizely.com)

Get Content

To retrieve a content item, a GET request is made to the designated URL, using the Guid of the page as the key. The key is in a UUID format so should not include any dashes e.g. 115988243510434482925671c3ee601a

https://app- xxxprod.cms.optimizely.com/_cms/v0.5/content/{key}

Example:

Conclusion

As you can see its very easy to interact with the API’s and retrieve the relevant information you may need, as well as programmatically being able to create Content Models and Instances of these models. Its great to see this has all been included from the get go and provides a lot of scope to decide on how we manage the content definition creation process.

A Quick Guide to Using the Content Management API and OpenID Connect Authentication

2023-11-01T22:44:53.0000000Z

Introduction

Content management in Optimizely CMS becomes more efficient and streamlined with the power of the Content Management API.

The Optimizely Content Management API adds REST endpoints for basic content management operations such as:

Create content objects
Modify existing content objects
Delete content objects
Get draft content objects
Move content objects

The REST API is useful for pushing external content to Optimizely without having to deploy custom integration code to the Optimizely Content Management System (CMS).

In this quick guide, I'll walk through the steps to set up a solution for content creation using the API.

Prerequisites

Before diving into the process, ensure you have the following:

An active Optimizely CMS instance (For Alloy site setup, refer to my guide here).
Familiarity with an API request tool like Postman.
A good understanding of your CMS's content structure and types.

Step 1: Install and Configure the Content Management API

First, let's set up the Content Management API. If you're using Visual Studio, you can install it via the Package Manager or via the CLI using this command:

dotnet add package EPiServer.ContentManagementApi

Once installed, modify the Startup Class to include the basic configuration. In the ConfigureServices method, add the following line:

services.AddContentManagementApi(o => o.DisableScopeValidation = true);

Then, build and run your solution with:

dotnet run

Step 2: Test the Endpoint

After installing the Content Management API, you can test the endpoint using Postman. Send a simple POST request to /api/episerver/v3.0/contentmanagement. As we haven't added any parameters, expect a 400 Bad Request status code with a specific JSON response.

{
    "errors": {
        "filename": [
            "The filename field is required."
        ],
        "content-Type": [
            "The contentType field is required."
        ]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-b2f4877cb70b04fc20ea6fc0dfe1d2fe-d37b0cf2e4dc9458-00",
    "code": "InvalidModel"
}

This response tells us the endpoint is operational. Alternatively, it would have resulted in a 404 status code. At this stage, we can try adding content to Optimizely CMS via Postman. Use the provided JSON body, but you'll likely encounter a 401 status due to permissions.

{
  "name": "Text Block (Content Management API)",
  "language": {
      "name": "en"
  },
  "contentType": [
      "Block",
      "EditorialBlock"
  ],
  "parentLink": {
      "id": "33"
  },
  "mainBody": {
      "value": "<p>Hello World</p>"
  },
  "status": "Published"
}

Response Example

{
    "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Access was denied to content 33. The required access level was \"Create, Publish\".",
    "instance": "/api/episerver/v3.0/contentmanagement",
    "traceId": "00-c91883ef32f39b8dda0571df62c44b7b-d48fe0471f6254da-00"
}

For testing purposes, you can temporarily grant access rights to "Everyone" for creating and publishing pages. After making this change, re-run the request. You should now receive a 201 (Success) status code with the content successfully created in CMS.

Step 3: API Authentication via OpenID Connect

In the real world, giving "Everyone" access to publish content is not acceptable. To ensure authorized individuals/services create and publish content, we need to authenticate Content Management API requests using OpenID Connect and Bearer Tokens (JWT). Here's how:

Install the OpenIDConnect NuGet package with this command:
```
dotnet add package EPiServer.OpenIDConnect.UI
```

Amend the Startup class to configure this package and make Content Management API support it. Update the code as follows:

services.AddContentManagementApi(OpenIDConnectOptionsDefaults.AuthenticationScheme, options =>
{
    options.DisableScopeValidation = true;
});

services.AddOpenIDConnect<ApplicationUser>(
    useDevelopmentCertificate: true,
    signingCertificate: null,
    encryptionCertificate: null,
    createSchema: true
);

services.AddOpenIDConnectUI();

After saving the file, build and run the solution and access Optimizely Admin mode. Look for "OpenID Connect" in Settings, create a new application (set Scopes as "epi_content_management").
Test if it all works by making a POST request in Postman to /api/episerver/connect/token with the following parameters:
- client_id: api-client
- client_secret: SuperSecret
- grant_type: client_credentials
You'll receive a time-limited access token.

Having got this far and sucessfully being able to generate a bearer token, we have to grant our newly created client permissions to create and publish content, we do this by managing access rights in Optimizely. Remove additional rights given to the "Everyone" group and add them to the api-client with the same rights instead.

Finally, copy the access token from Postman and make another POST request to /api/episerver/v3.0/contentmanagement, this time also setting the Authorization Token.

That's it! We're now securely creating content via the Content Management API using a JWT Bearer Token.

** For additional Security measures you can add some additional CORS policies to your Optimizely Solution so only certain services can call the Content Management API requests or even lock the API down via IP Restrictions.

Conclusion

The Content Management API alongside Content Definitions API are quite powerful tools, they are not difficult to setup and have many use cases for example with the Content Management API we can quite easily utilise for migration processes and import a large amount of content into the CMS in bulk all programmatically. With the recent announcement of the SaaS CMS offering the Content Definitions API is quite useful in creating Content Types and something that can quite easily be source controlled, so definitely something to look out for and try-out.

Blog posts by Minesh Shah

Virtual Teammates in Optimizely Mark: a hands-on first look

Teammate, not agent

The directory: eight teammates

Configuration, end to end

1. Before you start: email domain (admin)

2. Enable the teammate and choose its jobs (admin)

3. Install the connectors (admin)

4. Configure GA4 in Connect Platform (admin)

5. Hire your teammate (any permitted user)

6. Grant access inside Optimizely products (Opti ID admin)

Managing a teammate

Hands-on: what Rankin found on realyield.co.uk

The onboarding interview

The first snapshot

The action plan

Where it fell short

Where they earn their keep

Governance, credits and gotchas

Verdict

Sources

Categories have landed in Optimizely SaaS CMS: structure, translate, tag and query

Where to find it

Creating a structure

Translating categories

Tagging pages with categories

Querying categories in Optimizely Graph

Querying the category tree

Localised category names

Querying content by category

No roll-up through the hierarchy

Final thoughts

Further reading

Personalisation in CMS 13 when you go headless: variations in the CMS, decisions in Experimentation

Why Audiences do not work on a headless build

The new split: content in the CMS, the decision in Experimentation

Content variations in CMS 13

Fetching a variation from Graph

Route 1: Feature Experimentation (server-side, the native route)

Route 2: Web Experimentation and Personalization (client-side)

Which route should you use?

What about headed sites?

Shareable stakeholder previews for Optimizely SaaS CMS

Why a CMS UI Extension

The link

Rendering the real page

The key-value store

Configuration

What it offers

Closing

Personalisation in CMS 13 Using Audiences

Experimentation at Speed Using Optimizely Opal and Web Experimentation

The scenario: make a quick change and run an experiment

Why this matters: speed and experimentation velocity

Final thoughts

Building an Agent Replicator for Optimizely Opal

Introduction

What the Agent Replicator is in practice

How it works

The core implementation

1. Adding the Opal tools package

2. Hosting the tools and exposing endpoints for Opal

3. Creating the tool that generates a new persona agent

4. Listing persona agents inside Opal

5. Retrieving an agent and its prompt template

6. Defining tool parameters so Opal can guide users

Registering the Agent Replicator in Opal

Conclusion

Cleaning Up Content Graph Webhooks in PaaS CMS: Scheduled Job

The Problem

The Solution

Implementation

How It Works

Key Features

Benefits

Conclusion

Building a Lightweight Optimizely SaaS CMS Solution with 11ty

The Challenge: Performance vs. Preview

The Solution: 11ty Meets Optimizely SaaS CMS

Optimizely SaaS CMS & Content Graph