Blogs

Integrating a Third-Party DAM into Optimizely CMS 12: A Case Study

Tue, 07 Jul 2026 00:00:00 GMT

There is no handbook for wiring an external DAM into Optimizely CMS 12. This case study walks through the research, dead ends, and breakthroughs — decompiling the CMP package, extending ContentReferenceEditor, proxy content items, and a custom Assets pane tab — using Wedia as the concrete example.

Ringing a Physical Sales Bell from Optimizely Commerce

Mon, 06 Jul 2026 21:03:58 GMT

This one started as a weekend project that got a little out of hand.

I built an “On Air” sign for my office — one of those LED signs streamers use — that turns itself on whenever I’m in a Teams call or a Zoom meeting, so my family knows not to walk in. It’s driven by a cheap TP-Link Kasa smart plug and a bit of PowerShell that watches for a call and flips the plug. Nothing fancy. But once you can turn a plug on and off from code, your brain starts looking for other things that should turn it on. And if you spend your days in Optimizely Commerce like we do, the answer shows up pretty fast: every time an order is placed, ring a bell.

Old shops had a bell on the door. Trading floors had an actual bell. There’s something motivating about a real, physical signal when money comes in — the whole team hears it. Modern commerce replaced that with a toast notification nobody looks at. So let’s put the bell back, using nothing but an order event and fifteen dollars of hardware.

Note: everything below is a standalone sample. It depends only on public Optimizely and Microsoft NuGet packages — nothing from our codebase — so you can drop the files straight into your own Commerce solution. I built, compiled, and ran it against EPiServer.Commerce.Core 14.45. The same order-event API carries forward to Commerce 15, so it should work there unchanged, but I've only tested on 14. — IOrderEvents.SavedOrder and OrderEventArgs.OrderGroup (an IPurchaseOrder) are the same on both.

Overview

There are three moving parts:

Talk to the plug from C#.
A “sales bell” that blinks the plug — on a background worker, so it never touches checkout.
An order-event listener that rings the bell when an order is placed.

A quick word on part 1, because it’s the part that surprised me. These plugs used to speak a trivial local protocol over TCP, but newer firmware locked that down, and the usual libraries couldn’t authenticate against my account at all — the handshake just kept failing. The Kasa phone app works fine, though, because it goes through TP-Link’s cloud (wap.tplinkcloud.com). So that’s what we do too: log in, find the device by its alias, and relay the old set_relay_state command through the cloud’s passthrough method. The tradeoff is it needs internet and adds a second or two of latency — which is exactly why the bell runs in the background and never in the request.

Implementation

Talking to the plug

The plug client is a straight C# port of the PowerShell from the original project. It logs in once, caches the token and the device’s server URL, and re-logs in if a call fails. The one non-obvious bit: TP-Link wants the actual device command as a JSON string nested inside the request.

public async Task SetAsync(bool on, CancellationToken ct = default)
{
    if (!_opts.Enabled) return;

    // TP-Link expects the legacy device command as a JSON *string* inside requestData.
    var command = $"{{\"system\":{{\"set_relay_state\":{{\"state\":{(on ? 1 : 0)}}}}}}}";

    for (var attempt = 1; attempt <= 2; attempt++)
    {
        try
        {
            if (_token is null) await ConnectAsync(ct);

            var body = new
            {
                method = "passthrough",
                @params = new { deviceId = _deviceId, requestData = command }
            };

            var result = await PostAsync($"{_appServerUrl}?token={_token}", body, ct);
            if (result.GetProperty("error_code").GetInt32() != 0)
                throw new InvalidOperationException($"cloud error: {result.GetRawText()}");

            return;
        }
        catch (Exception ex)
        {
            _log.LogWarning(ex, "Kasa cloud attempt {Attempt} failed", attempt);
            _token = null; // force a fresh login next time
        }
    }

    _log.LogError("Kasa plug state not updated after retry");
}

ConnectAsync does the login and getDeviceList calls and stashes the deviceId and appServerUrl. It’s in the full sample; nothing exciting.

Heads-up if you drop this into an existing Commerce solution: many Optimizely sites transitively reference System.Net.Http.Formatting (via Microsoft.AspNet.WebApi.Client), which ships its own PostAsJsonAsync extension. When it’s in scope, the bare _http.PostAsJsonAsync(url, body, ct) becomes ambiguous and won’t compile. Fully-qualify the BCL one:

using var response = await System.Net.Http.Json.HttpClientJsonExtensions
    .PostAsJsonAsync(_http, url, body, ct);

A clean standalone project won’t hit this — it only bites when the WebApi.Client extension is also referenced.

Keeping it off the checkout path

Two rules for anything you bolt onto checkout: it can’t slow the order down, and it definitely can’t fail the order. A dead smart plug should never throw an exception up into SaveAsPurchaseOrder.

So the bell is completely decoupled. Ringing it just drops a token into a bounded channel — a fire-and-forget, non-blocking write — and a background service does the slow part (turn on, wait, turn off) somewhere else entirely.

public sealed class SalesBell : ISalesBell
{
    private readonly ChannelWriter<byte> _writer;
    public SalesBell(Channel<byte> channel) => _writer = channel.Writer;

    // Non-blocking, never throws. If the queue is full, we just drop the ring.
    public void Ring() => _writer.TryWrite(0);
}

public sealed class SalesBellWorker : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await foreach (var _ in _reader.ReadAllAsync(stoppingToken))
        {
            try
            {
                using var scope = _scopes.CreateScope();
                var plug = scope.ServiceProvider.GetRequiredService<IKasaPlug>();

                await plug.SetAsync(true, stoppingToken);
                await Task.Delay(TimeSpan.FromSeconds(3), stoppingToken);
                await plug.SetAsync(false, stoppingToken);
            }
            catch (Exception ex) { _log.LogWarning(ex, "Sales bell blink failed"); }
        }
    }
}

Because the channel is bounded and set to drop when full, a Black-Friday rush can’t queue up 4,000 blinks and fall an hour behind — the light just flickers and drops the overflow. Good enough for a novelty light.

Listening for orders

Optimizely’s order pipeline exposes IOrderEvents (in EPiServer.Commerce.Order). You resolve it from DI and subscribe to SavedOrder. Easy.

Gotcha: SavedOrder fires on every save of any order group. That includes carts, and it fires again every time an existing order’s status changes later. So we guard twice — only ring for an actual purchase order, and only the first time we’ve seen that order.

private void OnSavedOrder(object? sender, OrderEventArgs e)
{
    // Carts are order groups too — only ring for a completed purchase order.
    if (e.OrderGroup is not IPurchaseOrder po) return;

    // SavedOrder fires on every later save; only ring on first sight.
    var id = po.OrderLink.OrderGroupId;
    if (Seen.TryGetValue(id, out _)) return;
    Seen.Set(id, true, TimeSpan.FromHours(1));

    _log.LogInformation("Order {OrderNumber} placed — ringing the sales bell", po.OrderNumber);
    _bell.Ring();
}

Wiring it up

An IConfigurableModule registers everything and subscribes the listener once the site is up. The ModuleDependency on Commerce’s initialization module guarantees IOrderEvents is available by the time we ask for it.

[InitializableModule]
[ModuleDependency(typeof(EPiServer.Commerce.Initialization.InitializationModule))]
public sealed class SalesBellModule : IConfigurableModule
{
    public void ConfigureContainer(ServiceConfigurationContext context)
    {
        var services = context.Services;

        services.AddOptions<KasaOptions>()
                .Configure<IConfiguration>((o, cfg) => cfg.GetSection("SalesBell").Bind(o));

        services.AddHttpClient<IKasaPlug, KasaCloudPlug>();

        services.AddSingleton(_ => Channel.CreateBounded<byte>(
            new BoundedChannelOptions(100) { FullMode = BoundedChannelFullMode.DropWrite }));

        services.AddSingleton<ISalesBell, SalesBell>();
        services.AddHostedService<SalesBellWorker>();
        services.AddSingleton<SalesBellOrderListener>();
    }

    public void Initialize(InitializationEngine context)
        => context.Locate.Advanced.GetInstance<SalesBellOrderListener>().Subscribe();

    public void Uninitialize(InitializationEngine context)
        => context.Locate.Advanced.GetInstance<SalesBellOrderListener>().Unsubscribe();
}

One easy-to-miss detail: only ConfigureContainer gets an IServiceCollection. Initialize and Uninitialize receive an InitializationEngine, which has no .Services property — you resolve through context.Locate.Advanced.GetInstance<T>() instead.

Config lives in a SalesBell section — but put the password in Key Vault or DXP configuration, not appsettings.json in source control:

{
  "SalesBell": {
    "Username": "you@example.com",
    "Password": "keep-me-in-key-vault",
    "DeviceAlias": "On Air Lamp",
    "Enabled": true
  }
}

That "Enabled": false is worth setting in your Integration and Preproduction environments — otherwise a QA test order or a load test will strobe a light in a dark office at 2 a.m. Ask me how I know.

A few things to watch

A couple of honest caveats, because this is a novelty bolted onto a real checkout:

It’s an unofficial API. wap.tplinkcloud.com is reverse-engineered — the same path the Kasa app uses, but TP-Link could change it. Treat the bell as best-effort; the code already swallows every failure.
The success check is shallow — on purpose. SetAsync inspects error_code on the outer cloud envelope, which only tells you TP-Link accepted and relayed your passthrough request. The device’s own response is nested as a JSON string inside result.responseData, and we don’t crack it open — so “success” means the cloud took the command, not the relay physically flipped. Fine for a novelty bell; don’t reuse this client where you need to confirm device state.
You probably run more than one node. On DXP each instance gets the SavedOrder event, so each will try to ring. Either accept the extra cloud calls (harmless), gate ringing to one designated node, or move the bell behind a single small service. Your mileage may vary depending on your topology.
Throttle the strobe. The bounded channel keeps things from backing up, but during a real rush you may want one blink per N orders instead of one per order. Nobody needs a strobe light.
The de-dupe is per-instance. The in-memory cache is fine for a light. If you need it exact across a farm, back it with distributed cache or key off the order’s status transition.

Conclusion

The fun part is that once _bell.Ring() is a single line, the plug stops caring why it fired. Swap the bell for a color-changing bulb (green for a sale, red for a failed payment), point it at a different event — a first sale of the day, an order over some threshold, a low-stock SKU — and you’ve given your Optimizely site a little presence in the physical world.

The code above is the sample — it compiles and runs clean against Commerce 14 with nothing from any particular site, so you can drop the files straight in (the order-event API is unchanged in 15, though I’ve only run it on 14). The original Teams/Zoom “On Air” sign it grew out of — the PowerShell watcher and smart-plug script — is on GitHub: github.com/kennygutierrez/on-air-sign.

Thoughts, comments, concerns? Let me know below.

Exploring Asset Lifecycle Management Approaches for Bynder and Optimizely SaaS CMS

Sun, 05 Jul 2026 07:44:36 GMT

Note: This is Part 3 of our Bynder integration series. For setup and filtering prerequisites, see Part 1 and Part 2.

Introduction

In my previous article, I explored approaches for controlling asset ingestion from Bynder into Optimizely SaaS CMS through metadata-based filtering.

Filtering assets before they enter the platform is an important first step, but in many enterprise DAM integrations, it only addresses part of the lifecycle.

Once assets have been synchronized, a different set of challenges begins to emerge:

What happens when an asset's metadata changes after synchronization?
How should previously synchronized assets be handled when they no longer meet business rules?
How can organizations govern assets across Development, Staging, and Production environments?
How can teams safely determine whether an asset is still being used before removing it?
When does it make sense to extend an existing integration versus building a completely custom connector?

These questions gradually shift the conversation from asset synchronization to asset lifecycle management.

This article explores some architectural considerations and potential approaches that may help address those challenges.

The Asset Lifecycle Challenge

Synchronization is rarely a one-time event. Assets constantly evolve throughout their lifetime.
A typical lifecycle might look something like this:

