HomeDev guideRecipesAPI ReferenceGraphQL
Dev guideUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Install and configure Optimizely Graph

Describes how to install and configure content synchronization as part of the Optimizely Graph service.

Install Optimizely Graph

Install Optimizely.ContentGraph.CMS in your Optimizely Content Management System (CMS) site to sync content types and content. In Visual Studio, go to Tools > Nuget Package Manager > Package Manager Console. At the console, enter install-package Optimizely.ContentGraph.Cms.

📘

Note

Optimizely supports packages for ASP.NET with the package versions >= 2.0.

Configure Optimizely Graph for your site

Depending on your version of .NET, there are different methods to configure Optimizely Graph. The process for the different versions involves entering settings into configuration files. For that reason, gather the following information before beginning:

  • GatewayAddress – URL for the API gateway. This value should be set to https://cg.optimizely.com for all production environments.
  • AppKey – Sent to you when the account was created, is the public key from your HMAC authentication pair.
  • Secret – Sent to you when the account was created, is the secret key from your HMAC authentication pair.
  • SingleKey – Sent to you when the account was created, is the public key which you can use on the public site.
  • AllowSendingLog – Flag that lets you send errors and warnings to the API gateway. This data helps the Support team investigate when something goes wrong. Defaults to true.

📘

Note

The configuration for Optimizely Graph is only needed when working with the CMS site locally. The configuration is already set in the Optimizely Digital Experience Platform (DXP) site, so do not include the configuration for the CMS site when deploying it to DXP through the PaaS portal.

Configure the synchronization package settings in the .NET Framework

For newer versions of the .NET platform, you can enter the settings into the web.config file in the <appSettings> section:

<add key="optimizely__contentgraph__gatewayaddress" value="" />
<add key="optimizely__contentgraph__appkey" value="" />
<add key="optimizely__contentgraph__secret" value="" />
<add key="optimizely__contentgraph__singlekey" value="" />
<add key="optimizely__contentgraph__allowsendinglog" value="true"/>

The older settings format is still supported, but is deprecated:

<add key="optimizely:gatewayaddress" value="" />
<add key="optimizely:query.appkey" value="" />
<add key="optimizely:query.secret" value="" />
<add key="optimizely:query.singlekey" value="" />
<add key="optimizely:allowsendinglog" value="true"/>

Configure the synchronization package settings in ASP.NET Core

Open appsettings.json and add your settings to configure your account.

"Optimizely": {
  "ContentGraph": {
    "GatewayAddress": "",
    "AppKey": "",
    "Secret": "",
    "SingleKey": "",
    "AllowSendingLog": "true"
  }
}

If you do not use the Content Delivery API in your CMS site, add the following to the ConfigureServices(IServiceCollection services) method of Startup.cs. Optimizely Graph depends on the Content Delivery API, and this is the minimum configuration.

If you want to customize Content Delivery API, see the configure Content Delivery API documentation.

services.ConfigureContentApiOptions(o =>
  {
    o.IncludeInternalContentRoots = true;
    o.IncludeSiteHosts = true;
    //o.EnablePreviewFeatures = true;// optional
  });
services.AddContentDeliveryApi(); // required, for further configurations, see https://docs.developers.optimizely.com/content-cloud/v1.5.0-content-delivery-api/docs/configuration
services.AddContentGraph();

//the following is obsolete and is kept for compatibility for now
//services.AddContentGraph(_configuration);

If you are already using Content Delivery API in your application, you only need to add an additional line to register Optimizely Graph services:

//other configurations for Content Delivery API

services.AddContentGraph();

//the following is obsolete and is kept for compatibility for now
//services.AddContentGraph(_configuration);

Set the Content Delivery options to true for the data related to site information to be synchronized to Optimizely Graph. Then you can query them through the SiteDefinition content type:

