With the upcoming Drupal 8.1.0 release on April 20th, Migration will become a non-experimental part of Drupal core, with it’s powerful UI and rollbacks provided out-of-box. Some parts of these blog posts should become outdated as well, but we will do our best to keep updating them.

Let’s start from the beginning. The whole Migrate API was totally rebuilt for Drupal 8. For writing or customising your migrations, you should be familiar with the Plugin API, the OOP paradigm and the YAML file structure. 

Migrate API consists of multiple plugin types and one YAML file called the migration template. Plugins process data in each part of the migration process and the migration template glues these plugins together. For each migration, you will probably use at least three plugins: source, destination and process.

The source plugin, as its name implies, is used for describing the original data source. In this plugin you will need to implement several functions:

function fields() - in this function, you will need to define fields, which will be available for mapping in the process section in the migration template. You need to define an associative array of machine names and human-readable names. Machine names are used for mapping. Human-readable names can be translated, but to be honest, I’ve never seen this during migration execution.

function query() - in this function you need to build a database query for the original database. You will use the methods defined in SelectInterface in Drupal core.

function prepareRow(Row $row) - this function can perform operations on a single record obtained using the defined query. You can modify and fill some custom fields in this function.

getIds() - in this function you will define which fields are unique and their types.

The destination plugin describes new data sources. You don’t need to define this plugin for your custom entity if you don’t want any additional parameters. Examples of custom destination plugins are User and File.

The process plugin is a plugin you will probably never need to define. The Migrate module in Drupal core provides several migrate plugins covering all standard use cases. All of these plugins are described quite well in the official Drupal documentation. You will use these plugins for performing some operations, or setting the default value of a single field.

As I mentioned in the beginning, you need to glue these plugins together in the migration template. Let’s have a look at the migration template in some use cases.

The most common use case will probably be related to a change of the entity structure. First of all, you will need to find the YAML migration template. It is usually located in MODULE_NAME/migration_templates. Let’s use the most common entity in Drupal - node. You will find migration templates for nodes in core/modules/node/migration_templates. As you can see, there are multiple migration templates, depending on which version of Drupal you are performing the migration from.