Process plugin: migration_lookup (formerly migration)

Last updated on
19 May 2017

It is important to maintain relationships among content coming from the source site, but in most instances the unique identifiers of the content change in the process of migration. For example, on the source site a given user account may have an "author" ID of 123, but the Drupal user account created from it may have a uid of 456. The migration process maintains the relationships between source and destination identifiers in map tables, and this information is leveraged by the migration_lookup process plugin.

Drupal 8.3.2 and earlier

Renamed from migration to migration_lookup in Drupal 8.3.2. The old name is still supported for backwards-compatibility and should be used for any migration code which needs to run on Drupal core versions before 8.3.2.

Consider a node migration, where you want to maintain authorship. If you have migrated the user accounts in a migration named users, you would specify the following:

process:
  uid:
    plugin: migration_lookup
    migration: users
    source: author

This takes the value of the author property in the source data, and looks it up in the map table associated with the users migration, returning the resulting user ID and assigning it to the destination uid property.

The value of migration can be a list of migration ids. When using multiple migrations it is possible each use different source identifiers. In this case one can use source_ids which is an array keyed by the migration ids and the value is a list of source properties with the same features as normal source (see the get plugin for more on this). Example:

process:
  uid:
    plugin: migration_lookup
    migration: 
      - users
      - members
    source_ids: 
      users:
        - author
      members:
        - author

If the migration does not find the source ID in the migration map it will create a stub entity for the relationship to use. This stub is generated by the migration provided. In the case of multiple migrations the first value of migration list will be used, but you can select the migration you wish to use to create the stub:

process:
  uid:
    plugin: migration_lookup
    migration: 
      - users
      - members
    source_ids: 
      users:
        - author
      members:
        - author
    stub_id: members

Here, the value of stub_id selects the members migration to create any stub entities, overriding the default of the users migration.

To prevent the creation of a stub entity when no relationship is found in the migration map, use no_stub. It can be set to any non-empty value:

process:
  uid:
    plugin: migration_lookup
    migration: users
    no_stub: true
    source: author

Debugging tips

  • This plugin does not throw any errors if you put in an incorrect field name, it silently fails.

Examples for d6 node references and d7 entity references

migrating d6 node reference to d8

Scenario :
a) field_drupal6_pages is a drupal 6 node reference field.
b) field_drupal8_pages is a drupal 8 entity reference field.

  field_drupal8_pages:
    plugin: migration_lookup
    migration: ya_node_page
    source: field_drupal6_pages

migrating d7 entity reference to d8

Scenario :
a) field_drupal7_pages is a drupal 7 entity reference field.
b) field_drupal8_pages is a drupal 8 entity reference field.

  field_drupal8_pages:
    plugin: iterator
    source: field_drupal7_pages
    process:
      target_id:
        plugin: migration_lookup
        migration: ya_node_page
        source: target_id