Integrate Optimizely Graph

Get started with Optimizely Graph

Add the following to your startup file to activate the content graph integration:

services.AddContentGraph()

📘

Note

.NET SDK is not included for Optimizely Graph for the preview.

Added an SDK to support developers migrating applications from Optimizely Search & Navigation to Optimizely Graph in CMS 13.

• Content search modes
  • Content search – Compile-time type safety on filters, loads data from CMS through IContentLoader, and returns IContent instances, honoring shared content permissions and URLs.
  • Untyped search – Acceptance of type and fragments as strings, returning lists of raw JsonElement without compile-time type safety.
  • Typed search – Deserialization of responses to provided contracts, offering compile-time type safety on filters for global search pages and advanced external content listings.
• Search functionality
  • Full-text search across modes with highlighted search terms.
  • Support for filters, operators, and logical connectors is available in Optimizely Graph, including fuzzy matching and definition of filters through extension methods.
  • Locale and IDs arguments.
  • Sorting capabilities, including semantic sorting, and pagination with cursor support.
  • Autocomplete, variations, facets, and boosting.
• Security and performance
  • Integrated tracking, honoring "Do not track" settings.
  • Authentication using a single key by default, with opt-in HMAC.
  • Authorization through FilterForVisitor with IPrincipal and Locale arguments, and an option to include deleted documents.
  • Metrics, including built-in metrics for HttpClient.
  • Observability and query categorization.
  • Optional caching.
  • Pinned results.
• Documentation – Documents Optimizely Search & Navigation SDK features that are not supported, along with guidance on achieving similar results using the new SDK and Optimizely Graph, or noting when an upgrade path is not available.

📘

Note

The SDK does not include a full LINQ provider, direct support for links (recommending IContentLoader.GetAncestors()), recursive directives (recommending IContentLoader.Get()), routing (recommending IUrlResolver.Route() and ContentLoader.Get()), single document retrieval by ID, filtering on the current site, or multi-search.

Execute query and load CMS content

Execute queries against the Optimizely Graph API, deserialize the responses, and load corresponding CMS content.

• Execute queries against the Graph API.
• Deserialization of Graph API responses.
• Load and return CMS content based on the deserialized Graph data.

Integration for unpublished content preview

Enable authenticated editors to preview unpublished content within the context of their headless application through Optimizely Graph integration. Implemented the ability for authenticated editors to preview unpublished content. Preview unpublished content through Optimizely Graph

Preview token appending for unpublished content

Append a preview token to URLs for unpublished content, enhancing preview functionality in Edit view and Visual Builder, including considerations for rows and columns.

• Use UrlResolverArguments.AppendPreviewToken for UrlResolver.
• Preview URLs constructed for window.postMessage() events in communicationInjector.js include the preview token.
• Optionally control whether the preview token is appended.

External content integration

📘

Note

Not enabled in this preview version

Added a content provider integration pattern that lets you connect external content sources to CMS, starting with Optimizely Graph. This enables content editors to reuse external content items when composing content.

• Developers using Optimizely Graph sources can select specific content items for surfacing in CMS UI.
• Developers can restrict the usage of Optimizely Graph-surfaced content items, consistent with internal content item restrictions.
• Content creators in CMS can select developer-surfaced content items when composing pages, experiences, or blocks.
• Content creators have clear visual indicators to identify external content items and navigate to their original source URL when provided.

Surface an external content source in CMS UI

As a content provider integration pattern, you can connect external content sources, specifically Optimizely Graph, to the CMS. This enables content editors to reuse external content items.

• Developers can select specific content types from Optimizely Graph to be surfaced in the CMS UI.
• Content creators can select these surfaced external content items when composing pages, experiences, or blocks.
• Updates to referenced external content items at their origin are automatically reflected in the CMS.
• Developers must query content items directly when they contain externally referenced items.
• Content creators do not see properties of referenced external items because external content items in CMS do not inherit properties from their source.
• Content creators have a clear indication when an item is external and, if configured, a URL to its original source.

Shadow content type creation for external sources

Phase 1

You can create "shadow" content types in the CMS when selecting a content type from an external content source. This feature is designed to facilitate integrations like the DAM asset-picker.

• You can specify a base type for the shadow content type (e.g., Image).
• Content types are hidden from the CMS UI and the CMS Management API.
• Prevented shadow content types from being indexed to Graph.
• Implemented a naming convention for external content types (e.g., graph:{ContentSourceModel.SourceType}) to avoid conflicts with existing CMS content types.
• Added a metadata property on content types to indicate their source.
• Defined mappings to resolve Id and Name properties from the external type.
• Set the source for created shadow types to the internal graph source format.

Phase 2

Enhanced the creation of "shadow" content types in the CMS for external content sources, completing the functionality for integrating external content.

• You can specify a base type for shadow content types (for example, Image).
• Shadow content types are read-only in both the Admin UI and the CMS Management API.
• Prevented shadow content types from being indexed to Graph.
• Source field to distinguishes external content types from standard CMS content types.
• Implemented a naming convention for external content types, prefixing them with Graph:, to prevent conflicts with existing CMS content types.
• Automated the creation of properties by introspecting the schema of the external type in Optimizely Graph.
• Enabled the creation of additional shadow content types by the CMS when external source properties are complex objects.

Content type binding API

Added an API for developers to create bindings between existing content types in CMS, reducing content duplication for both internal and external content.

• Map properties between two existing content types, including nested block properties.
• You can map only properties of the same type.
• Provided full CRUD (Create, Read, Update, Delete) capabilities for content type bindings.
• View a list of existing content type mappings.
• You can update existing mappings, with changes applied to all instances of that content type binding.
• You can import and export content mappings.

Manage content type binding

Manage content type bindings, accessible behind a feature flag. This UI lets administrators view, edit, delete, and create content type mappings directly.

• Mappings is in the left-hand menu when editing a content type.
• Displays a list of available content type mappings.
• Sorts mappings to show those with the current content type as the source first, followed by those where it is the destination, both ordered alphabetically.
• You can edit and delete mappings in the list. Provides notifications about instances using a mapping when attempting to edit or delete it.
• Search functionality for mappings by source and destination type.
• You can create mappings through a dialog box, where the currently edited content type remains read-only during source and destination selection.

Manage content type binding configuration UI

You can create and update mappings between content types and contracts.

• Administrators can create and update property mappings between two existing content types or contracts.
• The source type displays on the left and the target type on the right during mapping configuration.
• Target type properties display as read-only and in their correct order.
• A dropdown for each target property selects a matching property from the source type.
• Indicated when no matching property is found for a target property.
• You can map a target property to a scalar property nested one level deep within a block on the source type.
• Made property mappings optional, except for those configured as IsRequired on the target type.
• Notifications alert administrators if a mapping is in use before deletion, requiring removal of prior usage prior to proceeding with deletion.

Content instance binding API

Developers can create bindings between existing content instances, reducing content duplication for internal and external content. This functionality is controlled by the Content Binding API feature flag.

• Developers can define a binding from one IContentData instance to another, provided a pre-defined binding exists between their content types.
• Each IContentData instance contains only one binding at each level, supporting binding on content levels, including block properties and inline blocks.
• Stored bindings define the specific content and language to which an instance is bound.
• Developers can retrieve lists of "to" (items a content is bound to) and "from" (items bound to an item) relations.
• Developers can delete a binding between IContentData instances.
• When a content instance that is part of a binding is deleted, the binding is also deleted.
• Developers can define a binding between IContentData instances of the same type without requiring a pre-defined content type binding.

Connect content for block property

You can bind block properties within the Visual Builder Edit view. You can connect properties of a block to a content source, similar to content binding.

• Enabled binding of block properties when editing content in the Visual Builder.

Limitations