services.ConfigureContentApiOptions(o =>
  {
    o.IncludeInternalContentRoots = true;
    o.IncludeSiteHosts = true;
    //o.EnablePreviewFeatures = true;//optional
    //o.SetValidateTemplateForContentUrl(true);//optional
  });
  • IncludeInternalContentRoots and IncludeSiteHosts –Set to true to sync information on content roots and site definitions to Optimizely Graph.
  • EnablePreviewFeatures – Set to true if you want beta features in Content Delivery to be enabled for more data in Optimizely Graph.
  • SetValidateTemplateForContentUrl (Optional) – Set to true to only provide URLs for content that has CMS templates. If not, the URL is null.

Include inheritance

To get results from inherited types when querying a content type, include inheritance in the ContentType list. To enable this, set IncludeInheritanceInContentType to true:

services.AddContentGraph(configureOptions: options =>
{
    options.IncludeInheritanceInContentType = true;
});

Enable extract media type

To enable extracting data from the content media type, set ExtractMedia to true. Defaults to true:

services.AddContentGraph(configureOptions: options =>
{
    options.ExtractMedia = false;
});

Configure allowlist contents

To set what content can be synchronized to Optimizely Graph and prevent synchronizing content with sensitive data, add the Include section to the appsettings.json file or use the configuration in startup.cs.

📘

Note

Configuration set in startup.cs would override appsettings.json.

appsettings.json:

"Optimizely": {
  "ContentGraph": {
    "Include": {
      "ContentIds": [],
      "ContentTypes": []
    },
    "OnlySyncContentTypesInWhitelistToSchema": false
  }
}

startup.cs:

services.AddContentGraph(configureOptions: options =>
 {
   options.Include.ContentIds = new int[3] { 1, 2, 3 };
   options.Include.ContentTypes = new string[2] { typeof(StandardPage).Name, typeof(ProductPage).Name };
 });
  • ContentIds – Array of content Ids (an array of integers) that synchronizes contents whose Ids exist in the ContentIds array and the contents whose ancestor Ids exist in the ContentIds array.
  • ContentTypes – Array of contentType names (an array of strings) that synchronizes content whose ContentTypes exist in the ContentTypes array.
  • OnlySyncContentTypesInWhitelistToSchema – By default, content types are included in the Optimizely Graph GraphQL schema. If you want only the content types listed in Include.ContentTypes to be in the GraphQL schema, set OnlySyncContentTypesInWhitelistToSchema to true.

Configuration options rules

  • ContentIds = [] and ContentTypes = [] – Content is synchronized as normal.
  • ContentIds = [] and ContentTypes != [] – Only the content whose ContentTypeID matches in the ContentTypes or in the descendants that are inherited directly or indirectly from the ContentTypes are synchronized.

    📘

    Note

    If the values in ContentTypes do not exist in Optimizely Content Management System (CMS), you cannot synchronize content.

  • ContentIds != [] and ContentTypes = [] – Two types of content can be synchronized:
    • Content whose Ids exist in ContentIds are synchronized.
    • Content whose ancestor Ids exist in ContentIds are synchronized.

      📘

      Note

      If no content exists in ContentIds, you cannot synchronize content.

  • ContentIds != [] and ContentTypes != [] – Two types of content can be synchronized:
    • Content whose Ids exist in ContentIds and whose ContentTypeID matches in the ContentTypes or in the descendants that are inherited directly or indirectly from the ContentTypes are synchronized.
    • Content whose ancestor Ids exist in ContentIds and whose ContentTypeID matches in the ContentTypes or in the descendants that are inherited directly or indirectly from the ContentTypes are synchronized.

📘

Note

  • When content is synchronized, language versions of that content is available in Optimizely Graph.
  • Content (that is linked to synchronized content) is synchronized within that synchronized content, regardless of any whitelist conditions that otherwise apply.
  • When querying contents in GraphiQL, you can only directly query the content types that exist in the ContentTypes array and their descendants that are inherited directly or indirectly from the ContentTypes array.

Configure sync version contents

