Drupal Migrate API — how to bring content from another system

🎧 Listen to every article back to back

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:

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:

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.

WebPro Company OÜ Technical lead: Kaido Toomingas

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.

Contact us