Asset Created  >  Asset Synchronized  >  Asset Referenced by Content  >  Asset Metadata Updated  >  Visibility Rules Changed  >  Environment Assignment Changed  >  Asset No Longer Valid
 
Most DAM integrations handle the first half of this journey very well.
The second half is often where complexity starts to appear.

For example:

An image may no longer belong to a target environment.
An image may become hidden through metadata changes.
An image may remain inside Optimizely despite no longer being available within Bynder.
An image may still be actively referenced by content authors even though business rules indicate it should be removed.

These scenarios introduce governance challenges that extend well beyond initial synchronization.

Orphaned Assets

One scenario that stood out during evaluation was the possibility of orphaned assets.

Consider the following sequence:

Asset synchronized  >  Metadata changes  >  Asset moves out of scope  >  Synchronization account can no longer access asset  >  Asset remains in Optimizely

From the perspective of the synchronization process, the asset has effectively disappeared.

The integration can no longer retrieve information about the asset.

However, the existing record may continue to exist inside Optimizely.

Over time, these records could accumulate, creating a divergence between the source DAM and the target CMS repository.

While this may not create an immediate problem, organizations with large asset libraries may eventually start asking:

Which assets are still valid?
Which assets should still exist?
Which assets are no longer governed by the current synchronization rules?

These questions become increasingly important as repositories grow.

Environment Governance

Another consideration involves environment ownership.

Most enterprise implementations maintain separate environments:

Development
Staging
Production

However, DAM platforms are often centrally managed.

A common scenario looks something like this:

Without additional controls, all environments may receive identical assets.

This can introduce several concerns:

Increased storage consumption
Cluttered non-production environments
Difficult testing scenarios
Confusion around environment-specific assets

Suggested Environment Metadata Approach

One possible approach is introducing an additional metadata property or use tags inside Bynder.

Example:

"website-environment" metadata property with possible values:

Development
Staging
Production

This metadata could travel alongside normal asset synchronization and provide additional governance information to downstream systems.

Suggested Visibility Configuration

Unlike visibility-based filtering rules, this property/tags does not need to setup separate profiles/users and any explicit filtering rules.

The goal is not to hide assets. The goal is to communicate intent.

For example: If an asset that is tagged for development environment received in production environement then that asset should be treated as out of scope and vice versa for other environments.
 
Asset target Environment: Development
Asset Synced in: Production
Result: Potentially Out of Scope
 
With this approach, a centralized DAM repository can continue serving multiple environments while still supporting environment-specific governance decisions.

Why Environment Metadata May Be Valuable

Without environment metadata, every environment receives same assets.

With environment metadata, environment validation processes can be setup to stop storing assets those are not required in the environment.

This approach may provide a lightweight governance layer without introducing separate DAM repositories, separate taxonomies, or separate synchronization configurations.

Architectural Note

The workflow described in the following sections represents an architectural approach that emerged during the evaluation of lifecycle management challenges associated with large-scale DAM integrations.

While the individual platform capabilities required for this model—including Bynder webhooks, permanent access tokens, Optimizely Graph/Content Management APIs, and Optimizely Graph reference queries— are available today, the complete end-to-end workflow has not yet been fully validated in a production implementation.

The intent of this article is to explore a potential governance pattern and discuss its trade-offs rather than present a proven production architecture.

Exploring an Event-Driven Governance Model

One approach that appears interesting from an architectural perspective is introducing a webhook-driven governance workflow.

For simplicity, this article assumes the webhook endpoint is deployed inside the frontend nextjs application.

In practice, the webhook could be hosted anywhere:

Next.js API Route
Azure Function
AWS Lambda
Google Cloud Function
Dedicated Middleware Service
Integration Platform

The location itself is less important than the validation process being executed.

At a high level:

Bynder Calls Webhook  >  Webhook Receives event  >  Validation Logic  >  Asset remains or Deleted
 

Three Gates

Gate 1: Visibility Validation

The first validation stage could determine whether the asset remains visible to the synchronization account.
Note: Use permanent token assigned for the synchronization account.

Conceptually:

Asset Updated > Retrieve Asset > Accessible > Decision

          Decision  >  YES  >  Continue
          Decision  >  NO  >  Potential Cleanup Candidate

The objective is not necessarily to delete the asset immediately. Instead, the objective is to determine whether the asset still falls within the intended synchronization scope. If visibility has changed, additional evaluation may be required.

Gate 2: Environment Validation

The second validation stage could evaluate environmental ownership.

Example workflow:

Asset Updated  > Read website-environment  >  Compare Against Current Environment  > Decision:

          Decision  >  Match  >  Continue
          Decision  >  No Match  >  Potential Cleanup Candidate

This allows governance decisions to be made without requiring separate DAM repositories.

An asset intended exclusively for Production could potentially be excluded from lower environments while remaining available in Production.

Gate 3: Reference Validation

Before any removal occurs, a critical question must be answered: Is the asset still being used?

Optimizely Graph does not currently expose a built-in reverse-reference lookup operator. This means there is no single, generic query to answer "which content items reference this asset?" without knowledge of the content model.

Possible implementation approaches include:

Full-text search — Query Content using _fulltext: { match: "asset-id" } to search across all indexed content. Quick but imprecise — depends on how asset IDs are indexed.
Schema introspection + targeted queries — Use GraphQL introspection to discover all content types with reference-type fields, then query each one. More thorough but requires automation to be practical.
Content Management API enumeration — Use the CMS REST API to walk content and check references programmatically.

The right approach depends on your content model complexity, performance requirements, and how frequently this validation runs. This gate will likely require a custom implementation tailored to your environment.

Deleting Assets from Optimizely

Once an asset has been evaluated, a governance process may decide that removal should occur.

Important questions include:

Is the asset still visible?
Is the asset assigned to the current environment?
Is the asset actively referenced?
Should the asset remain synchronized?

If all validation checks indicate removal is appropriate, a deletion request could be submitted through the Content Management API.

An important distinction exists between: Soft Delete vs Hard Delete

For lifecycle-management scenarios, hard deletion may be more relevant because the objective is often to reduce repository footprint rather than move content into a recycle state.

Url & Headers
 

POST /api/content/v2/data?id=bynd HTTP/1.1
Host: cg.optimizely.com
Content-Type: application/x-ndjson
Authorization: Basic V25KQmNtUlpSNTFYaDJuSmE1UWV5eEkwWW...[Your_Base64_Encoded_Credentials]
 


Body
{"delete":{"_id":"bynder-asset-guid-12345","language_routing":"en"}}
{}

Response
{
  "status": "success",
  "total_records_processed": 1,
  "deleted": 1,
  "errors": [],
  "took": 42
}


 
 

This would permanently remove the asset rather than transferring it into a recycle bin.

Monitoring and Troubleshooting

Whenever automated deletion is introduced, observability becomes extremely important.

Questions that operations teams will eventually ask include:

Was a delete triggered?
Which rule triggered it?
Which asset was deleted?
When did it occur?
What response was returned?
 
A potential audit trail might capture:

Asset identifier
Event timestamp
Validation results
Environment
API response
Deletion outcome

Monitoring Deletion Activity

One area that would require validation during implementation is how deletion activity can be monitored within the platform.

A potential starting point would be reviewing:

Search & Navigation portal logs
Graph activity logs
API diagnostics
Application telemetry
Hosting platform logs

This would help determine whether delete operations are executing successfully and provide additional visibility during troubleshooting.

Extending the Existing Integration vs Building a Custom Connector

A natural question that often emerges is:

If lifecycle governance is required, should we simply build a custom connector?

The answer depends on organizational priorities.

Option 1: Extend the Existing Integration

Option 2: Build a Fully Custom Connector

Bynder > OOTB Connector > Optimizely + Governance Layer

Advantages:

Faster implementation
Lower maintenance overhead
Vendor-supported synchronization
Smaller operational footprint

Potential limitations:

Less control over synchronization internals
Dependency on platform capabilities

Bynder  >  Custom Connector  >  Optimizely
 
Advantages:

Complete control
Custom business logic
Full synchronization ownership

Potential considerations:

Authentication management
Delta synchronization
Retry handling
Error recovery
Schema evolution
Long-term maintenance costs

For many organizations, extending an existing integration with additional governance capabilities may represent a more balanced approach than replacing the synchronization engine altogether.

Assumptions and Validation Status

The approaches discussed throughout this article are based on architectural evaluation and platform capability analysis rather than a fully validated production implementation.

At the time of writing, the proposed event-driven webhook model remains an architectural concept that appears technically achievable based on the currently available capabilities of:

Bynder webhooks
Bynder permanent tokens
Optimizely Content Management /Graph APIs
Optimizely Graph reference lookups
Standard event-driven integration patterns

However, several areas would benefit from additional validation before adoption within a production environment:

Large-scale webhook processing behavior
API rate limiting and throttling characteristics
Long-running operational reliability
Deletion timing and synchronization race conditions
Monitoring and alerting strategies
Reconciliation requirements for lost events
Long-term maintenance implications

As with any architectural pattern, organizations should conduct their own validation, performance testing, and operational reviews before implementing the approach within production workloads.

Conclusion

Asset synchronization is only one stage in the lifecycle of an enterprise DAM integration.

As asset repositories grow, organizations may also need to consider how visibility changes, environment allocation, content relationships, and cleanup processes should be handled over time.

The approaches discussed in this article should be viewed as architectural considerations rather than implementation recommendations. While the proposed event-driven governance model appears technically feasible based on the capabilities provided by Bynder, Optimizely SaaS CMS, and Optimizely Graph, additional validation and testing would be required before considering it for production adoption.

Ultimately, long-term success is unlikely to depend solely on controlling what enters the system. It may also require thoughtful approaches to governing assets throughout their lifecycle—from synchronization and distribution through validation, retention, and eventual removal.

📚 Bynder + Optimizely SaaS CMS Integration Series

This article is the final installment of a 3-part comprehensive architecture guide:

✅ Part 1: Implementing the Connector — Lessons Learned
What metadata syncs, how URLs behave, and how to query/render assets in a Next.js frontend.
✅ Part 2: Planning & Filtering — Avoiding Asset Sprawl and Unnecessary Sync
How we achieved metadata-based sync filtering with zero custom code.
👉 Part 3: Exploring Asset Lifecycle Management & Three-Gate Governance (You are here)
A webhook-driven, three-gate model to handle asset updates, environments, and usage verification.

Unlock AI-Ready Experiences with Optimizely

Sun, 05 Jul 2026 05:40:14 GMT

Over the past few months, almost every customer conversation has shifted from SEO to AI readiness. The questions are no longer just: “How do we...

The post Unlock AI-Ready Experiences with Optimizely appeared first on Madhu Anbalagan's Blog.

Planning Your Bynder DAM and Optimizely SaaS CMS Integration the Right Way: Avoiding Asset Sprawl and Unnecessary Synchronization

Sat, 04 Jul 2026 18:28:12 GMT

Note: This is Part 2 of our Bynder integration series. If you missed the Part 1, check out "Implementing the Bynder DAM Connector with Optimizely SaaS CMS: Lessons Learned".

In my previous article, I explored how the Bynder DAM Connector integrates with Optimizely SaaS CMS and how synchronized assets become available through Optimizely Graph and the CMS authoring experience.

This article focuses specifically on the Out-of-the-Box (OOTB) Bynder Connector available through Optimizely Connect Platform (OCP). The goal is to understand how much control can be achieved using standard Optimizely and Bynder capabilities before introducing custom integrations, middleware, or synchronization processes.

While the technical setup of the OOTB connector is relatively straightforward, I discovered that the most important decisions actually happen before the first synchronization is ever executed.

Many implementation teams focus on establishing the connection between Bynder and Optimizely. However, a more important architectural question is:

What assets should Optimizely be allowed to see in the first place?

For organizations that use Bynder as a centralized Digital Asset Management platform, the answer has significant implications for governance, editor experience, operational overhead, and long-term scalability.

