Prérequis:

• db accesible d'la nouvelle hôte
• fichiers privés accessible sur la nouvelle hôte (copier avec rsync par example)
• fichiers publiques accesible sur disque où à travers un url web
• considère travailler qlq'part avec une assez grande tampon de mémoire pour php (256-512M minimum)

Projet Redmine élaboré par Kienan avec image Vagrant pour faire de la formation sur migration D6/D7 et D8

• Dépôt - Drupal Migrations - Koumbit's Redmine

Consultez la documentation suivante:

• Documentation des modules migrate + liste des modules contrib utile

• Preparing for an upgrade

• Upgrade using the migration interface

• Étapes détaillées avec Docker

• Drush Migrate commands

• Migrate Devel

• Upgrade using Drush

• Customize migrations when upgrading to Drupal 8

Approche simple

Avant

• activer les modules nécessaires
• s'il y a des languages, activer ça, ajouter les langues requis, activer la traduction sur les entités divers
• Il faut activer d'abord le module Language.

• Ensuite aller à Configuration > Regional and Language > Languages ( admin/config/regional/language )

• Il faut ensuite activer les modules Configuration Translation, Interface Translation, Content Translation.
• De là on peut ajouter une langue.

Pendant

• activer le module migrate, migrate_drupal et migrate_drupal_ui

• go to admin -> extend -> migrate drupal ui -> click to expand -> click on configure

• remplir la formulaire
• voir les résultats: s'il y a des affaires qui manquent, ajoute les modules qui corréspondent.

Approche avancé

1. Télécharger les modules suivantes et les activer. Fasses attention de prendre des versions qui supportent la version de drupal 8 vous importez vers.

• migrate_plus
• migrate_upgrade
• migrate_tools
• (facultatif) migrate_manifest

2. Activer aussi le module migrate (et facultativement, migrate_ui) du coeur de drupal 8.

3. Activer les versions Drupal 8 des modules besoin, tel que book, etc.

4. Activer la localisation et traduction si nécessaire. Configurer la language par défaut en corréspondance avec les paramétrages du site source.

5. Prendre un backup (drush ard)

6. Ajouter les informations de connection de base de données dans le fichier local.settings.php à la racine du site d8. Nommer la base de données "drupal_6".

#Exemple

$databases['drupal_6']['default'] = array(
  'database' => 'xx',
  'username' => 'xx',
  'password' => 'xx',
  'port' => 3306,
  'host' => 'mysql.aegir.koumbit.net',
  'driver' => 'mysql',
  'prefix' => '',
);

7. Étape pour la création des migrations automatique:

drush migrate-upgrade --legacy-db-key=drupal_6 --legacy-root=http://monsite_d6.xyz --migration-prefix='' --configure-only

Il y a un bogue dans l'importateur et les migrations qui ont un préfixe ne fonctionneront pas. Le préfixe est défini par défaut par migrate-upgrade est "upgrade_".

8. Rouler toute les migrations:

drush migrate-import --all

Note: Pour les projets complexes considérer l'utilisation de migrate manifest pour clairement démontrer l'ordre des migrations.

Erreurs Fréquents

Migration failed with source plugin exception: base table of view not found: table X.i18n_varible

Si la localisation des variables n'est pas activé dans le site source, cette message ne devrait pas poser de problème.

Missing filter plugin: filter_null

Dans l'interface d'administration re-sauvegarder les filtres qui sont crées lors d'la migration.

Note: Ceci cause les contenus utilisant les filtres affectés à ne pas afficher de quoi avant que le filtre soit re-sauvegarder.

Migration des "Image" du module image ne transfer pas

• Référence: http://www.amitgoyal.in/2016/03/d6-d8-migration-d6-image-d8-image.html : ceci migre just les "image attach", pas les images sur le noeud de type image fourni par le module

Image nodes

