Content sync configuration

Content synchronization allows users to easily transfer content from one instance of Xperience by Kentico to another.

The purpose of content sync is to help manage content when using multiple environments. For example, a project’s developers may have a local Development instance, from which initial content is sent to a hosted Staging instance. The staging instance is accessible only by editors and other staff, who use it to prepare content updates. The final content is then synchronized during regular releases to a public-facing Production instance.

This page describes how to set up and configure your applications to use content sync:

1. Learn about the supported environment topologies
2. Set up content sync connections between environments:
   • Local environments and private cloud deployments
   • SaaS deployment environments
3. Configure Xperience features and data for content sync

To learn how to synchronize content, see Content sync.

Supported topologies

Before you start setting up content sync, it is important to understand which environment topologies are supported.

The most basic usage of content sync consists of a connection between one source instance and one target instance. Such connections can be chained to additional instances – a target can be configured as the source for another instance. However, only strictly linear topologies are supported. For example:

Development → QA → Staging → Production

More complex topologies, for example with multiple branching target connections, loops, or bi-directional connections are not supported. The system does not strictly block content sync with unsupported topologies, but it may result in inconsistencies, errors or unintentionally overwritten content.

Set up content sync

Prerequisites

• Instances connected via content sync must use exactly the same version of Xperience (including the hotfix version).
• Target instances must run on HTTPS with a valid trusted certificate.
• If using auto-scaling for a private cloud project with content sync, the ~/assets folder must be mapped to a shared storage location, such as Azure Blob Storage or Amazon S3.

Source and target configuration

To set up an application as the source or target in a content sync connection, configure ContentSynchronizationOptions using the .NET options pattern (available in the CMS.ContentSynchronization namespace).

The options are separated into Source and Target configuration. The following properties must be configured:

• Enabled – a bool value that enables the application as a source or target for content sync.
• Secret – a secret key containing at least 32 characters. The same secret must be configured for the source and target applications.
• TargetUrl – only available for the Source configuration. Specify the URL where the target application is running. Must be absolute, with the HTTPS scheme, without query or fragment components.

Use environment-specific configuration or IHostEnvironment extension methods to set the correct values for each application in your environment. To learn how to identify environments for SaaS projects, see Environment identification extension methods or Application settings for different SaaS deployment environments.

using Microsoft.Extensions.Hosting;

...

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

...

// Configures the development environment as the content sync source
if (builder.Environment.IsDevelopment())
{    
    builder.Services.Configure<ContentSynchronizationOptions>(options =>
    {
        options.Source.Enabled = true;
        options.Source.Secret = "147283795efb915cf7bcbe207678764e";
        options.Source.TargetUrl = "https://productiondomain.com";
    });
}
// Configures the production environment as the content sync target
if (builder.Environment.IsProduction())
{
    
    builder.Services.Configure<ContentSynchronizationOptions>(options =>
    {
        options.Target.Enabled = true;
        options.Target.Secret = "147283795efb915cf7bcbe207678764e";
    });
}

Content sync for SaaS environments

For SaaS projects, you do not need to configure content sync manually (except for local development environments).

SaaS deployment environments have their content sync configuration done automatically based on Content synchronization connections defined in Xperience Portal. However, the automatic configuration may be overridden by environment-specific configuration of ContentSynchronizationOptions as described in Source and target configuration.

Content staging best practices

You can use content sync with non-production environments (local development, QA, UAT) to transfer content during development. However, this is not recommended for stable, long-term editing and staging of content. Non-production environments do not have sufficient performance, availability, backup policies, etc.

To set up a proper content staging environment, add the optional Staging (STG) deployment environment to your service plan. The Staging environment provides a platform where editors and other staff can prepare content, and then transfer it to the production environment using content sync. Staging environments are designed to be nearly identical to production environments in most aspects, such as performance, availability, backup policies, and the option to set custom domains.

Set up a Staging environment

Use the following process to initialize a Staging deployment environment for an existing project:

1. Download a backup of your production environment.
2. Create a new deployment package.
   • Make sure that the package contains all required data by editing the $CDRepository/repository.config file (see Configure CI/CD repositories).
   • If you are updating to version 30.5.0 or newer as part of this deployment, you must include the cms.user object type in the package and use the CreateUpdate restore mode (Create is not sufficient).
3. Deploy the package through the available environments up to Staging (STG).
4. Configure any required custom domains for the staging environment.

Manage synchronization connections

To use content sync for SaaS projects, you need to create synchronization connections between environments in Xperience Portal:

1. Open the Content synchronization application in Xperience Portal.
2. Select Create new connection.
3. Choose the Source and Target environment.
   • When setting up a LOCAL development environment as the source, see Add connections from local development environments.
4. Select Create.

After you create connections, select the Apply changes button in the information ribbon at the top of the interface. Applying these changes triggers a restart of the affected applications. You may need to manually refresh the current page for the Apply changes button to appear in the information ribbon.

Once the connection becomes Active, content sync is configured for the given environments and users can start transferring content.

You can delete connections and apply the changes if you wish to disable content synchronization between the given environments.

Add connections from local development environments

When you create a content sync connection with a LOCAL environment as the source, Xperience Portal displays Target URL and Connection secret values. Copy the values and use them in the content sync configuration of the application in your local development environment:

• Target URL → ContentSynchronizationOptions.Source.TargetURL
• Connection secret → ContentSynchronizationOptions.Source.Secret

You need to ensure that the source configuration only applies to the local development environment. To learn how to identify environments for SaaS deployment environments, see Environment identification extension methods or Application settings for different SaaS deployment environments.

Configure Xperience for content sync

To prepare your Xperience instances for content sync, configure the following features:

• Permissions – to synchronize content items, users need to have a role with the Synchronize permission assigned for the Content hub application and the appropriate workspaces.
• Workflows –if you use workflows to control the lifecycle of your content, only set up and apply the workflow on the source instance where content is edited. Any workflow applied on target content sync instances is ignored, as content items are always transferred with the Published or Unpublished status and a completed workflow cycle.
• Allowed asset extensions – instances connected using content synchronization must use the same set of allowed file extensions for content item assets.
• Content folders – instances connected using content synchronization must have the same enabled/disabled status for content folders. See Enable content hub folders.

Additionally, the following objects are required by content items, but are not included in content synchronization:

• Channels that use the content (website, email, headless)
• Content types
  • Content item restrictions for content types do not apply when restoring synchronized content on target instances.
  • Image variant definitions for asset content types must also match between instances connected using content sync.
• Languages
• Workspaces

You need to ensure that all connected instances have exactly the same set of these objects. For example, an error will occur if you try to synchronize a content item for which an exactly matching content type is not available on the target.

The compatibility of objects is calculated based on their GUID identifiers and all available data. It is not sufficient to manually recreate objects with the same code name (with the exception of languages, which are only validated by their code name). When you update or add any of the required objects on the source server, you need to transfer them to the next environments using a standard deployment, i.e., SaaS deployment or Continuous Deployment.

Content sync internals

When a target application receives content through content sync, the updates are not immediately applied. Every synchronization is represented and stored in the following way:

• Data and asset files stored in the project’s ~/assets/synchronizations folder
• Synchronization task (stored in the CMS_Synchronization database table)

The synchronizations are applied automatically by the Content sync restoration scheduled task, which runs every 30 seconds. During the restoration, content is created or updated using the Xperience API:

• All content operations are performed in the context of the kentico-system-service (“System service user”) internal user account. Permissions are not evaluated.
• If an error occurs during the restoration, any updates that affect published content are rolled back. In some cases, added or modified Draft versions of content may remain after a failed synchronization restoration.
• Global events are triggered for the changes. The API is called in multiple waves when restoring content:
  1. Items are first created or updated in the Draft status.
  2. Items are published or unpublished (depending on the status of the synchronized content).
• Workflow events are not triggered (having workflows applied on target content sync instance is not recommended)

You can monitor synchronizations that recently occurred or are scheduled to take place in the Content synchronization application.