• Block property binding is available exclusively in the Visual Builder and not in Forms editing.
• This feature is currently limited to the first level of content (pages or shared blocks). It does not support scenarios involving block properties within content areas, inline blocks, lists of blocks with nested blocks, or multiple levels of nested block properties.
• Blocks used as sections that contain block properties do not support binding.

Bind block in Visual Builder Edit view

You can connect content sources to blocks within the Visual Builder edit view, enabling data binding for both CMS-created and external content.

• A "link" badge next to the title of block properties and blocks in content areas indicates if they are data-bound. This badge is visible in the content area item and when the block is opened in quick edit.
• Connect content option to the context menu of unbound blocks opens the Content Manager picker filtered to show only content types with a configured mapping for the current block type.
• Added Replace and Disconnect options in the context menu for already bound blocks. Replace reopens the filtered Content Manager picker, and Disconnect removes the current connection.
• Properties of a data-bound block, as defined by the mapping, are read-only. Other properties remain editable.
• Automatic updates occur for read-only properties when the mapping is modified, with connected values overriding any local values.

Manage content sources in the admin UI

Optimizely Graph now supports global contract indexing for CMS content, enabling consistent searching, filtering, and aggregation across CMS and external sources. This involves creating and provisioning Global Contracts in Optimizely Graph during CMS synchronization and application startup, with these contracts also provided as .NET classes for deserializing Optimizely Graph results. Various CMS content types, such as experience, page, section, block, media, and image instances, are indexed according to specific inherited contracts like _Item, _AssetItem, and _ImageItem, ensuring their _Metadata type field aligns with the schema name or concrete type in Optimizely Graph.

Global contract indexing

You can index CMS content to Optimizely Graph using Global Contracts to enable consistent searching, filtering, and aggregation of CMS and external content sources.

• Global Contracts are created in Optimizely Graph during synchronization from CMS.
• Implemented provisioning of contracts by CMS and re-indexing of schemas and content from CMS on application startup if contracts do not exist.
• Global contracts as .NET classes deserialize results from Graph.
• Configured the Content schema to inherit the Item contract.
• Indexed experience, page, section, and block instances according to the Item contract.
• Configured the Media schema to inherit the AssetItem contract.
• Indexed media instances according to the Item, AssetItem, and ImageItem contracts.
• Configured the Image schema to inherit the ImageItem contract.
• Indexed image instances according to the Item, AssetItem, and ImageItem contracts.
• The type field in Metadata corresponds to the Schema Name or concrete type of the instance in Optimizely Graph.

Enhanced indexing process reporting

Added improvements to the indexing process, providing more detailed reporting and error handling.

• Added exception details to the output for better debugging.
• Ensured that any failed steps are identified before returning a summary.
• Introduced a custom exception type for failed summaries.
• Grouped content type warnings by unique message.
• Enhanced journal collection steps with detailed metrics, including total journals, succeeded, queued, and failed counts.

Improve UI when connecting nested inline block

You can manage content bindings within inline blocks in the Visual Builder.

• You can save content binding changes alongside other property values within inline block dialogs.
• Save is active when a binding is modified, providing clear feedback that changes can be committed.
• You can cancel an inline block dialog, confidently discarding any binding changes made during that session.

Optimized sync to Optimizely Graph

You can improve the speed of full synchronizations to Optimizely Graph for large datasets in CMS PaaS and CMS (SaaS).

• You can prevent CMS from sending content to Optimizely Graph that is already up-to-date, leveraging document hash values.
• Improvements are applied to CMS PaaS and CMS (SaaS).
• Optimizely calculates document hashes with regard to the Conventions API and available extension points for the CMS PaaS.

Optimized media content extraction

Optimized the extraction of searchable text from media content by performing the process during file upload rather than during indexing.

• The system extracts media content during file upload (create/update).
• A job that updates existing assets on a schedule.
• Continued use of existing media content that the system caches and extracts for existing assets.
• Extraction that occurs when you publish a media version.