Synchronizing external content

By Optimizely Education
Published: Mar 5, 2026
Rating 1 star 2 stars 3 stars 4 stars 5 stars

Average rating: 0 No reviews

Outline

At a glance:

Purpose: The IContentProvider interface allows Optimizely CMS 12 to expose external data sources as if they were native CMS content.
Architecture: Instead of duplicating content into the CMS database, the provider virtualizes external data and loads it on demand.
Key implementation: Developers extend EPiServer.Core.ContentProvider and implement methods such as LoadContent and LoadChildrenReferences.
Integration model: External systems remain the source of truth while Optimizely handles presentation, routing, and editor visibility.
Important limitation: Content from custom providers is not automatically indexed by native CMS search.

Introduction

In Optimizely CMS 12, integrating external content sources is a common requirement in enterprise architectures. Organizations frequently maintain structured content in external systems such as product information management platforms, digital asset systems, or third-party editorial services.

The IContentProvider interface enables developers to integrate such systems directly into the Optimizely content tree. Rather than duplicating external data into the CMS database, this approach exposes content through a virtualized representation.

Within this model, Optimizely CMS interacts with the external system through a custom provider implementation. The CMS treats the external data as standard IContent instances (such as PageData or BlockData) even though the underlying data continues to reside in the external system.

This design reduces data duplication, preserves a single source of truth, and allows external systems to remain authoritative while still enabling editors and front-end components to consume the content through the CMS.

1. The role of IContentProvider in synchronization

A custom IContentProvider functions as a bridge between Optimizely CMS and an external data source. The provider exposes content items from an external system so that they appear within the CMS hierarchy alongside native pages and blocks.

Internally, Optimizely uses the DefaultContentProvider to manage content stored in its database. Custom providers extend this architecture by supplying additional content sources that the CMS can query when resolving content requests.

When the CMS requests content from a provider:

The CMS generates a ContentReference.
The provider interprets the reference and resolves it to an external data record.
The provider converts the external data into a valid IContent instance.
The CMS renders the content as if it were native.

This approach creates a seamless experience for editors and visitors while preserving external system ownership of the data.

2. Implementing a custom ContentProvider

To expose external content within Optimizely, developers implement a custom provider by inheriting from EPiServer.Core.ContentProvider. This class defines the integration logic between the CMS and the external system.

Key implementation steps

Inheritance - Create a new class that extends EPiServer.Core.ContentProvider. This allows the CMS to treat your provider as part of its content resolution pipeline.
Implementing LoadContent - The most critical implementation point. It retrieves an external data record and maps it to an Optimizely content instance.
Handling hierarchy - Methods such as LoadChildrenReferences determine how content appears in the CMS page tree and allow hierarchical navigation of external content structures.
Supporting routing and permanent links - Methods like GetContentLink and ResolveContent map URLs and GUIDs to provider-based content references.

Example ContentProvider structure

using EPiServer.Core;
using EPiServer.DataAbstraction;
using EPiServer.DataAbstraction.Internal;
using EPiServer.Framework.Localization;
using EPiServer.ServiceLocation;
using EPiServer.Web;
using System;
using System.Collections.Generic;
using System.Globalization;
using EPiServer.Configuration;

// Assuming ExternalApiService and ExternalArticlePage are defined elsewhere

[ContentProvider]
public class ExternalArticleContentProvider : ContentProvider
{
    private readonly ExternalApiService _externalApiService;
    private readonly IContentTypeRepository _contentTypeRepository;
    private readonly ServiceAccessor<ContentOptions> _contentOptionsAccessor;

    public ExternalArticleContentProvider(
        ExternalApiService externalApiService,
        IContentTypeRepository contentTypeRepository,
        ServiceAccessor<ContentOptions> contentOptionsAccessor)
    {
        _externalApiService = externalApiService;
        _contentTypeRepository = contentTypeRepository;
        _contentOptionsAccessor = contentOptionsAccessor;
    }

    public override ContentReference GetContentLink(Uri url)
    {
        var segments = url.Segments;
        if (segments.Length >= 2 && segments[1].Trim('/').Equals("external-articles", StringComparison.OrdinalIgnoreCase))
        {
            var externalId = segments[2].Trim('/').Split('/')[0];
            var contentType = _contentTypeRepository.Load<ExternalArticlePage>();
            if (contentType != null)
            {
                return new ContentReference(0, externalId, ProviderKey);
            }
        }
        return ContentReference.EmptyReference;
    }