• After the migration configuration are generated

  1. drush config-export sync # get the current config on disk 

  2. Add fileld_image (or another field) to the image node type
  3. In a custom module implement or add to an existing implementation of hook_migrate_prepare_row
     • get the term id for the gallery
     • get the original image fid

  4. Modify the configuration file for the migration and add in the process section something to the effect of:

       field_image:
         plugin: iterator
         source: field_image
         process:
           target_id:
             plugin: get
             source: fid
           alt: {  }
           title: {  }
       galeries_d_images:
         target_id:
           plugin: migration
           migration: upgrade_d6_taxonomy_term
           source: gallery_tid

  5. drush config-import sync # make sure there are no errors, even unrelated, otherwise the import  fails!!!

  6. Re-run the migration.

Forgot to enable modules?

1. Dump configuration to disk and save (eg. in git)

2. Revert all migrations : drush mr --all.

3. Through the interface, delete the migration group that was created: Structure -> Migrations (/admin/structure/migrate)

4. Re-run migrate-upgrade to regenerate the migrations.

5. Dump configuration to disk, and merge relevant changes from before

6. Import upgrade configuration drush config-import sync

7. Run migrations again.

Création des migrations custom

À faire...

Notes Emm pour l'approche avancée (drush)

Lister les modules existants dans Drupal 6

• La version 5 de drush ne permet pas de créer la liste avec le format cvs et c'est cette version qui est sur ceres.k.n.
• J'ai fait la commande suivante et ensuite dans vim j'ai formaté le fichier au format cvs en me servant des espaces et en enlevant les espaces de trop.

drush pml --no-core --status=enabled > noms_modules_du_site.csv

 Package                          Nom                                                               Type    Version 
 Access control                   Content Access (content_access)                                   Module  6.x-1.2 
 Administration                   Admin Role (adminrole)                                            Module  6.x-1.3 
 Administration                   Administration menu (admin_menu)                                  Module  6.x-1.9 
 Autre                            Advanced help (advanced_help)                                     Module  6.x-1.3 
 Autre                            Automatic Nodetitles (auto_nodetitle)                             Module  6.x-1.2 
 Autre                            BUEditor (bueditor)                                               Module  6.x-2.10
(...)

Pour obtenir que le nom machine des modules:

drush pml --no-core --status=enabled --pipe > noms_machine_modules_du_site.csv

content_access
adminrole
admin_menu
advanced_help
auto_nodetitle
bueditor
conditional_styles
custom_pagers
(...)

• On fait la même chose pour les noms machine des modules pour le D8.
• Normalement, comme c'est une installation vierge, on ne devrait voir que les modules pour la migration:

$ drush pml --no-core --status=enabled --pipe

migrate_upgrade
migrate_manifest
migrate_plus
migrate_tools

• On va installer tous les modules possibles dans le Drupal 8.

D'abord on fait une copie de sauvegarde du site avec

$ drush ard

# ou à ce stade-ci on peut juste sauvegarder la bd

$ drush cr
$ drush sql-dump > nom_du_site.d8.`date +%F`.sql

• On roule notre oneliner avec bash, il va y avoir beaucoup d'erreurs pour les modules qui n'existent pas en D8:

$ while read module; do drush dl $module; done < le_site_modules_d6_noms_machine.txt

• Le mieux est de vérifier sur les pages des modules qu'on a téléchargé leur status (le module peut être inutilisable en D8 même s'il est offert en téléchargement comme une version alpha, ou une version trop ancienne).

# dans le D8 du site
$ cd /modules
$ for module in *; do echo "https://www.drupal.org/project/"$module; done > /tmp/modules.d8.txt

# ça va nous donner un fichier qui va contenir quelque chose comme ceci:

https://www.drupal.org/project/advanced_help
https://www.drupal.org/project/blog
https://www.drupal.org/project/blogapi
https://www.drupal.org/project/bueditor
https://www.drupal.org/project/calendar
https://www.drupal.org/project/conditional_styles
(...)

* On peut ensuite télécharger le fichier modules.d8.txt sur notre machine et rouler un script bash pour ouvrir toutes les pages avec notre fureteur (ici chromium):

