21.05.2026 | Lothar Ferreira Neumann

Aggregate heterogeneous media fields for structured Drupal migration

migration_field_merge.yml
  field_media:
    - plugin: merge
      source:
        - field_image
        - field_images
    - plugin: sub_process
      process:
        target_id:
          - plugin: migration_lookup
            source: fid
            migration:
              - my_migration_media_image

Issue:

You want to combine multiple image fields from a legacy system into a single media field in a new Drupal system during migration.

Solution:

The code uses the migration API of Drupal to merge multiple source image fields into a single media field. It employs the merge plugin to combine the fields and a sub-process to transform the references into media entities using a migration lookup.