This article focuses on the planning and governance considerations that should be addressed before enabling the Bynder connector.

Understanding the Default Connector Behavior

The Out-of-the-Box (OOTB) Bynder connector synchronizes assets that are visible to the authenticated Bynder account.

In simple terms, the connector does not determine which assets should be synchronized. Bynder determines that by evaluating the permissions of the account used during the authorization process.

As a result, the overall scope of synchronization is directly influenced by:

The permission profile assigned to the integration account
Asset visibility settings within Bynder
Metadata visibility rules
The account used during connector authorization

The connector can only synchronize assets that the authenticated account can access.

This seemingly simple behavior becomes extremely important when working with large DAM implementations.

Why Asset Scope Matters

In many organizations, Bynder contains assets for multiple business functions and audiences.

Examples include:

Website assets
Campaign assets
Product photography
Internal communications
Regional marketing materials
Archived content
Partner-specific assets
Brand assets

Not all of these assets are intended for websites powered by Optimizely.

Without careful planning, the connector can synchronize substantially more assets than editors actually need.

At first glance this may not appear to be a major concern. However, every synchronized asset becomes another content item managed by the Optimizely ecosystem.

As synchronization volume grows:

More items are stored in Optimizely Graph
More content records are created
More synchronization events are processed
Asset selection becomes harder for editors
Governance becomes increasingly complex

Most importantly, organizations should understand how content volume contributes to overall platform usage and operational overhead.

For this reason, a successful DAM strategy is not about synchronizing everything that exists inside Bynder.

It is about synchronizing only what is required.

Start With Governance, Not Technology

One of the biggest lessons learned during implementation was that DAM integrations are primarily a governance challenge rather than a technical challenge.

The connector itself can be configured very quickly.

Determining which assets should be synchronized requires considerably more thought.

Before connecting Bynder to Optimizely, I recommend answering questions such as:

Which assets are intended for public websites?
Which business teams own those assets?
Which environments require those assets?
Who approves synchronization scope changes?
How will future asset growth be managed?

Answering these questions early can prevent a significant amount of cleanup work later.

The Common Mistake: Connecting With an Administrator Account

The easiest way to enable the connector is often to authenticate using an administrator account.

The workflow usually looks something like this:

Open the Bynder connector.
Click Connect.
Log in using administrative credentials.
Approve access.
Start synchronizing.

The problem is that administrator accounts often see virtually everything.

That means the connector can potentially see:

Website assets
Internal assets
Historical assets
Regional assets
Unused assets
Archived assets

In other words, the connector effectively inherits access to the entire DAM repository.

This removes any meaningful synchronization boundaries.

Why Creating a New User Is Not Enough

A common assumption is:

"I'll simply create a new user for Optimizely and restrict its permissions."

Unfortunately, this is where many implementations run into trouble.

Bynder permissions are primarily controlled through Permission Profiles.

The effective model looks like this:

Permission Profile → User → Asset Visibility

This means that simply creating a new user does not automatically reduce visibility.

If the new integration user remains associated with a highly privileged profile, that user may still inherit broad access to assets.

In practice, creating a new user and placing it within an administrator-level permission profile often results in another highly privileged user.

The desired filtering behavior never materializes.

This is why a dedicated Permission Profile becomes essential.

The Recommended Approach

Instead of creating a user within an existing administrative profile, create:

A dedicated synchronization user
A dedicated synchronization permission profile
Dedicated metadata visibility rules

Together, these become the foundation of your synchronization strategy.

The goal is to create an account that acts as a read-only integration consumer and nothing more.

1. Creating a Dedicated Synchronization Profile

The dedicated synchronization profile should be configured with only the permissions required for integration purposes.

Recommended permissions include:

Asset Bank

View assets
Search assets
View asset details
View metaproperties

General / Integration

API Access
Manage Webhooks

Permissions that generally do not need to be enabled include:

Upload assets
Edit assets
Delete assets
Manage taxonomy
Administrative functions

2. Create a Dedicated Synchronization Account

Once the synchronization profile has been configured, create a dedicated service account and assign it exclusively to that profile.

This account will be used during the Bynder authorization process and will ultimately determine which assets the Optimizely connector can access.

Avoid assigning the account to an existing administrative profile or a profile used by content creators. The goal is to create a narrowly scoped integration account whose sole responsibility is synchronizing approved assets into Optimizely.

By separating the integration account from day-to-day user accounts, you gain:

Predictable synchronization behavior
Easier troubleshooting
Clear ownership of integration permissions
Reduced risk of unintentionally exposing additional assets to Optimizely

3. Using Metadata as a Synchronization Boundary

Many teams think about metadata exclusively in terms of search and categorization.

During this implementation, I found it equally useful to think of metadata as a governance mechanism.

Metadata can help answer questions such as:

Should this asset be visible to websites?
Which business unit owns this asset?
Which region can use this asset?
Which environments should receive this asset?

By implementing metadata-driven visibility, organizations can define synchronization boundaries before assets enter Optimizely.

This keeps governance as close as possible to the source system.

4. Configuring Metadata Visibility

One effective approach is to use a required metadata property that identifies whether an asset is intended for website consumption.

For example: VisibleTo

To configure this:

Navigate to Settings → Taxonomy → Metaproperties Management
Select the metadata property
Open the Visibility configuration
Select the synchronization profile
Grant/deny visibility only to approved metadata values.

When configured correctly, the synchronization account becomes effectively blind to assets outside the approved scope.

5. Validate Before Connecting

One of the most valuable steps in the entire process happens before Optimizely is connected.

After creating the synchronization account and permission profile:

Open an Incognito or InPrivate browser session.
Login using the synchronization account.
Search for assets.
Browse collections.
Verify metadata visibility.
Validate that only the intended assets are available.

Ask yourself:

If I connect Optimizely using this account right now, am I comfortable synchronizing every asset visible on this screen?

If the answer is no, continue refining the profile before proceeding.

This simple validation step can save considerable troubleshooting effort later.

The Authorization Flow Trap

Another lesson learned during implementation is that the authorization process deserves more attention than most teams initially give it.

The connector authorization flow uses the account that participates in the OAuth approval process.

If an existing browser session already contains administrative Bynder credentials, those credentials may inadvertently be used during authorization.

To avoid this:

Open a fresh InPrivate or Incognito browser window.
Login to Optimizely SaaS CMS.
Start the Bynder App installation and connection process.
Most Important:
1. Installation process must open the Bynder login page.
2. Login using the dedicated synchronization account.
Complete the authorization flow.

Using a clean browser session helps ensure the connector is authorized with the intended account rather than accidentally inheriting access from an existing administrative session.

Understanding the Synchronization Flow

Scenario A : Asset is visible to the synchronization account

Asset uploaded/updated into Bynder.
Bynder triggers the OCP connector webhook.
Bynder receives a request from the connector.
The synchronization account is authorized to view the asset.
Bynder returns the asset payload.
OCP processes the response.
The asset is synchronized into Optimizely Graph.
The asset may become available within CMS depending on configuration.

Scenario B : Asset is not visible to the synchronization account

Asset uploaded/updated into Bynder.
Bynder triggers the OCP connector webhook.
Bynder receives a request from the connector.
Bynder evaluates permissions.
Access is denied because the synchronization account cannot see the asset.
No asset payload is returned.
OCP connector skips synchronization.

This means filtering occurs naturally through the permission model rather than through custom synchronization logic.

Key Lessons Learned

One of the biggest realizations are that successful DAM integrations are defined long before the first asset is synchronized.

A few recommendations I would strongly encourage:

Define synchronization boundaries before configuring the connector.
Create a dedicated integration profile instead of reusing administrative profiles.
Use metadata strategically rather than treating it purely as a categorization tool.
Validate permissions using a private browser session before connecting Optimizely.
Think carefully about which assets truly belong inside the website ecosystem.
Start with a smaller, controlled asset scope and expand incrementally if needed.

Most importantly:

Just because an asset exists in Bynder does not mean it needs to exist in Optimizely.

Conclusion

The Bynder connector makes it very easy to bring DAM assets into Optimizely SaaS CMS.

However, the long-term success of the integration depends less on connector configuration and more on governance decisions made beforehand.

By investing time in permission profiles, metadata design, synchronization boundaries, and dedicated integration accounts, organizations can significantly reduce operational overhead and create a much cleaner experience for both editors and developers.

In my next article, I'll take a deeper look at what happens after synchronization is established. We'll explore how asset visibility changes can create orphan records, how synchronization behavior is impacted when assets move in and out of scope, and the operational challenges that emerge in multi-environment implementations. I'll also discuss environment-specific asset governance considerations, common pitfalls organizations encounter as their DAM footprint grows, and architectural approaches for keeping Optimizely environments clean, scalable, and maintainable over time.

📚 Bynder + Optimizely SaaS CMS Integration Series

This article is the second installment of a 3-part comprehensive architecture guide:

✅ Part 1: Implementing the Connector — Lessons Learned
What metadata syncs, how URLs behave, and how to query/render assets in a Next.js frontend.
👉 Part 2: Planning & Filtering — Avoiding Asset Sprawl and Unnecessary Sync (You are here)
How we achieved metadata-based sync filtering with zero custom code.
⏭️ Part 3: Exploring Asset Lifecycle Management & Three-Gate Governance
Explore a webhook-driven, three-gate model to handle asset updates, environments, and usage verification.

Implementing the Bynder DAM Connector with Optimizely SaaS CMS: Lessons Learned

Fri, 03 Jul 2026 12:46:54 GMT

What I learned while integrating Bynder DAM with Optimizely SaaS CMS, exploring Optimizely Graph, and building a headless frontend experience.

Introduction

While working on an Optimizely SaaS CMS implementation, I spent considerable time understanding how the Bynder DAM connector works, what data gets synchronized, how assets appear in Optimizely Graph, and how frontend applications should consume those assets.

Although both Optimizely and Bynder provide documentation, I found very little content that shows the complete end-to-end picture:

What metadata gets synchronized?
How do assets appear in Optimizely CMS?
What does the data look like in Optimizely Graph?
How do developers render images, videos, and documents?
How do public and private assets behave?
What are the limitations of the connector?

This article summarizes my findings and lessons learned from exploring the integration.

What is Optimizely SaaS CMS?

Optimizely SaaS CMS is a cloud-native content management platform that enables organizations to create and manage content experiences across websites, mobile applications, portals, and other digital channels.

Key capabilities include:

Content modeling
Headless content delivery
Visual editing
Multi-site architecture
Optimizely Graph integration
API-first content management

Unlike traditional CMS platforms, content in Optimizely SaaS is managed through content types and delivered through APIs and Optimizely Graph.

What is Bynder?

Bynder is an enterprise Digital Asset Management (DAM) platform.

Organizations typically use Bynder to manage:

Images
Videos
Brand assets
Product photography
Brochures and documents
Marketing collateral
Digital media libraries

Bynder often serves as the single source of truth for digital assets while Optimizely serves as the source of truth for content.

Why Do We Need a Connector?

Without a connector, editorial teams typically follow this process:

Bynder DAM à Download Asset à Upload Asset to CMS à Use Asset on Website
OR
Bynder DAM à Copy Asset URL à Paste Asset URL to CMS à Use Asset on Website

This creates multiple problems:

Duplicate storage
Asset versioning issues
Governance challenges
Increased maintenance effort
Multiple sources of truth

The Bynder Connector changes the process significantly:

Bynder DAM à DAM Connector à Optimizely Graph & CMS à Frontend Application

Benefits include:

Single source of truth
No duplicate assets
Improved governance
Centralized asset management
Better scalability

Editors never need to download and re-upload assets.

Instead, references to Bynder assets become available directly within Optimizely CMS.

Understanding the Bynder Asset Model

One of the first things I wanted to understand was what data becomes available. A Bynder asset can be thought of as a combination of following:

