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 syncing.

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 syncing 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 syncing or indexing failures.

Common issues and solutions

Content not syncing

If content does not display in Optimizely Graph, verify if 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 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:

• 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.

Sync jobs

Optimizely Graph provides scheduled sync jobs to automate indexing and health checks.

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 – 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 sync intervals and provides control over retry and completion behavior.