Migración de contenidos - Cómo funciona el ETL del módulo migrate (Plugins).

En los anteriores post hablamos de cómo realizar un análisis y un plan para una migración de contenidos y cómo llevar a código las distintas migraciones. En este post veremos cómo ampliar funcionalidades a dichas migraciones creando y extendiendo plugins de Migrate API.

Procesos ETL

Como se comentó en la serie 2 de migración de contenidos, migrate API se basa en procesos de extracción, transformación y carga. Por lo que en la fase de origen se recupera un conjunto de datos fila, se envía a la fase de proceso donde se transforma según sea necesario y esta es lanzada a la fase de destino donde se carga o se almacena.

Plugins

Los plugins de migración especifican las fases del ETL a nivel individual como por ejemplo la migración de un tipo de contenido o una taxonomía.

Para cada una de esas fases los plugins se corresponden con las secciones que se añaden a los ficheros de configuración yml. Los plugins para esto son los siguientes:

• Source plugin son los encargados de extraer los datos de origen.
• Process plugin son los que transforman los datos.
• Destination plugin encargados de guardar los datos en drupal.

Source plugin

Para la implementación de un source plugin tenemos que tener en cuenta lo siguiente:

• Implementan \Drupal\migrate\Plugin\MigrateSourceInterface
• Suelen extender de \Drupal\migrate\Plugin\migrate\source\SourcePluginBase
• Utilizan anotaciones \Drupal\migrate\Annotation\MigrateSource
• Deben de estar dentro de nuestro módulo en src/Plugin/migrate/source y tener su Namespace Drupal\mymodule\Plugin\migrate\source.
• Los administra la clase \Drupal\migrate\Plugin\MigrateSourcePluginManager

La imagen anterior hace mención a una clase source plugin la cual extiende de la clase abstracta SqlBase que proporciona el módulo Migrate del core de drupal. Dicha clase hace una consulta a una base de datos de origen sobre la tabla “articles”. Esta clase debe implementar los siguientes métodos:

• query(): Devuelve la consulta sobre la base de datos origen.
• fields(): Devuelve los campos disponibles de la tabla.
• getIds(): Donde se definen el/los campos de origen que identifica de forma exlusiva la fila de origen, es decir, coincide con la/las clave/s primaria/s (PK) de la tabla de origen.

En el ejemplo también se hace uso del método prepareRow, donde tendremos los datos de la fila extraída. Este método se suele implementar para dos casos:

• Modificar datos o campos en función de nuestras necesidades.
• Omitir una fila devolviendo FALSE.

El yml de configuración para el ejemplo sobre la migración de “articles” sería como se ve a continuación:

Desde el yml también se pueden pasar parámetros al plugin, como por ejemplo el tipo de artículo (sillas, mesas, armarios, etc) y recogerlo en el método en el cual lo necesitemos mediante el atributo $configuration definido en la clase abstracta PluginBase. Dicho atributo es un array que contiene información sobre la configuración del plugin. Para este caso si añadimos en el yml una clave por ejemplo article_type: sillas, podemos recoger ese valor dentro del plugin haciendo uso de $this->configuration[‘article_type’] y podemos utilizarlo por ejemplo para añadir una cláusula “where” en la consulta y filtrar por el tipo de artículo. Por otro lado, se debe mencionar que este atributo también añade las constantes que se hayan definido en la migración, recuperándola mediante $this->configuration[‘constants’][‘mi_constante’] y consiguiendo así más versatilidad a la hora de realizar extensiones.

Process plugin

Para la implementación de un process plugin tenemos que tener en cuenta lo siguiente:

• Implementan \Drupal\migrate\Plugin\MigrateProcessInterface
• Suelen extender de \Drupal\migrate\ProcessPluginBase
• Utilizan anotaciones \Drupal\migrate\Annotation\MigrateProcessPlugin
• Deben de estar dentro de nuestro módulo en src/Plugin/migrate/process y tener su Namespace Drupal\mymodule\Plugin\migrate\process.
• Los administra la clase \Drupal\migrate\Plugin\MigratePluginManager

La imagen anterior hace mención a una clase process plugin la cual extiende de la clase ProcessPluginBase que proporciona el módulo Migrate del core de drupal. Dicha clase cambia el formato de un timestamp por el que le pasemos como parámetro desde el yml de configuración. Esta clase implementa el método transform que es donde vamos a modificar el valor. Dentro de este método también se puede utilizar excepciones con MigrateException para lanzar errores.

El yml de configuración para el ejemplo sería como se ve a continuación:

Destination plugin

Estos complementos están estrechamente relacionados con el sitio al que se está migrando, en este caso drupal 8/9. Rara vez tendremos que crear alguno ya que drupal proporciona la mayoría de los complementos de destino. De igual manera muchos módulos contribuidos incluyen también estos complementos para sus propios tipos de entidad y configuración.

Para la implementación de un destination plugin tenemos que tener en cuenta lo siguiente:

• Implementan \Drupal\migrate\Plugin\MigrateDestinationInterface
• Suelen extender de \Drupal\migrate\Plugin\migrate\destination\DestinationBase
• Utilizan anotaciones \Drupal\migrate\Annotation\MigrateDestination
• Deben de estar dentro de nuestro módulo en src/Plugin/migrate/destination y tener su Namespace Drupal\mymodule\Plugin\migrate\destination.

Esta clase debe implementar los siguientes métodos:

• fields(): Devuelve la matriz de campos de destino.
• getIds(): Obtiene los ID de destino.
• import(): Importa la fila.

Conclusiones

Concluimos con que lo más importante de este post atiende a lo siguiente:

1. Source plugins.
2. Process plugins.

No destacamos los destination plugins puesto que suelen venir definidos bien en el core de drupal o en módulos contribuidos para cualquier tipo de entidad que se necesite crear.

En el siguiente post veremos cómo administrar migraciones con migrate tools.