    protected override IContent LoadContent(ContentReference contentLink, LanguageSelector selector)
    {
        if (!contentLink.ProviderValue.IsNullOrEmpty())
        {
            var externalId = contentLink.ProviderValue;
            var externalData = _externalApiService.GetArticleById(externalId);

            if (externalData != null)
            {
                var externalArticlePageType = _contentTypeRepository.Load<ExternalArticlePage>();
                if (externalArticlePageType == null) return null;

                var page = CreateContent<ExternalArticlePage>(contentLink);
                page.ExternalTitle = externalData.Title;
                page.ExternalBody = new XhtmlString(externalData.BodyHtml);
                page.ExternalId = externalData.Id;
                page.ExternalUrl = externalData.Url;
                page.Name = externalData.Title;
                page.ContentGuid = GetContentGuid(externalId);
                page.ParentLink = contentLink.ParentLink.IsSet ? contentLink.ParentLink : GetEntryPoint();
                page.ContentTypeID = externalArticlePageType.ID;
                page.Status = VersionStatus.Published;
                page.StartPublish = DateTime.MinValue;
                page.StopPublish = DateTime.MaxValue;
                page.IsDeleted = false;
                page.Created = externalData.CreatedDate;
                page.Changed = externalData.ModifiedDate;
                page.Language = selector.Language.Name;
                if (!string.IsNullOrEmpty(externalData.Language))
                {
                    page.MasterLanguage = new CultureInfo(externalData.Language);
                }
                return page;
            }
        }
        return null;
    }
}

3. Defining content types for external data

Custom Optimizely content types define the structure used to represent external data inside the CMS. These types inherit from PageData, BlockData, or MediaData.

using EPiServer.Core;
using EPiServer.DataAnnotations;
using System.ComponentModel.DataAnnotations;

[ContentType(
    DisplayName = "External Article Page",
    GUID = "A2FF8C8B-1E5A-4B6A-B6A0-142B28B3EF4A",
    Description = "Represents an article fetched from an external source.",
    AvailableInEditMode = false
)]
public class ExternalArticlePage : PageData
{
    [CultureSpecific]
    public virtual string ExternalTitle { get; set; }

    [CultureSpecific]
    public virtual XhtmlString ExternalBody { get; set; }

    public virtual string ExternalId { get; set; }

    public virtual Url ExternalUrl { get; set; }
}

4. Data mapping and transformation

Direct mapping ▼

Primitive fields such as strings, numbers, and booleans can be mapped directly from the external data record to the corresponding content type property.

Rich content transformation ▼

External HTML content should be converted to XhtmlString to integrate correctly with Optimizely rendering pipelines.

Stable GUID generation ▼

Each external item must produce a deterministic ContentGuid. Without stable GUIDs, search indexing, permanent links, and caching may behave inconsistently.

5. Handling updates and persistence

Read-only by default ▼

Most providers expose content purely for display. The external system remains the authoritative source and no write operations are performed by the CMS.

Write-back operations ▼

If Create, Edit, or Delete capabilities are enabled, the CMS can push updates back to the external system through the provider implementation.

External change detection ▼

Scheduled jobs or webhooks are often used to invalidate caches and refresh provider content when the external system changes, ensuring the CMS reflects up-to-date data.

Full replication strategy ▼

When versioning, workflow, or relational data are required, developers often implement scheduled synchronization jobs using IContentRepository to replicate content natively into the CMS database.

6. Best practices

Performance optimization ▼

External APIs are slower than CMS database queries. Implement caching layers using IMemoryCache or IDistributedCache to reduce latency and protect against API failures under load.

Error resilience ▼

External dependencies may fail. Defensive coding and graceful fallback handling are essential inside LoadContent to prevent provider failures from surfacing as CMS errors.

Search limitations ▼

Content from custom providers is not automatically indexed by Optimizely's native search engine. If search coverage is required, a separate indexing strategy must be implemented for provider-sourced content.

Security integration ▼

External content can inherit permissions from its entry point or implement ISecurable for custom access control lists scoped to individual provider items.

Editor experience ▼

Ensure meaningful content type metadata and hierarchy implementation to provide a seamless editing experience. Editors should be able to navigate and interact with external content naturally within the CMS tree.

Conclusion

The IContentProvider pattern provides a robust mechanism for integrating external content systems with Optimizely CMS 12. By virtualizing external content rather than duplicating it, organizations can maintain a single source of truth while still leveraging the CMS for presentation, navigation, and editorial workflows.

When implemented correctly - with careful attention to caching, GUID generation, and provider capabilities - custom content providers enable scalable enterprise architectures that combine multiple content systems into a unified delivery platform.

End-user eLearning

Upcoming events

Certification

Partner training

Community

All Topics