Installing Opal as Add-on

Introduction

Optimizely Opal Chat is delivered to CMS 12 (PaaS) as an installable app (add-on) via NuGet. From a developer operations perspective, this means Opal enablement is treated like any other dependency change: it becomes part of the application build output and must flow through the same promotion pipeline (Dev → Test/Staging → Production).

This page focuses on the technical mechanics: package acquisition, version alignment, and deployment-artifact implications in CMS 12 PaaS.

1. Prerequisites and platform constraints

Opal Chat for CMS 12 has explicit platform prerequisites that affect whether installation will succeed and whether the feature will function after deployment.

Key requirements include:

• CMS 12 must be hosted on Optimizely DXP (DXP-only capability for CMS 12).
• The product instance must be enabled for Opti ID.
• Opal must be provisioned at the organizational level (typically coordinated via Customer Success).
• Third-party cookies must be allowed for the Opal UI experience.

These prerequisites are operational gates: installing the package in code does not guarantee the feature will be usable without the corresponding tenant-level enablement.

2. Identify the Opal package and version boundaries

For CMS 12, the Opal Chat integration is distributed as a NuGet package:

• Package: Optimizely.Cms.OpalChat

The package details also indicate a CMS UI version constraint. For example, version 1.2.0 declares a dependency on:

• EPiServer.CMS.UI (>= 12.29.0 && < 13.0.0)

This matters for build stability:

• If the CMS UI package is below the minimum required version, NuGet restore can fail or resolve incompatible dependency graphs.
• If the solution targets CMS 13 packages (or pre-release lines), the package’s < 13.0.0 boundary becomes a hard incompatibility.

3. Add the Optimizely NuGet feed

Optimizely apps are distributed through Optimizely’s NuGet feed. In many CMS 12 codebases, this feed is already present due to core package usage. Where it is not, add the Optimizely feed in a controlled manner.

A common enterprise approach is to store feed configuration in NuGet.Config at repository level (or in the build agent’s secured configuration).

Example: NuGet.Config snippet

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="Optimizely" value="https://nuget.optimizely.com/feed/packages.svc/" />
  </packageSources>
</configuration>

Operational notes:

• Some organizations proxy NuGet feeds through an internal artifact repository (Azure Artifacts, Nexus, Artifactory) to centralize caching and access control.
• If the Optimizely feed requires authentication in the environment, credentials should be injected securely and never committed to source control.

4. Install Opal Chat via NuGet

Option A: .NET CLI

dotnet add package Optimizely.Cms.OpalChat

Option B: Project file (.csproj)

<ItemGroup>
  <PackageReference Include="Optimizely.Cms.OpalChat" Version="1.2.0" />
</ItemGroup>

Option C: Visual Studio NuGet Package Manager

Optimizely’s add-on installation guidance supports installing apps via Visual Studio as a standard pattern. A notable operational note exists for Azure environments: app modules should be installed through Visual Studio rather than through the Add-ons UI.

5. Restore, build, and validate dependency resolution

After adding the package reference:

• Restore packages (local and CI).
• Compile the solution.
• Verify that the resolved package graph aligns with the CMS 12 baseline.

Recommended validation steps:

• Confirm the resolved EPiServer.CMS.UI version meets the minimum constraint required by the Opal package.
• Confirm no unintended major upgrades occurred (for example, upgrading CMS UI packages without coordinating with the rest of the CMS package family).
• Run automated tests, especially any CMS UI smoke tests and authentication-related tests (Opal relies on Opti ID enablement).

6. Deployment artifact implications

Installing Opal via NuGet changes the deployment artifact in the same way as any other dependency addition:

• The compiled output (and dependency set) now includes the Opal integration assembly.
• The application must be rebuilt and redeployed to each environment where Opal is intended to be available.

In a typical CI/CD workflow, this means:

• The repository contains a new package reference.
• Build outputs must be produced from the updated commit.
• The same build artifact (or an equivalent promoted artifact) should be deployed across environments to ensure parity.

A common pattern is to enforce a deterministic restore:

• Lock dependency versions (for example, via package lock files or centrally managed package versions).
• Restore using locked mode in CI to prevent dependency drift.

Conceptual example: locked restore in CI

dotnet restore --locked-mode

7. Post-deploy verification in CMS 12 PaaS

Once deployed:

• Verify that CMS loads normally (no startup exceptions).
• Verify the CMS UI experiences expected authentication behavior under Opti ID.
• Confirm that Opal entry points appear in the CMS UI as documented.

If Opal does not appear after a successful deployment, common causes are typically outside the codebase:

• The tenant is not provisioned for Opal.
• Opti ID is not enabled for the instance.
• Browser policies (third-party cookies) prevent the UI experience.

8. Why deployment discipline matters

From a business-operations angle, Opal installation is not just “adding a feature.” It introduces a new capability surface in the authoring workflow. Deployment discipline matters because:

• AI-assisted authoring changes editorial velocity and content production patterns.
• Access and availability must be predictable across environments (especially for training, UAT, and controlled rollouts).
• Rollback paths must be clear if governance or operational constraints require disabling the capability.

The technical implementation is straightforward (NuGet add-on). Operational success depends on environment parity, tenant provisioning, and disciplined release management.

Conclusion

Installing Opal in CMS 12 (PaaS) is a standard add-on deployment: introduce the Optimizely.Cms.OpalChat NuGet package, validate dependency constraints (notably CMS UI version alignment), and promote the resulting build artifact across environments. Successful enablement also requires DXP hosting, Opti ID, organizational provisioning, and browser policy compatibility.