Drupal 8 Migration: Migrating Taxonomy Term References (Part 2)

Jan 23, 2017 · by Jigar Mehta

Having completed the migration of academic program nodes as mentioned in Drupal 8 Migration: Migrating Basic Data (Part 1), this article will focus on the second requirement - importing tags (taxonomy terms) related to the academic programs. This article assumes:

  • You have read the first part of this article series on migrating basic data.
  • You are able to write basic entity migrations.
  • You are aware of taxonomy vocabularies / terms and their usage.

Need some help? Learn everything you need to know to get hands-on with Drupal - sign up for our Complete Drupal Training course.

The Drupal 8 Migration Series

Importing tags as taxonomy terms

As a general rule for migrating relations between two entities, first we need to write a migration for the target entities. In this case, since academic programs has a field named field_tags and we wish to store the IDs of certain taxonomy terms of the vocabulary tags in the program nodes, we need to write a migration to import tags first. Thus, while running the migrations for academic programs, the tags would already exist on the Drupal 8 site and migrate API would be able to refer to these tags using their IDs.

For achieving this, we write a simple migration for the tags as in the migrate_plus.migration.program_tags.yml file. One noteworthy thing about this migration is that we use the tags themselves as the unique ID for the tags. This is because:

  • The tags data-source, program.tags.csv, does not provide any unique key for the tags.
  • The academic programs data-source, program.data.csv, refers to the tags using the tag text (instead of unique IDs).

Once the tag data is imported, all we have to do is add some simple lines of YAML in the migration definition for academic programs to tell Drupal how to migrate the field_tags property of academic programs. As we did for program_level in the previous article, we will be specifying multiple plugins for this property:

    plugin: explode
    delimiter: ', '
    source: Tags
    plugin: migration
    migration: program_tags

Here is an explanation of what we are actually doing with the multiple plugins:

  • explode: Taking a look at the data-source, we notice that academic programs have multiple tags separated by commas. So, as a first step, we use the explode plugin which would split / explode the tags by the delimiter , (comma), thereby creating an array of tags. We do this using plugin: explode and delimiter: ', '. We have a space after the comma because the data source has a space after it's commas and adding that space in the delimiter, we would be able to exclude the spaces from the imported tags.
  • migration: Now that we have an array of tags, each tag identifying itself using it's unique tag text, we tell the migrate module that these tags are the same ones we imported in migrate_plus.migration.program_tags.yml and that the tags generated during that migration are to be used here in order to associate them to the academic programs. We do this using plugin: migration and migration: program_tags. You can read more about the migration plugin on Drupal.org.
    - program_tags
#     - program_image

To make sure that tag data is imported and available during the academic program migration, we specify the program_tags migration in the migration_dependencies for the program_data migration. Now, when you re-run these migrations, the taxonomy terms get associated to the academic program nodes. At this stage, you can keep the program_image dependency still commented, because we haven't written it yet.

Migrated tags visible in UI
Migrated tags visible in UI.

As simple as it may sound, this is all that is needed to associate the tags to the academic programs! All that is left is re-installing the c11n_migrate module and executing the migrations using the following drush command: drush mi --group=c11n --update. You should see the following output:

$ drush mi --group=c11n --update
Processed 8 items (8 created, 0 updated, 0 failed, 0 ignored) - done with 'program_tags'
Processed 4 items (0 created, 4 updated, 0 failed, 0 ignored) - done with 'program_data'

Because of the migration_dependencies we specified, the program_tags migration was run before the program_data migration.

Importing terms without a separate data-source

For the sake of demonstration, I also included an alternative approach for the migration of the field_program_type property. For program type, I used the entity_generate plugin which comes with the migrate_plus module. This is how the plugin works:

  • Looks up for an entity of a particular type (in this case, taxonomy_term) and bundle (in this case, program_types) based on a particular property (in this case, name).
  • If no matching entity is found, an entity is created on the fly.
  • The ID of the existing / created entity is returned for use in the migration.
  plugin: entity_generate
  source: Type
  entity_type: taxonomy_term
  bundle_key: vid
  bundle: program_types
  value_key: name

So, in the process instructions for field_program_type, I use plugin: entity_generate. So, during migration, for every program type, the entity_generate plugin is called and a particular taxonomy term is associated to the academic programs. The disadvantage of using the entity_generate method is when we rollback the migration, these taxonomy terms created during the migration would not be deleted.

Next steps

Evolving Web Newsletter

Sign up for tutorials, best practices and insights, plus info about our acclaimed Drupal Training series.