What Graph does in CMS 13

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

Architectural pivot: Graph becomes the mandatory middleware and primary delivery vehicle for CMS 13.
Global Contracts: Standardized schemas like _Item allow universal querying without knowing specific class names.
Index Optimization: Granular control via PropertyIndexingMode ensures search performance by excluding non-searchable data.
Secure Preview: A JWT-based workflow enables real-time visual editing in headless setups by bypassing public caches.

Optimizely CMS 13 marks a fundamental shift in the building, management, and delivery of digital experiences. The traditional "in-process" standard—where templates queried the database directly via IContentLoader and search functioned as an optional sidecar service—has been replaced.

Optimizely Graph serves as the mandatory middleware positioned between content creation and consumption. It functions as the primary delivery vehicle, necessitating a "Graph-First" architectural approach for all CMS 13 implementations.

1. The Architectural Shift: Moving from Database to Graph Hub

In traditional CMS internal delivery, the application logic and the content store were unified. When a visitor requested a page, the CMS fetched data from SQL, executed rendering logic, and served HTML. While reliable, this tight coupling created complexities for headless delivery and multi-channel synchronization.

CMS 13 decouples these concerns into three distinct layers to provide enhanced flexibility and performance:

Indexing (The Push): During the "Inbound" phase, content authored in the CMS is immediately synchronized (pushed) to Optimizely Graph upon being saved or published.
Delivery (The Pull): During the "Outbound" phase, headless React/Next.js applications or hybrid ASP.NET Core pages "pull" the required content using GraphQL queries.
The Activation Glue: The AddContentGraph() extension method in the Startup.cs file is a requirement to activate synchronization agents and internal routing logic.

public void ConfigureServices(IServiceCollection services)
{
    // Required for CMS 13 integration.
    // Activates specialized CMS-Graph sync and routing logic.
    services.AddContentGraph();
}

2. Global Contract System

The Global Contract system is a core technical feature of Optimizely Graph. Synchronization occurs within a strictly defined schema that integrates "Global Search" capabilities directly into the platform.

The system maps custom content types to standardized schemas in the Graph rather than pushing raw database rows:

The _Item Contract: Serving as the "Universal Base," every piece of content inherits from this contract, allowing for a single query to find "all items" across a site.
_AssetItem and _ImageItem Contracts: These handle media entities, enabling queries for assets regardless of their storage location.

Optimizing the Index via Property Modes

Developers possess granular control over the weight of the search index. Not every property stored in the CMS needs to function as a filterable search property.

public class StandardPage : PageData
{
    [Display(Name = "SEO Title")]
    public virtual string SeoTitle { get; set; } // Default: Searchable & Filterable

    [GraphProperty(PropertyIndexingMode.OutputOnly)]
    public virtual XhtmlString LegalDisclaimer { get; set; } 
    // OutputOnly: Included in the JSON payload but excluded from the 'where' filter search index.
}

Performance Note

Managing property indexing with OutputOnly decreases the size of search indices, ensuring that where clause filters and faceted searches remain performant.

3. Delivery: Navigating the GraphQL API

Content delivery in CMS 13 is executed via GraphQL. This protocol allows applications to request the exact data required for a specific component in a single request, eliminating the traditional overhead of over-fetching or under-fetching.

Typed vs. Untyped Search Strategies

Typed Search: Primarily used by .NET developers, the SDK deserializes Graph results directly into C# content classes for full compile-time safety.
Untyped Search: Returns raw JSON (JsonElement). This is effective for highly dynamic frontends or when retrieving "external content" from outside the local assembly.

Delivery Query Structure

A standard query in CMS 13 leverages the metadata layer to isolate specific content types efficiently:

query GetMarketingPages {
  Content(
    where: { 
      _Metadata: { types: { eq: "StandardPage" } },
      Market: { eq: "US" } 
    }
  ) {
    items {
      Title
      MainBody
      Published
    }
  }
}

4. The Revolution in Preview: Live Preview Tokens

Providing a visual preview for editors in headless implementations has historically been a significant challenge. CMS 13 addresses this via a secure Preview Token workflow:

JWT Generation: The CMS generates a short-lived, encrypted JSON Web Token (JWT) when an editor enters the "Edit" view.
Iframe Routing: The editor UI loads the frontend application inside an iframe, appending the preview_token as a query string parameter.
The Cache Bypass: The frontend application captures the token and attaches it to the Authorization header as a Bearer token during Graph calls.

# Frontend request for DRAFT content using the secure token
curl --location 'https://cg.optimizely.com/content/v2' \
--header 'Authorization: Bearer [THE_PREVIEW_TOKEN]' \
--data '{"query": "{ ... }"}'

Technical Significance

This token instructs Optimizely Graph to bypass the public Content Delivery (CD) cache and retrieve the "Draft" or "Saved" version of the content specifically for the authorized editor session.

5. Transitioning to a Graph-First Mindset

Succeeding with CMS 13 requires a departure from direct SQL-based data retrieval. The role of the developer shifts toward building a Content API.

Design for Reusability: Content stored as contracts in the Graph can be consumed by websites, mobile apps, and third-party tools simultaneously.
Optimize for Search-as-Service: Every property added to a C# class must be evaluated for its specific role in the Graph index (Default vs. OutputOnly).

Conclusion

Optimizely Graph represents a significant evolution in the CMS developer experience. By shifting from an "in-process" delivery model to a cloud-native, GraphQL-based Hub, CMS 13 addresses the requirements of modern multi-channel delivery while maintaining the sophisticated editorial experience expected by users. Mastery of this module requires focus on indexing optimization, query precision, and secure preview configurations.