# remplacer chromium-browser par firefox si on veut utiliser ce dernier
$ while read module;do chromium-browser $module;done < modules.d8.txt

Migrate Tools

• Migrate Tools

• Une fois installé, on peut interroger chaque outil via drush help.

migrate-status - Lists migrations and their status.
migrate-import - Performs import operations.
migrate-rollback - Performs rollback operations.
migrate-stop - Cleanly stops a running operation.
migrate-reset-status - Sets a migration status to Idle if it's gotten stuck.
migrate-messages - Lists any messages associated with a migration import.

General notes

• The drupal.org documentation on migration is so bad I subscribed to Drupal 8 Migration on drupalize.me

• These are my notes to give an overview of a migration.

Migrate Plus Module

• After reading this documentation, the best is to delve in the Migrate Plus module which contains 2 sub-modules as examples of migration with documented YAML files and PHP scripts, and also sample data to run a test migration.

  • sub-module migrate_example (database, SQL, Drupal to Drupal)
  • sub-module migrate_example_advanced (JSON, XML, SOAP)

Core Migration Modules

Migrate Module

• Contains the migrate API on which all other modules are based.

• Migrate API overview

• Migration API - migrate.api.php - Drupal 8.2.x - Drupal API

Migrate Drupal

• You need this module if you are doing inter drupal migration: i.e. Drupal 6 to Drupal 8
• You don't need this module if you are using another source (like xml, csv, etc).

• Lame documentation here (i.e. incomplete): Migrate Drupal overview

• In Drupal 8, the update.php script is used only for minor versions updates.
• This module is used in particular with entities that are fieldable (like the Node and User modules).

Migrate Drupal UI

• Web interface to the Migrate Drupal module.
• For simple migrations.

Migration Templates

• A migration template is a YAML file that provide instructions to map the path that the data needs to take from the source to the destination.

• Stored in module_name/migrations sub-directory of a module.

• Example: Drupal/core/modules/file/migrations/d6_file.yml (Drupal here is the root of the Drupal installation).

Extract, Transform, and Load

• See Extract, transform, load - Wikipedia

• Each stage of the migration can have a plugin: source plugin (extract), process plugin (transform), destination plugin (load).

  • Migration API

Source Plugins

• Overview of migrate source plugins

• More suitable for non-Drupal data store.
• Extract data (can come from Drupal, CVS, XML, YAML, etc.) and return as a set of rows and their properties (metadata?).
• Need that if you want to extract data from a custom plugin.

# Example from a migration plugin YAML file:

source:
  plugin: baseball_player

• The file will live here: /modules/custom/YOUR_MODULE/config/install (?)

There are generic source plugins:

• CVS: Migrate Source CSV

