Blog posts by Ritu Madan

Opal Workflow Agents And The Graph Webhook Trap

2026-10-14T01:06:16.0000000Z

What we did?

We built a compliance review workflow agent in Opal. The job was simple: when an editor submits a page for review in Optimizely CMS 13, the agent reads the content, checks it against defined compliance rules, and writes its findings back onto the item so a human reviewer sees them before approving.

One editorial action in, one review out. That was the whole contract. A complete run costs 100–130 credits and takes 2-4 minutes. This makes a single run fairly expensive on credits. Now picture that same run firing over and over, several at once, and the consumption climbs fast.

The trigger was the only open question. Opal workflow agents can fire a few ways — chat input, a schedule, email, or a webhook — but for a run that kicks off automatically when something happens in the CMS, the webhook is the one that fits. So something in Optimizely CMS had to notice “this page entered review” and POST to the trigger URL. The obvious source was Optimizely Graph. It’s pure configuration — register a webhook through the API, no CMS code to deploy — and it already models content changes, which is more or less what we were reacting to. So we started there: a Graph subscription pointed at the Opal trigger, filtered to the InReview status.

What we didn’t see coming?

The first run worked exactly as intended. An editor submitted a page, the status went to InReview, Graph synced, the webhook fired, and the agent ran its compliance check.

Then the agent did the one thing it was built to do: it wrote its findings back onto the page.

That write-back was a save. The save synced to Graph. The content was still InReview — writing findings doesn’t change an approval status — so Graph delivered a webhook for an InReview document, which is exactly the event we’d subscribed to. The agent fired again. Checked again. Wrote back again. Synced again.

By the time we were looking at it, we had four pages of execution logs: the same agent, on the same page, running over and over, several instances going at once. We started cancelling runs manually to stop them burning through credits. The agent was triggering itself, and nothing in the loop was going to stop it.

Nothing was broken, which is what made it hard. Graph was doing exactly what Graph does.

Why it looped?

Seeing the behaviour was easy. Finding the cause took a while. Two facts about Graph, neither of them a bug, combined into the loop:

Graph syncs on save, not on intent. It re-indexes whenever content is saved, published, moved, deleted, or expired. Our agent’s write-back is a save like any other, so every write re-syncs.

Status is part of a document’s identity. Graph identifies an indexed document as {contentGuid}_{version}_{locale}_{status}. Our write-back changed the content but left the status at InReview — so every re-sync produced the same InReview document, indistinguishable from the submit event we’d subscribed to. There was no status change to mark the work as handled, and no state anywhere saying “this one’s done.” So each sync looked like a fresh reason to run.

Underneath it, the mistake was conceptual: we were inferring an editorial decision from index activity. But the index was churning every time our own agent touched the page — and the agent never stopped touching the page.

The fix: subscribe to the decision, not the side effect

Optimizely CMS already raises an event for the exact moment we cared about. The approval engine exposes IApprovalEngineEvents, and its Started event fires once, when an approval instance begins — i.e. when a human submits for review. It’s raised by the approval lifecycle, not the persistence layer. Background saves, forced writes, and our own agent’s write-back don’t start approval instances, so they don’t raise it.

So instead of inferring the decision from Graph, we subscribed to it directly in the CMS solution and POSTed to the Opal trigger ourselves:

[InitializableModule] [ModuleDependency(typeof(EPiServer.Web.InitializationModule))] public class ComplianceReviewTriggerModule : IInitializableModule { private IApprovalEngineEvents _approvalEvents; // IContentLoader, IHttpClientFactory, config resolved in Initialize() public void Initialize(InitializationEngine context) { _approvalEvents = context.Services.GetRequiredService<IApprovalEngineEvents>(); _approvalEvents.Started += OnApprovalStarted; // raised once, on submit } private void OnApprovalStarted(object sender, ApprovalEventArgs e) { if (!e.IsContentApproval()) return; // approvals are generic var contentLink = e.GetContentLink(); // extension method if (ContentReference.IsNullOrEmpty(contentLink)) return; if (!_contentLoader.TryGet<MyCustomPage>(contentLink, out var page)) return; // scope to our content type // Mirror Graph's docId shape so the workflow is source-agnostic. var docId = $"{page.ContentGuid}_{contentLink.WorkID}_{page.Language.Name}_InReview"; _ = Task.Run(() => TriggerOpalAsync(docId)); // fire and forget, with a timeout } }

A few things that mattered in practice:

• ApprovalEventArgs has no ContentLink. Approvals are a general mechanism; content approvals are one implementation. You reach the item through the IsContentApproval() and GetContentLink() extension methods in EPiServer.Approvals.ContentApprovals.

• The Opal trigger wants auth. The webhook trigger takes an Auth Key and sends it as a header (e.g. Authorization: Bearer {token}). Our POST sets that header from config; a request that doesn’t match is rejected.

• We mirrored Graph’s docId shape in the payload, so the downstream workflow didn’t need to change. If we ever switch sources again, the agent doesn’t care.

• Fire-and-forget has a cost. Blocking the editor’s submit on an outbound call is a bad idea, so we don’t. The trade is that if Opal is unreachable the moment Started fires, that trigger is lost — at-most-once. For a review flow that’s fine, because an editor can resubmit. If it weren’t, we’d add retries or a durable queue.

Result: one submit, one execution. The write-back still syncs to Graph, but we’re no longer listening to Graph for this trigger, and writing content doesn’t start an approval — so there’s nothing left to re-fire. The loop was gone, not because we out-guarded it, but because we stopped listening to the wrong layer.

So when is Graph the right source?

The lesson isn’t “Graph is wrong.” Graph is excellent — for the thing it actually reports, which is content as the published world sees it.

Reach for Graph when:

• You’re reacting to content state, not editorial intent — a page got published, purge the CDN; rebuild the static site. This is Graph’s canonical use case, and duplicate deliveries are harmless because the second purge is a no-op.

• The consumer is idempotent — ISR cache invalidation, deploy hooks, downstream sync. Firing twice costs nothing.

• You don’t own the CMS codebase, or you’re on SaaS CMS. Graph is configuration, no deploy required.

• The consuming system is decoupled from CMS and you don’t want to couple to its internals.

Reach for a CMS server-side event (the code path) when:

• The trigger is an editorial decision — submitted, approved, rejected. That lives in the approval engine, and Graph can’t model it.

• Your workflow writes back to the item that triggered it. This is the one that bit us; any index-based trigger risks the same loop.

• Each execution is expensive. When a run costs real credits and minutes, precise firing matters far more than easy setup.

• You need business rules before firing — content type, language, site. Strongly typed C# beats filtering on payload shape.

For us it was a compliance review agent that wrote back to the page it reviewed, at 100+ credits a run. Three of those four boxes. Graph was the wrong tool for this job. We kept Graph for delivery-side concerns and moved the editorial trigger to the approval event. They answer different questions.

The takeaway

Both sources are honest. Graph faithfully reports that an indexed document changed. The approval engine faithfully reports that a person made a decision. Neither is broken.

The real question is which of those you care about — a document changing or a person deciding — and subscribing at that layer instead of inferring it from the one below. When a workflow fires more often than the business event behind it, the instinct is to bolt on a guard. Sometimes you need one. But first ask what your event source is actually reporting.

Ours was reporting every save. Our agent just happened to be the thing doing the saving.

Thomas in the AI Discovery Era

2026-10-06T02:48:33.0000000Z

Its been a while, but hope you haven't forgotten Thomas, our most loyal visitor, the one who suddenly stops showing up.
Not because he lost interest. Because he asked an AI tool the question he used to Google, got his answer in thirty seconds, and never came to the site at all.
That's the shift most brands haven't clocked yet. The front door moved. Search isn't the only way in anymore, and a lot of the traffic you're losing to AI never shows up as a loss in your analytics. It just quietly isn't there.
But here's the part worth sitting with: AI isn't only taking visits. It's also sending them, to the brands it decides are worth citing. Which means the game isn't over. It just changed.
I pulled apart what actually earns those citations, and the one tactic everyone's doubling down on that the 2026 data says barely moves the needle. Plus what it means for the visitor who lands on your site already halfway through a thought.

Read the full article here.

Finding Thomas Part 5 - The Closed Loop

2026-07-20T14:34:06.0000000Z

Five weeks. Five layers. One Thomas.

If you've followed this series from the start — thank you. If you're just landing here, the short version: Thomas is the returning visitor who reads everything, opens every email, converts on nothing, and one day quietly stops coming back. No warning. No signal. Just gone.

Over the last four posts we traced exactly how that happens — and how to stop it. The CMS watching Thomas's behavior as it unfolds. ODP turning that behavior into a persistent, scorable profile. Personalization making him feel seen for the first time. Opal scaling that recognition to every Thomas in your audience without a human bottleneck.

Part 5 is the final part where all four connect.

Not as adjacent tools. Not as a martech stack. As a single, continuous loop — one that finds Thomas while he's still Drifting, responds before he reaches At Risk, and gets smarter with every intervention it makes.

It also ends where the whole series began. With Thomas. And with the question worth asking honestly of any Optimizely implementation that has been live for more than a year:

Is your platform pointed at finding Thomas — or is it still primarily pointed at bringing new visitors through the door?

Read the full story here.

Finding Thomas Part 4 - The Intelligence Layer

2026-07-14T19:01:56.0000000Z

I've been finding Thomas for a couple weeks now. Bear with me — we're almost at the full picture.

Quick catch-up : Thomas is the returning visitor who reads everything, opens every email, converts on nothing — and one day quietly stops coming back. No warning. No signal. Just gone.

In Parts 1 through 3 we built the foundation — the CMS watching him, ODP profiling him, Personalization making him feel seen for the first time.

Part 4 is where it gets interesting.

Because everything we've built so far has a ceiling. Someone still has to hypothesize the Thomas profile, build the segment manually, monitor the scores, and make judgment calls. At the scale of a real content ecosystem, that human dependency is the bottleneck.

Opal removes the ceiling.

It doesn't guess what Thomas looks like. It learns what Thomas looks like — from the behavior of every visitor who eventually stopped coming back. Then it scales that recognition to thousands of Thomas-profile users without manual intervention.

There's also a productive paradox at the heart of this one: the answer to AI displacing your site traffic is AI deployed inside your own ecosystem. Part 4 makes that case. Read it here.

Finding Thomas Part 3 - The Moment of Recognition

2026-06-26T17:08:48.0000000Z

Remember Thomas?

In digital landscape, Thomas is the returning visitor who reads everything, opens every email, converts on nothing. In standard reporting, he is invisible — absorbed into aggregate metrics that look healthy, precisely because he keeps showing up.

In Part 1, we talked about the CMS - how it watches Thomas's behavior, page by page, scroll by scroll, without anyone assembling that data into a story.

In Part 2, we talked about ODP - how it takes that behavioral data and turns it into a real, scorable profile, complete with an Engagement Trajectory that tells you Thomas is Drifting before he's gone.

Here's where we left off - the data has recognized Thomas but the experience hasn't!

In Part 3, we recognize Thomas and curate his experience of your site.

This is where Optimizely Personalization comes into play. It translates Thomas's behavioural data profile from ODP into an experience that finally makes him feel seen without naing him or using surveillance language.

Read the full story here on how we remove the friction points and recalibrate the experience to appreciate Thomas's loyalty.

Finding Thomas Part 2 - The Recognition Engine

2026-06-01T16:59:04.0000000Z

Remember Thomas?

In Part 1, we talked about the CMS - how Optimizely CMS is not just a publishing platform but an observation post. Every visit Thomas makes generates behavioral data - which content he reads, how deeply he scrolls, which paths he returns through, how his visit frequency is trending over time. The data is there. The problem is that most implementations are not built to read it as a story. The narrative exists. Nobody is assembling it.

In Part 2, Thomas Becomes Visible

This is where ODP takes the raw behavioral events from the CMS, stitches them together across sessions and channels, and builds a persistent, unified profile that can be segmented, scored, and acted upon. This is not a data warehouse exercise. It is a recognition exercise.

Read the full story here on how we put together an engagement trajectory for Thomas in ODP, that then helps your digital estate recognize him.

Finding Thomas Part 1 - The Observation Post

2026-05-28T14:40:53.0000000Z

Meet Thomas

Thomas is the returning visitor who has been to your site forty times but has never filled out a form. He opens every newsletter but rarely clicks through. He reads your long-form content to the end while your analytics records him as just another session. He has a deep, genuine interest in the topics you cover — and an equally deep invisibility in the metrics your team reviews every week.

He does not bounce. He does not unsubscribe with a parting comment. He does not leave a one-star review. He just quietly, incrementally, recalibrates whether your experience is worth his time. And when he decides it is not — when the accumulated weight of feeling unseen finally tips the balance — he stops coming. Without a word. Without a signal.

We call this a recognition failure. And it's the most expensive problem in digital experiences that almost nobody is actively measuring.

About This Series

Finding Thomas is a five-part series about understanding and solving this problem using the Optimizely platform. Across these posts, we follow Thomas through the full digital experience layer — what your CMS can reveal about him, what ODP can connect across his behavioral history, how Personalization can respond in ways that make him feel known, and how Opal helps teams move from insight to action at scale.

Each post covers one layer of the stack. Together they trace a complete, closed-loop recognition system — one that finds Thomas before he finishes leaving, and makes him feel, for the first time, like someone noticed he was there.

In Part 1 of our Finding Thomas series, we trace where this starts — and why the CMS most teams treat purely as a publishing tool is actually the first place Thomas's story can be caught before it ends.

Read the full story here.

Optimizely Configured Commerce and Spire CMS - Figuring out Handlers

2025-03-12T19:33:49.0000000Z

I recently entered the world of Optimizely Configured Commerce and Spire CMS. Intriguing, interesting and challenging at the same time, especially when my past experience had been with traditional Optimizely CMS and Customized Commerce. The idea is the same, but the implementation is quite different. So yes it becomes a bit daunting, to forget old ways and get used to these new ones.

But I believe in learning on the job, so figuring things out sort of comes as part of the deal. This time, my challenge lies around figuring out how frontend handlers work in Spire CMS, where code lives, where should I intercept and tweak. Read below for the full story on how I went about this learning.

https://blogs.perficient.com/2025/03/10/optimizely-b2b-commerce-and-spire-cms-figuring-out-handlers/

Hoping to share more such learning as I gain them. :)

