Get started with Opal tools

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

Prerequisites

• 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 Administrator. See Get started with Optimizely Opal for administrators for information.

1. Go to the following Opal instance, https://opal.optimizely.com/instances/{OpalInstanceId}.
2. Go to the Tools\Registries tab.
3. Click Add tool registry.
4. 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. See Manage tools in the Opal documentation.

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.