Migration Configuration When Upgrading to Drupal 11

Create Your Initial Migrations

• Create migrations using drush migrate-upgrade --configure-only as described in the section "Upgrade Using Drush".
• Ensure you have a config/sync directory that will be used in the next step.
• Export the migrations using drush config:export
• Create your own migration module.
• Copy only the YML files you want to use from the config/sync directory to the config/install directory of your new custom module, editing them to remove uuid values and to modify the id, group, label, and other values as needed.
• Copy the file migrate_plus.migration_group.migrate_drupal_7.yml from config/sync to the config/install directory of your new custom module, naming it migrate_plus.migration_group.your_module.yml. You'll need the group file because it contains the database settings.

Managing the Migration

• Start with migrating user roles and users before moving on to nodes.
• As you continue adding files to the config/install directory, re-import the directory using something like drush config-import --partial --source=modules/custom/your_module/config/install (requires enabling the Config module).

Renaming Fields When Upgrading to Drupal 11

Suppose your Drupal 7 site has a content type A with fields foo, bar, and baz. Suppose you want to rename the baz field to zot in Drupal 8. These changes are fairly easy to make when you upgrade using drush.

• Create migrations using drush migrate-upgrade --configure-only, as referenced above.
• Run the node type and field migrations. This will generate content type A and the foo, bar, and baz fields.
• Manually create the zot field in Drupal 8. Delete the baz field created by the migration that you do not intend to use.
• The Migrate Plus module allows defining pluggable migrations as configuration objects, giving you flexibility to load, modify, and save them. Migrations created using drush migrate-upgrade --configure-only can be viewed at admin/config/development/configuration/single/export by selecting “Migration” as the configuration type. Select the migration for nodes (A).
• Copy and paste the migration into admin/config/development/configuration/single/import, but change the field mapping so that the destination field is field_zot while still mapping the source from field_baz. The exact contents of the migration definition will depend on the field type. Refer to examples in the Migrate API documentation for understanding migration anatomy.
• After importing the modified migration, run the node migration for A with Drush and confirm that the data was correctly migrated into the zot field.
• Repeat the field mapping change for the node revision migration (A) if you also plan to migrate node revisions.

Another way to achieve the same result is by manually creating the new zot field as described above and altering the field mapping of the node (A) migration using hook_migration_plugins_alter().

Writing Custom Process Plugins

If you need to define custom transformation logic (e.g., “if this, then that”), consider writing a custom process plugin.

An example in the Migrate API documentation demonstrates this using the user migration. Determining the user language code requires if-else logic, as described in the example, so the User module provides a custom UserLangcode process plugin.

The example describes how to store the process in the MODULE/src/Plugin/migrate/process directory and how to annotate it for usage. Use the UserLangcode and other process plugins as references for writing your own!

hook_migrate_prepare_row()

If you need to define custom transformation logic, you can also implement hook_migrate_prepare_row() in your custom module and apply your logic there.

According to the hook API documentation, the hook has three arguments:

• Row $row
• MigrateSourceInterface $source
• MigrationInterface $migration

To restrict your logic to a specific migration, use $migration->id().

To read a source property into a variable, use Row::getSourceProperty(). For example, to get the value of a property named type:

$type = $row->getSourceProperty('type');

To set a completely new property for use in the migration definition, use Row::setSourceProperty().

To query the source site’s database, use:

$source->getDatabase()->query();

To skip a row from the migration, throw a MigrateSkipRowException.

hook_migration_plugins_alter()

Another way to customize a migration is to implement hook_migration_plugins_alter() in your custom module.

As described in the API docs, this hook takes one argument—an associative array of all discovered migrations. You can modify migrations or remove ones you don’t want to execute.

Migrate Plus Provides a PREPARE_ROW Event

If you prefer to implement your custom prepare_row logic using an object-oriented approach rather than a procedural hook, and you have the Migrate Plus module enabled, you can subscribe to its PREPARE_ROW event.

For an example implementation of an event subscriber in a different context, refer to this example from the Simple FB Connect module documentation.