In previous posts, we have provided tips and tricks for a successful Drupal migration from earlier versions of the content management system to the latest Version 8. In this installment of our series, we will talk about the Drupal 8 Migrate Plugin System.

About Drupal 8 Migrate

The migrate module has been moved into the core in Drupal 8, showing the community dedicated to making the process of upgrading between versions or migrating into Drupal an easier path to a successful move. The migrate module takes advantage of the Drupal 8 Plugin system, offering developers several Plugin types that they can implement: MigrateProcessPlugin, MigrateSourcePlugin, MigrateDestinationPlugin.

In an earlier blog post in this series, we dove into an introduction of the Migrate module in Drupal 8 and reviewed a basic setup of the migration mappings needed to get started. In this post, we will dive into MigrateProcessPlugins: what they are, how they work and examples on how to create your own.

What is a Drupal 8 Migrate Processor?

A migration processor is a plugin that is used to manipulate data that is being mapped from a source to a destination. These plugins are typically small, but very powerful. Processors are used in the “process” portion of your migration configuration file.

Drupal 8 comes with several migration processors out-of-the-box. Some of the more notable ones that you will likely use on a regular basis are:

  1. get – Default, 1:1 data migration plugin
  2. default_value – Allows you to define a default value for a field
  3. explode – Converts a string into an array of strings based on a delimiter
  4. iterator – Iterates over an array of values to perform a process on
  5. migration_lookup – Looks up an entity based on an ID from a source to a destination
  6. skip_on_empty – Skips the current field or row if the value is empty in the migration

What Are the Benefits of Using a Drupal 8 Migrate Processor?

Migration process plugins provide developers with more flexibility and reusability when working with migrations in Drupal 8. By utilizing the Drupal 8 Plugin system, the Migrate module allows users to create new processors that implement a generic interface and can essentially be plug and play. In addition, the OO design of the plugin system allows developers to utilize inheritance of abstract classes and enforcement of methods if they have several variations of a plugin, without reinventing the wheel or duplicating code every time.

In English, this means that I can develop my own processors that manipulate data from my data source in any way that I want, and then reuse it across any migration that needs to use it.

How Does a MigrateProcessPlugin Work?

If you are finding that the out-of-the-box MigrateProcessPlugin’s are not enough for your use case, you may want to consider creating a new custom MigrateProcessPlugin. Creating a new process plugin in Drupal 8 is a fairly simple task.  

Let’s take a look at a simple MigrateProcessPlugin as an example to get us started.

In the DefaultValue MigrateProcessPlugin, we only have one method that is implemented, called “transform”. Transform takes in a value that is passed in by the user, checks to see if it is set, and sets that value for the field in the destination mapping.

How Do I Use a Process Plugin in My Migration?

Using a process plugin in your migration is relatively simple. If you have written a migration before, you have used these without even knowing it. Let’s take a look at the example below:

In this example, you will notice several plugins are utilized:

  1. get: The “get” plugin is the default plugin. Any mapping that does not have a child element defining a plugin will utilize the “get” plugin
  2. default_value: In this example, we are setting the user ID of a blog_post to user 1

When am I Going to Need a Custom Processor Plugin?

Before you venture down the path of creating custom processors, ask yourself the following questions:

  1. Can any of the existing process plugins, or a combination of any of the existing process plugins, manipulate the data to the format I need?
  2. Is the data transformation something that follows a pattern?
  3. Is this processing/data manipulation something that will need to be used for more than one migration?
  4. Is this a transformation that other users/migrations may benefit from?

If the answer to any of the questions above is “YES”, it is worth your time to create a custom processor plugin.

Stay tuned for our next blog post in our migration series on custom processors. In this post, we will dive into what it takes to create a custom processor for a WordPress to Drupal migration.

Would you like help to create a more detailed plan for migrating your website to Drupal 8?

Contact Us – We would be happy to help!

About Drupal 8 Migrate

The migrate module has been moved into the core in Drupal 8, showing the community dedicated to making the process of upgrading between versions or migrating into Drupal easier. The migrate module takes advantage of the Drupal 8 Plugin system, offering developers with several plugin types that they can implement: MigrateProcessPlugin, MigrateSourcePlugin, and MigrateDestinationPlugin.

Quick Recap of our previous blog:

  1. Complete rewrite & moved into Drupal 8 core
  2. Out of the box support for D6 -> D8 and D7 -> D8
    1. Nodes, Users, Comments, Profiles, Taxonomies
    2. Content & Configuration
  3. Support for custom sources and destinations
  4. Processors for working with/manipulating data

Series Mapping:

Part 1: Migration Setup & Mappings

Part 2: Working with Processors

Part 3: Coming soon!

Drupal 8 Migrate Module Overview

The Drupal 8 migrate module that is shipped with core provides a set of API’s for setting up migrations. The module also provides extensible object-oriented base classes and interfaces for migration plugins including:

  1. Source & Destination Plugins
  2. Process Plugins
  3. Config Migration Mappings

While the migrate module has been moved into core, the contributed space still provides significant value and I wouldn’t recommend trying to build a migration without it:

  1. Migrate Plus: The Migrate Plus project provides extensions to core migration framework functionality as well as examples.
  2. Migrate Tools: The Migrate Tools module provides tools for running and managing Drupal 8 migrations.

Creating Migration Mappings

In Drupal 8 all of your migration mappings are done through configuration files. In Drupal 7 these migration mappings would have been done in classes through the $this->addMapping() function.

Configuration files provide the blueprint for the migrations, and there are two main types of configuration files that we will need to define:

  1. migrate_plus.migrate_group.<name>.yml
  2. migrate_plus.migrate.<name>.yml

Migration Group

The migration group is a configuration file and is similar to the idea of hook_migrate_api in Drupal 7. This configuration file defines a group of migration classes and configures global configuration/settings to be shared across the classes.  

  1. id – Unique identifier
  2. shared_configuration – Defines shared configuration between all migration classes that are part of this group. **Example: setting the source database to use
  3. dependencies – Sets the dependencies for this set of migration classes to function

Let’s see an example:

Migration Configuration File

The migration configuration file is similar to a migration class in Drupal 7. At a high level, the migration config file defines the metadata and field mappings for a particular migration in Drupal 8. There are 5 key concepts that you need to be aware of in the migration configuration file:

  1. Definition – The definition of this migration class, its dependencies, and what migration_group it belongs to
  2. Source – What migration source should be used for this migration when it is run (i.e. where am I migrating my content from?)
  3. Destination – The destination for the migration (i.e. where am I migrating my content to?)
  4. Field Mappings – The mappings from Source -> Destination
    1. Processors – The processing of the source data so that it can be consumed by the destination

Let’s see an example:


Stay tuned for our next blog post in our migration series on custom processors. In this post, we will dive into what it takes to create a custom processor for a WordPress to Drupal migration.

Would you like help to create a more detailed plan for migrating your website to Drupal 8?

Contact Us – We would be happy to help!