• JSON, XML, SOAD: [Migrate Plus | Drupal.org](https://www.drupal.org/project/migrate_plus)

• Called from you custom migration module.

Source plugins live in the Drupal\{MY_MODULE}\Plugin\migrate\source
namespace. In our case this will be
Drupal\baseball_migration\Plugin\migrate\source, with our code living in
the file baseball_migration/src/Plugin/migrate/source/BaseballPlayer.php.

Write a Custom Source Plugin | Drupalize.Me : https://drupalize.me/tutorial/write-custom-source-plugin?p=2578

• Source plugins are managed by the MigratePluginManager

Migrate source plugins implement
\Drupal\migrate\Plugin\MigrateSourceInterface and often extend
\Drupal\migrate\Plugin\migrate\source\SourcePluginBase. They are annotated
with the \Drupal\migrate\Annotation\MigrateSource annotation and must
be at src/Plugin/migrate/source of the module that defines them.

Source Plugins | Drupalize.Me : https://drupalize.me/tutorial/source-plugins?p=2578

Example of source plugins from the Drupal core: 78 classes are annotated with MigrateSource

• Good examples in the Migrate Plus module.
• Good examples for uploaded files in Drupal/core/modules/file/src/Plugin/migrate/source/d6/

Process Plugins

• Process/manipulate data before inserting the data in Drupal 8 (load phase).
• Drupal core have a couple of process plugins.

Example with the concat plugin:

# We generate the node.title (which we treat as the name) by concatenating
# two soure fields together and putting a space between them
title:
  plugin: concat
  source:
    - nameFirst
    - nameLast
  delimiter: " "

Process Plugins | Drupalize.Me : https://drupalize.me/tutorial/process-plugins?p=2578

• Here's the list of process plugins. Yes they are called from YAML files

  • namespace Drupal\migrate\Plugin\migrate\process

• It's possible to write your own process plugin.

  • Write a Custom Process Plugin - Drupalize.Me

  • Migrate process overview

Destination Plugins

• Responsible for saving new data as Drupal content or configuration
  • Dictate the fields that data can be saved to
  • Determine the unique ID of the record created during the migration for mapping purposes
  • Create new records from imported data and persist them to Drupal's storage

    • Exerpts from Destination Plugins - Drupalize.Me

• Usually, there's no need to create custom destination plugins.
• Drupal Core provide a lot of destinations plugins:

  • 28 classes are annotated with MigrateDestination

• entity:node is one of the most important plugin in Core:

  • create node object
  • provide mapping from the source fields to the destination fields

• Importing configurations is another common task and there is a config destination plugin for that.

• Usually there's no need to write a custom plugin destination for configurations.

  • To edit YAML files for configurations is still a nightmare and the drupal.org documentation is so bad that the drupalize.me tutorial called it a little bit tricky to figure out.

  • You have to derive classes from one to another and it's not clear at all what to do here.

Contributed Modules: The Big Three

Migrate Tools

• Allow custom migrations other than Drupal to Drupal migrations.
• Provide drush commands for running and rollback (custom) migrations.

Drush commands supported include:

    migrate-status - Lists migrations and their status.
    migrate-import - Performs import operations.
    migrate-rollback - Performs rollback operations.
    migrate-stop - Cleanly stops a running operation.
    migrate-reset-status - Sets a migration status to Idle if it's gotten stuck.
    migrate-messages - Lists any messages associated with a migration import.

Migrate Tools | Drupal.org : https://www.drupal.org/project/migrate_tools

• Migrate Tools

Migrate Update

• Provide drush commands running Drupal to Drupal migrations.
• Replace the UI provided by Drupal core for migration and drush commands are also more reliable.

# example:

drush migrate-upgrade --legacy-db-url=mysql://user:pass@12.34.56.78/d6db --legacy-root=http://myd6site.com  --configure-only

• Migrate Upgrade

Migrate Plus

• Extend the core Migrate framework for sources in the XML, JSON or SOAP formats.
• This module provide also two examples modules: migrate_example (Drupal to Drupal) and migrate_example_advanced (XML, JSON, SOAP):
  • The example modules document how to write source, process and destinations plugins.
  • Also the example modules document how to write a migration plugin.

• Migrate Plus

Contributed Modules: Others

Migrate Manifest

• Provide drush commands to perform migration with a manifest file.
• The module let you run migration by group in a reproductible manner.

• Migrate Manifest

• You might need a patch: Not correct migrate templates directory [#2991905]

Migrate Source CSV

• Use CSV format or tab delimited files as source for a migration.

• Migrate Source CSV

Migrate Maps

• Quand on fait une migration avec un fichier yaml, Drupal génère dans la bd une table qui commence par migrate_map:

MariaDB [recitprescodev1a]> select * from migrate_map_                                                                 
Display all 969 possibilities? (y or n)                                                                                
migrate_map_block_content_body_field                                  migrate_map_d6_node_book.sourceid1               
migrate_map_block_content_body_field.destid1                          migrate_map_d6_node_calendrier                   
migrate_map_block_content_body_field.destid2                          migrate_map_d6_node_calendrier.destid1           
migrate_map_block_content_body_field.destid3                          migrate_map_d6_node_calendrier.hash              
migrate_map_block_content_body_field.hash                             migrate_map_d6_node_calendrier.last_imported     
migrate_map_block_content_body_field.last_imported                    migrate_map_d6_node_calendrier.rollback_action   
migrate_map_block_content_body_field.rollback_action                  migrate_map_d6_node_calendrier.source_ids_hash   
migrate_map_block_content_body_field.source_ids_hash                  migrate_map_d6_node_calendrier.source_row_status 
migrate_map_block_content_body_field.source_row_status                migrate_map_d6_node_calendrier.sourceid1         
migrate_map_block_content_body_field.sourceid1                        migrate_map_d6_node_formations                   
migrate_map_block_content_body_field.sourceid2                        migrate_map_d6_node_formations.destid1           
migrate_map_block_content_body_field.sourceid3                        migrate_map_d6_node_formations.hash              
migrate_map_block_content_entity_display                              migrate_map_d6_node_formations.last_imported     
migrate_map_block_content_entity_display.destid1                      migrate_map_d6_node_formations.rollback_action   
migrate_map_block_content_entity_display.destid2                      migrate_map_d6_node_formations.source_ids_hash   
migrate_map_block_content_entity_display.destid3                      migrate_map_d6_node_formations.source_row_status 

• Ça peut nous donner des informations importantes sur l'état de la migration.

Par exemple si on migre la node 1690 avec avec le fichier yaml migrate_plus.migrate.d6_node_album.yml de la manière suivante:

$ drush migrate-import d6_node_album --idlist=1690

On peut explorer migragte_map_d6_node_album :

MariaDB [recitprescodev1a]> select * from migrate_map_d6_node_album;
+------------------------------------------------------------------+-----------+---------+-------------------+-----------------+---------------+------+
| source_ids_hash                                                  | sourceid1 | destid1 | source_row_status | rollback_action | last_imported | hash |
+------------------------------------------------------------------+-----------+---------+-------------------+-----------------+---------------+------+
| 0e567e0ba28d9c4b12eba02737464bb2b773a667fda0ebeeb7efd86873fb7411 |      1690 |    1690 |                 0 |               1 |             0 |      |
+------------------------------------------------------------------+-----------+---------+-------------------+-----------------+---------------+------+
1 row in set (0.00 sec)

Migrate Manifest

• Migrate Manifest

• Upgrade using Drush

• Il faudra peut-être appliquer une rustine pour que $ drush migrate-template-list puisse fonctionner (génère un manifeste): Not correct migrate templates directory [#2991905]

Conversion module Drupal 7 en Drupal 8

Résolution des problèmes

Version de migrate_upgrade

• Il est possible que la dernière version de migrate_upgrade présente des problèmes:

  • Par exemple avoir un PHP Fatal Error

  • Il faut revenir à une version antérieure: 8 - Drush Migration between distant DB and local DB? - Drupal Answers

  • drush dl migrate_upgrate --select

drush config-import sync

• Erreurs liées à un thème absent
• L'erreur va lister la liste des configs liées à au thème absent qui provoque l'erreur.

• La manière officielle est d'utiliser drush config-delete NOM_DE_LA_CONFIG.yml

• Il se peut qu'à la suite de cette opération, drush config-import sync veuille recréer la config qu'on vient de supprimer.

  • En ce cas, on peut simplement supprimer la config avec bash: rm NOM_DE_LA_CONFIG.yml

  • Ensuite refaire drush config-import sync, on devrait voir lister comme delete la config qu'on vient de supprimer.

Migration migration_exemple is busy with another operation

• Si une migration ne réussit pas on peut avoir le message:

Migration migration_exemple is busy with another operation

• Faire d'abord drush migrate-status et repérer la ligne qui va avoir Importing. Cela va confirmer la migration problématique.

• Ensuite on peut faire la commande suivante qui devrait remettre à Idle le status de cette migration:

drush migrate-reset-status migration_exemple

• Migration is busy with another operation [#2563901] - Drupal.org

<none> block

• Active le module Book oubedon regarde avec l'inspecteur de ton fureteur l'id qui apparaît quand tu mets ton curseur sur <none> pour déterminer le module à activer.