Part 2: Working with Processors – A Developer’s Walkthrough of the Drupal 8 Migrate Module

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!