Configuring Migrate Module for Content Migration in Drupal

This guide covers Drupal migration using the Migrate module. Picture this: you're migrating an e-commerce store with 80,000 products, order history, and user profiles from an old Drupal 7 to Drupal 10. Categories are restructured, images stored in non-standard paths, and the comments table holds 300,000 records with nested replies up to 10 levels deep. Doing this manually would take months, and errors would be inevitable. We use Drupal's built-in Drupal ETL framework — the Migrate module — which extracts, transforms, and loads data. Over five years, we've completed 50+ migrations, ensuring data integrity (99.9% rate) and full compliance with the new structure. With proper configuration, Migrate processes 10,000 records in 15–20 minutes, achieving over 10,000 records per hour. Our typical migration costs range from $500 to $3000 depending on complexity. Reach out to us for a project audit and an optimal migration plan.

Architecture of Migrate

The module consists of three logical components configured via YAML files:

• Source — data source: CSV, SQL, JSON, old Drupal 7, WordPress, any API.
• Process — transformation: field mapping, format conversion, enrichment via plugins.
• Destination — where to write: Node, Term, User, File, Config.

Each migration is defined in a config/install/migrate_plus.migration.*.yml file. We use Migrate Plus, Migrate Tools, and additional source plugins. All migrations inherit from the base Migration class.

Migrate is typically 10x faster than manual transfer when comparing development and execution time.

How to Set Up a Migration in Drupal?

The process involves six steps:

1. Analyze source data: structure, types, relationships, volume. For example, determine that categories are stored in a separate table and images are external URLs.
2. Design migrations: field mapping, select source plugins, define dependencies (e.g., categories first, then articles).
3. Implementation: write YAML, custom plugins, test on a sample of 10–20 records.
4. Testing: verify integrity, regression, fix errors — run on a full copy.
5. Execution: phased import with monitoring, rollback if needed.
6. Support: adjustments for new sources, updates after Drupal releases.

What Data Sources Are Supported?

According to the Drupal Migrate documentation on drupal.org, the module natively supports CSV, JSON, XML, SQL databases via PDO, and older Drupal versions (6, 7). A ready-made source plugin exists for WordPress, and custom plugins are used for arbitrary APIs. Our methods are compatible with Drupal 8 migration as well. The table below shows popular options:

Example: Migration from CSV

For CSV import Drupal, use the csv plugin as shown below.

id: articles_from_csv
label: 'Articles from CSV'
migration_group: content_import

source:
  plugin: csv
  path: 'public://import/articles.csv'
  ids:
    - external_id
  header_row_count: 1
  column_names:
    - external_id
    - title
    - body
    - category
    - publish_date
    - image_url

process:
  title: title
  'body/value': body
  'body/format':
    plugin: default_value
    default_value: full_html
  created:
    plugin: format_date
    source: publish_date
    from_format: 'd.m.Y'
    to_format: 'U'
  status:
    plugin: default_value
    default_value: 1
  field_category:
    plugin: migration_lookup
    migration: categories_from_csv
    source: category
  field_image:
    plugin: download
    source:
      - image_url
      - '@filename'
    destination:
      plugin: 'public://images'
    rename: true

destination:
  plugin: 'entity:node'
  default_bundle: article

migration_dependencies:
  required:
    - categories_from_csv

Developing a Drupal custom source plugin is straightforward. Example custom source plugin for an API:

<?php
// src/Plugin/migrate/source/ExternalApiSource.php
namespace Drupal\mymodule\Plugin\migrate\source;

use Drupal\migrate\Plugin\migrate\source\SourcePluginBase;

/**
 * @MigrateSource(
 *   id = "external_api",
 *   source_module = "mymodule"
 * )
 */
class ExternalApiSource extends SourcePluginBase {
    public function getIds(): array {
        return ['id' => ['type' => 'integer']];
    }

    public function fields(): array {
        return [
            'id' => 'Record ID',
            'title' => 'Title',
            'content' => 'Content',
            'tags' => 'Tags (comma separated)',
        ];
    }