Decoding DI in Optimizely CMS 12

2024-01-23T21:31:43.0000000Z

DI or Dependency Injection is a complex topic, not just in Optimizely CMS, but in general in .net core implementations. Some aspects we get, like the different ways dependencies can be injected and which is better over others, while some leave us scratching our heads. Often times we end up doing a lot of troubleshooting, digging into internal code and finding the right alternatives to DI, to get things to work.

The biggest blocker here is understanding the order in which steps get executed, modules get initialized and services get registered. Once this is clear, we know where to add our custom code and avoid any surprise runtime errors around missing service registrations. One such error led me to this discovery so sharing my findings and learnings.

Read the complete post here for details.

Custom form element with dependencies

2024-01-17T18:26:42.0000000Z

Episerver Forms are cool as is. They provide solid ground to build basic forms out of the box. But often times, we have custom needs that require us to customize or add to the out of the box functionality.

In my case, I needed a custom form element that can support some unique requirements and at the same time I needed this to support the built in dependency logic.

For those of you unfamiliar with the forms dependency logic, see the Optimizely document here.

Read the complete blog here for all the fun details on how this was achieved with minor code tweaks.

Special symbols in TinyMCE

2024-01-10T23:27:54.0000000Z

TinyMCE has evolved over the years, allowing more and more flexibility with the features it offers and capabilities it allows to customize. And this is pretty handy as every client has their unique needs and requirements for what they want their Rich Text Editors to do.

