Drupal 8/9 Migration: Migrating Media Items and Their Relationships

High Score Labs News   •   Apr 19, 2021

After the release of Drupal 8.5, it became obvious to organizations using Drupal that they will eventually need to stop using Media Equity and embrace the use of media in core. If you are migrating from an earlier version of Drupal to Drupal 8.5 or beyond, it is important that you learn how to migrate media items and their relationships.

In case you aren’t conversant with the way migrations are done on Drupal. Migrating tools like migrate_tools and migrate plus are important for the success of the process. To follow the suggestions outlined in this article you need to install Drush.

Here is an example, let us assume that we are working on a database Dump & files Backup.

  • We will extract files from articles and send them to Drupal 8.
  • We will develop media items for all migrated files.
  • We will include all related media items after migrating articles to Drupal 8.
  • Migration set up

Create a module for the migration

The first thing to do is to create a new module for migration and name it as you want. But for the sake of this example, we will use migrate_example_media.

Thereafter, the following modules from Drupal.org are added as dependencies in the module declaration.


  • Generate a Migration Group

We can create a migration group to help us group the migrations. To achieve this, a fairly simple configuration file will be created. Thereby, helping to create a group immediately after the creation of the module.

  • Determine a new database connection

The next line of action is to load the database from the earlier version (Drupal 7 in this case) to Drupal 8. You can achieve this by defining a new database connection in settings.php.

Thereafter, import the aforementioned data base_dump into the new database. You can do this with any method you’re comfortable with.

  • Writing the migrations

It’s now time to write the actual migration. According to the requirements mentioned earlier, three migrations will be written. The first is for files, the second is for media and the last for articles.

Admittedly, it is possible to make configuration entities as your migrate_plus module. However, it is preferable to go along with the core recommendations. The latter is easier to develop.

  • Writing the file migration

The file migration is the first migration to write. To conserve time, you can place the file backup in a migratefile folder. And during the migration, you can copy the files from the right folder.

  • Writing the media migration

Media migration uses d7_file as a source. It’s good to use the step_on_value plugin temporary temp1 field. This will help skip all files that are not categorized as images.

  • Writing the article migration

Similar to every other entity migration. You can use the sub_process and migration lookup to set the image.

  • Run the migration

Because we already set the dependencies, we can run the migration group by instructing Drupal to do so. Other steps or elaborations will be considered in subsequent articles.

Contact us today!