The Migration class is built on the fundamental assumption that there is a one-to-one correspondence between source rows coming in and destination objects going out.

If however your source data corresponds to more than one Drupal object or entity, there are several ways to deal with this depending on the complexity of the different destination objects.

Create dependent objects on the fly

If you have simple objects as dependencies of a more complex one, you can create these on the fly in your migrate class's prepareRow() or prepare() methods. This is particularly suitable if your dependent object's data is only one field in your source data.

The downside however is that these dependent objects are not cleaned up on rollback, and depending on how you make them, you may not be able to implement cleaning them up yourself (as once you've created the missing objects, you can't tell which ones were missing before).

A special case is taxonomy term reference fields, where the 'create_term' field option lets you create taxonomy terms for source data that doesn't match an existing term.

Even if your destination object requires more than one source field, it can be useful to take this approach, for example, here we create taxonomy terms on the fly taking their term name from one source field and set a field value on them based on another source field:

<?php

Using drush, individual migrations can be imported and then rolled back. Running processes can be cleanly interrupted, individual source records can be migrated on their own, and performance can be instrumented.

drush help --filter=migrate provides a complete list of relevant commands

All commands in migrate: (migrate)

File classes

File classes, implementing the PHP interface MigrateFileInterface, are the key to the file import approach. A file class represents the logic for taking a particular representation of a file (such as a URL or a database blob) and tying it to a Drupal 7 file entity in the appropriate way. Each file field mapping, or migration to a file destination, will have a file class associated with it, and that file class determines what options and fields are available when mapping it.

There are three file classes provided by the Migrate module itself:

MigrateFileUri

This is the default file class - the one that will be used if you don't specify a file class. When using this class, the primary value (the value you map to a file or image field, or to 'value' in MigrateDestinationFile) is taken to be a URI or a local filespec, and the assumption is that the resource referenced will be copied into a Drupal file scheme.

It takes the following subfields and options:

The central class in the Migrate module - the one you'll spend most of your time dealing with - is the Migration class. You derive your own classes from Migration, each of which represents the migration of data from a given source (such as a query against a source database) to a given Drupal destination (such as nodes of a specific content type, like 'article').

You embed in this class instances of four other classes:

This Cookbook shows, how you can add a translation of the module A Wusel Migration (http://drupal.org/node/1285276).

This Cookbook shows, how you can add a help page to the module A Wusel Migration (http://drupal.org/node/1285276).