Introduction

Migration Assistant moves the content of a Drupal 7 site into an existing
Drupal 11 site through a guided admin UI, built on the core
Migrate API.
You don't have to write migration YAML by hand.

You connect a Drupal 7 database, and the module analyzes it and suggests a
mapping of content types, vocabularies, paragraphs, field collections and
fields onto your new site. It can also create the bundles and fields that are
missing. It then generates real migration plugins, validates them, lets you
preview the processed values without saving anything, and runs imports,
updates and rollbacks in time-boxed batches with per-migration status and
error messages.

Project Summary:
A mapping-driven Drupal 7 → Drupal 11 content migration UI for the
"rebuild first, then bring the content over" project, rather than an
in-place full-site upgrade.

Features

Source analysis: Connects to a Drupal 7 database, either
through a settings.php connection or credentials kept in
State and never exported. It checks that the database really is Drupal 7
and builds an inventory of users, roles, content types, vocabularies,
paragraphs, field collections, fields, files, menus, text formats, aliases,
redirects and languages.
Guided mapping: Maps each source bundle and field to a
target, offering only compatible target fields. Suggestions match by
machine name, then label; text formats from Drupal 6-upgraded sites are
matched by label. Missing content types, vocabularies, paragraph types,
menus and fields can be created from the Drupal 7
definitions, including list allowed values, reference targets, date
granularity and file settings.
Broad coverage: Supports users with password hashes,
roles, public and private files, media items created from files, taxonomy
terms with hierarchy, paragraphs and nested field collections, nodes,
comments, menu links, URL aliases and redirects.
Field conversions: Supports text with formats, numbers,
lists, booleans, e-mail, telephone, dates and date ranges, links, images
and files or media references, taxonomy/entity/node/user references and
paragraphs.
Safe IDs: By default, content is renumbered so that a
site that already has content is never overwritten. Internal links in
menus, link fields, aliases and redirects are rewritten to the new IDs.
Preserving IDs is an option for empty sites.
Validation before anything runs: Checks for unreachable
sources, missing or incompatible targets, unmapped required fields,
references to unmigrated bundles, missing modules, file locations, ID
collisions, unknown languages and unavailable plugins.
Preview / dry run: Runs a migration's real process
pipeline on sample rows with no writes at all. Lookups never create
stubs, no files are copied and a null ID map is used.
Execution UI: Provides import, update, limit, rollback
with optional dependent migrations, reset of stuck status and per-row
messages. Batches are time-boxed and resume where they stopped.
Standard migrations: Generated migrations are regular
migration plugins tagged Migration Assistant, so
drush migrate:import, migrate:rollback,
migrate:messages and migration_lookup all work.
They can also be exported as YAML files for a custom module.
Deployable mapping: The mapping and options are
configuration, so you can build them on a development copy and deploy
them with drush cim.
Drush commands: Provides ma-source,
ma-analyze, ma-suggest, ma-generate,
ma-validate with a non-zero exit on errors, and
ma-status for CI and scripted runs.

Post-Installation

After installing the module:

Go to People → Permissions and grant
Administer Migration Assistant only to trusted
administrators. The permission is restricted because it can create and
delete content.
Make the Drupal 7 database reachable. Ideally declare it in
settings.php as
$databases['migrate']['default'] with a read-only account.
Make the Drupal 7 files directory readable by the web server, or use the
old site's public URL.
Go to
Configuration → Development → Migration Assistant
(/admin/config/migration-assistant), open
1. Source, enter the connection and files location, and
click Save and analyze source.
On 2. Mapping, review the suggested mapping on each tab
(General, Users, Taxonomy, Paragraphs, Content, Files & media,
Menus & URLs). Choose targets or Create missing
bundles and fields.
On 3. Review & generate, resolve validation errors,
generate the migrations and use Preview to check the
values.
On 4. Execute, run a limited test import, review the
messages, then import everything. Re-run with Update to
resolve references between content migrated in different migrations.
When finished, Reset the assistant to remove the stored
source connection.

For large sites, run the import with Drush:
drush migrate:import --tag="Migration Assistant" --execute-dependencies

Additional Requirements

Drupal 11.2 or later
Core Migrate and Migrate Drupal modules
(enabled automatically)
Read access to the Drupal 7 database (MySQL/MariaDB, PostgreSQL or SQLite)

Optional, depending on the content being migrated:

Core Password Compatibility (phpass), so
users keep their Drupal 7 passwords
Paragraphs and
Entity Reference Revisions,
for Paragraphs and Field Collection content
Core Media, to turn files into media items
Redirect,
to migrate redirects
Core Link, Datetime, Datetime Range, Telephone, Options, Comment,
Menu Link Content and Path, for the matching data

Recommended modules/libraries

Paragraphs
for migrating and managing paragraph-based content.
Entity Reference Revisions
for paragraph and revision-aware entity references.
Redirect
for managing migrated redirects.

Similar projects

The core Migrate Drupal UI module performs an in-place
upgrade of a whole Drupal 7 site. It recreates the Drupal 7 configuration
and content model on an empty Drupal 11 site.

Migration Assistant targets a different workflow: a site that has already
been rebuilt, with its own content model, receives Drupal 7 content through
an explicit, reviewable mapping. You choose which bundles go where, which
fields map to which, and what should be created.

Migrate Plus and
Migrate Tools
provide building blocks for hand-written migrations, including YAML
configuration, groups, extra plugins, Drush commands and UI tooling.
Migration Assistant generates migrations from the analysis and mapping,
while the resulting migrations continue to use the standard Drupal Migrate
API and Drush commands.

Migrate Upgrade
exports core upgrade migrations as configuration for further hand editing.
It does not provide the same analysis, mapping UI, structure creation,
validation or preview workflow.

Supporting this Module

Bug reports, feature requests, patches and documentation improvements are
welcome through the Drupal.org issue queue.

Community Documentation

The project's README covers the full workflow, production checklist,
field conversion table, ID and link-rewriting model, Drush usage, known
limitations and troubleshooting.

docs/D7_DATABASE_SETUP.md explains how to load a Drupal 7 dump
and connect it locally with DDEV or on a server.

Permissions

Administer Migration Assistant: Configure the source
database, edit the mapping, create bundles and fields, generate, preview,
run and roll back migrations. Restricted.

Architecture

SourceConnection: Stores and opens the Drupal 7
connection in the core database_state_key format, so
credentials never reach configuration or the plugin cache.
SourceAnalyzer / TargetAnalyzer: Build the Drupal 7
inventory and describe the site's bundles, fields, media types, menus,
formats and languages.
MappingManager / FieldTypeMap / StructureCreator:
Store and suggest mappings, hold the Drupal 7 → Drupal 11 field type
compatibility rules, and create missing bundles, menus and fields.
FieldProcessBuilder / MigrationBuilder: Build per-field
process pipelines and complete migration definitions on top of the core
Drupal 7 source plugins.
MigrationRepository: Stores generated definitions and
exposes them as migration plugins through
hook_migration_plugins_alter(), with dependency ordering
and status reporting.
MigrationValidator / MigrationPreview: Perform
pre-flight checks and a side-effect-free dry run.
MigrationBatch: Provides time-boxed Batch API import and
rollback that resumes across requests.
Process plugins:
migration_assistant_internal_path rewrites
node/N-style paths to new IDs, while
migration_assistant_skip_translation_host handles translation
hosts.
Source plugins:
migration_assistant_d7_file provides MIME filtering and
migration_assistant_d7_comment handles per-content-type
comments.

The module requires Drupal 11.2 or later.

Maintainers

Chaitanya R Dessai

Migration Assistant