My use case - pretty straightforward - among the many customizations already on, we needed to accommodate very special symbols in the RTE. Now I'm not the first person to present this need ofcourse, which is why TinyMCE already had a plugin called Charmap that contains a whole ensemble of special symbols to use from. And talk about flexibility, it also gives you, the developer, the capability to customize this plugin and add more symbols to it, in case yours are not in the preset list.

And, what do you know.. not all of mine made the preset list cut, ofcourse! :)

So, I added them in there. Read the complete post here to find out exactly how! There are some good to know details in there for sure.

Optimizely CMS 12 Upgrade takeaways

2023-08-01T20:01:40.0000000Z

I've now gone through multiple CMS 12 upgrade projects. Each project had its own unique customizations and hence its own unique set of challenges when upgrading. I learnt something new, overcame a new hurdle, found/solved a new problem with every project. Some took quite a bit of time and synergy with Opti community, some back and forth on Opti support tickets, and solutions from other MVPs. So I thought it would be nice to put them all together in one place, for others on their upgrade journey, looking for same or similar solutions.

So here goes :

This first blog post talks about things like Marketing connector and Visitor group related issues.

This second one talks about small nitty gritty, more generic things, but if you don't know about them, they can end up giving you massive headaches.

Hope you find this one stop post helpful!

I am looking forward to hear other's upgrade stories and challenges faced/resolved, so please do share in comments if you encountered something unique.

Icon Library in Optimizely CMS

2023-05-15T21:20:56.0000000Z