Bynder Managed Fields - Maintained automatically by Bynder. These fields describe the physical asset itself.
User Managed Fields - These fields are managed by DAM users and are often used for: Search, Categorization, Filtering, Metadata enrichment.
User Managed Flags: These fields can influence asset behavior. These become particularly important when assets are exposed to public-facing websites.
URLs: Assets URLs based on asset object and various configurations and enabled features in Bynder.

Understanding the Available Asset URLs

One of the most useful discoveries was understanding which URLs are available for different asset types. Not every asset type exposes the same URLs.

Image Assets - Image assets typically provide:

Original URL

Thumbnail URL

Transform Base URL

Represents the original uploaded file.

Represents a smaller version of the image.

Instead of generating multiple physical image versions, Bynder allows images to be transformed dynamically.

Use cases:

High-resolution download,
Print-quality rendering,
Internal consumption

Use cases:

Asset pickers,
Search results,
Content listings,
Media libraries

Use cases:

Hero banners,
Product images,
Responsive image delivery,
Mobile optimization,
Social sharing images

Transform Base URL helps improve:

Performance
Page speed
Bandwidth consumption

Video Assets - Video assets typically provide:

Original URL

Thumbnail URL

Video Preview URL

The complete video asset

Poster image for the video.

Optimized preview version.

Use cases:

Full playback,
Downloads,
Media processing

Use cases:

Video cards,
Search results,
Carousel view

Use cases:

Video galleries,
Content previews,
Editorial review

Document Assets - Document assets typically provide:

Original URL

Thumbnail URL

Used for:

Document downloads,
Direct viewing,
PDF rendering

Used for:

Document previews,
Search results,
Asset browsers

Setting Up the Connector

Connector setup is relatively straightforward. Follow the documentation here:
https://support.optimizely.com/hc/en-us/articles/37465644973069-Configure-the-Bynder-app

Typical configuration requires:

Bynder Admin Access
Webhook permissions on your Bynder user profile to authorize this integration.
Bynder OAuth App, Client ID, Client Secret
OCP (Connect Platform) access in Optimizely SaaS instance.

Note that:
a) Setup separate sync for:

1. Each Bynder object i.e. image, document, video.

2. Each Optimizely environment i.e. Dev, Stage, Prod (test1, test2, Production)

3. Each Language (if applicable) otherwise use Neutral language

b) In the Destination create separate ContentType for each object i.e. Image à BynderImage, Document à BynderDocument, Video à BynderVideo

c) Ensure selection of “Make available as CMS Content” checkbox.

Once configured successfully:

Bynder Assets à DAM Connector à Optimizely Graph + CMS Content Type

Assets become available inside Optimizely Graph and CMS both without custom code.

Content Manager Experience

From an editorial perspective, this is where things become interesting.

After configuration, editors can browse DAM assets directly inside CMS.

The Content Manager navigation typically exposes a dedicated content provider area.

At this point, editors do not need to leave CMS to discover assets stored in Bynder.

They can: Search, Browse, Filter, Reference assets directly from the content authoring experience.

How Assets Appear in Optimizely Graph

Once synchronized, DAM assets become queryable through Graph.

A simplified query may look like (the exact query will depend on your field mappings)

Image

Video

Document

