Best practices and troubleshooting

Apply best practices for optimizing your integration between Optimizely Content Management System (CMS) and Optimizely Graph. Includes troubleshooting techniques and configuration examples to ensure efficient, secure, and reliable content synchronization.

Best practices

Content modeling

Follow these practices when designing content models to improve performance and maintain a clean GraphQL schema:

• 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

Optimize indexing and synchronization to maintain efficient operations in high-volume environments:

• 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 ensure stable performance in production.

Security

Protect data and prevent unauthorized access by following these 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 enhance security.

Monitoring

Establish monitoring and alerting to maintain visibility and ensure system reliability.

• Set up health checks for production monitoring.
• Monitor indexing performance, latency, and error rates.
• Implement alerting for synchronization or indexing failures.

Common issues and solutions

Content not synchronizing

If content does not appear in Optimizely Graph, verify whether it is excluded or if event triggers are not firing correctly.

// 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:

• Ensure 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 synchronization 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:

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

Synchronization jobs

Optimizely Graph provides scheduled synchronization jobs to manage indexing and health checks automatically.

Basic schedule job settings

Define synchronization 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 synchronization status.
• checkStatusSleepOnFailure – Defines the retry delay after a failure.
• waitUntilFinalResult – Ensures the job completes before continuing other tasks.

Schedule job options

Control job timing through the QueryOptions configuration.

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

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