Graph Integration

By Optimizely Education
Published: Mar 11, 2026
Rating 1 star 2 stars 3 stars 4 stars 5 stars

Average rating: 0 No reviews

Outline

At a glance

Core setup: Integration relies on specific NuGet packages and a strict service registration order.
Connectivity: Requires mapping DXP portal credentials within the appsettings.json configuration block.
Schema handshake: The first run triggers an automated provisioning of global contracts for content normalization.
Metadata sync: Site-level roots and host definitions require explicit activation via Content Delivery API options.

Activating the integration between Optimizely CMS 13 and Optimizely Graph requires explicit technical configuration within the application’s startup sequence. This process involves the installation of core middleware packages, the registration of services in the dependency injection container, and the environment-specific configuration of connectivity keys.

1. NuGet Package Prerequisites

The integration is facilitated through two primary NuGet packages that bridge the gap between the traditional CMS UI and the Graph delivery hub.

Optimizely.Graph.Cms: The core integration package containing background synchronization agents, Graph-first routing logic, and schema provisioning tools.
EPiServer.Cms.UI.ContentManager: A functional requirement for CMS 13 projects leveraging the search-first "Content Manager" interface powered by Graph.

# Command line installation
dotnet add package Optimizely.Graph.Cms
dotnet add package EPiServer.Cms.UI.ContentManager

2. Startup Service Registration

The registration of services occurs within the ConfigureServices method. The sequence of invocation is functionally significant; failing to follow the correct order can result in dependent UI services failing to initialize.

Mandatory Registration Sequence

The AddContentGraph() method establishes the underlying delivery and synchronization infrastructure. It must be registered before AddContentManager(), which utilizes that specific infrastructure.

public void ConfigureServices(IServiceCollection services)
{
    // ... existing CMS registrations

    // 1. Activate the Content Graph Infrastructure
    services.AddContentGraph(); 

    // 2. Activate UI features that depend on Graph
    services.AddContentManager(); 

    // ... additional configurations
}

3. Application Configuration (appsettings.json)

Service registration alone is insufficient without connectivity credentials. The application requires a specific configuration block to map credentials retrieved from the DXP PaaS portal to the Graph SDK.

{
  "Optimizely": {
    "ContentGraph": {
      "GatewayAddress": "https://cg.optimizely.com",
      "AllowSendingLog": "true",
      "AppKey": "[APPLICATION_KEY_FROM_PORTAL]",
      "Secret": "[SECRET_KEY_FROM_PORTAL]",
      "SingleKey": "[SINGLE_KEY_FROM_PORTAL]"
    }
  }
}

Key Definitions:

GatewayAddress: The base URI for the GraphQL endpoint.
AppKey and Secret: Administrative credentials used by the server-side sync agent.
SingleKey: A delivery-level credential used for client-side or public-facing read-only queries.

4. Schema Provisioning and the Handshake

Upon the first execution, the integration agent performs an "initial handshake" with the Optimizely Graph service to provision Global Contracts—predefined schemas that normalize CMS content for the Graph.

Verification of Schema Readiness

Developers should monitor application logs during the first startup. A successful integration is indicated by entries confirming that the "Content Graph schema has been provisioned successfully." If the schema already exists, the service proceeds directly to synchronization.

5. Interaction with Content Delivery API Options

For solutions utilizing the Content Delivery API (CDA), additional configuration ensures that site-level metadata—such as content roots and host definitions—is effectively synchronized to the Graph.

services.ConfigureContentApiOptions(options =>
{
    // Ensures internal structure and host mapping is indexed
    options.IncludeInternalContentRoots = true;
    options.IncludeSiteHosts = true;
});

Conclusion

Activating the Graph integration is a foundational requirement for modernizing any CMS 13 solution. By correctly sequencing service registration, securing connectivity credentials, and ensuring site metadata synchronization, developers establish a high-performance environment where content is distributed as a global engine rather than remaining trapped in a local database.