Get started with Opal tools

You can enable Optimizely Opal tools to enable AI-powered campaign and promotion management for Optimizely Commerce Connect websites.

Requirements

• Use .NET 8.0 or later.
• Have EPiServer.Commerce.Core 14.x.
• Have Optimizely.Opal.Tools 0.4.0+.
• Use Opti ID.
• Use Optimizely.Commerce.Graph for tools that query data.

Installation

Install the NuGet package from GitHub packages:

dotnet add package Optimizely.Commerce.Opal.Tools

Configuration

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 Opal instance

📘

Note

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

1. Go to the following Opal instance: https://inte.opal.optimizely.com/instances/{OpalInstanceId}.
2. Go to the Tools\Registries tab. Click Add tool registry.
3. Enter registry name and discovery URL from your Commerce Connect site, like https://{commercesite}/discovery.

When successful, Opal lists all tools. You can then enable each tool.

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 OptiID authentication. Include the authorization token in your requests:

Authorization: Bearer <your-optiid-token>

The tools use the OptiID scheme with default scope.