CMS Content Sync
Enterprise-grade content synchronization module enabling bidirectional content sharing between multiple Drupal sites through a centralized Sync Core service.
cms_content_sync
Install
composer require 'drupal/cms_content_sync:^3.0'
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.
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
Technical Details
Admin Pages 10
/admin/config/services/cms_content_sync/site
Register and configure your site with the Sync Core service. View site status, UUID, and connection details.
/admin/config/services/cms_content_sync/syndication
Embedded React dashboard showing real-time syndication progress, content status across sites, and sync operations.
/admin/config/services/cms_content_sync/pool
Manage content pools - logical groupings of content that control synchronization scope and access.
/admin/config/services/cms_content_sync/pool/add
Create a new content pool for organizing synchronized content.
/admin/config/services/cms_content_sync/flow
Manage synchronization flows that define which content types and fields are synchronized and how.
/admin/config/services/cms_content_sync/flow/add
Create a new synchronization flow defining what content is synchronized and how.
/admin/config/services/cms_content_sync/settings
Configure global settings for content synchronization including authentication, base URL, and logging.
/admin/config/services/cms_content_sync/compatibility
View entity type and field type support matrix showing which types can be synchronized.
/admin/config/services/cms_content_sync/flow/copy/remote
Multi-step wizard to copy flow configuration from another connected site.
/admin/cms-content-sync/publish-multiple-changes/confirm/{entities}
Confirmation dialog for pushing selected entities to other sites with translation and priority options.
Permissions 9
Hooks 6
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 6
drush cms_content_sync:configuration-export
Export all pool and flow configuration to the Sync Core service
drush cms_content_sync:pull
Pull entities from the Sync Core for a specific flow
drush cms_content_sync:push
Push entities to the Sync Core for a specific flow
drush cms_content_sync:reset-status-entities
Reset synchronization status for all entities in a pool, clearing push/pull timestamps
drush cms_content_sync:check-entity-flags
Check synchronization flags for a specific entity by UUID
drush cms_content_sync:register
Register this site with the Content Sync backend service
Troubleshooting 7
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 8
- 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