Get started with Optimizely Opal tools

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

Prerequisites

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

Installation

Install the NuGet package.

dotnet add package Optimizely.Cms.Opal.Tools

Configuration

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

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

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

Authentication

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:

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

This ensures all content operations respect the user's CMS permissions. Users can only read, create, edit, or delete content they can access.

Available tools

Category	Tool name	Description
Content Types	`paas_cms_list_content_types`	List all available content types.
	`paas_cms_get_content_type_details`	Get detailed information about a content type.
	`paas_cms_create_content_type`	Create a new content type.
	`paas_cms_update_content_type`	Update an existing content type.
	`paas_cms_delete_content_type`	Delete a content type.
Property Groups	`paas_cms_list_property_groups`	List property groups (tabs).
	`paas_cms_create_property_group`	Create a new property group.
Content Items	`paas_cms_create_content_item`	Create a new content item (draft).
	`paas_cms_get_content_data`	Get content item data and properties.
	`paas_cms_update_content_item`	Update content item properties.
	`paas_cms_delete_content_item`	Move content to the waste basket.
	`paas_cms_publish_content_item`	Publish a content item.
Variations	`paas_cms_create_content_variation`	Create a locale variation of content.
Preview	`paas_cms_get_content_preview_url`	Get the preview URL for content.
SEO	`paas_cms_seo_analysis`	AI-powered SEO analysis of content.
	`paas_cms_seo_edit`	Apply SEO recommendations to content.
Generative Engine Optimization (GEO)	`paas_cms_geo_analysis`	AI-powered generative engine optimization analysis.
	`paas_cms_geo_apply`	Apply JSON-LD schema markup to content.

See Available tools for CMS 13.

Endpoints

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

Method	Path	Description
`GET`	`/opal/discovery`	Returns the tool registry and lists all available tools with their parameter schemas.
`POST`	`/opal/{tool_name}`	Executes a specific tool (for example, `/opal/paas_cms_list_content_types`).

Local development

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

Start a SQL Server in Docker.

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

Create the database.

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

Set the connection string using user secrets.

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

Run the sample site.

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.