Note: The Migrate module documentation is, as befits a complex subject, always in need of improvement. The best way to contribute improvements is not comments on the documentation pages (unfortunately, there is no notification process to tell the authors of comments), but to submit a Documentation issue to the Migrate module issue queue.
For Drupal 8, see in-progress Migrate API in Drupal 8.
The Migrate module (V2) provides a flexible framework for migrating content into Drupal from other sources. It is important to recognize that the Migrate module is a developer's tool — if you do not have object-oriented programming skills in PHP, this module is not for you. The primary purpose is to provide the infrastructure for managing complex, large-scale site migrations. However, add-on modules can be developed on top of Migrate to provide a UI suitable for use by non-technical users for simpler migration cases — as an example, see the WordPress Migrate module for importing Wordpress exports into Drupal 7.
The Migrate module consists of:
- An API for defining and managing migration processes.
- A set of drush commands for running migration processes and obtaining status.
- The migrate_ui module, which provides visual status and details on defined migrations.
- The migrate_example* modules, which demonstrate many techniques used in defining migrations.
- An object-oriented architecture, allowing default behavior to be extended and/or overridden.
- Built-in support for PDO (DBTNG), XML, CSV, JSON, and native MSSQL and Oracle API sources; extendable for other sources.
- Built-in support for node, user, taxonomy term, comment, and file destinations; extendable for other destination entities and fields.
- Map tables maintain relationships between source data and the resulting Drupal objects.
- Import operations can be rolled back, allowing simple trial-and-error development of migration processes.
- Tools for managing dependencies between migrated content.
- Automated management of memory usage and framework for performance logging.
- A web UI supporting collaboration between stakeholders and implementers.
The Migrate V2 API consists of several classes representing data sources, Drupal destination objects, and the relationships between sources and destinations. This gives the migration implementer the flexibility to override any aspect of the migration process for specialized cases. Handlers also allow application-specific processing to be invoked at key points of the migration process.
The bundled migrate_ui module, in addition to displaying the current status of migration processes, presents the details of how each migration is set up - in particular, the source and destination fields available and the mappings between them. Mappings can be annotated and linked to external tickets, so stakeholders and implementers can see the reasons for particular mappings and stay a click away from full details. Mappings can also be classified arbitrarily - for example, those which require stakeholder review can be set aside in their own group and highlighted. Also, any source or destination fields which have not been either mapped, or explicitly marked as unmapped, are highlighted so they don't fall through the cracks.