Drupal Migrate API — how to bring content from another system
Content migration is part of every significant Drupal project. Migrate API is the right tool for the job — here is how it works and what to plan for.
What Migrate API is
Drupal Migrate API is a core framework for importing content from different sources in a structured way. It has three parts:
Source — where data comes from (old Drupal database, CSV, JSON, XML, REST API, Excel file, etc.).
Process — how data is transformed (renaming fields, converting values, filtering, resolving references).
Destination — where data goes (Drupal node, taxonomy term, media entity, user, etc.).
Common migration scenarios
Drupal 7 → Drupal 11
The most common migration. Drupal provides official migration modules (migrate_drupal, migrate_drupal_ui) that understand Drupal 7's data structure. These migrate automatically:
- Content types and their fields
- Users and roles
- Taxonomy
- Files and images
- Menus
- Blocks (partially)
Custom fields and modules require custom migration code.
WordPress → Drupal
WordPress has a different data model. Posts → nodes, categories → taxonomy, users → users. Design blocks (Gutenberg) do not migrate automatically — a decision is needed: convert to Paragraphs, Layout Builder, or handle manually.
Custom system → Drupal
If the old site was built in custom PHP, Joomla, TYPO3 or another system, a custom Source plugin is written that reads data directly from the old database or an API.
CSV / Excel import
For smaller datasets — product catalogues, event listings, team members. The Migrate module supports CSV natively.
How migration works in practice
1. Analysis
Before writing any code:
- What content types exist in the old system?
- How many records are in each type?
- Which fields map where?
- What data does not need to be migrated (temporary content, test content, spam)?
2. Environment
Migration is done in a separate environment, not in production. You need:
- Access to the old system's database (or an export)
- A fresh Drupal installation with the target content structure already configured
3. Migration files
YAML configuration (or PHP plugins) is written for each migration:
``yaml id: migrate_articles label: 'Article migration' source: plugin: old_articles_source key: legacy process: title: title body/value: body body/format: plugin: default_value default_value: basic_html field_image: plugin: migration_lookup migration: migrate_files destination: plugin: entity:node default_bundle: article ``
4. Testing and iteration
The migration is run multiple times: ``bash drush migrate:import migrate_articles drush migrate:rollback migrate_articles # if you need to start over drush migrate:status # overview ``
5. Final migration
In production a "freeze" is done — the old site goes read-only, the final migration runs, and the new site opens.
What migration does not solve automatically
- URL redirects — the old site may have had different URLs. 301 redirects must be set up separately.
- SEO — titles, meta descriptions, structured data need review.
- Design — content migrates, design must be rebuilt.
- Custom functionality — modules and plugins need Drupal equivalents.
How long migration takes
Simple migration (one content type, clean data structure): 1–2 days.
Complex migration (Drupal 7, many content types, custom fields, files, users): 2–6 weeks.
Read more about the migration process or contact us about your project.
Kaido Toomingas
WebPro Company OÜ
Need Drupal help?
If the article describes your situation, you do not have to read everything first. A real person will help you choose the next step.