A demo module created by Mauricio Dinarte (@dinarcon) to explain migrations concepts in Drupal.

This module has been used in conference talks to explain migration concepts. Find more information at:

• https://udrupal.com/migrations-by-example - Slide deck.
• https://www.youtube.com/watch?v=eBP2vQIwx-o - Recording. It is old and does not uses the latest code in the repo, but the concepts still apply.
• https://gist.github.com/dinarcon/72922e8cf634ada47483117ffa659d76 - JSON source migration example.

The following projects are required to run this demo. The version number indicates which version was last used for testing.

• Drupal 9.0.2
• Address 8.x-1.8
• Entity reference revisions 8.x-1.8
• Migrate plus 8.x-5.1
• Migrate source csv 8.x-3.4
• Migrate tools 8.x-5.0
• Paragraphs 8.x-1.12
• Drush 10.3.1

This demo includes 6 migration configurations.

• mbe_csv_book_paragraph for importing data into paragraphs entities. There are no dependencies on other migrations.
• mbe_csv_photo_field for importing data into file entities. There are no dependencies on other migrations.
• mbe_csv_professors for importing data into node entities. This depends on other migrations to be run before: mbe_csv_book_paragraph and mbe_csv_photo_field.

There are equivalent migrations to import data from JSON file: mbe_json_book_paragraph, mbe_json_photo_field, mbe_json_professors.

• Install module dependencies via composer: composer require 'drupal/address:^1.8' 'drupal/migrate_plus:^5.1' 'drupal/migrate_source_csv:^3.4' 'drupal/migrate_tools:^5.0' 'drupal/paragraphs:^1.12'
• If you do not have Drush available, install the latest version via composer: composer require drush/drush. After this step, you may call it via ./vendor/bin/drush.
• Make sure that your Drupal installation has a /modules/custom folder. The modules folder should exist, but the custom sub-folder might not. Create it if needed.
• Download the demo module contained in this repository into the /modules/custom folder. You can do this by cloning this repository or downloading a ZIP file. Important: The name of the folder containing this demo must ve mbe_professors. If you get it from the ZIP file the folder will be named mbe_professors-main. If that is the case, rename the folder to mbe_professors to prevent errors reading the CSV files.
• Verify that the CSV files are in the proper location. See instructions below.
• Enable the Professors Example Migration (mbe_professors) module.
• Run migrations using Drush. See instructions below.

The path configuration for the CSV source plugin accepts an absolute path or relative path from the Drupal installation folder.

The examples use a relative path and it is assumed that you place this demo module in a modules/custom folder. Therefore, the CSV files will be located at modules/custom/mbe_professors/sources/.

This would look similar to:

.
|-- autoload.php
|-- core
|-- index.php
|-- modules
|   |-- contrib
|   |   |-- address
|   |   |-- entity_reference_revisions
|   |   |-- migrate_plus
|   |   |-- migrate_source_csv
|   |   |-- migrate_tools
|   |   `-- paragraphs
|   `-- custom
|       `-- mbe_professors
|           |-- composer.json
|           |-- config
|           |-- mbe_professors.info.yml
|           |-- mbe_professors_setup
|           |-- migrations
|           |-- README.md
|           `-- sources
|-- profiles
|-- robots.txt
|-- sites
|-- themes
|-- update.php
`-- web.config

Not having the source CSV files in the proper location would trigger and error similar to:

[error]  Migration failed with source plugin exception: File path (modules/custom/mbe_professors/sources/mbe_csv_book_paragraph.csv) does not exist.

If you want to place the files in a different location, you need to update the path in the corresponding configuration files. That is the source:path setting in the migration files.

The Migrate Tools module provides drush commands to run the migrations.

drush migrate:import mbe_csv_book_paragraph
drush migrate:import mbe_csv_photo_field
drush migrate:import mbe_csv_professors

Note: The commands above work for Drush 10. In Drush 8 the command names and aliases are different. Execute drush list --filter=migrate to verify the proper commands for your version of Drush.

After the migrations are run successfully, visit /mbe_professors to see the content that was imported.

It might be necessary to apply the patch available at https://www.drupal.org/node/3117485 for migration dependencies to work properly. If using composer, you can apply the patch using the cweagans/composer-patches composer.

# Execute this command.
composer require cweagans/composer-patches

# Edit composer.json file.
vim composer.json

# Add the following under the 'extra' section.
"patches": {
  "drupal/migrate_tools": {
    "Migrate import --execute-dependencies fix": "https://www.drupal.org/files/issues/2020-03-06/fetch-migration-requirements-3117485-2.patch"
  }
}

# Apply the patch.
composer install