Import content with Migrate

Create and attach the destination compound before importing. Use core Migrate to map source values into its sub-fields. Compound Field also provides a process plugin for data exported in its API format.

For an existing string field on the same site, use the replacement-field tutorial.

Map individual values

Conference has a field_sessions compound containing Title, Topics and a Track reference. Add these mappings to a migration whose source provides the named values:

process:
  title: conference_title
  field_sessions/0/title/value: session_title
  field_sessions/0/topics: topics
  field_sessions/0/track/target_id: track_id

destination:
  plugin: 'entity:node'
  default_bundle: conference
  validate: true

Here track_id is the destination site's taxonomy term ID. The source topics value is a list such as [{value: Community}, {value: Accessibility}]. The 0 selects the first session, not its first topic.

Destination path	Writes
field_sessions/0/title	The string's main property
field_sessions/0/link/uri	One property of a link
field_sessions/0/topics/1/value	The second topic of the first session
field_sessions/0	One complete session as a nested array
field_sessions	A list of sessions

Map the whole field when the source already contains nested records. Avoid flattened database-column names.

Resolve references and dates

Ordinary entity destinations accept storage values, not serialized API values.

• References need target_id. Use core's migration_lookup for entities created by an earlier migration. Resolve existing entities to their local IDs.
• Datetime values need UTC in Y-m-d\TH:i:s format. Use format_date with the source timezone. Date-only fields use Y-m-d.
• Formatted text needs its value and an installed text format.

Passing target_uuid directly to an entity destination does not resolve it. Use the process plugin below when the source is in API format.

Import a serialized compound

Enable Serialization. If sessions_json contains a compound value from JSON:API or REST, use:

process:
  title: conference_title
  field_sessions:
    plugin: compound_field_wire_format
    source: sessions_json

destination:
  plugin: 'entity:node'
  default_bundle: conference
  validate: true

The plugin accepts a JSON string or decoded array. An object represents one compound item; a list represents several. It resolves reference UUIDs and converts serialized dates to storage values. Referenced entities must already exist; the plugin does not create them.

These options are usually inferred. Set them explicitly when needed:

Option	Default source
entity_type	Entity type in the destination plugin, such as entity:node
bundle	Destination default_bundle, or the row's processed bundle value
field_name	Destination property, such as field_sessions

A missing reference or incompatible value fails that source row. Inspect the migration messages before continuing.

Check limits and rollback behavior

Set validate: true on the destination. Programmatic saves otherwise need not enforce required sub-fields or other validation rules.

Check source counts against both cardinalities before importing. Values beyond a sub-field's cap can be discarded during assignment, before validation can report them. Reject oversized source records or deliberately map a subset.

Rollback follows the destination plugin's behavior. Rolling back newly created nodes deletes their compound values too. An import into existing nodes is not a backup of their previous values; plan recovery before running it.

Compound Field does not provide a Feeds target plugin. These instructions apply to Migrate.