External Entities

This module enables you to connect your Drupal 8, 9, or 10+ website to external data sources and integrate external datasets as if they were native Drupal content. Although the content remains hosted externally, Drupal treats these remote entities as internal, allowing you to modify field displays, add references, comments, path aliases, share buttons, webshop products, and more.

External data

You can incorporate external data into your site, such as museum collections, Wikipedia content, specialized wildlife thesauri, street names, member directories, or other organizational systems. If the external storage client supports updates, you can also create, edit, and delete remote entities, turning Drupal into a central hub for content management within an organization.

Plugins

External entities can be enhanced with plugins that extend both storage sources (data aggregators, storage clients) and field mappings (field mappers, property mappers, data processors). The module comes with native storage plugins (like REST) and mappers (such as Simple and JSONPath), and there are many additional plugins available (e.g. database storage, string function mappers). You can find a comprehensive list on this page.

Background

Drupal 8+ is database-agnostic, meaning it no longer matters whether the data for an entity comes from Drupal's internal SQL database, an external JSON file, or any other source.

Technique

The module lets you define an external entity type that retrieves data from a storage client and maps those external fields to Drupal fields, creating a "virtual" entity in Drupal.

Known limitations

• Views support: Version 3 offers native Views support through the xnttviews companion module, while version 2 does not, except with the xnttviews extension. Depending on the speed of querying external entities, using a local index system like Search API may be more efficient than relying on External Entities Views support.
• File and Image field support: Version 3 natively supports File and Image field types, but version 2 does not. These fields require a Drupal file entity ID rather than a file path. Workarounds include using the ImageCache External extension for image URLs and the External Entities files storage client module for file paths or image URLs.
• Comments: For comments, use comment fields attached as annotations (#2496699: Allow comments to be attached to entities using a string primary key).

By default, External Entities assumes that all fields of an entity come from the same dataset, but it allows for mixing data sources. Version 3 uses data aggregator plugins to combine data from multiple sources either "vertically," "horizontally," or both. For version 2, you can use the xnttmulti extension. However, external entity fields are only populated if they are mapped to source fields or constants. When editing an external entity, field values are only saved to remote sources, not to Drupal’s database. If you need to store extra data not mapped to a remote source, you can use annotations, which are linked to a local Drupal content entity where you can define custom fields.

To automatically generate annotation entities, manage field mappings, and synchronize local Drupal content types with external entity types, consider using the External Entity Manager extension.

External Entities is available in two versions:

• v2: A stable version with a couple of plugins.
• v3: The latest version with many improvements, fixes, and new features. v3 introduces breaking changes in the API (from v2), but v2 can be upgraded to v3. v3 is quite stable now and will have a full release in 2025.

Slack channel #external-entities