Icons are graphical representations of different elements on a website. They make the webpages visually appealing and like any other image, have a stronger connection and retention to the end user’s memory than plain text. When used in moderation and the right way, they can be self-explanatory and reduce the need for text content in a lot of use cases.

Icon Library is basically a curated list/dictionary of icons that ties an icon to a meaningful name. This library can then be used to pick icons for the different elements of the website. A good use case would be websites that use icons heavily and need to give CMS Editors control to pick icons with content within CMS, in a way that's well in line with the site's theme and design as well as maintains consistency in terms of meaning and usage. It also allows to have dedicated user roles that control the creation and modification of the actual Icon Library, so they can ensure the icons added are per design and theme and that other user roles can't mess the list up. And by providing a select list of the icon library on content types, instead of a ContentReference property where any media can be added, it can be ensured that no icons outside of this curated list are added to content.

Please see my detailed post here on how to setup the Icon Library and then use it in CMS.

Bitbucket CI/CD pipelines for Optimizely CMS 12

2023-05-05T20:10:20.0000000Z

Recently, we had a client with code repository hosted on Bitbucket and they showed interest in setting up CI/CD pipelines for automating Optimizely CMS deployments from within Bitbucket. When I started researching, I found several blog posts and documentation around building Azure Devops pipelines for Optimizely CMS deployments. But none that would guide us through building Optimizely CI/CD pipelines in Bitbucket. So after spending quite some time understanding Bitbucket pipeline basics, a lot of trial and error and help from other fellow colleagues, I was able to setup a Bitbucket CI/CD build pipeline for my project.

This exercise was quite the learning as it wasn't just Bitbucket pipeline specific. I learnt Bash and Powershell scripting. I learnt how Azure Devops and Bitbucket pipelines are so drastically and syntactically different from each other.

I also learnt that this effort needed sharing, because this topic is relevant and very much in need of more readily available, one stop shop content. Hopefully, after this, others on the same path won't have to spend as much time figuring smaller pieces and syntax for Bitbucket pipelines like I did.

Please follow along to the detailed blog here, providing step by step breakdown of the Bitbucket pipeline code.

I will look forward to feedback and recommendation from others here, to make this better.

Optimizely CMS 12 – Unique upgrade challenges

2023-02-17T20:56:45.0000000Z

By now, a lot of us have already participated in one or more CMS 12 upgrade projects. The others are still evaluating whether they should do it now or wait some more. Regardless of when you do it, there will definitely be some unique upgrade challenges you will come across, as I and many others […]

Optimizely CMS – the importance of GUIDs and Assembly Names

2022-08-16T16:34:16.0000000Z

In Optimizely CMS world, we see GUIDs everywhere. They are the unique identifiers for content types and more. As part of developing with Optimizely CMS, developers are advised to always specify GUIDs in there Content Type declarations. If one isn’t specified, the DB assigns one dynamically when saving the Content type. A big reason for […]

Optimizely CMS 12 – Dependency Injection(DI) – StructureMap vs ASP.Net Core

2022-06-30T19:43:59.0000000Z

If you are upgrading to Optimizely CMS 12, one of the breaking changes to consider is the change to the Dependency Injection(DI) framework. Earlier versions of Optimizely CMS had their own DI hosting framework that supported other concrete DI implementations, like StructureMap. With CMS 12 and ASP.Net Core, DI framework is built into the system. […]

Optimizely Page Publish Options – Do’s and Dont’s

2022-05-13T13:58:55.0000000Z

Page Publish is the most basic feature of a CMS. This is what makes our content visible to the world. Episerver CMS (now known as Optimizely Content Cloud) too has the feature and some more flexibility built around it to aid our content authors. There’s the usual page publish, where you hit a button and […]

Optimizely Search : How to search for all expired assets

2022-05-03T14:41:05.0000000Z

First of all, I want to mention that EPiServer Find (now known as Optimizely Search and Navigation) is a great tool to search for content on an Optimizely site, whether its CMS or Commerce. It comes with a range of options to customize and with filtering and boosting ability to get the best results. Often […]

Kathryn Bogen Recognized on 2022 CRN Women of the Channel List

2012-05-19T18:06:00.0000000Z

CRN’s annual Women of the Channel program honors some of the most influential women leaders within the channel. We’re proud to have five Perficient colleagues recognized in the 2022 CRN Women of the Channel list, and we’re highlighting their individual accomplishments in a special blog series. We previously celebrated Liza Sisler, Liz Stuart, and Lynn […]