CMS Content Sync
cms_content_sync
Enterprise-grade content synchronization module enabling bidirectional content sharing between multiple Drupal sites through a centralized Sync Core service.
Overview
CMS Content Sync is a comprehensive Drupal 10/11 module that provides sophisticated content synchronization capabilities between multiple Drupal installations. It uses a centralized Sync Core service to manage and orchestrate the distribution of content, enabling organizations to maintain consistent content across their multi-site infrastructure.
The module supports bidirectional push and pull operations, allowing sites to both publish content to and receive content from a central repository. Content can be synchronized automatically, manually, or as dependencies when related content is pushed. The system tracks entity status across sites, handles content conflicts, and supports translation workflows.
Key capabilities include support for over 20 entity types (nodes, media, taxonomy terms, menu links, paragraphs, blocks, and more), 19+ field handlers for different field types, REST API integration for remote operations, batch processing for large-scale synchronization, and comprehensive admin interfaces for configuration and monitoring.
Install
composer require 'drupal/cms_content_sync:^3.0'
Features
- Bidirectional content synchronization (push/pull) between multiple Drupal sites using a centralized Sync Core service
- Flow management system allowing granular control over what content types, bundles, and fields are synchronized
- Pool-based content organization enabling content grouping and access control across sites
- Support for 10+ entity types including nodes, media, taxonomy terms, menu links, paragraphs, blocks, files, config pages, entity queues, and group content
- 19 field handlers supporting text fields, entity references, paragraphs, files, images, layout builder, moderation state, links, paths, webforms, and more
- Real-time entity status tracking with sync history, timestamps, and failure detection
- REST API endpoints for remote site communication and Sync Core integration
- Batch processing for large-scale push/pull operations preventing timeouts
- Translation support with language-aware synchronization and independent translation handling
- Content override protection allowing local modifications while preserving sync relationships
- Manual pull dashboard for content discovery and selective importing from remote sites
- Health monitoring dashboard for tracking sync status, failures, and configuration issues
- Drush commands for CLI-based configuration export, push, pull, and status management
- Migration tools for transitioning from Acquia Content Hub
- Private environment support for local development and non-publicly accessible sites
- DraggableViews integration for synchronized content ordering
- Cross-sync capabilities allowing content to flow between sites bidirectionally
Use Cases
Multi-site Content Distribution
A central editorial team creates content on a primary Drupal site and pushes it to multiple regional or brand-specific sites. Each regional site automatically receives new content, updates, and deletions while maintaining local customizations through the override feature.
Content Staging Workflow
Content is created and edited on a staging environment, then pushed to production when approved. The staging site pushes content while the production site pulls, ensuring controlled content deployment with full translation support.
Decoupled Content Repository
Multiple frontend applications (web, mobile, kiosk) pull content from a central Drupal repository. The repository pushes content to a Sync Core which then distributes to consuming applications, enabling true headless architecture.
Franchise/Dealer Network
A corporate site maintains core content (products, policies, brand assets) that is automatically distributed to hundreds of franchise sites. Local sites can add their own content while receiving corporate updates, with pool-based access control.
Editorial Collaboration Across Sites
Multiple editorial teams across different sites can push content to shared pools, enabling cross-site content reuse. Each site maintains control over what content it receives through flow configuration.
Content Migration and Consolidation
Legacy content from multiple older Drupal sites is pulled into a new central platform. The migration submodule helps transition from Acquia Content Hub, and entity mapping ensures content relationships are preserved.
Tips
- Always export configuration after making flow changes using the UI or 'drush cse' command
- Use the Health dashboard (cms_content_sync_health submodule) to monitor synchronization status and identify failures
- For development environments behind firewalls, enable the private_environment submodule to use request polling
- When copying flows from remote sites, use the transformation options to adjust push/pull settings for your site's role
- Entity type versions are calculated automatically - if you see version mismatches, use the developer submodule to identify field differences
- Use pool-based organization to control which sites receive which content types
- The 'Override' checkbox on content allows local modifications while still tracking the sync relationship
- For large initial synchronizations, use Drush commands with the --type option to process in batches
- Preview functionality for the pull dashboard requires enabling it in settings and re-exporting flows
- Configure deletion settings carefully - pushed deletions will remove content from receiving sites
Dependencies
Related Projects
Required for Views integration. Allows storing references to multiple entity types in the entity status table.
Required for secure storage of authentication credentials and API keys for Sync Core communication.
Full support for paragraph entity synchronization including nested paragraphs and revision handling.
Full support for media entity synchronization including file handling and crop data.
Support for synchronizing layout builder configurations with embedded block references.
Support for moderation states with options to pull content as unpublished revisions.
Integration with path alias generation during content pull operations.
Support for webform config entity synchronization and webform reference fields.
Support for group and group content entity synchronization.
Support for commerce product and product variation entities.
Support for Cohesion layout entities and entity reference fields.
Support for image crop entities preserving focal point data.
Integration for synchronizing sitemap configuration (via submodule).
Integration for synchronizing content ordering (via submodule).
Admin Pages
| Title | Path | Description |
|---|---|---|
| Content Sync Registration | /admin/config/services/cms_content_sync/site |
Register and configure your site with the Sync Core service. View site status, UUID, and connection details. |
| Syndication Dashboard | /admin/config/services/cms_content_sync/syndication |
Embedded React dashboard showing real-time syndication progress, content status across sites, and sync operations. |
| Pools | /admin/config/services/cms_content_sync/pool |
Manage content pools - logical groupings of content that control synchronization scope and access. |
| Add Pool | /admin/config/services/cms_content_sync/pool/add |
Create a new content pool for organizing synchronized content. |
| Flows | /admin/config/services/cms_content_sync/flow |
Manage synchronization flows that define which content types and fields are synchronized and how. |
| Add Flow | /admin/config/services/cms_content_sync/flow/add |
Create a new synchronization flow defining what content is synchronized and how. |
| Content Sync Settings | /admin/config/services/cms_content_sync/settings |
Configure global settings for content synchronization including authentication, base URL, and logging. |
| Compatibility | /admin/config/services/cms_content_sync/compatibility |
View entity type and field type support matrix showing which types can be synchronized. |
| Copy Remote Flow | /admin/config/services/cms_content_sync/flow/copy/remote |
Multi-step wizard to copy flow configuration from another connected site. |
| Push Changes Confirmation | /admin/cms-content-sync/publish-multiple-changes/confirm/{entities} |
Confirmation dialog for pushing selected entities to other sites with translation and priority options. |
Permissions
| Permission | Description |
|---|---|
|
Allows users to push content changes to other sites via the Sync Core |
|
View the manual pull dashboard and content overview pages |
|
Full administrative access to configure pools, flows, settings, and manage synchronization |
|
Shows the Sync status tab on content items. Admins can also access serialized content data. |
|
Display a button allowing users to find entity type schema differences between connected sites |
|
Access REST endpoint for content previews |
|
Access REST endpoint for pushing entities to this site |
|
Access REST endpoint to retrieve entities for import |
|
Access REST endpoint to post entities for import |
Hooks
| Hook | Description |
|---|---|
hook_cms_content_sync_entity_handler_info_alter |
Alter entity handler plugin definitions |
hook_cms_content_sync_field_handler_info_alter |
Alter field handler plugin definitions |
hook_cms_content_sync_before_entity_push |
Called before an entity is pushed, allowing modifications or cancellation |
hook_cms_content_sync_after_entity_push |
Called after an entity is successfully pushed |
hook_cms_content_sync_before_entity_pull |
Called before an entity is pulled, allowing modifications or denial |
hook_cms_content_sync_after_entity_pull |
Called after an entity is successfully pulled |
Drush Commands
| Command | Description |
|---|---|
|
Export all pool and flow configuration to the Sync Core service |
|
Pull entities from the Sync Core for a specific flow |
|
Push entities to the Sync Core for a specific flow |
|
Reset synchronization status for all entities in a pool, clearing push/pull timestamps |
|
Check synchronization flags for a specific entity by UUID |
|
Register this site with the Content Sync backend service |
Troubleshooting
1. Verify the flow is active and exported (check for 'Export required' warning). 2. Ensure the entity type/bundle is configured for push in the flow. 3. Check that at least one pool is set to 'Force' or 'Allow'. 4. Verify the site is registered with the Sync Core. 5. Run 'drush cse' to export configuration. 6. Check watchdog logs for errors.
1. Verify the flow has pull configured for the entity type. 2. Check pool settings allow pulling from the source pool. 3. Ensure the pulling site's entity type version matches the source. 4. Check for required fields that may be missing. 5. Review the Health dashboard for pull failures.
Entity type versions are calculated from field configuration. When fields differ between sites, versions won't match. Enable the developer submodule to see specific differences. Either add missing fields to both sites or configure the flow to ignore the mismatched fields.
1. Ensure file entities are configured in the flow (either directly or as dependencies). 2. Check that the file handler is selected for file/image fields. 3. Verify the destination site can write to the file directory. 4. For private files, ensure authentication is configured correctly.
1. Verify both sites have the same languages enabled. 2. Check flow configuration for translation handling. 3. For independent translation handling, each translation is pushed separately. 4. Ensure the default language exists on both sites.
When pushing content with untranslated reference fields containing new embedded entities, all translations may be pushed. This ensures embedded content is available in all languages. The confirmation dialog explains this behavior.
1. Use Drush commands (cs-push, cs-pull) instead of UI for bulk operations. 2. Enable batch processing. 3. Consider filtering by entity type or bundle. 4. Check Sync Core status for queue backlog. 5. Enable extended logging temporarily to identify bottlenecks.
Security Notes
- CMS Content Sync uses encrypted storage (Real AES) for authentication credentials - ensure the encryption key is properly configured and secured
- REST endpoints are protected by Drupal's permission system - review role assignments for REST permissions carefully
- The dedicated 'cms_content_sync' user role should only be assigned to the system user, not human users
- Basic Auth authentication type may expose credentials if not used over HTTPS - always use HTTPS in production
- When using private environments with request polling, be aware that requests originate from the Sync Core service
- The 'allow local deletion of import' setting should be carefully considered - enabling it allows users to delete content that came from other sites
- Extended logging options capture full entity data in watchdog - disable after debugging to avoid storing sensitive content in logs
- Site registration tokens expire after 5 minutes - do not store or share them