Install Content Graph

Install Optimizely.ContentGraph.CMS in your Optimizely Content Management System (CMS) site to synchronize 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

Prepare to configure Content Graph for your site

You can configure content Graph using a method that depends on the version of the .NET platform you are using. The process for both versions involves entering settings into configuration files. For that reason, you will need to gather the following information before beginning either procedure:

• 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 allows sending errors and warnings to the API Gateway. This data helps the support team investigate when something goes wrong. Defaults to true.

📘

Configuration does not have to be updated for a DXP site

The configuration for Content 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 its better to not include the configuration for the CMS site when deploying it to DXP through PaaS portal.

Configure the synchronization package settings in the .NET Framework

For earlier versions of the .NET platform, you can enter the settings into the web.config file in the  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"/>

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"
  }
}

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

If you want to customize CD API, see: https://docs.developers.optimizely.com/content-cloud/v1.5.0-content-delivery-api/docs/configuration and customize CD API as needed.

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

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

//other configurations for Content Delivery API

services.AddContentGraph(_configuration);

Ensure that the following CD options are set to true so those data related to site information are synchronized to Content Graph. Then you can query them through SiteDefinition content type.

services.ConfigureContentApiOptions(o =>
  {
    o.IncludeInternalContentRoots = true;
    o.IncludeSiteHosts = true;
    o.EnablePreviewFeatures = true;
    o.SetValidateTemplateForContentUrl(true);
  });

Configure whitelist contents

To determine which contents can be synchronized to Content Graph and prevent synchronizing content with sensitive data, add the Include section to the appsettings.json file or use configuration in startup.cs. A note here is that configuration in startup.cs would override appsettings.json.

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

   services.AddContentGraph(_configuration, 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 ContentIds array and the contents whose ancestor Ids exist in ContentIds array.
• ContentTypes – Array of contentType names (an array of strings) that synchronizes contents whose ContentTypes exist in the ContentTypes array.
• OnlySyncContentTypesInWhitelistToSchema – By default, content types are included in the ContentGraph 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

1. When ContentIds = [] and ContentTypes = [], contents are synchronized as normal.

2. When ContentIds = [] and ContentTypes != [], only the contents 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.

3. When ContentIds != [] and ContentTypes = [], two types of content can be synchronized:

   • Contents whose Ids exist in the ContentIds are synchronized.
   • Contents whose ancestor Ids exist in the ContentIds are synchronized.

     📘

     Note

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

4. When ContentIds != [] and ContentTypes != [], two types of content can be synchronized:

   • Contents whose Ids exist in the ContentIds and whose ContentTypeID matches in the ContentTypes or in the descendants that are inherited directly or indirectly from the ContentTypes are synchronized.
   • Contents whose ancestor Ids exist in the 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 Content 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 query directly 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 Content Graph. There are three options:

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