Conseils pour écrire des migrations Drupal

Nous avons présenté plusieurs exemples dans le cadre de cette série de blogues sur la migration. Elles ont commencé de façon très simple et sont devenues de plus en plus complexes. Jusqu’à présent, nous avons été plutôt optimistes. Obtenez le code exemple, installez n’importe quelle dépendance de module, activez le module qui définit la migration, et exécutez-le en supposant que tout fonctionne du premier coup. Mais les migrations Drupal impliquent souvent un peu d’essais et d’erreurs. Il s’agit à tout le moins d’un processus itératif. Aujourd’hui, nous allons parler de ce qui se passe après les opérations d’importation et de rollback, comment récupérer après une migration ratée, et quelques conseils pour écrire des fichiers de définition.

Importation et rollback des migrations

Lorsque vous travaillez sur un projet de migration, il est courant d’écrire de nombreux fichiers de définition de migration. Même si vous n’en aviez qu’un seul, il est très probable que votre destination nécessitera de nombreuses cartographies de champs. Exécuter une opération d’importation pour obtenir les données dans Drupal est la première étape. Avec autant de pièces mobiles, il est facile de ne pas obtenir les résultats escomptés dès le premier essai. Lorsque cela se produit, vous pouvez lancer une opération de rollback. Ceci demande au système d’annuler tout ce qui a été introduit lors de l’importation initiale de la migration. Après le rollback, vous pouvez apporter des modifications au fichier de définition de migration et reconstruire le cache de Drupal pour que le système puisse récupérer vos modifications. Enfin, vous pouvez effectuer une autre opération d’importation. Répétez ce processus jusqu’à ce que vous obteniez les résultats escomptés. L’extrait de code suivant montre un flux de travail de base de la migration Drupal :

Loading gist https://gist.github.com/dinarcon/73cf3dc1af44ba59ae3daae1051aeaf4

L’exemple ci-dessus suppose que vous utilisez Drush pour exécuter les commandes de migration. Plus précisément, les commandes fournies par Migrate Run ou Migrate Tools. Vous choisissez l’un ou l’autre, mais pas les deux car les commandes fournies pour deux modules sont les mêmes. Si vous aviez activé les deux, ils entreraient en conflit l’un avec l’autre et échoueraient. Une autre chose à noter est que l’exemple utilise Drush 9. Il y a eu des remaniements majeurs entre les versions 8 et 9 qui incluent des changements au nom des commandes. Finalement, `udm_subfields` est le `id` de la migration à exécuter. Vous trouverez le code complet dans cet article.

Conseil: Vous pouvez utiliser les alias de commande Drush pour écrire des commandes plus courtes. Tapez `drush [nom-commande] –help` pour une liste des alias disponibles.

Note technique: Pour rendre les modifications apportées au fichier de définition fonctionnelles, vous devez reconstruire les caches de Drupal. C’est la procédure à suivre lors de la création des fichiers YAML en utilisant les fonctionnalités de base de Migrate API et en les plaçant dans le répertoire `migrations`. Il est également possible de définir des migrations en tant qu’entités de configuration à l’aide du module Migrate Plus. Dans ces cas, les fichiers YAML suivent une convention d’appellation différente et sont placés dans le répertoire `config/install`. Pour reprendre les modifications dans ce cas, vous devez synchroniser la définition YAML à l’aide des workflows de gestion de configuration. Cette question sera abordée dans un prochain article.

Arrêt et réinitialisation des migrations

Parfois, vous n’obtenez pas les résultats escomptés en raison d’un oubli dans l’établissement d’une valeur. Dans d’autres cas, des erreurs PHP fatales peuvent survenir lors de l’exécution de la migration. Il se peut que l’API de migration ne soit pas en mesure de récupérer de telles erreurs. Par exemple, utiliser une fonction PHP inexistante avec le plugin `callback`. Essayez-le en modifiant l’exemple de cet article. Lorsque ces erreurs se produisent, la migration est laissée dans un état où aucune opération d’importation ou de rollback ne peut être effectuée.

Vous pouvez vérifier l’état de toute migration en exécutant la commande `drush migrate:status`. Idéalement, vous les voulez dans l’état `Idle`. Quand quelque chose échoue pendant l’importation ou le rollback, vous obtiendrez les états `Importing` ou `Rolling back`. Pour récupérer la migration vers `Idle` vous arrêtez la migration et réinitialisez son statut. L’extrait suivant montre comment le faire:

Loading gist https://gist.github.com/dinarcon/73cf3dc1af44ba59ae3daae1051aeaf4

Conseil: Les erreurs générées par l’API Migrate peuvent ne pas fournir suffisamment d’informations pour déterminer ce qui s’est mal passé. Une excellente façon de vous familiariser avec les erreurs possibles est de gâcher intentionnellement les migrations de travail. Dans le référentiel d’exemple de cette série, il existe de nombreuses migrations que vous pouvez modifier. Essayez tout ce qui vous vient à l’esprit: ne pas laisser d’espace après les deux points (:) dans une attribution de valeur-clé; ne pas utiliser d’indentation correcte ; utiliser des noms de sous-champs erronés; utiliser des valeurs invalides dans l’attribution de propriétés; etc. Vous pourriez être surpris de la façon dont l’API Migrate traite ces erreurs. Notez également que de nombreuses autres APIs Drupal sont impliquées. Par exemple, vous pouvez obtenir une erreur d’analyse de fichier YAML ou une erreur de sauvegarde de l’API Entity. Lorsque vous avez déjà vu une erreur, il est généralement plus rapide d’en identifier la cause et d’y remédier dans le futur.

Que se passe-t-il lorsque vous annulez une migration Drupal?

Dans un scénario idéal, lorsqu’une migration est annulée, elle se nettoie après elle-même. Cela signifie qu’il supprime toute entité créée lors de l’opération d’importation : nœuds, termes de taxonomie, fichiers, etc. Malheureusement, ce n’est pas toujours le cas. Il est très important de le comprendre lors de la planification et de l’exécution des migrations. Par exemple, il se peut que vous ne souhaitiez pas laisser des termes de taxonomie ou des fichiers qui ne sont plus en usage. La question de savoir si une entité dépendante est supprimée ou non est liée au fonctionnement des plugins ou des entités.

Par exemple, lorsque vous utilisez les plugins `file_import` ou `image_import` fournis par Migrate File, les fichiers et images créés ne sont pas supprimés du système lors du rollback. Lors de l’utilisation du plugin `entity_generate` de Migrate Plus, l’entité créée reste également dans le système après une opération de rollback.

Dans le prochain billet du blog, nous allons commencer à parler des dépendances migratoires. Que se passe-t-il avec les migrations dépendantes (e.g., fichiers et paragraphes) lorsque la migration pour l’entité hôte (e.g., noeud) est annulée? Dans ce cas, l’API de migration effectuera une opération de suppression d’entité sur le nœud. Dans ce cas, les fichiers référencés sont conservés dans le système, mais les paragraphes sont automatiquement supprimés. Pour les curieux, ce comportement pour les paragraphes est en fait déterminé par la dépendance de son module: Entity Reference Revisions. Nous parlerons plus en détail des migrations de paragraphes dans les prochains billets de blog.

La morale de l’histoire est que le système de migration du comportement pourrait être affecté par d’autres API Drupal. Et dans le cas d’opérations de rollback, assurez-vous de lire la documentation ou de tester manuellement pour savoir quand les migrations sont suppriment tout le nécessaire et quand elles ne le font pas.

Remarque: Cette section portait sur les migrations d’entités de contenu. L’idée générale peut être appliquée aux entités de configuration ou à toute cible personnalisée du processus ETL.

Réimporter ou mettre à jour les migrations

Nous venons de mentionner que l’API Migrate émet une action de suppression d’entité lors qu’un rollback d’une migration est effectué. Ceci a un autre effet secondaire important. Les ID d’entité (nid, uid, tid, fid, etc. ) vont changer à chaque fois que vous annulez à nouveau une importation. Dépendre des identifiants générés automatiquement n’est généralement pas une bonne idée. Mais gardez-le à l’esprit au cas où votre flux de travail pourrait être affecté. Par exemple, si vous exécutez des migrations dans un environnement de mise à disposition de contenu, les références aux entités migrées peuvent se casser si leurs ID changent. De plus, si vous deviez mettre à jour manuellement les entités migrées pour nettoyer les cas des bords (edge cases), ces changements seraient perdus si vous effectuez un rollback et importez à nouveau. Enfin, gardez à l’esprit que les données d’essai peuvent rester dans le système, comme décrit dans la section précédente, qui pourrait se retrouver dans les environnements de production.

Une alternative aux rollbacks d’une migration est de ne pas exécuter cette opération du tout. Au lieu de cela, vous exécutez à nouveau une opération d’importation à l’aide du marqueur `update`. Ceci indique au système qu’en plus de migrer les postes non traités de la source, vous souhaitez également mettre à jour les postes qui ont été précédemment importés en utilisant leurs valeurs actuelles. Pour ce faire, l’API Migrate s’appuie sur des identificateurs de source et des tables de correspondance. Vous pouvez envisager cette option lorsque votre source change fréquemment, lorsque vous avez un grand nombre d’enregistrements à importer ou lorsque vous souhaitez exécuter la même migration plusieurs fois sur une même planification.

Remarque: Lors des opérations d’importation, l’API Migrate émet une action de sauvegarde d’entité.

Conseils pour écrire des migrations Drupal

Lorsque vous travaillez sur des projets de migration, vous pouvez vous retrouver avec de nombreux fichiers de définition de migration. Ils peuvent définir des dépendances l’un par rapport à l’autre. Chaque fichier peut contenir un nombre significatif de mappages de champs. Il y a beaucoup de choses que vous pouvez faire pour rendre les migrations Drupal plus simples. Par exemple, pratiquer avec différents scénarios de migration et étudier des exemples de travail. Comme référence pour vous aider dans le processus de migration vers Drupal, voici quelques conseils :

• Partir d’une migration existante. Recherchez un exemple en ligne qui fait quelque chose de proche de ce dont vous avez besoin et modifiez-le selon vos besoins.
• Portez une attention particulière à la syntaxe du fichier YAML. Un espace superflu ou un niveau d’indentation incorrect peut casser toute la migration.
• Lisez la documentation pour savoir quels plugins source, processus et destination sont disponibles. Il en existe peut-être déjà un qui fait exactement ce dont vous avez besoin.
• Assurez-vous de lire la documentation des plugins spécifiques que vous utilisez. Souvent, un plugin offre des configurations optionnelles. Comprendre les outils à votre disposition et trouver des façons créatives de les combiner.
• Recherchez les modules contribués qui pourraient offrir plus de plugins ou de chemins de mise à jour à partir des versions précédentes de Drupal. L’écosystème migratoire est dynamique et de nombreuses personnes y contribuent.
• Lorsque vous écrivez le pipeline de migration, mappez un champ à la fois. Les problèmes sont plus faciles à isoler s’il n’y a qu’une seule chose qui pourrait se briser à la fois.
• Lorsque vous mappez un champ, travaillez sur une sous-champ à la fois, si possible. Certains types de champs comme les images et les adresses offrent de nombreuses sous-champs. Encore une fois, essayez d’isoler les erreurs en introduisant des changements individuels à chaque fois.
• Faites un commit à votre référentiel de code tout changement qui produit de bons résultats. De cette façon, vous pouvez remonter dans le temps et récupérer une migration partiellement fonctionnelle.
• En savoir plus sur les migrations de débogage. Nous parlerons de ce sujet dans un prochain billet de blog.
• Voir l’aide de la communauté. Les développeurs et les passionnés de Migrate sont très actifs et réactifs dans le canal #migrate de Drupal slack.
• Si vous vous sentez coincé, faites une pause de l’ordinateur et revenez-y plus tard. Le repos peut faire des merveilles pour trouver des solutions à des problèmes difficiles.

Qu’avez-vous appris dans le billet d’aujourd’hui? Saviez-vous ce qui se passe lors de l’importation et de l’annulation d’une migration? Saviez-vous que dans certains cas, les données peuvent rester dans le système même après les opérations de rollback? Avez-vous un cas d’utilisation pour exécuter des migrations avec le marqueur `update`? Avez-vous d’autres conseils sur l’écriture des migrations? Veuillez partager vos réponses dans les commentaires. Aussi, je vous serais reconnaissant de bien vouloir partager ce billet de blog avec vos collègues.