Updated on June 20, 2022

If you followed along while we migrated academic program nodes in part 1 of this series, Drupal Migration: Migrating Basic Data (Part 1), we'll be continuing with the same example this time around as we learn how to import tags (taxonomy terms) related to those academic programs. This article assumes:

  • You've read the first article in this series on migrating basic data.
  • You're able to write basic entity migrations.
  • You're aware of taxonomy vocabularies/terms and their usage.

👩‍💻 Get up to speed on Drupal 9! Watch Evolving Web and Pantheon's webinar on Drupal migrations.

The Drupal 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 have 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 website and migrate API would be able to refer to these tags using their IDs.

To achieve 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:

field_tags:
  -
    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 in order to split (or "explode") the tags by the delimiter , (comma), thereby creating an array of tags. We do this using plugin: explode and delimiter: ', '. We leave a space after the comma because the data source has a space after its commas, meaning that adding that space in the delimiter will allow us to exclude the spaces from the imported tags.
  • migration_lookup: Now that we have an array of tags, each tag identifying itself using its unique tag text, we can 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_lookup and migration: program_tags. You can read more about the migration_lookup plugin on Drupal.org.
migration_dependencies:
  optional:
    - 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 with 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.
field_program_type:
  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 with the academic programs. The disadvantage of using the entity_generate method is when we roll back the migration, these taxonomy terms created during the migration would not be deleted.

Next steps

Category
Drupal and Web Development
Tags
Migration
Tutorial
Drupal Planet
Drupal