Foto de Unsplash, de Krzysztof Niewolny, @epan5

Índice

• 1. Introducción
• 2. Depuración básica: revisa tus archivos
• 3. Depuración intermedia con Migrate Devel
• 4. :wq!

1. Introducción

Siguiendo los últimos artículos, quiero ampliar la información sobre migraciones en Drupal. He pensado en una pequeña subserie sobre depuración dentro de esta serie principal. Esta es la primera parte: un conjunto de pasos básicos para obtener toda la información disponible de un proceso de migración. Los ejemplos proceden del módulo migration_google_sheet de mi cuenta de GitLab.

2. Depuración básica: revisa tus archivos

Empezaremos por una aproximación muy elemental a la detección de errores. Es fundamental reducir las posibles causas abordando la migración de forma iterativa e incremental: avanzaremos paso a paso y ampliaremos progresivamente los datos migrados.

2.1. Revisar el archivo de definición de la migración

Comenzamos con el paso más intuitivo. Hay errores que están a la vista y, por habituales que sean, no siempre resultan evidentes.

Antes de nada, revisaremos dos cuestiones que aparecen con frecuencia:

Espacios en blanco: un espacio adicional puede causar problemas en el archivo de definición. Recorre sus líneas para localizar espacios sobrantes.

Errores de sangrado: el formato YAML organiza los datos mediante claves y valores, con niveles padre e hijo y sangrado de dos espacios en cada nivel del ejemplo. Un sangrado incorrecto puede provocar un error al procesar el archivo. Revisa todos los niveles, igual que has revisado los espacios.

Puedes apoyarte en un validador de sintaxis YAML como www.yamllint.com, aunque también tendrás que comprobar el resultado.

2.2. Revisar los registros de la base de datos

En la instalación básica utilizada en el ejemplo, con el perfil estándar, tenemos setenta y tres tablas. Tras activar migrate, migrate_plus, migrate_tools y el módulo personalizado migration_google_sheet_wrong, pasan a ser setenta y cinco. Se han generado dos tablas nuevas:

cache_migrate
cache_discovery_migration

Después de ejecutar la migración con identificador taxonomy_google_sheet_wrong, incluida en el módulo personalizado, aparecen otras dos tablas relacionadas con la migración:

• migrate_map_taxonomy_google_sheet. Contiene la información sobre el recorrido de cada fila de datos: las migraciones trabajan fila a fila. Migrate API almacena el identificador de origen, el de destino y un hash relacionado con la fila. Estas correspondencias permiten seguir cambios, actualizar información progresivamente y resolver dependencias entre migraciones. Las búsquedas o lookups se apoyan en estos datos. Por ejemplo, para cargar un término de taxonomía puede ser necesario buscar antes su término padre y mantener así la jerarquía. Si, después de lanzar la migración, no encontramos resultados registrados, no se han almacenado los datos y tendremos que depurar el proceso.
• migrate_message_taxonomy_google_sheet. Guarda los mensajes asociados a la ejecución, también organizados por fila. Cada mensaje tiene su propio identificador y está asociado al id_hash de la fila de origen:

Podemos obtener esta información con Drush: el contenido de la tabla es lo que aparece al ejecutar:

drush migrate:messages id-migration

Es una forma útil de empezar a recopilar información sobre los errores de la migración.

2.4. Recargar los objetos de configuración

Durante la depuración también necesitamos actualizar los cambios realizados en el objeto de configuración creado a partir del archivo de definición de config/install.

Cada vez que instalamos el módulo se genera un objeto de configuración disponible en Drupal. Mientras depuramos tendremos que modificar el archivo y recargarlo para comprobar el efecto de los cambios. ¿Cómo podemos facilitar este ciclo?

Primero vincularemos el ciclo de vida del objeto de configuración de migración a la instalación de nuestro módulo. Como vimos al tratar las migraciones como configuración, declararemos el módulo personalizado como dependencia forzada:

dependencies:
   enforced:
      module:
          - migration_google_sheet

Podemos realizar importaciones específicas con Drush o Drupal Console, aprovechando las opciones de importación individual.

Con Drupal Console:

drupal config:import:single --directory="/modules/custom/migration_google_sheet/config/install" --file="migrate_plus.migration.taxonomy_google_sheet.yml"

Con Drush:

drush cim --partial --source=/folder/

También podemos eliminar objetos de la configuración activa con ambas herramientas:

drush config-delete "migrate_plus.migration.taxonomy_google_sheet"
drupal config:delete active "migrate_plus.migration.taxonomy_google_sheet"

Si preferimos la interfaz de Drupal, el módulo contribuido Config Delete incorpora opciones al menú de sincronización para eliminar elementos de configuración. Basta con descargarlo con Composer y activarlo con Drush o Drupal Console:

composer require drupal/config_delete
drush en config_delete -y

Así podemos volver a importar objetos sin chocar con versiones ya existentes en la base de datos. Si prefieres actualizar y comparar versiones, puedes valorar Configuration Update Manager.

3. Depuración intermedia con Migrate Devel

Hemos revisado los datos detenidamente y, aun así, la migración de términos desde Google Spreadsheet no parece funcionar.

Necesitamos técnicas intermedias para obtener más información. En esta fase nos ayudarán módulos y plugins que permiten observar mejor lo que ocurre durante la migración.

3.1. Migrate Devel

Migrate Devel es un módulo contribuido que añade funcionalidades mediante opciones nuevas de Drush. Funciona con migrate_tools y migrate_run.