"Optimizely": {
    "ContentGraph": {
       "ContentVersionSyncMode": "DraftAndPublishedOnly"
    }
}

To determine which version contents can be synchronized to Optimizely Graph, you have the following options:

  • DraftAndPublishedOnly (Default) – To sync the published content and draft content.
  • PublishedOnly – To sync only the published content.
  • All – To sync all status version content.

Configure resynchronization of referencing contents

When content is referenced by other content using ContentLink, ContentReference, LinkItem or ContentArea, if the content is modified, other referencing content can be resynchronized to Optimizely Graph.

To enable this, set SyncReferencingContents to true in appsettings.json. The default value is false.

If the number of referencing contents is large, resynchronization can take a long time after the related content is updated. You should set the setting to false and wait for the next time the Optimizely Graph synchronization scheduled job runs again instead.

"Optimizely": {
    "ContentGraph": {
       "SyncReferencingContents": "false"
    }
}

Configure synchronization of content type when the site starts

Open Startup.cs and add:

services.Configure<EventIndexingOptions>(ops => 
{
  ops.SyncContentTypesOnInit = true;
});

Configure to enable preview tokens for On-page editing (OPE) feature

When calling AddContentGraph, you can enable preview tokens for OPE feature by setting EnablePreviewTokens to true.

You can also set the OnGeneratingPreviewUrl event to customize your content preview URL before the preview token is added as a query string parameter.

You can enable preview tokens in your Program.cs,Startup.cs, or appsettings.json.

For more details on OPE, refer to On-page editing and Optimizely Graph.

services.AddContentGraph(options =>
{
	options.EnablePreviewTokens = true;

  options.Events.OnGeneratingPreviewUrl = ctx =>
  {
    // ctx.UpdateUrl(new Uri("/test?id=" + ctx.ContentReference, UriKind.RelativeOrAbsolute));
    return Task.CompletedTask;
  };
});
"Optimizely": {
    "ContentGraph": {
       "EnablePreviewTokens": "true"
    }
}

Configure the format for XhtmlString

You can get rich text stored in XhtmlStringin a different structured delivery format than just a raw HTML string.

By default XhtmlString is returned as a single string containing the raw HTML:

services.Configure<ContentApiOptions>(op =>
{
    op.RichTextFormat = RichTextFormat.Html;
});

Optimizely Graph query:

 StandardPage {
    items {
      Name,
      MainBody 
   }
}

Response example:

 "MainBody": "<p><strong>The weather is very nice !</strong></p>"

To return XhtmlStringas structured HTML:

services.Configure<ContentApiOptions>(op =>
{
    op.RichTextFormat = RichTextFormat.Structured;
});

Optimizely Graph query:

 StandardPage {
    items {
      Name,
      MainBody {
         Structure
      }
   }
}

Response example:

  "MainBody": {
    "Structure": "{\"type\":\"richText\",\"children\":[{\"type\":\"paragraph\",\"children\":[{\"text\":\"The weather is very nice !\",\"bold\":true}]}]}"
  }

You can return both the raw HTML and the structured HTML:

services.Configure<ContentApiOptions>(op =>
{
    op.RichTextFormat = RichTextFormat.HtmlAndStructured;
});

Optimizely Graph query:

 StandardPage {
    items {
      Name,
      MainBody {
         Structure
         Html
      }
   }
}

Response example:

  "MainBody": {
    "Structure": "{\"type\":\"richText\",\"children\":[{\"type\":\"paragraph\",\"children\":[{\"text\":\"The weather is very nice !\",\"bold\":true}]}]}",
    "Html": "<p><strong>The weather is very nice !</strong></p>"
  }

📘

Note

  • Changing the configuration of ContentApiOptions.RichTextFormat requires you to re-run the synchronization job.
  • The HTML elements that Optimizely has seen a mapping for are mapped, but HTML elements that Optimizely has not seen a mapping for are returned unmapped (the HTML element name).