    protected function initializeIterator(): \Iterator {
        $page = 0;
        do {
            $response = \Drupal::httpClient()->get(
                'https://api.external.com/posts?page=' . $page,
                ['headers' => ['Authorization' => 'Bearer ' . $this->configuration['api_key']]]
            );
            $data = json_decode($response->getBody(), true);
            $items = $data['items'];

            foreach ($items as $item) {
                yield $item;
            }

            $page++;
        } while (!empty($items) && $page < $data['total_pages']);
    }
}

Avoiding Duplicates When Re-running Migration

Use highwater mark or track_changes: true in the source configuration. Then only new or modified records are migrated. This is especially useful for incremental migration after the initial import. Example configuration:

highwaterProperty:
  name: updated_at
  alias: u

Media Files Migration and Incremental Import

Media files migration involves images and files migrated in a separate YAML config, then linked to entities via migration_lookup. Example file migration:

id: files_migration
source:
  plugin: csv
  path: 'public://import/files.csv'
process:
  filename:
    plugin: callback
    callable: basename
    source: file_url
  uri:
    plugin: download
    source:
      - file_url
      - '@filename'
    destination:
      plugin: 'public://migrated'
destination:
  plugin: 'entity:file'

In the node migration, the field_image field uses migration_lookup to reference the uploaded file.

What Is Included in Our Content Migration Services?

Deliverables: As part of a turnkey solution, we provide:

• Documentation of migration structure
• Repository access with configuration
• Performance optimization: batch size, highwater mark, parallel processing
• Training for your developers on using Migrate
• One month of support after launch
• Guarantee of uninterrupted site operation during migration
• Cost: $500 - $3000 depending on complexity

Timeline

Simple migration from CSV (500–5000 records) — 2–3 days. Complex migration from multiple sources with custom plugins and transformations — 1–2 weeks. Exact timeline determined during a free audit.

Why Migration with Migrate Is Better Than Manual Transfer?

Migration via Migrate is not only about speed but also integrity assurance. We use best practices: highwater mark, track_changes, continue-on-failure. Our engineers hold Drupal certifications and have experience with projects exceeding 500,000 content records. Contact us to discuss your task. Get a free migration consultation.

Website Redesign and Migration: CMS Change, SEO Preservation

A client came to us 6 weeks after a self-attempted redesign: 'We moved from WordPress to Tilda, traffic dropped by 70%.' I opened Google Search Console — 847 pages returned 404, the URL structure had completely changed, not a single 301 redirect was in place. Yandex hadn't reindexed the new site yet, positions collapsed. Recovery took 4 months and resulted in significant revenue loss for the quarter. Our experience — over 7 years and 80+ successful migrations, we guarantee position retention with the right approach.

Why Do Migrations Break SEO?

Search engines have indexed specific URLs. If /catalog/shoes/nike-air-max-270 turned into /products/nike-air-max-270 without a 301 redirect — all the link equity, traffic, and rankings go nowhere. Google says 301 passes ~99% of PageRank, but in practice positions recover over 2–8 weeks, not instantly.

Commonly, SEO gets broken not out of malice, but because a developer doesn't view the URL structure as a public API. Here are typical breakages:

How to Recover Traffic After a Failed Migration?

If traffic dropped, act immediately:

1. Crawl the new site for 404s and compare with the pre-migration URL list.
2. Create redirects for all lost pages with traffic >0.
3. Check structured data and meta tags on a test sample.
4. Daily monitor Coverage in Search Console and positions for top 50 queries.
5. If after 2 weeks traffic does not recover — deep audit of redirects (transitivity, chains, loops).

In our practice, a large e-commerce site lost 50% of traffic when moving from Bitrix to React + Strapi. We restored 95% of redirects in three days, and within 3 weeks traffic returned to 90% of original.

What Does a Pre-Migration Audit Include?

Before starting development on the new site:

1. Full crawl of current site via Screaming Frog or Sitebulb. Get list of all indexable URLs with traffic from Google Search Console.
2. Export all pages with organic traffic >0 over the last 6 months — these are priority for redirects.
3. Record all external backlinks to specific pages — Ahrefs, Semrush.
4. Snapshot current positions for key queries — baseline for post-migration comparison.
5. Save Core Web Vitals from Search Console for the previous 90 days.

Table for recording:

Contact us for a detailed pre-migration audit — we will help identify all risks and create an action plan.

URL Mapping and Redirects

For projects with 200+ pages, we create a mapping table: old URL → new URL → status (301, merged with another page, deleted). Each row is verified: does the content actually migrate here?

In Laravel, redirects are handled via configuration file and middleware, not .htaccess — faster and more manageable. For WordPress → Next.js: redirects are set in next.config.js (static) and at the Nginx/CDN level for dynamic ones. Old .htaccess on shared hosting with 500+ lines of redirects is a special hell. Each redirect is checked sequentially, performance suffers. We move to Nginx map directive or Redis cache for dynamic lookup. More at Wikipedia: HTTP 301.

How to Migrate Content from Different CMSs?

WordPress → Headless CMS (Contentful, Strapi, Sanity): WordPress REST API or WP All Export to export posts, meta fields, media files. Migration script in Node.js: parse export, transform structure, upload via CMS API. Media files are reuploaded to new storage, links updated in content. Typical problem — shortcodes in WordPress content ([gallery id="123"]): need parser and transformation to new format.

1C-Bitrix → modern stack: Bitrix stores content in non-standard tables with IBLOCK_ELEMENT_PROPERTY. Direct SQL export via phpMyAdmin or Bitrix API. Transformation is the longest part due to specific Bitrix data structure.

Heavy WYSIWYG → structured content: Years of editing in FCKEditor/TinyMCE leave inline styles, non-standard tags, broken attributes. HTML sanitize + transformation to Markdown or Portable Text (Sanity) with manual check of problematic pages.

How to Preserve Technical SEO Elements During Migration?

Structured data (Schema.org) — if the old site had Product, Article, BreadcrumbList markup, they must be on the new site too. Google Search Console → Enhancement reports will show loss of rich snippets.

Sitemap XML: generated automatically, submitted to GSC a day after launch. Old sitemap remains until full reindexing.

hreflang for multilingual sites: if tags are lost during migration, conflicts between language versions in search results will start within weeks.

Open Graph and Twitter Card meta tags — often forgotten when changing template, pages stop displaying correctly when shared on social networks.

Launch and First Weeks Monitoring

DNS propagation: DNS switching takes up to 48 hours, plan launch with buffer. Cloudflare as DNS provider — propagation takes minutes, not hours.

After launch, monitor daily: Search Console → Coverage (indexing errors), Analytics → organic traffic, year-over-year comparison, crawl site for 404 errors.

First 2 weeks are critical. If traffic drops more than 30% — immediate audit of redirects and comparison with pre-migration crawl.

What the Service Includes

Results you receive:

1. Migration plan with URL mapping and redirects in Excel/Google Sheets format.
2. Configured 301 redirects at server level (Nginx/Cloudflare/Vercel).
3. Migrated content with integrity check: images, meta fields, links.
4. Structured data (Schema.org) on the new site, identical to old or improved.
5. SEO report: position trend at 1, 3, and 6 weeks after launch.
6. Coverage monitoring in Search Console with error notifications.
7. Guaranteed position retention: if traffic drops more than 15% within the first month — free audit and correction.

Timelines and Estimates

• Redesign with migration for a small site (up to 100 pages): 4–8 weeks.
• E-commerce migration with 500+ product pages: 8–16 weeks.
• Only technical migration part (redirects, metadata) without redesign: 1–3 weeks.

Cost is calculated individually based on scope.

Get a consultation for your project — we will respond within a day. Order a pre-migration audit of your site and receive a detailed proposal with a redirect plan. Contact us to discuss details.