Actualización del 03/07/2020: versión 8.x-2.0-alpha2

Justo cuando publiqué este artículo, Andrew Macpherson, nuevo mantenedor de Migrate Devel y uno de los mantenedores de accesibilidad del core de Drupal, dejó un comentario al pie del original con novedades importantes. Desde que empecé el borrador se había publicado una versión nueva, el 28 de junio, compatible con Drush 9, ¡y no lo sabía! Esa versión evita instalar el parche que se describe más abajo.

Para instalarla, la descargamos con Composer y la activamos con Drush: Migrate Devel 8.x-2.0-alpha2.

composer require drupal/migrate_devel
# To install the 2.0 branch of the module:
composer require drupal/migrate_devel:^2.0
drush en migrate_devel -y

Para versiones anteriores a 8.x-2.0-alpha2

Si trabajas con versiones anteriores, hay algunas particularidades. Estaban preparadas para Drush 8 y la adaptación a Drush 9 y posteriores aún no parecía cerrada.

En la rama 8.x-1.x había una etiqueta publicada dos semanas antes: migrate_devel/tree/8.x-1.4.

Para utilizar esas versiones con Drush 9 o superior, el parche de esta incidencia resultaba prácticamente imprescindible. Aunque tampoco parecía definitivo, permitía ejecutar de forma controlada algunas funciones del módulo. Veremos sus aportaciones.

Podemos descargar el parche con wget y aplicarlo con git apply:

cd /web/modules/contrib/migrate_devel/
wget https://www.drupal.org/files/issues/2018-10-08/migrate_devel-drush9-2938677-6.patch
git apply migrate_devel-drush9-2938677-6.patch

Otra posibilidad es añadirlo a la sección de parches de composer.json, si tenemos activada la extensión composer-patches.

La instalamos con:

composer require cweagans/composer-patches

Y añadimos el parche a la sección extra de composer.json:

Cómo funciona

Al ejecutar una migración con las opciones de Migrate Devel obtenemos valores por consola que podemos inspeccionar. Por ejemplo, con –migrate-debug:

Es una vista parcial del procesamiento de una fila: muestra la fuente, los valores asociados y el identificador final de destino, almacenado en la tabla de correspondencias para seguir el proceso:

Vemos que al valor 1 de origen, en el primer array, se le asignó el identificador 117 en destino. También será el identificador interno de la nueva entidad de Drupal, aquí un término de taxonomía. Así relacionamos el registro de migración con la entidad creada y almacenada.

¿Y los suscriptores de eventos? Migrate Devel crea una clase que implementa EventSubscriberInterface y escucha eventos de Migrate API, disponibles en el módulo migrate del core:

Called from +56
/var/www/html/web/modules/contrib/migrate_devel/src/EventSubscriber/MigrationEventSubscriber.php

La llamada procede de la clase que escucha estos eventos. En modules/migrate/src/Event se definen muchos, pero Migrate Devel presta atención especialmente a dos:

1. MigratePostRowSaveEvent.php.
2. MigratePreRowSaveEvent.php.

Estos corresponden a las dos opciones Drush del módulo, que originalmente acababan llamando a dump() de Kint, proporcionado por Devel, para imprimir los mensajes. En la versión 8.x-2.0-alpha2 se sustituyen esas llamadas por Symfony VarDumper. Donde antes teníamos:

  /**
   * Pre Row Save Function for --migrate-debug-pre.
   *
   * @param \Drupal\migrate\Event\MigratePreRowSaveEvent $event
   *    Pre-Row-Save Migrate Event.
   */
  public function debugRowPreSave(MigratePreRowSaveEvent $event) {
    $row = $event->getRow();

    $using_drush = function_exists('drush_get_option');
    if ($using_drush && drush_get_option('migrate-debug-pre')) {
      // Start with capital letter for variables since this is actually a label.
      $Source = $row->getSource();
      $Destination = $row->getDestination();

      // We use kint directly here since we want to support variable naming.
      kint_require();
      \Kint::dump($Source, $Destination);
    }
  }

Ahora tenemos:

  /**
   * Pre Row Save Function for --migrate-debug-pre.
   *
   * @param \Drupal\migrate\Event\MigratePreRowSaveEvent $event
   *    Pre-Row-Save Migrate Event.
   */
  public function debugRowPreSave(MigratePreRowSaveEvent $event) {
    if (PHP_SAPI !== 'cli') {
      return;
    }

    $row = $event->getRow();

    if (in_array('migrate-debug-pre', \Drush\Drush::config()->get('runtime.options'))) {
      // Start with capital letter for variables since this is actually a label.
      $Source = $row->getSource();
      $Destination = $row->getDestination();

      // Uses Symfony VarDumper.
      // @todo Explore advanced usage of CLI dumper class for nicer output.
      // https://www.drupal.org/project/migrate_devel/issues/3151276
      dump(
        '---------------------------------------------------------------------',
        '|                             $Source                               |',
        '---------------------------------------------------------------------',
        $Source,
        '---------------------------------------------------------------------',
        '|                           $Destination                            |',
        '---------------------------------------------------------------------',
        $Destination
      );
    }
  }

Puedes consultar los cambios en MigrationEventSubscriber.php de 8.x-2.0-alpha2.

También encontrarás más información sobre eventos y suscriptores en el artículo de The Russian Lullaby Building Symfony events for Drupal.

3.2. El plugin de proceso Debug

Migrate Devel también incorpora un plugin de proceso llamado debug, definido en Debug.php. Lo encontrarás en /web/modules/contrib/migrate_devel/src/Plugin/migrate/process/Debug.php. Su documentación explica su responsabilidad:

/**
 * Debug the process pipeline.
 *
 * Prints the input value, assuming that you are running the migration from the
 * command line, and sends it to the next step in the pipeline unaltered.
 *
 * Available configuration keys:
 * - label: (optional) a string to print before the debug output. Include any
 *   trailing punctuation or space characters.
 * - multiple: (optional) set to TRUE to ask the next step in the process
 *   pipeline to process array values individually, like the multiple_values
 *   plugin from the Migrate Plus module.

El método transform(), heredado de la clase abstracta ProcessPluginBase, no transforma el valor: utiliza print_r de PHP para mostrar por consola tanto valores escalares como arrays.

Podemos incluir el plugin de forma autónoma en la cadena de procesamiento para que imprima resultados al procesar cada fila. En nuestro caso modificaremos el bloque process de la migración de términos para revisar los valores que se están migrando.

Primero cambiaremos la estructura. Como sabemos por las entregas anteriores, esta forma:

process:
 name: name
 description: description
 path: url
 status: published

Utiliza implícitamente el plugin Get.php y equivale a esta otra:

process:
 name:
   plugin: get
   source: name
 description:
   plugin: get
   source: description
 path:
   plugin: get
   source: url
 status:
   plugin: get
   source: published

Añadimos Debug a la cadena con una etiqueta informativa para cada campo:

process:
 name:
   plugin: debug
   label: 'Processing name field value: '
   plugin: get
   source: name
 description:
   plugin: debug
   label: 'Processing description field value: '
   plugin: get
   source: description
 path:
   plugin: debug
   label: 'Processing path field value: '
   plugin: get
   source: url
 status:
   plugin: debug
   label: 'Processing status field value:  '
   plugin: get
   source: published

Después recargamos el objeto de configuración desinstalando e instalando nuestro módulo. Como figura como dependencia, al desinstalarlo también se elimina la configuración de la migración:

drush pmu migration_google_sheet && drush en migration_google_sheet -y

Al ejecutarla de nuevo aparecerá información sobre los valores:

Así obtenemos información más detallada de los datos que vamos a migrar. Para escenarios más avanzados podemos combinar argumentos y opciones. Por ejemplo, si queremos revisar un solo elemento:

 drush migrate-import --migrate-debug taxonomy_google_sheet --limit="1 items"

Esto combina la salida posterior al almacenamiento —a diferencia de --migrate-debug-pre— con la información del plugin, los valores mostrados por la herramienta de volcado y el identificador final de la única entidad procesada.

Aquí los valores son sencillos y apenas los transformamos: los extraemos y los cargamos en destino. En migraciones posteriores introduciremos tratamientos más complejos y esta información resultará aún más valiosa. Piensa en valores que hay que concatenar, recortar, ampliar o adaptar: si mostramos el resultado en cada paso podremos observar mejor toda la secuencia de transformación.

Puedes revisar el código de Debug.php y la incidencia de Drupal.org en la que surgió la propuesta de este plugin.

Con esta aproximación empezamos la subserie de depuración de migraciones. ¡Pronto, más experiencias!

4. :wq!

Canción recomendada

Foto de Unsplash, de Pan Xiaozhen, @zhenhappy

Índice

• 1. Introducción: recordemos los procesos ETL
• 2. Exponer datos mediante Google Spreadsheet
• 3. Particularidades de la transformación a JSON
• 4. Características de la migración
• 5. Módulo personalizado para la migración
• 6. :wq!

1. Introducción: recordemos los procesos ETL

Empecemos planteando un escenario: tenemos que migrar una lista de términos de taxonomía a nuestra instalación Drupal. El origen de los datos importa, porque determina qué plugins utilizaremos para la extracción y puede influir también en el procesamiento y en la carga final en el destino.

En este artículo imaginaremos que hemos «heredado» una tarea de migración que había iniciado otra persona. Consiste en poblar con términos de taxonomía un vocabulario ya existente en Drupal. Para practicar con otros plugins y modelos de migración, utilizaremos una hoja de Google como fuente. No olvidemos el marco en el que trabajamos:

Nuestro objetivo es rellenar los campos de un término de taxonomía con los datos de una hoja externa de Google. Estos son los campos que debemos completar:

Lo haremos describiendo un proceso Migrate y ejecutándolo como configuración. ¿Conoces las diferencias entre migraciones como código y como configuración? Encontrarás algunas claves en el artículo anterior de la serie.

2. Exponer datos mediante Google Spreadsheet

Para extraer los datos necesitamos una hoja cuyos valores estén expuestos. He creado esta hoja de cálculo de Google, con columnas que corresponden a los campos de un término de taxonomía y están preparadas para la migración.

Para procesar la fuente utilizaremos el módulo contribuido Migrate Google Sheets. Descárgalo con Composer y actívalo:

composer require drupal/migrate_plus #If applicable
composer require drupal/migrate_google_sheets
drush en migrate_plus migrate_google_sheet -y

Este módulo trata el recurso como un archivo JSON, pero antes tenemos que realizar algunas tareas: exponer la hoja como fuente JSON utilizando las herramientas de Google.

• Primero extraemos el workbook-id de la dirección de la hoja: docs.google.com/spreadsheets/d/1bKGbPbgeuXaBfcKetaDqoDimmYcerQY_hT1rqzw4TbM/. En este caso, workbook-id: 1bKGbPbgeuXaBfcKetaDqoDimmYcerQY_hT1rqzw4TbM.
• También necesitamos el worksheet-index, el índice de la pestaña que contiene los datos. Aquí es 1.
• Construimos la URL JSON con el patrón spreadsheets.google.com/feeds/list/[workbook-id]/[worksheet-index]/public/values?alt=json. Para nuestro ejemplo: URL de los valores en JSON.

¡Eso es todo! La hoja queda expuesta como un archivo JSON y podemos obtener los valores mediante los plugins de origen elegidos para Migrate API.

3. Particularidades de la transformación a JSON

Ahora podemos ver la fuente JSON en el navegador. Puede resultar útil una extensión que presente los datos con formato, como hace Firefox de forma predeterminada:

      {
        "gsx$id": {
          "$t": "1"
        },
        "gsx$name": {
          "$t": "Term 1"
        },
        "gsx$description": {
          "$t": "Descrip 1"
        },
        "gsx$url": {
          "$t": "/t1"
        }
        "gsx$published": {
          "$t": "1"
        }
      }

Algunos elementos han cambiado respecto al formato original. Fíjate en la comparación:

La transformación a JSON introduce cambios respecto a la hoja. Por ejemplo, Google modifica los identificadores de los campos añadiendo prefijos:

• gsx$ para los nombres de campo.
• $t para los valores almacenados en los campos.

Las cabeceras cambian así:

1. Id pasa a ser gsx$id.
2. Name pasa a ser gsx$name.
3. Description pasa a ser gsx$description.
4. Url pasa a ser gsx$url.
5. Published pasa a ser gsx$published.

Como estos cambios son estables, el plugin se encarga de procesarlos:

// Class GoogleSheets.php
// Module migrate_google_sheets
// @see https://git.drupalcode.org/project/migrate_google_sheets/

// Actual values are stored in gsx$<field>['$t'].
$this->currentItem[$field_name] = $current['gsx$' . $selector]['$t'];

Esto nos permite utilizar los nombres de los datos en su forma «plana»: en minúsculas y sin espacios ni caracteres especiales. Además, las filas se encuentran en la ruta feed/entry, que el módulo también resuelve:

// For Google Sheets, the actual row data lives under feed->entry.
if (isset($array['feed']) && isset($array['feed']['entry'])) {
 $array = $array['feed']['entry'];
}

4. Características de la migración

La primera observación es que el plugin de Google Spreadsheet extiende el analizador JSON, como vemos en la clase:

use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
use Drupal\migrate\MigrateException;
use Drupal\migrate_plus\Plugin\migrate_plus\data_parser\JSON;
use GuzzleHttp\Exception\RequestException;

/**
 * Obtain Google Sheet data for migration.
 *
 * @DataParser(
 *   id = "google_sheets",
 *   title = @Translation("Google Sheets")
 * )
 */
class GoogleSheets extends JSON implements ContainerFactoryPluginInterface {
...
}

Su bloque de anotaciones lo identifica como un Data Parser, así que necesitamos más piezas: un plugin de origen y un Data Fetcher. El plugin de Google Spreadsheet será la tercera pieza del proceso.

¿Qué plugins de origen tenemos disponibles en nuestra instalación Drupal? Vamos a consultarlos:

drupal debug:plugin migrate.source

La consola mostrará:

drupal@migrations-web:/var/www/html$ drupal debug:plugin migrate.source
 --------------- ---------------------------------------------------------
  Plugin ID       Plugin class
 --------------- ---------------------------------------------------------
  embedded_data   Drupal\migrate\Plugin\migrate\source\EmbeddedDataSource
  empty           Drupal\migrate\Plugin\migrate\source\EmptySource
  url             Drupal\migrate_plus\Plugin\migrate\source\Url
 --------------- ---------------------------------------------------------

drupal@migrations-web:/var/www/html$

Podemos utilizar la clase Url.php como plugin de origen, ya que el archivo se expone mediante una URL. En la clase Url.php vemos que necesita un analizador de datos; en nuestro caso será la clase de Google Spreadsheet:

  /**
   * The data parser plugin.
   *
   * @var \Drupal\migrate_plus\DataParserPluginInterface
   */
  protected $dataParserPlugin;

Al buscar un componente que recupere los datos encontramos la clase Http.php, preparada para trabajar con el plugin de origen URL mediante HTTP:

/**
 * Retrieve data over an HTTP connection for migration.
 *
 * Example:
 *
 * @code
 * source:
 *   plugin: url
 *   data_fetcher_plugin: http
 *   headers:
 *     Accept: application/json
 *     User-Agent: Internet Explorer 6
 *     Authorization-Key: secret
 *     Arbitrary-Header: foobarbaz
 * @endcode
 *
 * @DataFetcher(
 *   id = "http",
 *   title = @Translation("HTTP")
 * )
 */
class Http extends DataFetcherPluginBase implements ContainerFactoryPluginInterface {

Por otra parte, el constructor de Url.php recibe las direcciones de origen. Podemos proporcionar una URL o un conjunto de ellas:

