Migrating Your Data from D7 to D10: Migrating taxonomy vocabularies and D7 field collections into D10 paragraphs

Series Overview & ToC | Previous Article | Next Article

In the previous article, we began migrating configuration from Drupal 7 example site to our Drupal 10 instance, specifically content types. In today's article, we will continue with two more D7 entities: taxonomy vocabularies and field collections. The latter will be imported as Paragraphs in Drupal 10. Along the way, we will review the content model and the migration plan. This will help us determine what parts of the migration should be automated and what can be performed manually.

Before we begin

This series is designed to build on top of explanations and examples presented in previous articles. Moving forward, we will assume familiarity with the topics discussed in these five articles:

• Article 8: Site audit and lightweight migration plan
• Article 11: How to customize and execute generated migrations
• Article 12: The syntax of migration files
• Article 13: Source constants, pseudo-fields, and the migration process pipeline
• Article 14: Troubleshooting instructions for common errors when working with migrations

Troubleshooting instructions will be included only for issues not yet covered. Likewise, commands will be presented without much explanation if they had already been discussed. New commands or new flags for previously introduced commands will be explained when presented for the first time. The same applies for other migration concepts that have been discussed. If necessary, take the time to go back in the series and revisit those articles.

Migrating taxonomy vocabularies

We continue the process of migrating Drupal 7 configuration with taxonomy vocabularies. For this we use upgrade_d7_taxonomy_vocabulary, the same migration to explain how to customize generated migrations from article 11. Let's copy it from the reference folder into our custom module and rebuild caches for the migration to be detected.

cd drupal10
cp ref_migrations/migrate_plus.migration.upgrade_d7_taxonomy_vocabulary.yml web/modules/custom/tag1_migration/tag1_migration_config/migrations/upgrade_d7_taxonomy_vocabulary.yml
ddev drush cache:rebuild

Note that while copying the file, we also changed its name and placed it in a migrations folder inside our custom module. After copying the file, make the following changes:

• Remove the following keys: uuid, langcode, status, dependencies, field_plugin_method, cck_plugin_method, and migration_group.
• Add two migration tags: taxonomy_vocabulary and tag1_configuration.
• Add key: migrate under the source section.

After the modifications, the file should look like this:

id: upgrade_d7_taxonomy_vocabulary
class: Drupal\migrate\Plugin\Migration
migration_tags:
 - 'Drupal 7'
 - Configuration
 - taxonomy_vocabulary
 - tag1_configuration
label: 'Taxonomy vocabularies'
source:
 key: migrate
 plugin: d7_taxonomy_vocabulary
process:
 vid:
   -
     plugin: make_unique_entity_field
     source: machine_name
     entity_type: taxonomy_vocabulary
     field: vid
     length: 30
     migrated: true
 label:
   -
     plugin: get
     source: name
 name:
   -
     plugin: get
     source: name
 description:
   -
     plugin: get
     source: description
 weight:
   -
     plugin: get
     source: weight
destination:
 plugin: 'entity:taxonomy_vocabulary'
migration_dependencies:
 required: {  }
 optional: {  }

Now, rebuild caches for our changes to be detected and execute the migration. Run migrate:status to make sure we can connect to Drupal 7 and the number of vocabularies to import is correct. Then, run migrate:import to perform the import operation.

ddev drush cache:rebuild
ddev drush migrate:status upgrade_d7_taxonomy_vocabulary
ddev drush migrate:import upgrade_d7_taxonomy_vocabulary

This should create the two taxonomy vocabularies from Drupal 7: Article Tags (tags) and Session topics (session_topics). You can check them at https://migration-drupal10.ddev.site/admin/structure/taxonomy and compare them to their Drupal 7 equivalent at https://migration-drupal7.ddev.site/admin/structure/taxonomy.

Adding taxonomy vocabularies creates configuration entities. Remember to export configuration and commit the changes. Also, commit the new upgrade_d7_taxonomy_vocabulary migration.

From content type to taxonomy vocabulary

In the lightweight migration plan we drafted in article 8, We specified that nodes of type sponsor will be migrated as taxonomy term entities. Therefore, we need to convert the sponsor content type into a taxonomy vocabulary.

Pay close attention to the terminology used. Nodes and taxonomy terms are content entities. Content types and taxonomy vocabularies are configuration entities. Refer to article 7 for a refresher on these concepts and the difference among them.

Before we do anything else, let's have a look at the sponsor content type in Drupal 7. Take time to thoroughly review how the content type is configured. It is important to check the fields attached to it: https://migration-drupal7.ddev.site/admin/structure/types/manage/sponsor/fields

There are two fields we need to account for: field_logo of type Image and field_description of type Long text. After further inspecting field_description, we can see that it is a rich text field that allows selecting a text format. Additionally, we have the node properties title and path. The latter stores a path alias for the node, if one is set.

Before thinking about migrating either configuration or content related to sponsors, we need to come up with a plan on how to convert the Drupal 7 content type into a Drupal 10 taxonomy vocabulary. Check this article to learn about base field definitions for Drupal 10 taxonomy term content entities.

Now, consider the following:

• The Drupal 7 node title will be migrated as the Drupal 10 taxonomy term name.
• The Drupal 7 node field_description will be migrated as the Drupal 10 taxonomy term description property. No need to create a new field for this because the term’s description is already a rich text field.
• We would need to add an image field to the vocabulary in Drupal 10 to map field_logo from Drupal 7. We could use a media entity reference field here, but let's keep things simple and use a regular image field instead.
• Drupal 10 taxonomy terms have a path property which could be used to map the node’s path property from Drupal 7. We will talk about URL alias migration later in the series. For now, the Drupal 7 path alias will not be considered.

In addition to the above, it is important to review other fields and properties either from Drupal 7 or Drupal 10. For example, we will not migrate node IDs (nid) as taxonomy term IDs (tid). It is possible that in Drupal 7, the value of the node id of a sponsor matches the value of an existing taxonomy term id. If we were to map the nid as tid, we can potentially overwrite and lose data as discussed in article 5. We will work on preventing entity ID conflicts during the future content migrations.

To automate or not to automate, that is the question. We could probably come up with a way to automate the creation of the new sponsor taxonomy vocabulary in Drupal 10 and add an image field, but shall we? No. As described in the previous article, we need to strike a balance between what to automate and what changes to do manually in Drupal 10.

In this case, it is easy enough to create a new vocabulary via the interface and subsequently add the image field. Basic site-building knowledge is assumed for those following this series. We will not list every step of the process but start by visiting https://migration-drupal10.ddev.site/admin/structure/taxonomy/add to create the new vocabulary. Then proceed to attach the image field for the logo and configure the form and view modes. Refer to the final example to see how everything is set up.

Creating a new sponsor taxonomy term in Drupal 10 should look like the above. Notice that the description does not offer a way to select a text format. We have yet to migrate them so at the moment only the default Plain text format exists. When more formats become available, it will be possible to choose from them based on the user's permissions.

From field collections to paragraphs

Field collection was a very popular module in Drupal 7. It has no Drupal 10 version, but the Paragraphs module can be used as a replacement. Paragraphs also offers an automated migration for moving configuration and content from Drupal 7 field collections. This time, we will take advantage of the automation available. This was part of the lightweight migration plan from article 8.

As a reminder, our use of field collections in Drupal 7 is rather contrived. We have a single field collection named field_favorite_quote attached to the speaker content type. The field collection itself has only two fields. We could have planned a different way to migrate this data, but bare with us. We want to include examples of paragraph migrations. That being said, always evaluate what is the best content model taking into account new features or modules that become available in the most recent version of Drupal. For example, I have migrated Drupal 7 field collections into Drupal 10 double fields or other entity types altogether.

For now, copy the upgrade_d7_field_collection_type migration from the reference folder into our custom module and rebuild caches for the migration to be detected. For this migration to exist, you should have had the Paragraphs module enabled in Drupal 10 before generating the migrations with the Migrate Upgrade module as discussed in article 10.

cd drupal10
cp ref_migrations/migrate_plus.migration.upgrade_d7_field_collection_type.yml web/modules/custom/tag1_migration/tag1_migration_config/migrations/upgrade_d7_field_collection_type.yml
ddev drush cache:rebuild

Note that while copying the file, we also changed its name and placed it in a migrations folder inside our custom module. After copying the file, make the following changes:

• Remove the following keys: uuid, langcode, status, dependencies, field_plugin_method, cck_plugin_method, and migration_group.
• Add two migration tags: paragraphs_type and tag1_configuration.
• Add key: migrate under the source section.

After the modifications, the file should look like this:

id: upgrade_d7_field_collection_type
class: Drupal\migrate\Plugin\Migration
migration_tags:
 - 'Drupal 7'
 - Configuration
 - paragraphs_type
 - tag1_configuration
label: 'Paragraphs - Field Collection type configuration'
source:
 key: migrate
 plugin: d7_field_collection_type
 add_description: true
process:
 id:
   -
     plugin: get
     source: bundle
 label:
   -
     plugin: get
     source: name
 description:
   -
     plugin: get
     source: description
destination:
 plugin: 'entity:paragraphs_type'
migration_dependencies:
 required: {  }
 optional: {  }

Now, rebuild caches for our changes to be detected and execute the migration. Run migrate:status to make sure we can connect to Drupal 7 and the number of field collections to import is correct. Then, run migrate:import to perform the import operation.

ddev drush cache:rebuild
ddev drush migrate:status upgrade_d7_field_collection_type
ddev drush migrate:import upgrade_d7_field_collection_type

If you get an Invalid migration IDs: upgrade_d7_field_collection_type error when trying to execute any of the migrate commands, make sure the paragraphs module is enabled in Drupal 10. This migration uses the d7_field_collection_type source plugin provided by that module. If the paragraphs module is uninstalled or not present at all in the codebase, the migrate API will filter out the migration even if the upgrade_d7_field_collection_type.yml file exists in the expected location. The example repository already adds the paragraphs module to the project. If using a different setup, install it via Composer: composer require 'drupal/paragraphs:^1.17'.

This should create one paragraph in Drupal 10 which you can review at https://migration-drupal10.ddev.site/admin/structure/paragraphs_type. Note that the name of the paragraph is derived from the Drupal 7 field name. As for the machine name, it is the Drupal 7 field name without the field_ prefix. In our case, the Drupal 7 field_favorite_quote field collection was imported as the favorite_quote paragraph in Drupal 10.

Great job! Three entity types are now migrated. In the next article, we will begin migrating the fields attached to these and other entities.

Image by Georg_Wietschorke from Pixabay