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 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 Optimizely Graph for your site
You can configure Optimizely 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 tohttps://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 totrue
.
Configuration does not have to be updated for a DXP site
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 it is 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 <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"/>
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
. Optimizely Graph depends on Content Delivery API, this is the minimum configuration.
If you want to customize Content Delivery API, see the configure Content Delivery API documentation and customize Content Delivery API as needed.
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);
Ensure that the following Content Delivery options are set to true so those data related to site information are synchronized to Optimizely Graph. Then you can query them through SiteDefinition
content type.
services.ConfigureContentApiOptions(o =>
{
o.IncludeInternalContentRoots = true;
o.IncludeSiteHosts = true;
//o.EnablePreviewFeatures = true;//optional
//o.SetValidateTemplateForContentUrl(true);//optional
});
- IncludeInternalContentRoots and IncludeSiteHosts: needed to sync information on content roots and site definitions to ContentGraph.
- EnablePreviewFeatures: set this to true if you want some beta features in ContentDelivery to be enabled for more data in ContentGraph.
- SetValidateTemplateForContentUrl: set this to true to only provide URLs for contents that has CMS templates, if not the URL will be null. This is optional.
Configure whitelist contents
To determine which contents can be synchronized to Optimizely 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
.
appsettings.json
"Optimizely": {
"ContentGraph": {
"Include": {
"ContentIds": [],
"ContentTypes": []
},
"OnlySyncContentTypesInWhitelistToSchema": false
}
}
startup.cs
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 inContentIds
array and the contents whose ancestor Ids exist inContentIds
array.ContentTypes
– Array of contentType names (an array of strings) that synchronizes contents whoseContentTypes
exist in theContentTypes
array.OnlySyncContentTypesInWhitelistToSchema
– By default, content types are included in the Optimizely Graph GraphQL schema. If you want only the content types listed inInclude.ContentTypes
to be in the GraphQL schema, setOnlySyncContentTypesInWhitelistToSchema
to true.
Configuration options rules
-
When
ContentIds = []
andContentTypes = []
, contents are synchronized as normal. -
When
ContentIds = []
andContentTypes != []
, only the contentswhose 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. -
When
ContentIds != []
andContentTypes = []
, 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.
- Contents
-
When
ContentIds != []
andContentTypes != []
, two types of content can be synchronized:- Contents
whose Ids exist in the ContentIds
andwhose 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
andwhose ContentTypeID matches in the ContentTypes or in the descendants that are inherited directly or indirectly from the ContentTypes
are synchronized.
- Contents
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 query directly the content types that exist in the
ContentTypes
array and their descendants that are inherited directly or indirectly from theContentTypes
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 synchronize the published content and draft content.PublishedOnly
– To synchronize only the published content.All
– To synchronize all status version content.
Configure resynchronization of referencing contents
When a content is referenced by many other contents, either by ContentLink
, ContentReferece
, LinkItem
or ContentArea
, if the content is modified other referencing contents 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 very 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;
});
Updated 10 days ago