Drupal Migrate API: An Overview of the Migration System in Drupal 8

About to migrate your website from... Drupal 7 to Drupal 8? Or maybe from an external data source to Drupal 8? The good news is that Drupal Migrate API, the migration system in Drupal 8, is extremely powerful and conveniently flexible.

The "trick" is that you should be familiar with all its robust features, hidden gotchas and planning steps to take.

But, fear not: we've got you covered.

Here's a quick-start guide to migrating in Drupal 8, which covers both Drupal-to-Drupal and external data store-to Drupal migration scenarios.
 

1. But First: What Is Drupal Migrate API?

It's Drupal's robust migration system that enables you to pull data from various sources and to "inject" them into... Drupal (duh).
 

And the entire framework is made mostly of... migration plugins:
 

• source plugins
• process  plugins
• destination plugins
   

It's these migration plugins that are responsible for extracting, transforming and fitting data into the Drupal 8 destination website.

2. A System Designed to Pull Content to Drupal from... Any Source

One of the Drupal Migrate API's most powerful features is extracting content from... pretty much anywhere:
 

• XML
• previous versions of Drupal
• MariaDB, MySQL
• JSON
• CSV
• other platforms (e.g. WordPress)
   

The overly simplified Drupal 8 migration process would look something like this:
 

1. connect the Drupal Migration API system to your external datastore
2. write your custom migration paths
3. transform the source data into a suitable format to fit perfectly into the content types and fields in your destination Drupal website
    

3. Consider Creating Your Own Custom Source Plugin

Is there no way to pull content from your source? Then you'll need to write your custom source plugin to map the extracted data to its destination fields.

A plugin that suits your own migration scenario to the slightest detail.

For instance, mapping the titles and subtitles of the... blog posts on your current WordPress website to the article node type's titles and subtitle fields in your Drupal 8 destination website.

IMAGE Image by Ulrike Mai from Pixabay  

You'll need to define the specific fields in your source data to the Drupal 8 Migrate API so that it should perform a proper mapping.

4. Process Plugins: The Key Elements in the Drupal 8 Migration Process

They play a critical role in any Drupal 8 migration, being responsible for converting the source data into the appropriate format. 

Here are just a few examples of process plugins "in action" during the migration process:
 

• they import data behind HTTP authentication
• they parse images from text
   

Image source: Drupal.org 

5. The Migration System Handles Everything... "The Drupal Way" 

The unparalleled flexibility of the Drupal Migrate API resides in its way of handling each operation... the Drupal way.

It's "smart" enough to automatically import and validate the source data into the right fields of the destination site. It's designed to "understand" how to adjust the imported data to the various fields, entities, and configurations specific to your Drupal 8 destination website.

In short: the Drupal 8 migrate system makes it easy for you to handle all migration operations the... "Drupal way".
 

6. Drupal 8 Migration Modules that Extend the System's Functionality

Now, let's say that, although extremely powerful, the Drupal Migrate API framework doesn't meet all your functionality requirements. You can always enhance its flexibility with migration modules that serve your particular migration needs.

Here are just 3 examples:
 

Migrate Plus

It adds extra features to the framework such as an URL source plugin that makes it possible for you to pull data from XML, Soap, and JSON file formats.
 

Migrate Tools

The module provides tools for various running and managing migration operations. Here are just some of the Drush commands triggering such operations:
 

• migrate-import – it will run a migration.
• migrate-status – it will display all migrations and their status
• migrate-rollback – it will roll back a migration

Migrate Source CSV

It enables you to import CSV files to your Drupal 8 destination website.
 

Migrate Spreadsheet

It makes it possible to extract data from spreadsheet files...
 

7. External Data Source to-Drupal Migration: A 4-Step Guide

Now, let's talk facts.

Or, better said: the essential steps to take for migrating your content from an external source to Drupal 8.
 

1. first, enable the Drupal 8 Migrate module
2. next, install both Migrate Tools and Migrate Plus for the Drush migration commands and a whole variety of much-needed extensions and plugins
3. set up a custom module for your specific migration case
4. use YAML configuration files for field mapping from the right data source; trigger your process plugins to convert data to the right format
    

Note: your config files should get stored in “my_migration_module/config/install/“.

8. Drupal-to-Drupal 8 Migration: A 2-Step Guide

If it's a Drupal-to-Drupal migration challenge that you're facing, here's the whole process brought down to its key steps:
 

1. run the "migrate-upgrade" command in Drush using the "-configure-only" flag to trigger stub YAML configurations    Upgrade Using Drush
2. copy the resulting YAML files into the config/install directory of your custom module (remember to give them proper names and to edit them)
    

9. Final Word

The Drupal Migrate API is highly flexible and, therefore, very powerful. 
 

It's designed for a whole variety of migration scenarios, of different levels of complexity: from importing a collection of blog posts to... pulling hundreds of thousands of nodes.
 

And yet, with great flexibility comes great complexity:

Since every website's user-generated content architecture is different, every Drupal 8 migration is highly website-specific.

With no "one-size-fits-all" type of standards at hand, you're at the same time free and "constrained" to... customize your migration to your specific needs.

Better said: with great flexibility comes... great(er) responsibility.


Main image by wandaquinn from Pixabay