Migration Drupal Development

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.

Subscribe via RSS
Kaido Toomingas 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.

Contact us