query {

BynderImage {

items {

name

originalUrl

thumbnailUrl

transformBaseUrl

}

query {

BynderVideo {

items {

name

originalUrl

thumbnailUrl

videoPreviewURL

}

query {

BynderDocument {

items {

name

originalUrl

thumbnailUrl

}

One of the biggest advantages is that content and media can now be retrieved through a single API layer.

Using DAM Assets in Content Types

The connector enables DAM-specific property types.

Example:

News Article Page

- Headline

- Summary

- Hero Image

Where:

Hero Image is a Bynder Image reference.

Product Page

- Title

- Product Image

- Product Video

- Product Brochure

Where:

Each asset property can reference a different Bynder asset type i.e. BynderImage, BynderVideo, and BynderDocument

Frontend Consumption

Once data is available through Graph, frontend applications can retrieve and render it.

Example:

query {

NewsArticle {

items {

headline

heroImage {

name

thumbnailUrl

originalUrl

transformBaseUrl

}

query {

Product {

items {

title

productImage {

name

thumbnailUrl

originalUrl

transformBaseUrl

}

productVideo {

name

thumbnailUrl

originalUrl

videoPreviewUrl

}

productBrochure{

name

thumbnailUrl

originalUrl

}

Asset Rendering:

Rendering Images

Rendering Videos

Rendering Documents

Basic rendering:
<img src="{thumbnailUrl}" />

Responsive Rendering:
<img
src="{transformBaseUrl}?width=200"
/>

Video example:
<video controls>
<source src="{originalUrl}" />
</video>

Video Poster:
<img src="{thumbnailUrl}" />

PDF example:
<a href="{originalUrl}">
Download PDF
</a>

Preview example:
<img src="{thumbnailUrl}" />

An ideal worflow (Bynder à Optimizely à Frontend application):

Asset will be uploaded into Bynder along with metadata.
Asset will be marked as Public in Bynder (if asset must be available using a public URL).
OCP Connector will sync the asset inforamtion into Optimizely Graph.
Authors in Optimizely SaaS CMS will be able to ses/select the asset inside the content manager/content items for referencing on relevant fields.
Content Items will be published in Optimizely SaaS CMS.
Frontend application (nextjs) will retrieve the page item content along with asset URLs using Graph query.
Appropriate URL of asset will be used to render/retrieve the asset infroamtion in the application/browser.
If frontend application needs asset information that is not synced in Optimizely but available in Bynder then frontend application will use Bynder APIs to retrieve the information.

Public vs Private Assets

One area that deserves special attention is asset visibility.

Public Assets

IsPublic = true

Typically means:

Frontend can access asset directly.
No authentication required.

Non-Public Assets

IsPublic = false

Potential implications:

Requires authentication
Requires authorization
URL will not be accessible publicly

This becomes extremely important for:

Extranets
Employee portals
Restricted content

Use Retrieve asset download location from Bynder API to get the URL to dowlaod the asset item.

Things I Learned

After exploring Bynder and the connector, several observations stood out.

Not every asset type exposes the same URLs
Images typically expose more transformation capabilities than videos or documents.

Transform Base URL is incredibly useful
The Transform Base URL alone can eliminate the need for multiple image renditions.

Public vs Private matters early
Teams should decide asset visibility strategy before building the frontend application.
Changing this later can require rework.

Things to Validate Early

Metadata Availability
- Not every Bynder field is necessarily synchronized.
- Always validate:
  - Which fields are available?
  - Which fields are searchable?
  - Which fields appear in Graph?
Filtering of Assets
- You may not need to have all assets in Optimizely. Ideally Assets used on your website or target channel must be synced but rest assets should be avoided.
  Read the article [Planning Your Bynder DAM and Optimizely SaaS CMS Integration the Right Way: Avoiding Asset Sprawl and Unnecessary Synchronization]
Private Asset Consumption
- Private assets often introduce additional frontend delivery considerations.
- Validate architecture before implementation.

Transformation Support
- Image transformations are powerful.
- Equivalent functionality may not exist for every asset type.

Connector Scope
- The connector solves many DAM scenarios, but not every possible Bynder feature, or workflow may be surfaced through the OOTB connector.
Language Translation
- Bynder does not have concept of language version of asset items hence if you need to store language specific content in your assets metadata properties then figure out where that content will be stored and how the translation workflow will be executed. One of the options to keep language specific content inside Bynder is to create language specific properties e.g. Title_en, Title_fr etc. These properties can then be read through the Retrieve specific asset endpoint.
- Also note that Bynder allows to set the language specific labels for the options inside single select and multi-select properties. But when you retrieve assets information using the API it only returns the default language labels. In case you need language specific labels in your frontend application then you need to get all metadata properties using Retrieve metaproperties API endpoint.

Frequently Asked Questions

Does the connector synchronize custom metadata fields?
All text type metadata fields in Bynder are supposed to be exposed through synchronization but actual synchronization depends on the connector configuration.
Always validate available fields before finalizing content models.
Can filtering of assets be set during sync configuration?
OOTB connector does not support filtering; it is developed to sync all assets.
The connector itself has no filtering UI, but selective synchronization can be achieved through Bynder's permission profiles and metadata visibility rules — see [Planning Your Bynder DAM and Optimizely SaaS CMS Integration the Right Way: Avoiding Asset Sprawl and Unnecessary Synchronization].
Or Using the Bynder API custom connector can be developed to support filtering and other required features based on your business needs.
Can I call Bynder APIs directly from my frontend application?
Absolutely. A common pattern is: DAM Connector + Bynder APIs.
The connector handles asset references while custom APIs handle advanced functionality.
Use Retrieve specific asset endpoint from Bynder API to retrieve metadata and URLs (including custom metadata) for a specific assets.
What if information is not synchronized?
Retrieve it directly from Bynder APIs. Examples: Workflow Status, Usage Rights, Approval State, Custom Metadata.
Can frontend applications retrieve private assets?
It depends on the DAM security model and implementation approach.
Possible solutions include: Authentication, Proxy APIs, Token-based access.

Final Thoughts

The Bynder DAM Connector provides a clean bridge between enterprise asset management and modern headless content delivery.

The most important takeaway for me was that the connector is not simply an asset picker. It establishes a relationship between:

Bynder DAM à Optimizely Graph & Optimizely CMS à Frontend Applications

When implemented correctly, it enables organizations to maintain Bynder as the single source of truth for digital assets while still providing content authors with a seamless CMS authoring experience.

For organizations already invested in Bynder and Optimizely SaaS CMS, the connector can significantly simplify asset governance, reduce duplication, and improve overall content delivery architecture.

📚 Bynder + Optimizely SaaS CMS Integration Series

This article is the first installment of a 3-part comprehensive architecture guide:

👉 Part 1: Implementing the Connector — Lessons Learned (You are here)
What metadata syncs, how URLs behave, and how to query/render assets in a Next.js frontend.
⏭️ Part 2: Planning & Filtering — Avoiding Asset Sprawl and Unnecessary Sync
Discover how we achieved metadata-based sync filtering with zero custom code.
⏭️ Part 3: Exploring Asset Lifecycle Management & Three-Gate Governance
Explore a webhook-driven, three-gate model to handle asset updates, environments, and usage verification.

Optimizely London developer meetup 2026: a round up

Fri, 03 Jul 2026 11:50:58 GMT

Well, what can I say?

Last night we wrapped up! Yet another London Developer Meetup, hosted at the superb Lightwell venue

And this is also a celebration of my 10th year of co-hosting/hosting this meetup, something that has been very dear to my heart because of my love of the Optimizely community. It's always been the greatest of pleasures to organise these and help people get together, because the people I've met, the friends I've made, and the conversations we've had over a couple of beers have always made everything seem more vibrant and exciting and have really made my life so much better. Thank you to everyone who's been to any of these and connected with me. You're all amazing.

So the night, we had a great packed line up of talks

So we kicked off with a bit of an intro and a retro from myself and Mark, talking a little bit about where we were ten years ago and sharing a number of photos!

As a really touching point, our Niteco UK/US leader and friend Mark Welland (https://www.linkedin.com/in/markwelland/) arranged a couple of videos to celebrate my 10 years from Patrick Lam https://www.linkedin.com/in/patrickpclam/ Nicola Ayan (https://www.linkedin.com/in/nicolaayan/) and the big dog and CEO of Optimizely Alex Atzberger (https://www.linkedin.com/in/aatzberger/)

these are all such lovely videos, and it was really, really kind of everyone to put together such touching thoughts. It really meant the world to me.

And then we had all of the talks. Every single one of the talks was well thought out, well presented, and engaging, and I want to thank every single one of the speakers. Rather than recap it all here, you can actually view the recorded and live streamed output masterfully created by my good friend Jacob Pretorius (https://www.linkedin.com/in/jacobpretorius/) here

and also a big thank you to Techspace and the amazing food spread that they put on. We've been coming here a number of years, and it really is a great venue. Also, thank you so much to Satata (https://www.linkedin.com/in/satatasatez/). Patrick and Shamim (https://www.linkedin.com/in/shamim605/) for helping organise this and a big thank you to every one of the speakers today.

Mark Evard - https://www.linkedin.com/in/everard/ and thank you so much for all the kind words.
Guilherme Menezes - https://www.linkedin.com/in/guilherme-menezes-0521a715a/
Minesh Shah - https://www.linkedin.com/in/minesh-shah-dev/
Graham Carr - https://www.linkedin.com/in/carrgraham/
Simon Chapman - https://www.linkedin.com/in/sgchapman/
Andrew Markham - https://www.linkedin.com/in/markham-andrew/

Thanks everyone for attending, and I look forward to next year.

AvantiBit Custom Settings for Optimizely CMS

Fri, 03 Jul 2026 00:00:00 GMT

AvantiBit Custom Settings is a free, Apache-2.0 Optimizely CMS add-on for typed, site- and language-aware configuration that stays out of content while supporting policy-based access, caching, and multi-server sync.

Building an experience with Visual Builder in Optimizely CMS 13

Thu, 02 Jul 2026 13:35:17 GMT

Visual Builder changes how we can think about campaign pages, landing pages and other highly curated editorial experiences in Optimizely CMS. Instead of modeling every page layout as a fixed set of content areas, editors can compose an experience from sections, rows, columns and reusable elements. That gives us more flexibility, but it also gives […]

LanguageMaster! From Managing to Mastering Languages!

Thu, 02 Jul 2026 08:52:15 GMT

Two years ago, I released my first Optimizely add-on. It was an extension to the Labs.LanguageManager tool from Optimizely that allowed the user to choose to use DeepL as their translation provider. I noticed recently that it has the highest number of downloads of any NuGet package used by LanguageManager – I’m very sure more to do with how many people are using DeepL rather than with the stunning code quality.

In the two years since, we have used DeepL and LanguageManager with a few of our clients, and I’m sure each of them would have a significant list of issues with both the functionality and usability of LanguageManager, and more than a few would have complaints about the quality of DeepL too – and I don’t particularly think the issues or complaints they're raised (and internalised) are unfounded.

As a tool, LanguageManager (which has been newly updated to support CMS 13) allows CMS users to select a root node, then either choose to include all children, and/or all associated blocks, and then fire them at a translation endpoint, where what is returned is used to create or update a new language branch version of the source page. It’s basic, though does the job, but also has some shortcomings – especially (in my humblest of opinions) with Page References in content areas, where suddenly those “children and associated content items” checkboxes can result in what you thought was a 15 item content translation job turning into 15,000 content items as the spider crawls outwards, upwards and forever on and on (this has happened, huge costs have been incurred, people have not been happy).

And you’re tied to one translation provider at a time – maybe Azure is great for general content, but products would benefit going through DeepL? And translations into Chinese must use Baidu because it’s got the best vocab for that locale. LanguageManager can’t do that without constantly updating the settings to match the provider you have in mind.

And the locale granularity problem, where in China for example, the many variations of dialect and character mean that the target slug as a translation target isn't ideal - you want Hong Kong oriented translations on /cn? No way!

In small demo sites, translation management can look simple, but in the real-world of CMS and Commerce builds, content relationships, reusable blocks, products, variants, regional language requirements and even provider functionality make it much more complicated.

Enter Language Master!

Powerful selection tools for choosing what you want to translate, including full CMS and Commerce content tree, and Smart Select functionality for batch selections!
Multi-provider functionality for different scenarios, with translation endpoints for MS Azure, DeepL, Google Cloud, Amazon Translate, Claude, Baidu, ModernMT, OpalAI and Smartling – or build your own!
Per provider translation caching – so you can’t accidentally end up repeatedly sending the same source language and content items to be translated!
Provider routing so you can choose which configured provider delivers translations for which content!
Chained provider routing allows you to make better use of monthly free character tiers across multiple providers. Once Azure’s free allowance is used, for example, fallback can seamlessly continue through Google’s free allowance!
Language target override allows you to use a specific provider-supported locale, such as zh-Hant-HK, even when your site branch uses a simpler slug such as /cn/!
Projects allow you to build translation packages over time and run them once when you’re ready to translate all your content!
Full audit logging allows you to see if anything went wrong and why!
Commerce support for Categories, Products and Variations!
And… Multisite support!

What all of that looks like in practice...

Language Master’s Tree View allows an editor to select page content nodes, select block content node, select child nodes - you have full individual control over what is going to be translated. It also shows what’s already been translated, and what’s still in need of a new language version.

For larger trees, Smart Select allows for batch selections based on defined criteria – content types, publish status, parent node, date modified – completely extensible interface to build your own criteria for selection.

Language Master has pre-built Translation Providers for MS Azure, DeepL, Google Cloud, Amazon Translate, Claude, Baidu, ModernMT, OpalAI and Smartling – all of which can be configured and activated at the same time! And a framework to allow you to build your own provider if it’s not in the list.

Your activated providers can then be used to create Routing Rules for different language pairs – with a fallback for if you’ve got no specific language requirements.

The same language pairs can be configured multiple times – essentially Chaining Providers - to provide fallback in the event of error – or having no translation credits left.

Provider Overrides mean that for content specific cases, you can abandon routing rules and send individual content items to a selected provider.

Language target override allows the editor to define the specific language code to be used to translate into – depending on provider availability!

Batch Update means that selected content items can have their translation properties – publish status, provider choice, name and slug translation options - updated all at once.

Projects update the tree view to show what is in the project and what is not.

Projects can support multiple language pairs, making it possible to prepare translation work for different source and target content items, and run them as a single package when the content is ready. This means you don’t need to have separate projects for different languages – though you can if you want to!

And provides a way of batching together multiple updates over time, to be translated all at once.

Audit Log allows the editor to see what has been translated and when, whether any errors occurred, and if needed allows the editor to invalidate any cache that exists for the content item and provider.

And it has Commerce support. Language Master covers Categories, Products, and Variations — not just CMS pages and blocks.

Going back to that DeepL extension: releasing it and watching it used across real projects showed me exactly where LanguageManager struggles. Not because it's a bad tool — it does what it does — but because real multilingual projects in production are messier than it was built to handle.

Language Master has been designed to tidy up that mess.

The packages are available on Optimizely's Nuget Feed for CMS and optionally Commerce.

If you try it, I'd genuinely like to hear what works, what doesn't, and what you'd want to see next - I'm thinking a SaaS version...?

List Properties of a Optimizely Content Type programmatically

Thu, 02 Jul 2026 08:48:45 GMT

Properties are simply fields used to create a content type in Optimizely. Lets explore how to get a list of properties of a specific content type defined in Optimizely. These properties can be simple text, rich text, images, links, etc. The blog is useful for devs aiming to map opti content type properties while migrating content.

Content

In Optimizely CMS, the first term you will hear is content. Content is just like items in Sitecore.

Content Type

The different types of content could be of type page, block, media, video, image, or a custom type.

IContentTypeRepository

To get a list of all available content types defined in Optimizely CMS project, first, we will need an instance of IContentTypeRepository, as this is the primary API for accessing the repository methods.

Through the content type repository instance, we can perform CRUD (Create, Read, Update and Delete) operations on content. Alternatively, if you only need read-only access, use the IContentLoader instance.

var repository = ServiceLocator.Current.GetInstance<IContentTypeRepository>();

The list() method lists all available content types (Block, Media, Page, Image, Video) in the repository.

var contentTypeList = repository.List();

Content type - To get the content type of block or page type, we can filter the list by passing the content type.

var pageTypes = repository.List().OfType<PageType>();

var blockTypes = repository.List().OfType<BlockType>();

By passing PageType as a parameter, we shall get all the content of the type page.

To get a specific content type, use the Load() method on the repository instance. The Load() methods have overloads, and we can get the specific content type by passing Id, Guid, ContentType, or Name as parameter.

var contentType = repository.Load<LocationItemPage>();

In solutions, which do not have a reference to the Optimizely CMS project example a razor class library project. The specific content type is not accessible, which is present in Optimizely Project. In such a scenario, we can use the Guid or Id saved in global constants file.

var contentTypeById = contentTypeRepository.Load(contentTypeId);

PropertyDefinitions

Returns a property collection containing all properties defined in a specific content type.

var properties = contentType.PropertyDefinitions;

Getting property names

We can retrieve the properties and save them in list. we can use EditCaption property for getting display names of properties. If one needs actual property names use Name property.

List Properties = new List<string>();

foreach (var property in properties)

{

string propertyName = property.EditCaption;

Properties.Add(propertyName);

}

You can further explore PropertyDefinitions class as it gives access to other properties and methods which can be of use in development.

Happy Learning!

Optimizely CMS SaaS – Chrome Extension to Stop Accidentally Editing Production

Wed, 01 Jul 2026 13:18:25 GMT

If you work with Optimizely CMS SaaS across multiple clients, you know the anxiety — multiple tabs, multiple environments, and one wrong edit away from breaking a live site. At Horizontal Digital, we manage several Optimizely CMS instances for different clients, each with production and test environments. The Optimizely UI looks identical across all of […]

Optimizely SaaS CMS Contracts: Define Shared Structure Across Content Types

Wed, 01 Jul 2026 13:09:35 GMT

📌 Scope: This post covers Optimizely CMS (SaaS) only — using the @optimizely/cms-sdk toolchain. CMS 13 (PaaS) handles shared structure differently via .NET interfaces. When you’re building a multi-content-type site, you quickly run into a problem: Blog Articles, Press Releases, and News Pages all need category and tags — but without a shared structure, you […]

Finding Thomas Part 3 - The Moment of Recognition

Fri, 26 Jun 2026 17:08:48 GMT

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.

Add more scheduled job settings from the Optimizely CMS 12 admin UI -- with OptiScheduledJob.ExtraParameters

Thu, 25 Jun 2026 14:25:57 GMT

Optimizely (EPiServer) CMS 12 ships a great scheduled-jobs framework, but it has one frustrating gap: a job has nowhere to store its own configuration. Want an administrator to tweak a batch size, flip a feature flag, pick a priority, or set a cut-off date for a job — within Scheduled Job Settings UI directly? Out of the box you can't. Teams usually end up hard-coding values, hanging them off `appsettings.json`, adding more content type as settings type.

OptiScheduledJob.ExtraParameters closes that gap. It lets you attach a strongly-typed settings class to any custom scheduled job and edit it right on the job's detail page in the admin UI — no extra plumbing, no custom screens.

✅ Edited by CMS admins in a form rendered automatically under the default job settings

✅ Persisted in Optimizely's Dynamic Data Store

✅ Read back inside the job at execution time through a simple service

How to install

The package is published to the Optimizely NuGet feed https://nuget.optimizely.com. Register that feed as a source first, then install:

dotnet nuget add source https://api.nuget.optimizely.com/v3/index.json -n optimizely

dotnet add package OptiScheduledJob.ExtraParameters

using OptiScheduledJob.ExtraParameters.Infrastructure.Configuration;

public void ConfigureServices(IServiceCollection services)

{

services.AddCms();

// ...

services.AddScheduledJobExtraParameters();

}

1. Define your settings

Create a class deriving from ScheduledJobExtraParametersBase and decorate each property with

[ExtraParametersPropertyDisplay] for its label, help text, and (optionally) dropdown options:

using OptiScheduledJob.ExtraParameters.Attributes;

using OptiScheduledJob.ExtraParameters.Models;

public class CleanupJobParameters : ScheduledJobExtraParametersBase

{

[ExtraParametersPropertyDisplay(DisplayName = "Source folder", Description = "Path to scan")]

public string SourceFolder { get; set; }

[ExtraParametersPropertyDisplay(DisplayName = "Batch size", Description = "Items per run")]

public int BatchSize { get; set; }

[ExtraParametersPropertyDisplay(DisplayName = "Threshold", Description = "Minimum match score")]

public decimal Threshold { get; set; }

[ExtraParametersPropertyDisplay(DisplayName = "Send notifications")]

public bool SendNotifications { get; set; }

[ExtraParametersPropertyDisplay(DisplayName = "Run after")]

public DateTime RunAfter { get; set; }

// A string[] of options renders a dropdown.

[ExtraParametersPropertyDisplay(DisplayName = "Priority", Options = new[] { "Low", "Medium", "High" })]

public string Priority { get; set; }

}

2. Attach it to your job

[ScheduledPlugInWithExtraParameters] is a drop-in replacement for [ScheduledPlugIn]:

using EPiServer.Scheduler;

using OptiScheduledJob.ExtraParameters.Attributes;

[ScheduledPlugInWithExtraParameters(

DisplayName = "Unused Image Removal",

ExtraParameterDefinition = typeof(CleanupJobParameters))]

public class UnusedImageRemovalJob : ScheduledJobBase

{

// ...

}

3. Read the values when the job runs

using OptiScheduledJob.ExtraParameters.Services;

public class UnusedImageRemovalJob : ScheduledJobBase

{

private readonly IScheduledJobExtraParametersDataService _extraParameters;

public UnusedImageRemovalJob(IScheduledJobExtraParametersDataService extraParameters)

{

_extraParameters = extraParameters;

}

public override string Execute()

{

var settings = _extraParameters.Get<CleanupJobParameters>(this.ScheduledJobId);

var batchSize = settings?.BatchSize ?? 100;

// ... use the settings

return "Done";

}

How it looks in the admin

Open Admin → Scheduled Jobs → your job. Below the standard "When to run" controls, an Extra Parameters form appears automatically. Each property is rendered with the right input control for its type — text box, number, date picker, checkbox or dropdown — one per row:

Saving — with notification

Hit Save on the Extra Parameters form and the values are posted back stored. You get a clear toast notification confirming the result:

Compatibility

- Optimizely CMS 12 (EPiServer.CMS 12.x)

- .NET 6, 8, 9 and 10 — the package multi-targets all four runtimes

- Optimizely CMS 13 - planned in future no far

Links

- NuGet: Optimizely NuGet feed — https://nuget.optimizely.com/

- Source & issues: https://github.com/binhboong1802/optimizely-scheduledjob-extraparameters

Automated Search & Navigation to Graph Migration with Claude Code

Wed, 24 Jun 2026 17:58:56 GMT

A Claude Code plugin that scans your S&N codebase, applies Graph SDK transformations, and validates the result. Install once, run one command.

CMS 13 Optimizely Graph Migration Claude Code Automation Search & Navigation

TL;DR

The cg-migrate Claude Code plugin automates the Search & Navigation to Graph SDK migration. It scans your .NET solution for every Find API usage, rewrites the code to use Optimizely.Graph.Cms.Query, and validates the result by building the project and attributing compiler errors back to the specific transformation that caused them.
Five skills cover the full workflow: /migrate-all runs the entire pipeline end-to-end, or use the individual skills for more control: /migrate-scan discovers all S&N usage and classifies complexity, /migrate-transform rewrites the code, /migrate-validate checks the build, and /migrate-map handles one-off translations.
It understands your codebase structure. The scan traces dependency graphs through wrapper classes and DI registrations, so indirect consumers of Find are identified too.
You keep control over the hard decisions. When a pattern has no direct Graph equivalent (like UnifiedSearch or custom FilterForVisitor implementations), the plugin generates a decisions file and pauses for your input before continuing.
Install with two commands and the plugin loads on every Claude Code session automatically.

1. Why This Plugin Exists

The Graph SDK blog post on Optimizely World covers how to write queries with Optimizely.Graph.Cms.Query. If you have not read it yet, start there. It walks through Where(), SearchFor(), Facet(), and the rest of the API that replaces Search & Navigation.

What the blog post does not cover is the mechanical work of actually migrating a real codebase. A typical Optimizely solution has Search & Navigation calls spread across dozens of files. Some are straightforward Search<T>().Filter().GetResult() chains. Others are wrapped behind repository classes, injected through DI containers, or built up conditionally with .OrFilter() composition. Finding all of that, understanding the dependency graph, and rewriting it file by file takes time that could be spent on the parts of a CMS 13 migration that genuinely require human judgment.

The cg-migrate plugin handles the mechanical part. It is a set of Claude Code skills that scan your solution, apply the known API mappings from the Graph SDK blog post, flag the patterns that need human decisions, and validate the result against the compiler. You stay in control of architecture questions. The plugin handles the find-and-replace at scale.

2. Getting Started

Prerequisites

You need Claude Code installed and a .NET solution that currently uses the Search & Navigation (EPiServer Find) SDK.

Before running the migration, check out a dedicated branch with no pending changes. The solution should build cleanly and all tests should pass. This gives the plugin a clean baseline so it can distinguish migration-introduced errors from pre-existing issues.

Installation

Run these two commands in Claude Code:

/plugin marketplace add episerver/content-graph-sdk-migrations
/plugin install cg-migrate@content-graph-sdk-migrations

The plugin loads automatically on every subsequent Claude Code session. No configuration files to edit.

What Gets Installed

The plugin adds five slash commands to your Claude Code session:

Command	Purpose
/migrate-all	Run the full migration pipeline end-to-end: scan, transform, validate, and fix
/migrate-scan	Discover all S&N usage across the solution and produce a migration manifest
/migrate-map	Translate a single file or code snippet from S&N to Graph SDK
/migrate-transform	Apply transformations to all files identified by the scan
/migrate-validate	Build the project and map each compiler error back to the transformation that caused it

Three Ways to Use the Plugin

You do not have to use all five commands. Pick the approach that fits where you are in your migration:

Approach	Commands	When to use
Full pipeline	/migrate-all	You want to migrate the entire solution end-to-end in one run. The command handles scan, transform, validate, and build-fix phases automatically, pausing only for manual decisions.
Step by step	/migrate-scan → /migrate-transform → /migrate-validate	You want to review the scan report before transforming, re-run a single phase after making manual edits, or iterate on specific files without restarting the full pipeline.
One-off translation	/migrate-map	You want to translate a single file or code snippet, understand how a specific S&N pattern maps to the Graph SDK, or handle a file individually before or after a larger migration run.

The rest of this post covers each approach in detail. If you just want to get started, skip to section 3 for the full pipeline or section 5 for one-off translations.

3. Running the Full Migration

The fastest way to migrate is /migrate-all. It orchestrates the entire pipeline in a single invocation:

/migrate-all --project path/to/YourSolution.sln

If you omit --project, the plugin searches for .sln files in the current directory.

What Happens

The command runs six phases sequentially:

Phase 1: Scan. Invokes /migrate-scan to discover all Find SDK usage, trace dependency graphs, and classify each pattern by complexity. If no migration targets are found, the command stops early.

Phase 2: Confirm. Presents a summary of what will be transformed automatically and what will require manual decisions, then pauses for your confirmation before making any changes.

Phase 3: Transform. Invokes /migrate-transform to apply all known API mappings, swap NuGet packages, and flag items for manual review.

Phase 4: Validate. Invokes /migrate-validate to build the project and attribute compiler errors to specific transformation rules. If errors are found, it automatically retries the transformation on the failed files for a second pass.

Phase 5: Build & Fix. Rebuilds the project and iteratively fixes remaining compiler errors that have clear automated solutions, such as CS0266 type mismatches, CS1061 missing members, CS0246 unknown types, and NuGet version conflicts. Errors that require business logic decisions are deferred for you to handle manually.

Phase 6: Report. Generates a comprehensive migration report at .cg-migrations/migrate-all/ that ties together the results from every phase: targets scanned, files transformed, errors fixed, and remaining manual items with prioritized next steps.

The final report classifies the migration status as Complete (all errors resolved), Partial (some errors remain), or Nothing to migrate (no targets found).

Tip

Use /migrate-all for the typical workflow. The individual skills (/migrate-scan, /migrate-transform, /migrate-validate) are still available when you need to re-run a specific phase or want more control over the process.

4. Scanning Your Codebase

If you want to inspect the migration scope before committing to a full run, or if you need to re-run just the scan phase, use /migrate-scan directly:

/migrate-scan --project path/to/YourSolution.sln

If you omit --project, the plugin searches for .sln files in the current directory.

The scan runs in four phases:

Phase 1: NuGet Detection. The scan parses .csproj files to find which projects reference EPiServer.Find packages and what versions they use.

Phase 2: Direct Reference Scan. Using regex patterns from a built-in registry of 50+ S&N API patterns, the scan locates every file that calls into the Find SDK. Each match is categorized by type (filtering, facets, sorting, search, DI registration, etc.).

Phase 3: Dependency Graph Tracing. This is where the scan goes beyond simple text search. It follows constructor injection, DI registrations, and wrapper class hierarchies up to 5 hops deep. If you have a SearchService that wraps IClient and a SearchController that injects SearchService, both get flagged as migration targets even though only SearchService contains direct Find API calls.

Phase 4: Complexity Classification. Every identified pattern gets one of three labels:

Classification	Meaning	Example
direct-swap	1:1 Graph SDK equivalent exists	.Filter() to .Where(), .Take() to .Limit()
pattern-rewrite	Needs restructuring but the approach is known	.OrFilter() composition to BuildFilter<T>().Or()
manual	No automated equivalent, needs human decision	UnifiedSearch, custom FilterForVisitor

Scan Output

The scan produces a console summary with statistics and a detailed markdown report at .cg-migrations/migrate-scan/scan-report.md. The report includes every target file, the specific patterns found, the dependency tree, and the complexity breakdown.

Tip

Add .cg-migrations/ to your .gitignore. This directory is for migration artifacts and should not be committed.

5. Translating Individual Queries

For one-off translations or to understand how a specific pattern maps to the Graph SDK, use /migrate-map:

/migrate-map

Point it at a file or paste a code snippet. The skill applies 17 translation rules covering the full S&N API surface.

Before and After

Before - Search & Navigation

var result = searchClient.Search<ArticlePage>()
    .For("chocolate cake")
    .InField(x => x.Title, 3.0)
    .InField(x => x.Summary, 2.0)
    .Filter(x => x.Category.Match("Dessert"))
    .Filter(x => x.IsPublished.Match(true))
    .TermsFacetFor(x => x.Category)
    .OrderByDescending(x => x.PublishDate)
    .Take(10)
    .Skip(20)
    .GetResult();

After - Graph SDK

var result = await _graphClient
    .QueryContent<ArticlePage>()
    .SearchFor("chocolate cake")
    .UsingField(x => x.Title, boost: 3)
    .UsingField(x => x.Summary, boost: 2)
    .Where(x => x.Category == "Dessert" && x.IsPublished)
    .Facet(x => x.Category)
    .OrderBy(x => x.PublishDate, OrderDirection.Descending)
    .Limit(10)
    .Skip(20)
    .IncludeTotal()
    .GetAsContentAsync();

The /migrate-map skill is useful for building intuition about the mapping rules before running a full transformation, and for handling files you want to review individually.

6. Transforming the Full Codebase

Once you have reviewed the scan report and understand the scope, run the full transformation:

/migrate-transform --project path/to/YourSolution.sln

You can optionally pass the scan report path if you have already run /migrate-scan:

/migrate-transform --project path/to/YourSolution.sln --scan-report .cg-migrations/migrate-scan/scan-report.md

How the Transform Works

The transform runs in six phases:

Phase 1: Decision Resolution. For every pattern classified as manual in the scan, the transform generates a decisions file at .cg-migrations/migrate-decisions.md. This file groups patterns and presents strategy options. The plugin pauses here and asks you to choose a strategy for each group before continuing.

Example decision groups and strategies:

Pattern Group	Suggested Strategy
UnifiedSearch (searches across multiple content types)	type-specific-queries (create separate QueryContent<T>() per type)
ContentIndexer / .Track() calls	remove (comment out, no Graph equivalent for direct indexing)
Custom site/visitor filters	custom-implementation (you provide the replacement logic)
.UsingSynonyms()	per-filter-synonym (move to .Match("value", SynonymSlot.One))

Phase 2: NuGet Package Setup. Adds Optimizely.Graph.Cms.Query to the relevant projects and tracks the S&N packages for removal.

Phase 3: Code Transformation. Each file gets 13 transformation steps applied in sequence: namespace updates, DI registration changes, query entry points, full-text search, filtering, sorting, pagination, facets, projections, execution (all made async), result access patterns, manual pattern strategies, and cleanup of orphaned using statements.

Phase 4: Cleanup. Removes using EPiServer.Find statements that are no longer needed.

Phase 5: Build Validation. Runs dotnet build and auto-fixes common issues like NuGet conflicts and generic constraint mismatches (the Graph SDK requires where T : class, IContentData rather than just IContentData). Iterates up to 2 cycles.

Phase 6: Reporting. Generates a transform report at .cg-migrations/migrate-transform/transform-report.md with per-file results.

The decisions file persists across runs

If you run /migrate-transform again, it reads your previous decisions. You can edit the file directly to change strategies for specific patterns or files.

7. Validating the Result

After the transform completes, run validation:

/migrate-validate --project path/to/YourSolution.sln

The validation phase does more than just run dotnet build. It parses every compiler error, matches it against a built-in lookup table of known migration-related error signatures, and attributes each failure to the specific transformation rule that likely caused it.

Validation Output

The report separates errors into three buckets:

Bucket	Meaning
Migration-caused (high confidence)	File was transformed AND error matches a known migration pattern
Possibly migration-related (medium confidence)	Error matches a known cause but the file was not directly transformed
Pre-existing / out-of-scope	Error does not match any migration pattern

Each error includes the file path, line number, error code, message, and the likely cause with a suggested fix.

Example Error Attribution

CS1061 in SearchService.cs:42
  'IContentQuery<ArticlePage>' does not contain a definition for 'TotalMatching'
  Likely cause: Rule 11 (Result Access)
  Suggested fix: Add .IncludeTotal() to the query chain and access result.Total

After reporting, the validation skill offers to re-run /migrate-transform on just the failed files for a second pass (max 2 rounds). This catches cases where the first pass produced valid but incomplete transformations.

8. Full Workflow at a Glance

# 1. Check out a clean branch
git checkout -b feature/graph-migration

# 2. Run the full migration
/migrate-all --project src/MySolution.sln

# 3. Make decisions for manual patterns when prompted

# 4. Review the migration report
# (open .cg-migrations/migrate-all/*-migration-report.md)

# 5. Fix any remaining manual items and commit

That is the simplest path. If you need more control, the individual skills (/migrate-scan, /migrate-transform, /migrate-validate) can be run separately and repeated as needed. The decisions file and scan report persist between runs, so you can iterate without losing your choices.

9. What the Plugin Handles vs. What You Handle

The plugin handles	You handle
Finding every S&N API call across the solution	Reviewing the scan report for completeness
Tracing wrapper classes and DI dependency chains	Deciding strategies for manual patterns
Applying the 17 known API translation rules	Custom filter/visitor logic that has no Graph equivalent
Making methods async when execution changes to GetAsync() / GetAsContentAsync()	Business logic changes (e.g., if UnifiedSearch was used to merge results, you decide how to restructure)
Adding generic constraints (class, IContentData)	Integration test updates
Attributing compiler errors to specific transformation rules	Verifying that query results are functionally equivalent
NuGet package additions	NuGet package removals (tracked but left for you to confirm)

Looking Ahead

The plugin's pattern registry will continue to grow as partners encounter additional S&N patterns during real-world migrations.

If you run into a Search & Navigation pattern that the plugin does not handle, the validation report will call it out. File an issue on the GitHub repository at episerver/content-graph-sdk-migrations so the pattern can be added to the registry.

Next Steps

Install the plugin with /plugin marketplace add episerver/content-graph-sdk-migrations
Run /migrate-all on your solution to migrate end-to-end, or start with /migrate-scan to preview the scope first
Review the migration report and fix any remaining manual items
Read the Graph SDK blog post to understand the API you are migrating to

Resources:

Introducing the Optimizely CMS 13 Graph SDK (the companion blog post covering the Graph SDK API)
Plugin Repository: episerver/content-graph-sdk-migrations

Start with the scan

Running /migrate-scan is read-only. It does not modify any files. You can run it against any branch at any time to understand the scope of the migration before committing to the transformation.

This guide is based on the cg-migrate Claude Code plugin for migrating Search & Navigation to the Optimizely Graph SDK. The plugin is actively maintained and the pattern registry grows with each release.

Migrating from Find to Graph: Lessons Learned from a Real CMS 13 Project

Wed, 24 Jun 2026 11:26:37 GMT

While migrating a search solution from Optimizely Search & Navigation (Find) to Optimizely Graph in CMS 13, I encountered several issues that were not immediately obvious from the documentation.

Most of these issues were discovered through experimentation, debugging startup errors, investigating generated Graph schemas, and comparing behavior with Search & Navigation.

Here are details about them:

1. Graph Conventions Only Existing Starting from CMS 13.1.0

It took me quite some time to figure out how to apply Graph Conventions based on the following documentation while working on a CMS 13.0.0 project:

https://docs.developers.optimizely.com/content-management-system/v13.0.0-CMS/docs/indexing-conventions

The documentation describes Graph Conventions using APIs such as:

services.ConfigureGraphConventions(...)

OR

services.AddContentGraph(configureConventions: c =>
{
    //add conventions here
});

However, I was unable to find this API in a CMS 13.0.0 implementation.

After further investigation, I discovered that the Graph Convention API was introduced in CMS 13.1.0 together with Optimizely.Graph.Cms 13.1.0 and is not available in earlier CMS 13 releases.

This initially caused some confusion because the documentation is published under the CMS 13 documentation section without clearly indicating the minimum version required for the feature.

My recommendation is to use CMS 13.1.0 or later if you plan to leverage Graph Conventions during your migration. And It would be helpful if the documentation included version-specific notes or minimum version requirements for Graph Convention APIs, as this could save developers a considerable amount of troubleshooting time during migration projects.

2. Extension Methods Work for Queries but Not for Facets

One of the first surprises I encountered was that extension methods included through Graph Conventions can be queried successfully but cannot be used for faceting.
Here is sample code:

- Configuration
services.ConfigureGraphConventions(conventions => { conventions .ForInstancesOf<StandardPage>() .IncludeField(x => x.ContentTypeName(), IndexingType.Searchable); });

- Extension method:

public static string ContentTypeName(this ISitePageData sitePageData)
{
    return sitePageData.GetOriginalType().Name;
}

However, when attempting to create a facet using the extension method:

query.Facet(x => x.ContentTypeName());
I saw this error

I tried running the same facet query directly in Graph Explorer, and it worked as expected. This leads me to believe that the issue may originate from the Optimizely Graph Client API when it builds the query from a lambda expression. However, I'm not sure whether this behavior is intentional or if it should be considered a bug.

Impact: Existing Find implementations that rely on calculated fields for faceting may require redesign when migrating to Graph.

3. Search By Base Type Works Differently Than Search & Navigation

In Search & Navigation, it is common to search across multiple content types by using a shared base class or marker interface.

Examples:

Search<SitePageData>()

Search<ISearchableContent>()

Many developers expect the same approach to work in Optimizely Graph. Unfortunately, Graph uses a different model and does not automatically support these patterns.

- What does not work

The following approaches do not create a shared Graph schema that can be queried across all implementing content types.

Simple interfaces:

public interface ISearchableContent { }

Abstract base classes:

public abstract class SearchablePage : PageData { }

Although these patterns work well in Search & Navigation, Optimizely Graph does not automatically generate a queryable Graph contract from them.

- What works

To query multiple content types through a shared schema, Optimizely Graph requires a Graph Contract.

For example:

[ContentType]
public interface ISitePageData

The contract must then be implemented by each content type that should participate in the shared schema:

public class ArticlePage : ISitePageData

public class NewsPage : ISitePageData

When content is synchronized to Graph, a shared Graph type is generated for the contract, allowing queries across all implementing content types.

Content Type Management UI Behavior

One side effect of using a Graph Contract is that the interface becomes visible in the CMS Content Type Management UI.

For example, after adding the [ContentType] attribute to the interface:

[ContentType]
public interface ISitePageData
{
}

the contract appears as a content type in the CMS administration interface as following:

This behavior can be surprising at first, especially since the interface is not intended to be created or edited by content editors. However, this is currently the mechanism Optimizely Graph uses to discover and generate shared schema contracts.

Key takeaway: In Optimizely Graph, interfaces annotated with [ContentType] enable cross-type queries. Base class inheritance does not.
Impact: Search architectures based on inheritance hierarchies or marker interfaces must be redesigned using Graph Contracts. This can affect query models, schema design, and migration effort.

4. Using the Content Type Management UI to Change a Property's Indexing Type

Note: The indexing convention API cannot be used to exclude a field from Graph indexing. It only supports extension methods for calculated properties, not actual content type properties.

I tried to add this below to disable an actual field:

services.AddContentGraph(configureConventions: c =>
{
    c.ForInstancesOf<StandardPage>().IncludeField(x => x.ContentAreaCssClass, IndexingType.Disabled);
});

Here is the error when I try to disable a field from indexing via convention:

To disable indexing for a field, use the Content Type Management UI or apply the following attribute to the property in your content type:

[IndexingType(IndexingType.Disabled)]
public virtual bool HideSiteFooter { get; set; }

5. Graph Contracts and Content Types Must Use the Same IndexingType

When working with Graph Contracts, I discovered an unexpected validation rule that can prevent the application from starting.

Optimizely Graph validates property metadata across the entire contract hierarchy during startup. If the same property exists on both a Graph Contract and a content type, the IndexingType must be identical everywhere.

Example

Graph Contract:

[ContentType]
public interface ISitePageData
{    
    string ContentTypeName { get; }
}

Base content type:

public abstract class SitePageData : PageData, ISitePageData
{
    [GraphProperty(IndexingType.Queryable)]
    public virtual string ContentTypeName =>
    GetOriginalType().Name;
}

Here is the error you will see if this happens:

Impact: Inconsistent indexing metadata can prevent the application from starting. This validation rule becomes especially important when multiple teams maintain shared contracts and content models.

6. Getter-only/fallback properties are included in the Graph schema, but their indexed values are null

For example:

public string ContentAreaCssClass => "teaserblock";

public virtual string TeaserText
{
    get
    {
        var teaserText = this.GetPropertyValue(p => p.TeaserText);

        // Use explicitly set teaser text, otherwise fall back to description
        return !string.IsNullOrWhiteSpace(teaserText)
            ? teaserText
            : MetaDescription;
    }
    set => this.SetPropertyValue(p => p.TeaserText, value);
}

Here are the their value when indexing:

Impact: Properties that appear to work correctly in CMS may produce unexpected Graph results. Search queries, filters, and facets relying on computed values may silently return incorrect data.

7. Extension Methods Cannot Be Added to a Graph Contract as Calculated Fields

When using a Graph Contract, extension methods cannot be added as calculated fields on the contract itself.
Here is the error that I got when trying to do this:

Impact: Shared Graph Contracts cannot be enriched with convention-based calculated fields. Developers may need to duplicate calculated properties across content types or redesign their schema strategy.

Conclusion

Optimizely Graph provides a powerful and flexible search platform, but it differs significantly from Search & Navigation in several areas.

When migrating existing Find implementations, pay particular attention to:

- Graph Contracts
- Graph Convention limitations
- Faceting behavior
- Property indexing rules
- Calculated fields

Understanding these differences early can save significant debugging and migration effort.

Optimizely: Upgrade Opti-ID and .NET 10 in CMS 12

Tue, 23 Jun 2026 16:22:29 GMT

Many Optimizely customers are planning their roadmap around a future migration to Optimizely CMS 13. As a result, upgrades such as Opti ID adoption and...

The post Optimizely: Upgrade Opti-ID and .NET 10 in CMS 12 appeared first on Madhu Anbalagan's Blog.

Understanding Optimizely Graph: Caching, Webhooks & Avoiding Stale Content (Optimizely SaaS CMS)

Tue, 23 Jun 2026 04:28:27 GMT

📌 Scope: This post covers Optimizely CMS (SaaS) only — using the official @optimizely/cms-sdk and @optimizely/cms-cli packages with Next.js 15. If you’re on Optimizely CMS 12 (PaaS/DXP), the caching architecture and tooling are different. See the DXP ISR docs for that path. Your editor hit Publish. Five minutes later the page still shows the old […]

Optimizely Content APIs: the Setup the Docs Don't Walk You Through

Mon, 22 Jun 2026 13:31:38 GMT

CMS 13 is pushing things firmly in the direction of Optimizely Graph, but plenty of teams are still running on older CMS versions, or have good reasons to stick with the Content Delivery, Content Definitions, or Content Management APIs regardless of what version they're on. This guide is for those teams.

What follows is a step-by-step walkthrough to get any of the content APIs up and running, tested locally, and fully understood, in one place. No jumping between API reference pages, no piecing together fragments from several different resources. Just the things the documentation doesn't make obvious, learned the hard way.

The mental model first

Optimizely uses OpenID Connect (via a library called OpenIddict under the hood) to issue JWT bearer tokens. When you want a system to be able to call one of the content APIs, you define it as an OpenID Connect application, either in code, in the CMS Admin UI, or both. We'll cover the specifics of each in the steps below.

"Application" in this context is not referring to your CMS instance or front-end site, it refers to discrete client identities registered specifically for machine-to-machine communication. Your CMS can have as many of these as you need.

Why grant_type=client_credentials and not something else

OAuth 2.0 has several grant types: different flows for getting a token, each suited to a different kind of requester or use case.

authorization_code is for interactive users: a person clicks login, gets redirected, enters their credentials, and the app receives a token on their behalf.

client_credentials is for machine-to-machine communication. Your service acts as itself, not on behalf of a user. There are no redirects, it simply exchanges its credentials directly for a token.

Why the token endpoint is at /connect/token

This is OpenIddict's default endpoint path, and OpenIddict is the OpenID Connect server library Optimizely uses under the hood. Optimizely didn't invent this URL, it's baked into the library. The /api/episerver prefix in front of it is the actual Optimizely part of the route, sitting in the same legacy episerver namespace you'll see across the older API paths.

The flow from here is straightforward: you request an access token for one of these applications, then pass that token in subsequent requests to the content APIs. Importantly, the access rights you configure in the CMS are tied to the application identity itself, so when a request comes in using that token, content access is evaluated against whatever permissions that application has been granted.

The Add User/Group dropdown showing the Applications section with two OpenID applications listed

Let's set it all up

Step 1: Install the required NuGet packages

dotnet add package EPiServer.OpenIDConnect
dotnet add package EPiServer.OpenIDConnect.UI # Optional

You'll also need the API package for whichever API you're securing:

Content Delivery API: EPiServer.ContentDeliveryApi.Cms
Content Management API: EPiServer.ContentManagementApi
Content Definitions API: EPiServer.ContentDefinitionsApi

Version gotcha: Make sure your EPiServer.OpenIDConnect version is compatible with your CMS version. Mismatched versions are a common source of silent failures at startup.

Step 2: Wire up the configuration in code

In your Startup.cs, you need to configure OpenID Connect and register whichever content APIs you need:

public void ConfigureServices(IServiceCollection services)
{
    // ASP.NET Identity must be configured before OpenID Connect
    services.AddCmsAspNetIdentity<ApplicationUser>();

    services.AddOpenIDConnect<ApplicationUser>(
        useDevelopmentCertificate: _webHostingEnvironment.IsDevelopment(),
        createSchema: true,
        options =>
        {
            // Seeding an application here is optional: see note below
            options.Applications.Add(new OpenIDConnectApplication
            {
                ClientId = "your-client-id",
                ClientSecret = "your-client-secret",
                Scopes =
                {
                    "epi_content_delivery",
                    "epi_content_management",
                    "epi_content_definitions"
                }
            });
        });

    services.AddOpenIDConnectUI(); // Optional: adds the OpenID Connect panel in CMS Admin

    services.AddContentDeliveryApi(OpenIDConnectOptionsDefaults.AuthenticationScheme);
    services.AddContentDefinitionsApi(OpenIDConnectOptionsDefaults.AuthenticationScheme);
    services.AddContentManagementApi(OpenIDConnectOptionsDefaults.AuthenticationScheme);
}

A few things worth noting here:

Each API registration method accepts an authentication scheme parameter, don't leave it out. Without it, the API has no way to validate incoming Bearer tokens and will return a 401 regardless of whether your token is valid. Pass OpenIDConnectOptionsDefaults.AuthenticationScheme to wire them up correctly.
useDevelopmentCertificate : tying this to IsDevelopment() means it uses a local dev certificate in your local environment and expects a real one in production. On DXP, certificates are provided automatically via EPiServer.CloudPlatform.Cms 1.6.1 or later.
Scopes: each scope string controls which API that client is permitted to call, and must match the scope you pass when requesting a token. There are constants available if you'd prefer not to use raw strings: ContentDeliveryOptionsDefaults.Scope, ContentDefinitionsApiOptionsDefaults.Scope, and ContentManagementApiOptionsDefaults.Scope.
Seeding applications in code is optional. The options.Applications.Add(...) block pre-creates the client on startup, which is convenient for local development. If you'd rather manage clients entirely through the UI, you can omit it, that's what the AddOpenIDConnectUI() line enables. It adds an OpenID Connect section under Settings in CMS Admin where you can create and manage applications directly.

The "OpenID Connect" settings panel can be seen in the screenshot above.

Step 3: Request a token

Once you have an application configured, either in code or the UI, you first need to request an access token for the application before calls to any of the content APIs can be made.

Using curl:

curl -X POST https://your-site.com/api/episerver/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=your-client-id&client_secret=your-client-secret&scope=epi_content_management"

Using Postman:

Set the request to POST, the URL to your token endpoint, and under the Body tab select x-www-form-urlencoded. Add the four key-value pairs: grant_type, client_id, client_secret, scope

A successful response looks like this:

{
  "access_token": "eyJhbGci...",
  "expires_in": 3599,
  "token_type": "Bearer"
}

Copy the access_token value, you'll use it in Step 5.

Step 4: Assign CMS access rights to the client

This is the most commonly missed step, and it causes some of the most confusing symptoms, you have a valid token, your requests aren't getting 401s, but you're getting empty results or unexpected 403s.

The API client you created is effectively a user in the CMS. Like any user, it needs to be granted access rights to the content it's trying to read or write. There are different levels you could configure access rights, let's get into them below.

Global access rights

Global access rights apply at the page or section level in your content tree and cascade down to every item beneath. For instance, if you want to deny a specific OpenID application Read access to a sensitive area, say, an "Admin" page or a "Members Only" section, you set the restriction at that page, and the cascade ensures every sub-page inherits the same rule automatically. You don't have to configure each one individually.

On this level, either all content is returned, or none of it. Either 200-OK, or 403-Forbidden

Navigate to Settings → Set Access Rights, select the page or section you want the client to access, and add it using Add User/Group. Your registered applications (from either the code or created in the CMS on the OpenID Connect settings panel) will appear under the Applications group in the dropdown.

Grant it the appropriate permissions: Read is sufficient for Content Delivery, while Content Management will need Read, Change, and Publish depending on what operations you need to perform. Check Apply settings for all subitems to cascade the rights down the content tree.

alloy-client application granted Read access on the Start page, cascading to all subitems.

Why this matters: Skipping this step produces one of two outcomes depending on your setup: either the API returns a 403 Forbidden response, or it returns content that was never actually restricted to begin with, because the Everyone group already has read access. In the latter case everything appears to be working, but your access rights configuration isn't doing anything. If you ever tighten down content permissions, your client will silently lose access.

Content-level access rights (per page/block instance in the tree)

Content-level access rights give you more granular control than the global settings screen, you can restrict access to specific pages or blocks directly in the content tree rather than applying a blanket rule across everything.

A practical example: imagine you have a pricing page that should only be visible to authenticated partners. Rather than locking down your entire content tree, you can grant your API client access to everything by default and then explicitly restrict access on those specific items, or invert it entirely, grant no global access, and only open up the specific content the client needs to see.

Same request, different response. The restricted client's "Pricing" entry isn't returned as a 403 error, it's simply omitted from the response. This is what makes content-level access rights powerful: the client doesn't need to know what they can't see, and the API does the filtering server-side.

The result isn't binary. It's not just 200 or 403, you can build quite precise access models by combining global and content-level rights.

Content-level access rights are set directly on a specific page or block in the edit interface. To access them, right-click the item in the content area or page tree and select Edit, then look for the Visible to panel at the top of the properties view. If access is unrestricted it will show as Everyone. Click Manage to open the Access Rights dialog and configure it the same way as the global screen.

Right-clicking a content item in the page tree to access its properties

The "Visible to" panel showing the current access restriction status for a content item, with the Manage link to open the Access Rights dialog

The Access Rights dialog for a specific content item, with alloy-client granted Read access and "Inherit settings from parent item" unchecked to override the global defaults

Step 5: Make your first authenticated request

With your token in hand (from Step 3) and access rights set, you can now call the API. Pass the token as a Bearer token in the Authorization header.

curl -X GET https://your-site.com/api/episerver/v3.0/content/{contentGuid} \
  -H "Authorization: Bearer eyJhbGci..."

Success response from the Content Delivery API (200 - OK)

However, if I revoke read access from the OpenId Application, I get the following:

Forbidden response from Content Delivery API (403 - Forbidden)

Common errors and what they actually mean

For the last example, the 403 is exactly what we'd expect, but it's worth understanding the difference between a 401 and a 403, since they're easy to confuse and point to very different problems.

401 Unauthorized means the API doesn't recognise or can't validate the token itself. Either it's malformed, it's expired, or the API isn't configured to accept it. Check that you're passing OpenIDConnectOptionsDefaults.AuthenticationScheme into your API registrations in Startup.cs, that your token hasn't expired (3599 seconds), and that your client_id and client_secret match exactly what's registered in CMS Admin.

403 Forbidden means the token is valid and recognised, but the application it belongs to doesn't have permission to access that content. This is the access rights problem covered in the previous step, the API knows who you are, it just won't let you in.

Token endpoint returns 404. The OpenID Connect middleware isn't registered, or the package isn't installed. Confirm the NuGet package is installed and correctly configured in Startup.cs.

invalid_client error from the token endpoint. The client_id or client_secret doesn't match what's registered in CMS Admin (or code). These must be identical, including case.

invalid_scope error from the token endpoint. The scope you're requesting (epi_content_management, etc.) doesn't match what was registered for the client in CMS Admin.

unsupported_grant_type from the token endpoint. The client was not registered with the client_credentials grant type. Check the application configuration in CMS Admin and ensure Client Credentials is selected as a permitted grant type.

Conclusion

Getting the Optimizely content APIs working for the first time involves piecing together information from several different sources, the official docs, community posts, and a fair amount of trial and error. Hopefully this post brings it all into one place and saves someone the same legwork.

If you're already on CMS 13 or considering the move, Optimizely Graph changes the delivery layer significantly and much of the authentication setup described here won't apply in the same way. But for teams on CMS 12 or those still needing to use any of the content APIs, this remains the path.

Url & Headers	POST /api/content/v2/data?id=bynd HTTP/1.1 Host: cg.optimizely.com Content-Type: application/x-ndjson Authorization: Basic V25KQmNtUlpSNTFYaDJuSmE1UWV5eEkwWW...[Your_Base64_Encoded_Credentials]
Body	{"delete":{"_id":"bynder-asset-guid-12345","language_routing":"en"}} {}
Response	{ "status": "success", "total_records_processed": 1, "deleted": 1, "errors": [], "took": 42 }