Get started with Optimizely Opal tools

Optimizely Opal offers AI-powered content management tools for CMS 13 (PaaS) sites. Use these tools to create and edit AI-driven content, improve Search Engine Optimization (SEO), and generate schema markup within the CMS editorial interface.

Prerequisites

• .NET 10.0 or later.
• EPiServer.Cms.Core 13.x (Optimizely CMS 13).
• Optimizely.Opal.Tools 13.0.0 or later.
• Opti ID configured for your CMS instance.

Install the NuGet package

Install the NuGet package.

dotnet add package Optimizely.Cms.Opal.Tools

Configure services and endpoints

Register services

Add the CMS Opal tools to your service collection in Startup.cs or Program.cs.

services.AddCmsOpalTools();

This registers the Opal tool service and all CMS tools in a single call. The underlying services (for example, IContentService and ISeoService) register automatically with Optimizely's [ServiceConfiguration] attribute and require no manual configuration.

Configure endpoints

Map the tool discovery and execution endpoints in your application pipeline.

app.UseEndpoints(endpoints =>
{
    endpoints.MapContent();
    endpoints.MapOpalTools("/opal/");
});

The MapOpalTools method accepts a prefix parameter (for example, "/opal/") that determines the base path for all tool endpoints.

• GET {prefix}discovery – Tool discovery endpoint (for example, /opal/discovery).
• POST {prefix}{tool_name} – Tool execution endpoints (for example, /opal/paas_cms_list_content_types).

Configure Opal instance

Register your tool endpoints with the Opal backend so Opal can discover and invoke them.

1. Go to the Opal instance admin portal (for example, https://opal.optimizely.com/instances/YOUR_INSTANCE_ID)
2. Add a new Tool Registry entry.
3. Set the discovery URL to your application's discovery endpoint.
   Text

   https://YOUR_CMS_HOST/opal/discovery

The Opal backend calls this URL to retrieve the list of available tools and their parameter schemas.

Authenticate users with Opti ID

All tools require authentication with Opti ID. When a user interacts with the Opal chat widget in the CMS UI, authentication flow is as follows:

1. The user authenticates with Opti ID when logging in to CMS.
2. Opal Chat passes the user's Opti ID token to the Opal backend.
3. The Opal backend forwards the token when it invokes tool endpoints.
4. Each tool validates the token and impersonates the authenticated user for all CMS API calls.

The authentication flow ensures all content operations respect each user's CMS permissions. Each user can only read, create, edit, or delete content they have permission to access.

Available tools

See Available tools for CMS 13.

Endpoints

When you configure MapOpalTools("/opal/"), the package exposes the following:

Local development

See the samples/OptiAlloy directory for a working sample site. To run it locally, complete the following:

1. Start a SQL Server in Docker.

   Bash

   docker run -e "ACCEPT_EULA=Y" -e "SA_PASSWORD=Qweerty123" -p 1433:1433 --name ms_sql_server -d mcr.microsoft.com/mssql/server:2022-latest

2. Create the database.

   Bash

   docker exec ms_sql_server /opt/mssql-tools18/bin/sqlcmd -S localhost -U SA -P Qweerty123 -C -Q "CREATE DATABASE OptiAlloyOpal"

3. Set the connection string using user secrets.

   Bash

   dotnet user-secrets set "ConnectionStrings:EPiServerDB" "Server=localhost,1433;Database=OptiAlloyOpal;User Id=SA;Password=Qweerty123;Encrypt=false;TrustServerCertificate=true;Connect Timeout=30" --project samples/OptiAlloy/OptiAlloy.csproj

4. Run the sample site.

   Bash

   dotnet run --project samples/OptiAlloy/OptiAlloy.csproj

The site runs at https://localhost:5000. Verify tools are registered by going to https://localhost:5000/opal/discovery.