Best practices and troubleshooting

Apply best practices to optimize your integration between Optimizely Content Management System (CMS) and Optimizely Graph. This article also covers troubleshooting techniques and configuration examples that help you keep content syncing efficient, secure, and reliable.

Best practices

Adopt the following practices across content modeling, performance, security, and monitoring to keep the integration healthy under production load.

Content modeling

Design content models that produce a clean GraphQL schema and predictable query performance. Apply the following practices when defining content types:

• Use meaningful content type names that translate well to GraphQL.
• Mark required fields appropriately for the Graph schema generation.
• Limit ContentArea nesting depth to prevent performance issues.
• Use appropriate property types to ensure accurate Graph representation.

Performance

Tune indexing and syncing to keep throughput high in environments with large content volumes. Apply the following practices:

• Configure batch sizes according to your content volume.
• Use content filtering to exclude unnecessary or temporary content.
• Monitor indexing delays and adjust batching parameters as needed.
• Implement health checks to confirm stable performance in production.

Security

Protect indexed data and prevent unauthorized access. Apply the following practices:

• Secure HMAC credentials in production environments.
• Use preview tokens to access unpublished content.
• Implement content filtering to exclude sensitive data from indexing.
• Rotate credentials regularly to strengthen security.

Monitoring

Maintain visibility into the integration so issues surface before they affect content delivery. Apply the following practices:

• Configure health checks for production monitoring.
• Monitor indexing performance, latency, and error rates.
• Implement alerting for syncing or indexing failures.

Common issues and solutions

Diagnose the most frequent integration issues with the patterns in this section. Each subsection lists the symptom, a diagnostic snippet, and the steps that resolve the problem.

Content not syncing

If content does not display in Optimizely Graph, check whether the content is excluded or whether event triggers fire incorrectly.

// Check if content is excluded
if (content is IExcludeFromSearch excludeFromSearch && excludeFromSearch.ExcludeFromSearch)
{
    // Content is explicitly excluded
}

// Verify content events are firing
var events = ServiceLocator.Current.GetInstance<IContentEvents>();
events.SavingContent += (sender, args) => 
{
    Logger.Information($"Saving content: {args.Content.Name}");
};

To resolve the issue:

• Confirm that the content type does not implement an exclusion interface (such as IExcludeFromSearch).
• Confirm that content events (for example, SavingContent, PublishedContent) are registered and firing.
• Review application logs for indexing-related warnings or errors.

Performance issues

If indexing or syncing slows down, adjust batching and parallelism settings to balance performance and resource usage.

// Monitor and tune indexing performance
services.AddContentGraph(options =>
{
    options.BufferedIndexingGracePeriod = 30000; // Increase batching delay (30 seconds)
    options.MaxBatchSize = 50; // Reduce batch size
    options.MaxDegreeOfParallelism = 2; // Reduce parallel processing
});

To resolve the issue:

• Increase batching intervals to reduce system load.
• Reduce maximum batch size or degree of parallelism when the system experiences memory or CPU pressure.
• Use production health checks to monitor indexing throughput and responsiveness.

Sync jobs

Automate indexing and health checks with the scheduled sync jobs in Optimizely Graph. Use these jobs to keep content current without manual intervention and to surface failures through retry behavior.

Basic schedule job settings

Define sync intervals and error-handling behavior for background jobs:

// Configure schedule job intervals
services.ConfigureScheduleJob(
    checkStatusInterval: TimeSpan.FromSeconds(10),      // Check status every 10 seconds
    checkStatusSleepOnFailure: TimeSpan.FromSeconds(5), // Wait 5 seconds on failure
    waitUntilFinalResult: true                          // Wait for completion
);

• checkStatusInterval – Defines how often the job checks sync status.
• checkStatusSleepOnFailure – Defines the retry delay after a failure.
• waitUntilFinalResult – Confirms the job completes before continuing other tasks.

Schedule job options

Control job timing through the QueryOptions configuration to align background work with your operational windows.

services.Configure<QueryOptions>(options =>
{
    options.ScheduleJob.WaitUntilFinalResult = true;
    options.ScheduleJob.CheckStatusInterval = TimeSpan.FromMinutes(1);
    options.ScheduleJob.CheckStatusSleepOnFailure = TimeSpan.FromSeconds(15);
});

This configuration maintains predictable sync intervals and provides control over retry and completion behavior.