  /**
   * {@inheritdoc}
   */
  public function __construct(array $configuration, $plugin_id, $plugin_definition, MigrationInterface $migration) {
    if (!is_array($configuration['urls'])) {
      $configuration['urls'] = [$configuration['urls']];
    }
    parent::__construct($configuration, $plugin_id, $plugin_definition, $migration);

    $this->sourceUrls = $configuration['urls'];
  }

Al reunir las piezas, debemos darles una estructura según su función y posición. Nuestro bloque de origen quedará así:

source:
  plugin: url
  data_fetcher_plugin: http
  data_parser_plugin: google_sheets
  urls: 'http://spreadsheets.google.com/feeds/list/1bKGbPbgeuXaBfcKetaDqoDimmYcerQY_hT1rqzw4TbM/1/public/values?alt=json'

5. Módulo personalizado para la migración

Crearemos un módulo llamado migration_google_sheet con esta estructura:

/project/web/modules/custom/
                     \__migration_google_sheet/
                         \__migration_google_sheet.info.yml
                           \__config/
                                \__install/
                                     \__migrate_plus.migration.migration.taxonomy_google_sheet.yml

Archivo de definición de la migración: migrate_plus.migration.taxonomy_google_sheet.yml.

langcode: en
status: true
dependencies:
  enforced:
    module:
      - migration_google_sheet
id: taxonomy_google_sheet
label: 'Migrating Taxonomy'
source:
  plugin: url
  data_fetcher_plugin: http
  data_parser_plugin: google_sheets
  urls: 'http://spreadsheets.google.com/feeds/list/1bKGbPbgeuXaBfcKetaDqoDimmYcerQY_hT1rqzw4TbM/1/public/values?alt=json'
  fields:
    - name: id
      label: 'Id'
      selector: id
    - name: name
      label: 'Name'
      selector: name
    - name: description
      label: 'Description'
      selector: description
    - name: url
      label: 'Url'
      selector: url
    - name: published
      label: 'Published'
      selector: published
  ids:
    id:
      type: integer
process:
  name: name
  description: description
  path: url
  status: published
destination:
  plugin: 'entity:taxonomy_term'
  default_bundle: tags

Ejecutamos la migración desde la consola:

drush en migration_google_sheet -y
drush migrate:import taxonomy_google_sheet

[notice] Processed 30 items (30 created, 0 updated, 0 failed, 0 ignored) - done with 'taxonomy_google_sheet'

¡Hecho! Hemos migrado treinta términos de taxonomía desde una hoja de Google:

Puedes descargar o clonar el módulo personalizado desde mi repositorio de GitLab.

6. :wq!

Canción recomendada

En la entrega anterior abordé las migraciones en Drupal desde el punto de vista de una caja de herramientas: un conjunto de recursos básicos que nos ayudan a plantear una migración.

Hay mucha información que procesar y, por supuesto, intervienen más conceptos, técnicas y tácticas a la hora de resolver una migración. Por eso, este mes quiero escribir algo que me permita experimentar con ellas de una forma más práctica.

Foto de Unsplash, de Émile Séguin, @emileseguin

Índice

• 1. Introducción
• 2. Preparativos
• 3. Enfoques
• 4. Migraciones
• 5. Conceptos clave
• 6. Recursos
• 7. :wq!

1. Introducción

La API de migraciones de Drupal puede ser una de las más interesantes, pero también una de las más complejas: sus operaciones suelen estar relacionadas con clases y métodos de otras APIs de Drupal, algo que se hace especialmente evidente al depurar. En cualquier caso, como la cantidad de conceptos puede resultar abrumadora, creo que podemos practicar la mecánica de las migraciones mediante un par de ejercicios.

Para este artículo me había propuesto modelar dos procesos de migración diferentes siguiendo una idea que podría resumirse como «primum vivere, deinde philosophari»: primero experimentar y después teorizar. Por eso he decidido organizarlo de una manera particular:

• Los dos procesos se dividen en apartados comunes. En lugar de terminar uno y empezar el siguiente, avanzaremos con ambos en paralelo: tú eliges tu propia aventura.
• Solo al final del artículo encontrarás algunos de los conceptos clave que utilizaremos. Primero vamos a jugar con las estructuras y después las entenderemos.

En los siguientes pasos trabajaremos con dos experiencias concretas:

1. Migrar datos desde un formato embebido, quizá el ejemplo más sencillo de una migración en Drupal.
2. Migrar datos desde un archivo CSV, un caso algo más complejo que el anterior.

Ambos son, probablemente, de los escenarios más básicos de migración. Por eso recomiendo este artículo a quien quiera iniciarse en su mecánica, como complemento práctico al estudio de las migraciones en Drupal.

2. Preparativos

Primer caso: migrar datos embebidos

Para el primer caso necesitaremos, por una parte, activar el módulo Migrate del core de Drupal y, por otra, descargar e instalar un módulo contribuido con el que gestionar las migraciones.

Entre las opciones disponibles elegiremos migrate_run, que ya mencionamos en la entrega anterior. Podemos entenderlo como una versión ligera de migrate_tools, aunque en realidad es un fork del proyecto. Ambos proporcionan comandos Drush para ejecutar migraciones, por lo que, si tienes migrate_tools instalado, debes desinstalarlo para evitar conflictos con migrate_run.

La primera lección, como detalle curioso, es que ni migrate_plus ni migrate_tools son dependencias obligatorias para ejecutar migraciones en Drupal: podemos implementar migraciones sin tener estos módulos activados en nuestra instalación.

Conviene saber, además, que migrate_run está optimizado para Drush 9 y posteriores. Si utilizas Drush 8, tendrás que recurrir a una versión adaptada, como la Alpha 4, que todavía estaba preparada para Drush 8.

Con Composer y Drush:

composer require drupal/migrate_run
drush pmu migrate_tools # If you need
drush en migrate migrate_run -y
drush cr

Con Drupal Console:

composer require drupal/migrate_run
drupal mou migrate_tools # If you need
drupal moi migrate migrate_run

En la ruta /admin/modules verás lo siguiente:

Construcción de los recursos

Crearemos un módulo personalizado para nuestra primera migración:

cd project/web/modules/custom
mkdir migration_basic_module

Después, el archivo migration_basic_module.info.yml, con este contenido:

name: 'Migration Basic Module'
type: module
description: 'Just a basic example of basic migration process.'
package: 'Migrations Examples 2000'
core: 8.x
dependencies:
  - drupal:migrate

Crea el archivo de definición de la migración en la ruta /migration_basic_module/migrations/basic_migration_one.yml.

Nuestro archivo declarativo basic_migration_one.yml describe la migración mediante una lista de parámetros y valores en un archivo estático de tipo YAML. Incluiremos los datos embebidos de dos nodos del tipo de contenido «página básica», cargando únicamente dos valores:

1. Un título: una cadena de texto.
2. Un cuerpo: un texto basado en el generador ChiquitoIpsum*, http://www.chiquitoipsum.com.

*Chiquito de la Calzada fue una figura popular en España, un humorista legendario.

basic_migration_one.yml

id: basic_migration_one
label: 'Custom Basic Migration 2000'
source:
  plugin: embedded_data
  data_rows:
    -
      unique_id: 1
      page_title: 'Title for migrated node - One'
      page_content: 'Lorem fistrum mamaar se calle ustée tiene musho pelo.'
    -
      unique_id: 2
      page_title: 'Title for migrated node - Two'
      page_content: 'Se calle ustée caballo blanco caballo negroorl.'
  ids:
    unique_id:
      type: integer
process:
  title: article_title
  body: article_content
destination:
  plugin: 'entity:node'
  default_bundle: page

Esta será la estructura del nuevo módulo personalizado del ejemplo de migración básica:

/project/web/modules/custom/
                     \__migration_basic_module/
                         \__migration_basic_module.info.yml
                             \__migrations/
                                 \__basic_migration_one.yml

Activación de todos los módulos necesarios con Drush:

drush pm:enable -y migrate migrate_run migration_basic_module
drush cr

O con Drupal Console:

drupal moi migrate migrate_run migration_basic_module

Segundo caso: migrar desde archivos CSV

Para el segundo caso desactivaremos migrate_run, si procede, y activaremos el conjunto de módulos migrate, migrate_plus y migrate_tools. Para tratar los archivos CSV utilizaremos un plugin de origen incluido en el módulo contribuido Migrate Source CSV, migrate_source_csv. En su versión 3.x, este módulo utiliza league/csv para procesar los archivos CSV. Vamos allá, con Composer y Drush:

composer require drupal/migrate_plus drupal/migrate_tools drupal/migrate_source_csv
drush pmu migrate_run # If you need
drush en migrate migrate_plus migrate_tools migrate_source_csv -y
drush cr

Ahora, en la ruta /admin/modules/:

Construcción de los recursos

Crearemos otro módulo personalizado para la segunda migración:

cd project/web/modules/custom
mkdir migration_csv_module

Con un nuevo archivo migration_csv_module.info.yml:

name: 'Migration CSV Module'
type: module
description: 'Just a basic example of basic migration process with a CSV source.'
package: 'Migrations Examples 2000'
core: 8.x
dependencies:
  - drupal:migrate
  - drupal:migrate_tools
  - drupal:migrate_plus

En este ejemplo también necesitaremos un archivo declarativo de la migración, como en el caso anterior, pero lo ubicaremos en otro lugar: la ruta /migration_csv_module/config/install/.

La estructura tendrá este aspecto:

/project/web/modules/custom/
                     \__migration_csv_module/
                         \__migration_csv_module.info.yml
                          \__csv/
                               \_migration_csv_articles.csv
                           \__config/
                                \__install/
                                     \__migrate_plus.migration.article_csv_import.yml

Necesitamos un CSV con los datos originales que vamos a migrar. Podemos generarlo fácilmente con herramientas web como Mockaroo, un generador de datos aleatorios bastante bueno. He creado un CSV con los campos id, title, body, tags e image. Los recursos relacionados se mantienen ahora en mis snippets de GitLab.

Este archivo será la fuente de datos del proceso de migración. De momento, crea los directorios del módulo y coloca el CSV en la ruta /csv:

Y ahora, nuestro archivo migrate_plus.migration.article_csv_import.yml. En apartados posteriores explicaremos su construcción y sus secciones:

uuid: 1bcec3e7-0a49-4473-87a2-6dca09b91aba
langcode: en
status: true
dependencies: {  }
id: article_csv_import
label: 'Migrating articles'
source:
  plugin: csv
  path: modules/custom/migration_csv_module/csv/migration_csv_articles.csv
  delimiter: ','
  enclosure: '"'
  header_offset: 0
  ids:
    - id
  fields:
    -
      name: id
      label: 'Unique Id'
    -
      name: title
      label: Title
    -
      name: body
      label: 'Post Body'
    -
      name: tags
      label: 'Taxonomy Tag'
    -
      name: image
      label: 'Image Field'
process:
  title: title
  body: body
  tags: field_tags
  image: field_image
  type:
    plugin: default_value
    default_value: article
destination:
  plugin: 'entity:node'

Ya tenemos todos los recursos necesarios para crear la nueva migración. Veamos cómo vamos a abordar el proceso.

3. Enfoques

Describiremos los diferentes enfoques que aplicaremos a nuestros ejemplos para entenderlos mejor.

Primer caso: migrar datos embebidos

En el primer caso hemos planteado una migración tan ligera como sea posible: solo dos nodos con dos campos básicos cada uno y los datos embebidos. Lo más sencillo posible.

Además, en las tres fases ETL de la migración —extracción, transformación y carga— utilizaremos plugins que Drupal ya proporciona. No desarrollaremos ningún plugin personalizado. Si todavía no conoces el concepto de plugin de migración, detente un momento y lee la introducción del primer artículo de esta serie.

Para aligerar el ejemplo utilizaremos Migrate Run, esa versión «lite» de Migration Tools. Emplearemos únicamente los comandos básicos, sin opciones ni parámetros complementarios, con el identificador del archivo de migración como argumento.

Segundo caso: migrar desde archivos CSV

En esta ejecución quiero probar algo interesante. Como ejecutaremos la segunda migración como configuración, me parece divertido recorrer el camino inverso. Propongo no instalar ni activar el módulo personalizado del CSV: lo dejaremos únicamente como ubicación del archivo de datos.

Vamos a llevar la migración a otro lugar y ejecutarla desde allí. Sorpresa. Visita la ruta /admin/config/development/configuration/single/import de tu instalación Drupal. ¡Nos vemos allí!

4. Migraciones

Primer caso: migrar datos embebidos

Consultar las migraciones disponibles

drush migrate:status
drush ms

Output from console:
----------------- -------- ------- ---------- ------------- ---------------------
  Migration ID      Status   Total   Imported   Unprocessed   Last Imported
----------------- -------- ------- ---------- ------------- ---------------------
basic_migration_one   Idle     2       0          2
----------------- -------- ------- ---------- ------------- ---------------------

Ejecutar las migraciones

drush migrate:import basic_migration_one
drush mi basic_migration_one

Output from console:
----------------- -------- ------- ---------- ------------- -------------------
  Migration ID      Status   Total   Imported   Unprocessed  Last Imported
----------------- -------- ------- ---------- ------------- -------------------
basic_migration_one   Idle     2       2 (100%)   0            2020-03-17 23:19:36
----------------- -------- ------- ---------- ------------- -------------------

Al visitar /admin/content verás los dos nodos nuevos:

Revertir las migraciones: deshacer la importación

drush migrate:rollback basic_migration_one
drush mr basic_migration_one

Output from console:

[notice] Rolled back 2 items - done with 'basic_migration_one'

Segundo caso: migrar desde archivos CSV

En la ruta /admin/config/development/configuration/single/import importaremos el archivo de definición de nuestra migración personalizada.

Cargar la configuración de la migración

Ve a Importar → Elemento individual, selecciona «Migration» como tipo de configuración y pega el contenido del archivo original de la migración:

Pulsa «Importar» y se creará el nuevo objeto en el sistema de configuración.

¿Y ahora?

Ejecutar la migración

Con el archivo de migración bajo la gestión de configuración, puedes ejecutar el proceso con las mismas herramientas del caso anterior. Ahora tenemos una nueva migración disponible desde la consola. Compruébalo con drush migrate:status:

Puedes ejecutar la migración con drush migrate-import article_csv_import. Se crearán los nuevos nodos. ¿La limitación? No se migrarán las etiquetas ni las imágenes: una etiqueta es una referencia a entidad y una imagen no es simplemente un enlace, sino un archivo. Ambos tipos necesitan otros plugins; lo veremos en futuras entregas.

Drush cex / Drush cim

Al estar la migración en el sistema de configuración, podemos editarla, importarla y exportarla con las herramientas básicas de Drush. Por ejemplo, probando drush cex:

Como puedes ver, el sistema de configuración ha puesto directamente el nuevo archivo bajo la gestión de Migrate Plus y ha realizado algunas operaciones: renombrarlo con el prefijo migrate_plus.migration o añadir un archivo para el grupo, que sirve para agrupar procesos de migración.

¿Recuerdas el nombre del archivo? Es el mismo que utilizábamos en /config/install: migrate_plus.migration.article_csv_import.yml. Hemos realizado el mismo proceso, pero desde otra dirección. ¿Te impresiona? ¿No? ¿Al menos te parece interesante?

Recuerda también que puedes utilizar drush cim con este archivo de configuración para cargar la migración en otra instalación Drupal, siempre que tenga acceso al CSV como fuente de datos, claro.

Así hemos migrado unos 102 nodos nuevos utilizando dos enfoques y metodologías diferentes. No está mal.

5. Conceptos clave

Plugins de migración

Esto es importante, así que toca repetir la misma canción: hay que conocer el formato de los plugins y el diverso mundo de los plugins de migración existentes.

Cada plugin responde a un tipo de dato, un formato o una fuente concreta. Conviene conocer bien los principales e investigar los que puedas necesitar, porque las migraciones los utilizan intensivamente. Por eso, por ejemplo, no hemos podido migrar los términos de taxonomía ni las imágenes del segundo caso directamente desde el CSV.

Vamos a revisar los plugins que intervienen en estas dos migraciones a partir de sus archivos de definición.

Migración básica con datos embebidos

source:
  plugin: embedded_data
  data_rows:
         ...
process:
  title: creative_title
  body: engaging_content
destination:
  plugin: 'entity:node'
  default_bundle: page

Para extraer los datos utilizamos el plugin Embedded Data, una clase PHP disponible en /web/core/modules/migrate/src/Plugin/migrate/source/EmbeddedDataSource.php. En su bloque de documentación puedes ver algunas claves de configuración que puedes utilizar en la definición:

 *
 * Available configuration keys
 * - data_rows: The source data array.
 * - ids: The unique ID field of the data.
 *

Precisamente data_rows e ids son las claves que utilizamos: el array de datos de origen y su identificador único. Puedes leer más sobre la clase EmbeddedDataSource en la documentación de la API de Drupal.org.

Ahora fíjate en el bloque process y busca… ¿dónde está el plugin de procesamiento? Esto es interesante. Normalmente cada correspondencia de campos necesita un plugin de proceso. Con un poco de «azúcar sintáctico», Migrate API permite simplificar la definición: cuando un campo no necesita un tratamiento específico, el mismo plugin puede encargarse de obtener su valor. Además, ese plugin predeterminado puede quedar implícito. Si no lo declaramos, Drupal aplica el plugin de proceso por defecto.

Ese plugin implícito es la clase Get, la solución básica para procesar campos. La encontrarás en /web/core/modules/migrate/src/Plugin/migrate/process/Get.php. Más información sobre Get.php en la API de Drupal.org. En otras palabras, escribir esto:

process:
  title: page_title

Equivale a escribir esto otro:

process:
  title:
    plugin: get
    source: page_title

Así la vida resulta un poco más sencilla, ¿verdad? Recuerda: si no declaras un plugin de procesamiento para un campo, Drupal aplicará Get por defecto.

Por último, en el destino utilizamos el plugin de entidad con el parámetro node para crear nodos del tipo page. Esto recurre al plugin de destino Entity.php, una clase abstracta ubicada en web/core/modules/migrate/src/Plugin/migrate/destination/Entity.php, y a su plugin derivado. Puedes leer más sobre los plugins derivados en Drupal, el plugin de destino Entity.php y la clase derivadora de migraciones.

Migración con un CSV como fuente de datos

Creo que en este caso revisar los plugins resulta más sencillo e intuitivo:

source:
  plugin: csv
 ...
 process:
 ...
   type:
     plugin: default_value
     default_value: article
 destination:
   plugin: 'entity:node'

Para el origen utilizamos el plugin CSV del módulo contribuido migrate_source_csv. En el procesamiento usamos Get por defecto y Default Value para el tipo de contenido. En el destino repetimos el plugin del ejemplo anterior: nuevas entidades.

Migraciones como código o como configuración

Como has visto, hemos tratado cada proceso de una manera distinta. El primero, con datos embebidos, forma parte del código, sin más particularidades. El segundo se trata como un elemento de configuración del sistema: al situarlo en config/install, la instalación puede crear un objeto de configuración.

En ambos casos escribimos una definición YAML y colocamos el archivo en una ubicación u otra. Pero hay más diferencias. Resumamos las claves:

• Las migraciones «como código» están disponibles de serie. El módulo Migrate Plus permite tratar la definición como un objeto de configuración.
• Según el enfoque, cambian la ubicación de los archivos y el flujo de trabajo.
• Como código, necesitas acceso al sistema de archivos para modificar la definición y gestionarla como cualquier otro archivo de código. Es un enfoque orientado a desarrolladores.
• Como configuración, puedes modificar la definición desde la interfaz de sincronización de Drupal, en /admin/config/development/configuration, y utilizar las herramientas de exportación e importación drush cex y drush cim. La migración se sincroniza y su definición se guarda en la base de datos. Esto permite trabajar con las definiciones desde la interfaz de usuario. Toda una sorpresa.
• Como objeto de configuración, la migración crea un registro en el sistema de configuración que puede permanecer cuando se desinstale el módulo de migración. Para eliminarlo con el módulo, añade tu módulo personalizado como dependencia forzada en el YAML. Así se eliminará de la configuración activa al desinstalarlo:

  dependencies:
    enforced:
      module:
        - my_own_migration_custom_module

• Otra diferencia del enfoque como configuración es el uso de un UUID: un identificador global del sistema de gestión de configuración de Drupal. Añade un UUID propio y único al principio del archivo. Su formato consta de 32 dígitos hexadecimales repartidos en cinco grupos con el patrón 8-4-4-4-12. ¡Genera el tuyo! El original utiliza como ejemplo ilustrativo uuid: cacafuti-1a23-2b45-3c67-4d567890a1b2; contiene caracteres no hexadecimales, por lo que debes sustituirlo por un UUID válido.

6. Recursos

Descarga, prueba y experimenta con los recursos utilizados en el artículo. Los recursos relacionados se mantienen ahora en mis snippets de GitLab.

1. Archivo de migración básica.
2. Archivo de migración CSV.
3. CSV de origen con datos aleatorios.
4. Código de los dos módulos de migración, básico y CSV, referenciado desde mi perfil de GitLab. Este será un repositorio central para los módulos de la serie, con los dos ejemplos:
   • Primera migración básica con datos embebidos.
   • Segunda migración básica con un CSV como fuente de datos.
5. En paralelo a estos artículos publico snippets en GitLab sobre migraciones, con un formato más breve. Desde el primero puedes acceder al resto de la serie: Drupal Migrations Tips (I): Creating a new basic migration structure.

7. :wq!

Canción recomendada