Migration classes

Last updated September 15, 2012. Created by mikeryan on December 24, 2010.
Edited by loopduplicate, radiobuzzer, Vacilando, derhasi. Log in to edit this page.

The Migrate module provides an abstract class named Migration - in most cases, you'll do nearly all your work in extending this class. The Migration class handles the details of performing the migration for you - iterating over source records, creating destination objects, and keeping track of the relationships between them. All you need to do is

1. Define where the source data is coming from.
2. Define the destination object type and "bundle" (where appropriate).
3. Define mappings from source fields to destination fields.

In doing so, you will make use of other classes provided by Migrate - some you can use as-is, some you may have need to override.

Here is an example of a bare-bones (but fully-functional) migration (source data not included). Scroll down to get the detailed explanation of what every piece of code does:

This code can be place in the .module file. A common practice is also to create separate .inc files for different migrations or groups or migrations, so that your code in each file is not too big. All files (with a suffix of .inc or .module) that contain class declarations should be included in the .info file.

Once you have defined this migration class (and created the necessary .info and .module files, and enabled your module), you should be able to see your migration class with the command:

drush migrate-status

As you see, the name of the migration defined by the ExampleMigration is Example (as shown on the first column).
If you have a table in your Drupal database named example_pages, with pgid, page_title, and page_body fields in it,

drush migrate-import Example

will create a Drupal page node for each row in the example_pages table. Then, running

drush migrate-rollback Example

will undo the import, deleting the pages that were initially created. And you accomplished this with 20 lines of code! How did you manage it? Let's take it apart piece by piece:

Class declaration

First, the basic overhead of extending a class and overriding its constructor:

This says that the class we're declaring, ExampleMigration, will behave exactly like the Migration class except for any behavior we override. Then, we override the class constructor - this is the first method to be called when an instance of the class is instantiated. In almost all cases, you begin a method by calling the parent's implementation of that method - usually, you are adding behavior to the base class, so you want to make sure that the base class does its thing.

Note the parameter to the parent constructor. What we're doing here is saying that ExampleMigration will be part of a group named 'example' (if we had simply called parent::__construct(), it would be part of the 'default' group). We can then run only migrations from this group thusly:

This may be useful if you have many migrations which fall into logical groups - say, a group for importing from a MySQL database, and another group operating off XML feeds. Migration groups may depend on other groups being migrated first. From wine.inc: "The second argument to MigrateGroup::getInstance is an array of groups which should come before this when viewing migration statuses, or running migration operations using --all." See the wine example in migrate_example for more detail.

Define Source

Next, we identify where our source data is coming from:

In this case, because our data is (conveniently!) in a table in our Drupal database, we can use the Drupal 7 Database API (on Drupal 6, this is provided by the DBTNG module) to define a query for the data. It is important that this query return one row containing all the data for what will become a single page - dealing with cases where the data might span multiple rows (e.g., if we also joined to a category table with multiple rows per page) is a little more advanced and is discussed here.

Once we've constructed the query, we use it to create a MigrateSourceSQL object and save it in our ExampleMigration object.

Define Destination

Next, we identify what we want to create from the source data:

That was even easier than the sources - we just told the migration module we want to create nodes of type page, or in Drupal 7 parlance: bundle.

Mapping Source and Destination

Next, we tell the migrate module how source and destination records are related.

To track migration status, and allow rollback, the migrate module needs to remember what source record resulted in the creation of which destination object. It does this using a MigrateSQLMap class - this class creates database tables which map source and destination keys. To do this, it needs to know what data types the respective keys are. Thus, we pass in schema arrays declaring the respective source and destination keys. For the source key, since the migrate module knows nothing about the source table, you need to explicitly define the schema array (making sure that the key of the array, pgid in this case, matches the field name used in the query passed to MigrateSourceSQL above). On the other hand, since we're using the canned class MigrateDestinationNode, it knows what the correct schema is already and can provide it through the static method getKeySchema().

Oh, and the machineName passed as the first argument? MigrateSQLMap will create a map table and message table for each migration, and will name them by prepending migrate_map_ and migrate_message_ to this parameter. It is a handy convention to pass your migration's machine name here, so that the names are unique and it's easy to identify what migration they're associated with, but you could pass a different suffix here if you prefer.

Note: If you got ambiguous columns for your sourceKey due to multiple joins in the source query, you can set alias in your sourceKey definition to the specific table alias.

Field mapping

Finally, we define data mappings:

This tells the migration that, for each source row processed, to take the page node title from the source row's page_title field, and the node body from the page_body field. When looking at an addFieldMapping() call, remember that the destination field is the first parameter and the source field is the second parameter. Think of it like an assignment statement: