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 to Test/Staging to 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: Optimizely.Cms.OpalChat.

The package declares a CMS UI version constraint. For example, version 1.2.0 requires:

• 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 it 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

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

Three installation methods are supported. Choose the one that fits your team's workflow.

Option A: .NET CLI

Option B: Project file (.csproj)

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 applies 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 locally and in 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 now includes the Opal integration assembly, and 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 - locking dependency versions and using locked mode in CI to prevent dependency drift.

Locked restore in CI

7. Post-deploy verification in CMS 12 PaaS

Once deployed, confirm the following:

• CMS loads normally with no startup exceptions.
• The CMS UI shows expected authentication behavior under Opti ID.
• Opal entry points appear in the CMS UI as documented.

If Opal does not appear after a successful deployment, the cause is 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.

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. A successful deployment is necessary - but not sufficient - for Opal to be usable.