Optimizely Opal

10 min

Optimizely Opal tools bring AI-powered campaign and promotion management to Optimizely Commerce Connect websites. Enable the tools to let business users create, update, and analyze campaigns and promotions through Opal.

Prerequisites

.NET 10.0 or later.

EPiServer.Commerce.Core 15.x.

Optimizely.Opal.Tools 0.4.0 or later.

Opti ID.

Optimizely.Commerce.Graph (required for tools that query data).

Install

Install the NuGet package from GitHub packages:

dotnet add package Optimizely.Commerce.Opal.Tools

Register services

Add Commerce Connect Opal tools to your service collection in Startup.cs or Program.cs.

public void ConfigureServices(IServiceCollection services)
{
    // Add EPiServer Commerce services first
    services.AddCommerce();

    // Add Commerce Opal Tools
    services.AddCommerceOpalTools();
}

Configure endpoints

Choose one of the following options to expose the tool endpoints.

Option A – UseCommerceOpalTools (recommended)

public void Configure(IApplicationBuilder app)
{
    app.UseCommerceOpalTools(
        basePath: "",
        includeExperimentalTools: false
    );
}

Option B – MapCommerceOpalTools (minimal APIs)

var app = builder.Build();

app.MapCommerceOpalTools(options =>
{
    options.BasePath = "";
    options.IncludeExperimentalTools = true;
});

Option C – Manual endpoint mapping

app.UseEndpoints(endpoints =>
{
    endpoints.MapControllerRoute(name: "Default", pattern: "{controller}/{action}/{id?}");
    endpoints.MapOpalTools("");

    // Optional: Separate endpoint for experimental tools
    endpoints.MapOpalTools("/experimental/",
        filter: t => t.IsExperimentalTool());
});

Configure the Opal instance

📘 Note To configure the Opal instance, you must be an Opal Admin.

Go to the following Opal instance: https://inte.opal.optimizely.com/instances/OPAL_INSTANCE_ID.

Go to the Tools > Registries tab.

Select Add tool registry.

Enter the registry name and the discovery URL from your Commerce Connect site, such as https://YOUR_COMMERCE_SITE/discovery.

On success, Opal lists all tools. Enable the tools you need.

Configure Content Graph (optional)

If you plan to use Graph tools, add the Content Graph configuration to appsettings.json:

{
  "Optimizely": {
    "ContentGraph": {
      "GatewayAddress": "https://YOUR_GATEWAY.optimizely.com",
      "AppKey": "YOUR_APP_KEY",
      "Secret": "YOUR_SECRET"
    }
  }
}

Authentication

All tools require Opti ID authentication. Include the authorization token in your requests:

Authorization: Bearer YOUR_OPTI_ID_TOKEN

The tools use the OptiID scheme with the default scope.