If you followed along while we migrated academic program nodes in part 1 of this series, Drupal 8/9 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 9 migrations.
The Drupal 8/9 Migration Series
- Part 1: Migrating Basic Data
- Part 2: Migrating Taxonomy Terms and Term References (You are here!)
- Part 3: Migrating Files and Images
- New: Migrating Hierarchical Taxonomy Terms
- Coming soon: Migrating Media Items and Their Relationships
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 8 site 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
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
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.
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,
- 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.