External Entities
Allows connecting to and using datasets from external sources as native Drupal entities through REST APIs, file systems, SQL databases, and other storage backends.
external_entities
Overview
External Entities is a powerful module that enables you to connect to external data sources and expose them as native Drupal entities. While content lives externally (on remote servers, in files, or in external databases), Drupal treats these entities as if they were internal content. This makes it possible to leverage Drupal's entity system features including field display configuration, entity references, comments, path aliases, Views integration, and more.
The module provides a flexible plugin architecture with five plugin types: Data Aggregators for combining multiple sources, Storage Clients for connecting to different data backends, Field Mappers for mapping source data to Drupal fields, Property Mappers for mapping source properties to field properties, and Data Processors for transforming data values. The module supports annotations, which allow adding locally-stored data to external entities, and provides multi-language support with language-specific configuration overrides.
External Entities is ideal for scenarios where you need to display data from external REST APIs, import content from legacy systems, aggregate data from multiple sources, or create a unified view of distributed data without duplicating it in Drupal's database.
Features
- Create external entity types that map remote data to Drupal entities with full entity system integration
- Connect to REST APIs with comprehensive configuration including authentication, custom headers, query limiting, and response caching
- Use files as entities with support for file metadata extraction and path pattern matching
- Connect to SQL databases (MySQL/PostgreSQL) via the companion xnttsql module
- Aggregate data from multiple storage clients using horizontal, vertical, or group aggregation modes
- Map source data to Drupal fields using configurable field mappers and property mappers with JSONPath support
- Process data values with built-in data processors for boolean conversion, date/time formatting, numeric extraction, string case transformation, and value mapping
- Add local annotations to external entities by linking them to local content entities
- Support for multi-language configurations with per-language field mapping and storage client overrides
- Entity caching with configurable cache durations to improve performance
- Read-only mode support for external entity types
- Debug mode with detailed logging for troubleshooting
- Views integration via the xntt_views companion module
- Pathauto integration via the external_entities_pathauto companion module
- File and image field support via the xntt_file_field companion module
Use Cases
Displaying REST API data as Drupal content
Connect to external REST APIs (e.g., a product catalog, news feed, or user directory) and display the data as native Drupal content. Configure field mappings to transform API responses into structured entity fields, apply Views to create listings, and use display modes for consistent theming.
Migrating from Drupal 7
Use the JSON:API or REST storage client to connect to a Drupal 7 site running RESTful Web Services. Display D7 content in Drupal 10/11 during migration, with the option to use External Entity Manager to physically import and synchronize data.
Aggregating data from multiple sources
Use the Group Aggregator to combine data from multiple storage clients. For example, merge product information from a REST API with pricing data from an SQL database, or combine user profiles from different systems using join conditions.
File-based entity storage
Use the Files storage client to treat local files as entities. Extract file metadata (name, size, date) and path components as fields. Useful for managing document libraries or media assets stored on the filesystem.
Annotating external content
Enable annotations to add local Drupal data (comments, ratings, tags) to external entities. Link external entities to local content types and inherit selected fields from the annotation entity for display.
Multi-language external content
Configure language-specific storage clients or field mappings to retrieve localized content from different API endpoints or databases based on the current language context.
Tips
- Always map the entity identifier (id) field first - this is required for entity loading and listing
- Use the JSON:API storage client for connecting to other Drupal sites as it provides optimized integration
- Enable debug mode during development to log all storage client operations and identify mapping issues
- Configure persistent caching for production to reduce load on external APIs
- Use the Group Aggregator's 'virtual group prefix' feature when combining sources with potentially overlapping IDs
- Consider Search API integration for Views with large external datasets for better query performance
- Lock external entity type configurations created programmatically to prevent accidental UI modifications
- Use the xntt_file_field module when mapping external file URLs to take advantage of image styles
Technical Details
Admin Pages 3
/admin/structure/external-entity-types
List all external entity types configured in the system. From this page you can add, edit, and delete external entity types, as well as access Field UI operations for managing fields and displays.
/admin/structure/external-entity-types/add
Create a new external entity type by configuring its basic settings, storage sources, field mappings, caching, and annotation options.
/admin/config/external
Configuration category page for external data related settings.
Permissions 6
Hooks 1
hook_external_entity_transform_raw_data_alter
Alter raw data before it is mapped to an external entity
Troubleshooting 5
Ensure the entity identifier field (id) is correctly mapped. Check that the storage client endpoint is accessible and returning valid data. Enable debug mode to log API requests and responses.
Verify the property mapper configuration uses the correct path syntax. For nested data, use JSONPath expressions ($.field.subfield) or simple dot notation (field.subfield). Check data processor configurations if values need transformation.
Configure the 'Maximum number of queries per second' setting in the REST storage client to respect API rate limits. Enable query limiting to track and throttle requests.
Enable persistent caching with an appropriate cache duration. Consider using Search API to index external data for Views queries. For REST sources, ensure the list endpoint returns complete entity data to avoid individual entity loading.
Ensure required field mappings (id, title) are configured before saving. Check for validation errors in the storage client configuration. Clear caches and verify the galbar/jsonpath library is installed.
Security Notes 6
- External data sources may contain untrusted content that could compromise site security if not properly filtered
- Administrators with 'administer external entity types' permission can access system files and database credentials - grant this permission only to trusted users
- Always validate and sanitize data from external sources, especially when displaying user-generated content
- Configure storage clients with read-only mode when write access to external systems is not needed
- Use secure connections (HTTPS) for REST API endpoints when transmitting sensitive data
- Be cautious with SQL storage clients as they can execute arbitrary queries on configured databases