Moving data from a different technology, such as migrating an old website from Drupal 6 or importing a database of news articles into Drupal 8, can be a daunting task. In Drupal 7, data migrations were possible using the contributed Migrate [1] module. The new Migrate API in Drupal 8 is based on the same methodologies for moving your data into Drupal (see the "Experimental Status" box). The Migrate API is excellent for upgrading from Drupal 6 or 7 and for one-time imports of large datasets. In this article, I look briefly at Drupal-to-Drupal upgrades and provide an in-depth example of migrations, including custom Source, Destination, and Process plugins.

Drupal-to-Drupal Upgrades

The Migrate API comprises three modules in Drupal 8 core (Figure 1). You might need to enable one, two, or all three modules depending on your requirements. The Migrate module contains the main API used to define and run migrations. Migrate Drupal provides plugins for upgrading from an older version of Drupal. Migrate Drupal UI contains the interface for the official upgrade from Drupal 6 or Drupal 7. Before diving into custom migrations, I'll take a quick look at the Migrate Drupal UI module.

Figure 1: Core migration modules.

In theory, the Migrate Drupal UI module is a one-stop shop for Drupal upgrades. To try it out, make sure you are logged in as User 1 and navigate to the upgrade form at /upgrade. Follow the prompts to connect to an old Drupal 6 or 7 database and click Review upgrade (Figure 2). The module builds all the migrations needed for an entire upgrade.

Figure 2: Drupal upgrade form.

The upgrade process has been tested for core upgrades but depends on contributed modules providing their own upgrade paths. Most Drupal sites use many contributed modules, and after you click Review upgrade , you will see a list of missing upgrade paths (Figure 3). Before you can use this UI, you will need to wait for contributed modules to provide an upgrade path or create your own. Drupal-to-Drupal upgrades via the UI are all or nothing.

Figure 3: Migrate Drupal UI with missing upgrade paths.

A better solution (for now) is to build your own custom migrations (see the "Migration Help Hint" box) by building a new Drupal 8 site from scratch, including content types and other configurations, instead of migrating everything; then, run custom migrations to import discrete pieces of content from the old site. Building a new site from scratch lets you use the latest modules and best practices instead of working around a legacy system. This method also gives you an opportunity to clean up data as it is imported.

Custom migrations are also used if you are migrating data from a non-Drupal source.

Building Custom Migrations

To write custom migrations, you should be comfortable managing Drupal 8 configurations in the YAML format. For more advanced migrations, you should be able to perform basic object-oriented tasks like extending a class, overriding methods, implementing an interface, and working with PHP annotations.

A Drupal migration is a configuration object consisting of a source and a destination. The source could be another database, a .csv-formatted file, or even content scraped from an HTML document. The destination is a component of Drupal where data is saved, such as an entity (node, user, etc.) or configuration (content type, vocabulary, etc.). When the migration is executed, a row of data is fetched from the source, and each field is mapped to the destination using a process plugin. Different process plugins are used to manipulate the data before it is saved to the destination. Figure 4 shows this migration workflow.

Figure 4: Migration source, process, and destination workflow.

Two contributed modules help configure and run custom migrations: Migrate Plus [2] and Migrate Tools [3]. Migrate Plus provides additional API tools and allows you to group similar migrations. It also includes a number of example migrations. Migrate Tools adds Drush commands to list, import, and roll back individual migrations. As of this article, Drush is the only way to run custom migrations, but a UI is currently in progress. You can follow the UI progress in the Migrate Tools issue queue [4].

Migration Example: Pets

Looking at an example is a great way to learn. Imagine you have a database full of information about dogs and cats and their owners. You just built a Drupal 8 website with a Pet content type and want to migrate the pet data. Pet owners become Drupal user accounts and pets are imported into Pet nodes. In the source database, the Pet table contains five fields:

• pid – Unique pet ID
• oid – Owner ID
• type – Type of pet (dog or cat)
• name – Pet's name
• picture – Photo of the pet

The Owner table contains three fields:

• oid – Unique owner ID
• name – Owner name
• email – Owner's email address

To import this data, you need to create two migrations and a migration group, along with custom source, destination, and process plugins.