Entity Share
Entity Share enables content sharing between multiple Drupal websites using the JSON:API. It provides server-side channels and client-side pull interfaces for synchronizing entities across sites.
entity_share
Install
composer require 'drupal/entity_share:8.x-3.13'
Overview
Entity Share is a comprehensive module that enables content sharing between multiple Drupal websites using the JSON:API. The module follows a server-client architecture where one website can act as a "server" (providing content via channels) and another as a "client" (pulling content from servers). A single website can also act as both server and client simultaneously.
The module provides a complete UI for managing server channels with customizable filters, sorts, searches, and access controls. On the client side, it offers remote website management, import configuration with a processor-based pipeline, and entity import status tracking. Advanced features include diff viewing between local and remote entities, import locking to prevent editing of imported content, and asynchronous import capabilities via queue processing.
Entity Share supports multiple authorization methods including OAuth 2.0, Basic Auth, Header-based authentication, and anonymous access. The module also provides JSON:API field enhancers for complex field types like metatags, pathauto fields, block fields, and embedded entities.
Features
- JSON:API based entity sharing between Drupal sites with full CRUD support
- Server-side channel configuration with filters, sorts, searches, and filter groups
- Client-side remote website management with multiple authorization methods (OAuth, Basic Auth, Header, Anonymous)
- Import configuration with processor-based entity import pipeline supporting pre-process, process, and post-process stages
- Entity import status tracking with change detection capabilities
- Asynchronous entity import support via queue workers
- Side-by-side diff viewing of local and remote entity versions
- Import locking to prevent editing of synchronized content
- JSON:API field enhancers for metatag, pathauto, block field, and embedded entities
- Drush commands for CLI-based entity imports
- Views integration for import status management
- Support for complex field types including paragraphs, entity references, files, and media
Use Cases
Multi-site Content Distribution
Set up a central content hub as the Entity Share Server with multiple regional or department sites as clients. Content editors create articles on the hub, then regional editors pull relevant content to their sites. Each regional site can have different import configurations to handle local requirements like translation handling or content policies.
Staging to Production Content Sync
Use Entity Share to synchronize content from a staging environment to production. Configure the staging site as the server with channels for reviewed content. Production acts as the client, pulling only approved content. Import configurations can skip already-imported content and prevent overwrites of locally modified entities.
Content Aggregation from Multiple Sources
Configure a site as a client connecting to multiple Entity Share servers (different departments, partners, or content sources). Each remote has its own authentication configuration. Import configurations can be customized per source to handle different content structures or policies.
Headless CMS Content Distribution
Use Entity Share Server to expose content channels from a headless Drupal CMS. Multiple presentation layer applications can pull content via the JSON:API-based channels. This provides a standardized content synchronization mechanism beyond the basic JSON:API read operations.
Content Backup and Recovery
Set up Entity Share between primary and backup sites for content redundancy. The backup site periodically pulls content from the primary site using Drush commands in cron jobs. Import status tracking ensures only changed content is synchronized, and the diff feature allows verification of content integrity.
Selective Content Sharing Between Partner Sites
Organizations with partner relationships can share specific content types through carefully configured channels with access controls. Channels can be restricted to specific users or roles on the server side, and clients can be configured with appropriate authentication. Import policies control how shared content integrates with local content.
Tips
- Use OAuth authentication for production environments rather than Basic Auth for improved security
- Configure channel filters to limit exposed content and reduce import overhead
- Set appropriate recursion depth in Entity Reference processor to balance completeness with performance
- Enable Skip Imported processor to avoid re-processing unchanged content on subsequent imports
- Use the diff feature to review changes before importing updated content
- Consider using the Key module for credential storage in multi-environment deployments
- Set up Drush commands with cron for automated content synchronization
- Use filter groups with AND/OR conjunctions for complex channel filtering logic
- Configure searches on channels to enable content editors to find specific content easily
- Monitor import status entities to track synchronization state and identify issues
Technical Details
Admin Pages 10
/admin/config/services/entity_share
Main configuration hub for Entity Share module. Provides links to all Entity Share configuration pages including channels, remote websites, import configurations, and diff settings.
/admin/config/services/entity_share/channel
List and manage server channels for sharing content. Each channel exposes a specific entity type and bundle via JSON:API. Channels can be configured with filters, sorts, searches, and access controls.
/admin/config/services/entity_share/channel/add
Create a new channel to expose entities for sharing.
/admin/config/services/entity_share/remote
List and manage remote website connections for pulling content. Configure the remote site URL and authorization method.
/admin/config/services/entity_share/remote/add
Configure a connection to a remote Entity Share server.
/admin/config/services/entity_share/import_config
List and manage import configurations that define how entities are processed during import. Each configuration contains a set of processors with specific settings.
/admin/config/services/entity_share/import_config/add
Create a new import configuration with processor settings.
/admin/content/entity_share
Main interface for pulling entities from remote websites. Select a remote, choose a channel, search and filter entities, then import selected content.
/admin/content/entity_share/statuses
View tracking information for imported entities. Shows entity type, bundle, UUID, source remote, channel, and last change time.
/admin/config/services/entity_share/diff
Configure diff display settings for entity comparison.
Permissions 8
Hooks 1
hook_entity_share_server_channel_list_alter
Allows modules to alter the list of channels returned to clients.
Drush Commands 2
drush entity-share-client:pull
Pull all entities from a channel on a remote website.
drush entity-share-client:pull-entities
Pull specific entities by UUID from a channel.
Troubleshooting 8
Verify the remote URL is correct and accessible. Check that the authorization method is properly configured with valid credentials. Ensure the authenticated user on the remote has the 'Access channels list' permission. Check browser console for CORS errors if sites are on different domains.
The authenticated user on the remote server needs view access to the entities being pulled. For nodes, this typically requires 'View published content' or appropriate node access permissions. For menu links, install the Menu Link Content View Access module.
Enable the Entity Reference processor in the import configuration. Check the 'Max recursion depth' setting - it may need to be increased for deeply nested references. For paragraphs, ensure the Embedded Entity Importer processor is enabled.
Enable the Physical File processor. Ensure the remote server allows file downloads and the client site has proper file system permissions. Check that the authenticated user can access file entities on the remote.
Import status tracking is based on entity UUID and language. If entities were deleted and re-created locally, or if the import status entities were cleared, they will appear as new. The import service tracks status per remote/channel combination.
Verify all OAuth credentials (client ID, secret, endpoints). Ensure the Simple OAuth module is properly configured on the server with matching client configuration. Check that the username/password for Resource Owner Password Credentials grant are correct.
Check Entity Share Diff settings for context line configuration. Ensure both local and remote entities exist. The diff feature requires the entity to have been previously imported to have a local version for comparison.
Ensure cron is running regularly on the site. Check the queue status in Database logging. The entity_share_async_worker queue needs to be processed. Consider increasing PHP memory limits for large imports.
Security Notes 7
- Store OAuth credentials and API keys using the Key module rather than in config for production sites
- Restrict 'Administer channel entity', 'Administer remote website entity', and 'Administer import config entity' permissions to trusted administrators only
- Channel access controls should be configured to limit which users can access content via JSON:API
- Consider network-level restrictions (firewall, VPN) for content sharing between sensitive environments
- The 'Display technical errors' permission should only be granted to developers as it may expose sensitive request details
- Review imported content policies to ensure appropriate content ownership and moderation workflows
- OAuth tokens and credentials should be rotated periodically following security best practices