Last updated August 4, 2014. Created on November 5, 2013.
Edited by chx, mikeryan, michaellenahan, YesCT. Log in to edit this page.

[Note: the Migration API is, as of December 2013, still a work-in-progress and not yet complete. This documentation will describe the intended form of the API, but expect further change before the release of Drupal 8].


The Migration API provides services for migrating data from one place to another (usually, importing it into Drupal entities). The migrate module implements the general-purpose framework, while migrate_drupal builds on that foundation to provide an upgrade path from Drupal 6 and Drupal 7 to Drupal 8.

The easiest way to understand migrate is to start with import: the source plugin provides rows. Each row is handed over to a series of process plugins and finally to the destination plugin for saving.

For each row, both source and destination have properties and values. For example, when importing nodes, sticky is a property with possible values of 0 and 1. Some of the properties are identifiers, for example uid for users or retailer and SKU for a product import.

Identifiers enable us to track changes and more. Once the destination plugin saves the row and the destination identifier values are known, we save the values of the source identifiers, the values of the destination identifiers and the row hash in an identifier (id) map. The source identifier and the hash in the map allows for tracking changes for continuous migrations. The source identifier and the destination identifier allows for looking up values based on a previous migration -- if a source had user uid 44 which became user uid 56 on the destination, a source node authored by uid 44 needs to be able to look up that 56.

Highwater marks offer another way to track changes. This requires the source to have a property (the highwater property) telling when did the record change last, like the node changed property. If there is a highwater property we can import in changed order and save the changed timestamp of the last successfully imported record.

All the configuration is kept in a migration configuration entity.

A configuration contains four keys typically: id, source, process, destination. The first is a simple string, the identifier of the migration. The rest will discuss each in their respective child pages.

There is a tutorial on writing entity migrations.

Looking for support? Visit the forums, or join #drupal-support in IRC.