Esta sexta entrega vuelve al lado práctico de la migración de datos: poblar Drupal con datos remotos y estructurados obtenidos de varias API. El objetivo no es construir de una sentada la migración más espectacular del mundo, sino diseñar un proceso lo bastante sencillo para entenderlo y lo bastante complejo para resultar realmente útil.

¿Qué demuestra esto sobre Drupal? Que puede incorporar datos de varias API a un modelo de contenido estructurado, conservar las relaciones entre registros y convertir ese modelo en páginas que las personas puedan recorrer y consultar. Para quienes desarrollan directorios, catálogos u otros sitios que combinan datos externos, la experiencia Rick and Migraty ofrece un ejemplo práctico con la API Migrate, entidades de contenido personalizadas y Views. El repositorio enlazado y la configuración de DDEV permiten ejecutar el proyecto en local y examinar cómo encajan esas piezas.

Para conseguirlo, nos conectaremos a API externas, abiertas y de acceso gratuito. Recursos como la API de Rick and Morty, la API de TVmaze y la wiki de Rick and Morty en Fandom nos proporcionarán los datos necesarios para poblar nuestras entidades de Drupal con personajes, localizaciones, episodios, puntuaciones y descripciones.

La API de Rick and Morty será nuestra fuente principal y proporcionará las entidades básicas y sus relaciones. TVmaze se unirá a la fiesta como fuente secundaria de enriquecimiento, aportando puntuaciones de episodios que integraremos en las entidades de Drupal existentes. Por último, Fandom contribuirá con descripciones narrativas, detalles biográficos y otra información contextual, para construir perfiles más ricos de los personajes y lugares de nuestro universo animado favorito.

Nota: A fecha de 14 de octubre de 2026, la versión original de este artículo supera los 52.000 caracteres y ronda las 10.000 palabras, con un tiempo de lectura estimado de entre 50 y 60 minutos.

Fotografía de Unsplash, del usuario Julian Kraus, @juliankraus

Índice de contenidos

0. TL;DR (solo quiero jugar con Drupal)
1. De dónde salió la idea (orígenes)
2. Qué buscamos (objetivos)
3. Analizar los datos (comprender)
4. Algunas restricciones iniciales (espera)
5. Contenedores de destino en Drupal (entidades)
6. Diseñar la migración (cocinar)
7. Definir plugins de migración (soluciones)
8. Más información de las fuentes (enriquecimiento)
9. De los datos al contenido (navegar)
10. La migración como operación (ejecutar)
11. Perder la cabeza (depurar)
12. Decisiones que merece la pena destacar (decidir)
13. Qué he aprendido (reflexionar)
14. Próximos pasos (planificar)
15. :wq!

0. TL;DR (solo quiero jugar con Drupal)

Vale, vale, no te juzgo. Asegúrate de cumplir los requisitos previos del proyecto:

1. Tener Git instalado en tu equipo (git v2.43.0).
2. Tener DDEV instalado (ddev v1.25.4, Docker v29.9.0).
3. Disponer de una terminal de Linux.

Una vez comprobado todo, sigue estos pasos:

git clone https://gitlab.com/davidjguru/rick-and-migraty.git

cd rick-and-migraty/

ddev start

ddev composer install

Con ello habrás configurado el proyecto en tu entorno de desarrollo local (LDE) utilizando DDEV. Ahora vamos a preparar la instalación de Drupal:

ddev drush site:install --existing-config \
  --account-name=admin \
  --account-pass=admin \
  -y

ddev launch

Así se completará la configuración del sitio y se abrirá el proyecto en tu navegador, en https://rick-and-migraty.ddev.site:

Vista principal de Rick and Migraty en el navegador

Lo que realmente importa en la portada son las acciones que permite realizar el proyecto:

Menú de acciones: aprender, explorar y borrar cosas

¡Recuerda! Las credenciales de instalación son user: admin, password: admin. También puedes acceder a la documentación del proyecto en la URL local https://docs.rick-and-migraty.ddev.site. ¡Disfrútalo!

¿Te gusta lo que ves? Puedes apoyarme compartiendo este artículo, dando a conocer el repositorio (https://gitlab.com/davidjguru/rick-and-migraty) o añadiéndole una estrella en GitLab:

¡Apoya el proyecto con una estrella! ⭐

1. De dónde salió la idea (orígenes)

Durante una temporada estuve trabajando en procesos de migración en Drupal basados en la API Migrate. Algunas de aquellas experiencias profesionales terminaron convirtiéndose en la serie de artículos sobre migraciones en Drupal publicada aquí.

Por esas mismas fechas llegó a mi vida la serie de animación de Adult Swim Rick and Morty (2013–actualidad). Durante un tiempo fue una de mis series favoritas, a pesar de sus altibajos, gracias a su ritmo frenético, su absoluta falta de filtros, sus colores vibrantes y la excéntrica relación entre un científico loco (Rick Sanchez) y su nieto (Morty Smith).

Quería hacer algo con todo aquello: preparar una poción mágica con un poco de Drupal, mucho Rick and Morty y una dosis generosa de la API Migrate de Drupal. Llevaba tiempo dando vueltas a la idea de reunir información útil sobre la serie en una plataforma web que indexara su enorme cantidad de personajes, una cifra que parece crecer exponencialmente. Decidí probar… y así descubrí The Rick and Morty API, que me entusiasmó bastante.

Y así nació The Rick and Migraty Experience.

La nueva experiencia Rick and Migraty: ¡Wubba Lubba Dub-Dub!

Algunos acontecimientos recientes me han dejado algo más de tiempo libre para retomar la idea justo donde la había dejado. Por suerte había conservado el trabajo anterior: investigación de experiencia de usuario, maquetas, esquemas de interfaz, diseños de entidades de Drupal y casos de uso para consultas. Montones de consultas, preparadas para recibir montones de respuestas JSON.

El tercer artículo de esta serie ya utilizaba una fuente con formato JSON, pero lo hacía mediante una transformación de una hoja de cálculo de Google y un analizador de un módulo contribuido que sabía interpretar aquella estructura especial. Esta vez quería centrarme en un escenario más propio del trabajo con API.

La API de Rick and Morty es un buen campo de pruebas para las migraciones en Drupal: es pública, lo bastante estable para un artículo, paginada, relacional y un poco disparatada en el buen sentido. Esa combinación vale más de lo que parece. Un ejemplo de migración no debería limitarse a importar tres filas planas y dar el trabajo por terminado; debería mostrar algunos de los problemas estructurales que encontramos en proyectos reales.

En este caso, el objetivo es diseñar el proceso de migración antes de escribir todo el código. Identificaremos los recursos de origen, propondremos un modelo de destino en Drupal, definiremos el orden de las operaciones y enumeraremos los plugins de proceso o transformaciones que probablemente necesitaremos.

2. Qué buscamos (objetivos)

La idea principal, el objetivo central, es construir una plataforma unificada para explorar y seguir tanto a los personajes que pueblan los episodios como a los propios episodios. Un lugar donde consultar perfiles de personajes como este:

Esquema de baja fidelidad de un perfil de personaje

Un sitio que resulte útil para consultar información sobre los aproximadamente mil personajes existentes —las cifras varían según la fuente, pues muchos habitan en distintos lugares y no siempre hay consenso— y sobre los numerosos episodios y temporadas. Todo envuelto en una apariencia coherente, sencilla y atractiva. Se trata de convertir los bocetos originales en algo más interesante:

Evolución del perfil: del esquema a la maqueta y al diseño

En un plano más concreto necesitamos una navegación básica, directa e intuitiva; una pequeña herramienta de búsqueda fácil de usar, con la que localizar y filtrar información; y, junto a la plataforma de datos, un espacio centralizado para reunir la documentación y el conocimiento del proyecto.

Como ya existen plataformas de este tipo, necesitamos ir un paso más allá: reunir información que actualmente no se encuentra en un único lugar.

Para conseguirlo, diseñaremos un proceso de migración capaz de combinar datos de varias fuentes cuando sea necesario. Pero antes de escribir archivos YAML debemos comprender bien la naturaleza del problema —o, mejor dicho, del desafío tecnológico— que pretendemos resolver.

3. Analizar los datos (comprender)

Lo primero es pensar cómo modelar lo que buscamos: qué información queremos obtener, qué novedad queremos introducir para ofrecer algo distintivo, como comentábamos antes, y cómo vamos a hacerlo.

La primera pregunta es: ¿qué consideraríamos información valiosa? Aquí van algunas ideas:

• Disponer de una sinopsis de cada episodio que contextualice lo que sucede.
• Obtener una puntuación o valoración de cada episodio.
• Tener una lista de los personajes que aparecen en cada episodio.
• Contar con información de contexto sobre los personajes, ya sea biográfica o relacionada con su papel en la historia.
• Consultar la lista de episodios en los que aparece un personaje concreto.

Aquí comienza una breve fase de selección de fuentes de datos. Por razones obvias —forma parte de la motivación original del proyecto— queremos que la fuente principal sea The Rick and Morty API. Sin embargo, frente a los requisitos anteriores, esta API presenta algunas limitaciones:

• Los episodios no incluyen sinopsis ni descripción.
• Los episodios no incluyen puntuación ni valoración.
• Los personajes no incluyen descripción.

Esta API será la fuente canónica del dominio principal. Es decir, decidirá qué personajes, localizaciones y episodios existen en nuestro modelo de Drupal. Otras API podrán enriquecer los registros importados, pero no deberían alterar silenciosamente la identidad principal del conjunto de datos. Como puedes comprobar en la propia fuente (https://rickandmortyapi.com/documentation#get-a-single-episode), aún falta información para completar el modelo:

Ejemplo de datos obtenidos de un episodio

Por tanto, necesitamos fuentes adicionales que aporten lo que falta y enriquezcan los datos existentes: descripciones de episodios y personajes, y puntuaciones de episodios.

Para obtener las biografías y las sinopsis podemos utilizar la API de la wiki de Fandom, que ofrece esa información.

¿Y las puntuaciones de los episodios? Fandom puede ofrecer un campo llamado ratings, pero no se refiere a valoraciones o reseñas. En las páginas de episodios de la wiki de Rick and Morty en Fandom, ese campo parece representar cifras de audiencia, en millones de espectadores, y no una puntuación numérica.

Así que necesitamos otra fuente para obtener esas puntuaciones. Utilizaremos la API de TVmaze, una base de datos y plataforma comunitaria de seguimiento de series de televisión y series web.

Esto no consiste solo en «leer JSON y crear contenido en Drupal». Esa frase siempre se queda corta. Estamos modelando un pequeño dominio de contenido a partir de API remotas: personajes, lugares, episodios, puntuaciones, descripciones, referencias entre registros y reglas operativas para que las importaciones repetidas sean predecibles.

En resumen… En este punto ya trabajamos con tres API al modelar el contenido y la migración:

Esta separación importa. Cuando varias API participan en el mismo modelo de destino, cada fuente necesita una responsabilidad clara. De lo contrario, la migración se convierte en una discusión silenciosa entre sistemas remotos y a Drupal le toca recoger el desastre.

Los tres recursos principales de la API de Rick and Morty deberían corresponderse de forma natural con entidades de contenido de Drupal:

1. Personajes: son los registros más visibles. Contienen estado, especie, género, origen, última localización conocida, URL del avatar y referencias a episodios. También son lo primero que la mayoría querrá consultar.
2. Localizaciones: proporcionan la estructura espacial del multiverso: planetas, cúmulos, dimensiones y otros lugares. No son meras etiquetas de los personajes, sino entidades con sus propios metadatos y relaciones inversas a través de sus residentes.
3. Episodios: aportan la estructura narrativa. Conectan muchos personajes, tienen códigos de temporada y episodio y son el mejor lugar para integrar las puntuaciones de TVmaze, porque ambas API pueden ponerse de acuerdo sobre temporada y número de episodio.

En este artículo quiero tratarlos como datos estructurados reales del dominio, y no como JSON de ejemplo de usar y tirar. Por eso no nos limitaremos a importar personajes como nodos ignorando lo demás. De hecho, lo interesante es el grafo de relaciones:

Relaciones entre conceptos y entidades del proceso de migración

Como muestra la imagen:

• Los personajes tienen un origen y una última localización conocida.
• Los personajes aparecen en episodios.
• Los episodios contienen muchos personajes.
• Las localizaciones contienen residentes.
• Los residentes son personajes.

Y sí: esto implica relaciones circulares.

4. Algunas restricciones iniciales (espera)

Esas relaciones circulares son la primera restricción arquitectónica. Nos indican que la migración no puede resolverse con una única importación heroica. Pongamos un poco de orden.

La primera restricción es el orden de migración. Las localizaciones y los episodios deben existir antes de que los personajes puedan referenciarlos. Los personajes deben existir antes de rellenar characters en los episodios y residents en las localizaciones. El orden no es un detalle técnico que dejamos para el final: forma parte del modelo de contenido.

La segunda restricción es la autoridad de las fuentes. Los registros de la API de Rick and Morty incluyen identificadores numéricos estables y URL de los recursos; esos valores serán nuestra capa de identidad externa mediante campos como api_id y api_url. TVmaze puede enriquecer episodios, pero no debería crear episodios adicionales en Drupal que no existan en la fuente canónica. Fandom puede aportar contexto editorial de la wiki, pero tampoco debe sobrescribir alegremente la fuente principal. Antes de introducir un valor en un campo de destino, debemos decidir si representa identidad de origen, enriquecimiento editorial, ayuda para la presentación o simples metadatos de diagnóstico.

La tercera restricción es la repetibilidad. Durante el desarrollo ejecutaremos muchas importaciones, reversiones y reinicios; limitaremos páginas, almacenaremos respuestas en caché y, a veces, utilizaremos fixtures. No es solo un ejercicio de modelado, sino también de operaciones: ¿podremos volver a ejecutar la migración mañana sin tener que adivinar el estado de la base de datos, las tablas de correspondencias o la API remota?

Bienvenidos a las migraciones. Los datos son un desastre, pero al menos vienen en JSON.

5. Contenedores de destino en Drupal (entidades)

Mi primera reacción es evitar los nodos. No porque tengan nada de malo, sino porque estos datos son importados, estructurados, externos y fuertemente relacionales. Parece más fiel a su naturaleza modelarlos como entidades de contenido personalizadas.

En el proyecto habrá un módulo personalizado dedicado a la API de entidades: rick_and_migraty_api.

Su función no es obtener datos remotos. Su función es proporcionar el modelo permanente de Drupal que rellenará la capa de migración y que después el sitio expondrá mediante rutas, Views, plantillas y navegación. Definirá tres entidades de contenido personalizadas:

1. rick_and_migraty_character
2. rick_and_migraty_location
3. rick_and_migraty_episode

Las tres extienden la misma clase base abstracta:

Drupal\rick_and_migraty_api\Entity\RickAndMigratyEntityBase

Esta clase centraliza los campos necesarios para cualquier recurso importado: api_id, name, api_url, api_created, uid, created, changed y path. El fundamental es api_id: es obligatorio, tiene una restricción de unicidad y representa el identificador numérico estable de la API de Rick and Morty. En la práctica, es la identidad externa que utilizamos para actualizaciones, búsquedas de relaciones y depuración.

El campo name actúa también como etiqueta de la entidad mediante entity_keys, mientras que api_url y api_created permiten rastrear la entidad hasta el recurso remoto original. Los campos locales created y changed indican cuándo creó o actualizó Drupal su copia. Existe un campo uid porque son entidades de contenido reales y Drupal sigue necesitando un propietario para comprobar el acceso y gestionar los formularios de edición.

La entidad base conserva además los campos de enriquecimiento para una pasada posterior de Fandom: fandom_description, fandom_page_id, fandom_url y fandom_source. Es deliberado: la identidad canónica procede de la API de Rick and Morty, pero el contexto editorial puede llegar después desde la API de Wiki/Fandom, mediante una actualización independiente. El modelo hace visible esa diferencia, en lugar de fingir que todos los campos importados tienen la misma autoridad.

Por último, cada entidad incluye un campo base path. Así Pathauto tiene dónde guardar alias legibles, mientras las rutas canónicas internas permanecen estables.

Los tres tipos de entidad deben compartir también la misma estructura administrativa: rutas canónicas, de colección, creación, edición y borrado; un constructor de listados personalizado para los resúmenes administrativos; datos disponibles para Views; y un permiso común:

administer rick and migraty api entities

Un detalle pequeño pero importante: la visualización es pública, mientras las operaciones administrativas permanecen protegidas. Encaja con el objetivo del módulo: cualquiera puede recorrer el universo importado, pero la gestión de sus registros sigue sometida a los permisos de Drupal.

Localizaciones

Campos de rick_and_migraty_location:

Las localizaciones se importan pronto porque los personajes las referencian mediante origin y location.url. La relación inversa residents puede esperar a otra pasada. Así evitamos pedir a la migración que referencie personajes todavía inexistentes.

Episodios

Campos de rick_and_migraty_episode:

Con los episodios empezamos a ir más allá de la API de Rick and Morty. Esta nos da la identidad, el título, el código y las URL de los personajes. TVmaze enriquece ese mismo episodio con su puntuación. Por eso la entidad almacena tanto los campos canónicos como los de trazabilidad de TVmaze.

Conservamos deliberadamente episode_code como texto de origen y lo descomponemos en season y episode_number. Estos enteros derivados resultan más útiles para filtrar, ordenar, emparejar episodios con TVmaze y construir la navegación.

Personajes

Campos de rick_and_migraty_character:

Los personajes son las entidades más conectadas: apuntan a localizaciones y episodios y aparecen en sus listas inversas. Por eso su migración no debe ejecutarse primero. Necesita que las localizaciones y los episodios existan para resolver con seguridad origin, last_location y episodes.

La URL remota image_url y el campo local avatar están separados intencionadamente. La primera conserva el dato de la API; el segundo representa un archivo gestionado por Drupal que podemos mostrar de manera uniforme en las páginas de personajes.

El módulo mantiene así un grafo que refleja la API de origen, sin obligarnos a resolver todo en una única pasada:

• rick_and_migraty_character.origin apunta a rick_and_migraty_location.
• rick_and_migraty_character.last_location apunta a rick_and_migraty_location.
• rick_and_migraty_character.episodes apunta a rick_and_migraty_episode.
• rick_and_migraty_episode.characters vuelve a apuntar a rick_and_migraty_character.
• rick_and_migraty_location.residents vuelve a apuntar a rick_and_migraty_character.

Al ser entidades de contenido personalizadas, participan de forma natural en Views, rutas de entidad, plantillas y permisos, sin hacerse pasar por nodos editoriales normales. Puedes ver las entidades implementadas en el repositorio.

El proyecto define además patrones legibles de Pathauto:

Estos alias son deliberadamente plurales y fáciles de leer. Por debajo, las rutas canónicas siguen siendo rutas estables de Drupal, como /rick-and-migraty/character/{rick_and_migraty_character}. Esta separación mantiene predecible la implementación y agradables las URL públicas.

6. Diseñar la migración (cocinar)

Una vez resuelto —o casi— el modelo de destino, el siguiente paso no es escribir archivos YAML a toda velocidad. Ahora toca cocinar el diseño: comprender cómo se organizan los datos de origen, decidir el orden de importación, determinar qué problemas podemos resolver con YAML y cuáles requieren plugins personalizados y, solo entonces, conectar origen, proceso y destino.

También debemos asumir que aparecerán dificultades y retos nuevos por el camino. Habrá que iterar, experimentar y encontrar soluciones mediante ensayo y error. Paciencia.

Para empezar a cocinar, recordemos que la API de Rick and Morty es una API REST que devuelve JSON. No es JSON:API en el sentido estricto del módulo del núcleo de Drupal. Sin embargo, desde la perspectiva de una migración, la idea fundamental es la misma: recibir registros estructurados de una fuente remota y transformarlos en entidades de Drupal.

La API utiliza peticiones GET sobre HTTPS y devuelve respuestas JSON. Los puntos de acceso de los listados están paginados e incluyen un objeto info con los metadatos de paginación:

{
  "info": {
    "count": 826,
    "pages": 42,
    "next": "https://rickandmortyapi.com/api/character/?page=2",
    "prev": null
  },
  "results": []
}

La fuente proporciona tres colecciones principales:

Las cifras exactas importan menos que la estructura de los datos de origen:

• Los resultados de los listados están en results.
• La paginación está en info.next.
• Las relaciones se representan mediante URL.
• Cada objeto tiene un identificador numérico estable.
• Desde nuestro punto de vista, la fuente es de solo lectura.

Un registro de personaje permite ver el principal problema de la migración:

{
  "id": 1,
  "name": "Rick Sanchez",
  "status": "Alive",
  "species": "Human",
  "type": "",
  "gender": "Male",
  "origin": {
    "name": "Earth (C-137)",
    "url": "https://rickandmortyapi.com/api/location/1"
  },
  "location": {
    "name": "Citadel of Ricks",
    "url": "https://rickandmortyapi.com/api/location/3"
  },
  "image": "https://rickandmortyapi.com/api/character/avatar/1.jpeg",
  "episode": [
    "https://rickandmortyapi.com/api/episode/1",
    "https://rickandmortyapi.com/api/episode/2"
  ],
  "url": "https://rickandmortyapi.com/api/character/1",
  "created": "2017-11-04T18:48:46.250Z"
}

El contenido es fácil de leer, pero no es plano. Los personajes apuntan a localizaciones y episodios mediante URL. Los episodios vuelven a apuntar a personajes. Las localizaciones apuntan a residentes, que también son personajes. En otras palabras, la fuente es lo bastante pequeña para explicarla en un artículo, pero lo bastante relacional para obligarnos a tomar decisiones reales de migración.

La primera decisión es el orden de importación. Si intentamos resolver todo el grafo en una única importación heroica, nos estamos ofreciendo voluntarios para sufrir.

El proceso que implementaremos estará dividido en fases:

1. Importar las localizaciones.
2. Importar los episodios, ya enriquecidos con las puntuaciones de TVmaze cuando estén disponibles.
3. Descargar los archivos de los avatares.
4. Importar los personajes, resolviendo localizaciones, episodios y archivos de avatar.
5. Actualizar los episodios para resolver su campo characters.
6. Actualizar las localizaciones para resolver su campo residents.

Esta secuencia es la respuesta práctica al grafo circular. Algunos campos de relación ya figuran en el YAML de la primera migración, pero migration_lookup utiliza no_stub: true, de modo que las referencias no resueltas no crean entidades provisionales. Las referencias inversas pendientes se completan después con --update, cuando ya existen las entidades locales de los personajes.

Ahora que la secuencia está clara, por fin toca implementar los pasos que acabamos de describir. Sigamos.

Primero, las localizaciones

En esta migración, una localización es un dato fundamental sobre un personaje: nos dice de dónde procede y dónde estaba establecido, al menos al principio, porque los personajes importantes suelen moverse entre dimensiones, planetas y demás.

Las localizaciones son el primer contenedor estable, ya que los personajes las necesitan para origin y last_location.

• Punto de acceso: /api/location.

Cargaremos:

• api_id
• name
• location_type
• dimension
• api_url
• api_created

Esta es la definición completa de la migración de localizaciones:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

id: rick_and_migraty_location
label: 'Rick and Migraty locations'
migration_group: rick_and_migraty

source:
  # Custom source plugin that follows the Rick and Morty API info.next pager.
  plugin: rick_and_morty_api
  resource: location
  # Avoid status/listing commands walking the public API just to count rows.
  skip_count: true
  # Cache each API page by URL so repeated imports and retries are gentle.
  cache: true
  cache_ttl: 86400
  # Keep this at 0 by default; raise it locally if the public API throttles.
  request_delay_ms: 0

process:
  # Store the external ID as a first-class field. The migrate map still owns
  # the Drupal entity ID mapping.
  api_id: id
  name: name
  location_type: type
  dimension: dimension
  residents:
    -
      # Location rows contain an array of resident character URLs.
      plugin: rick_and_migraty_url_id
      source: residents
    -
      plugin: migration_lookup
      migration: rick_and_migraty_character
      no_stub: true
  api_url: url
  api_created:
    plugin: format_date
    source: created
    from_format: 'Y-m-d\TH:i:s.v\Z'
    to_format: 'Y-m-d\TH:i:s'
    from_timezone: UTC
    to_timezone: UTC
  uid:
    plugin: default_value
    default_value: 1

destination:
  plugin: 'entity:rick_and_migraty_location'
  validate: true

migration_dependencies: {}

El primer bloque es la definición del origen. En lugar de enumerar URL concretas, la migración pide al plugin personalizado rick_and_morty_api el recurso location. Ese pequeño ajuste, resource: location, basta para que construya el primer punto de acceso, siga la paginación, almacene las respuestas en caché y exponga cada localización de results como una fila de migración.

Las asignaciones directas de campos son deliberadamente aburridas, y eso es bueno. api_id guarda el identificador numérico externo; name, la etiqueta visible; location_type recibe el valor type de la API; y dimension conserva el espacio ficticio al que pertenece la localización. Por su parte, api_url y api_created permiten rastrear el registro hasta la respuesta original.

Hay una transformación que merece atención: api_created utiliza format_date. La fuente proporciona una marca temporal como 2017-11-10T12:42:04.162Z; Drupal la guarda en UTC con el formato más limpio Y-m-d\TH:i:s. No es una transformación espectacular, pero estas pequeñas normalizaciones facilitan consultar los datos después.

La asignación de residents resulta más interesante porque es un campo de relación. Las filas contienen un array de URL de personajes, no identificadores locales de Drupal. Por eso el proceso utiliza primero rick_and_migraty_url_id para extraer los identificadores numéricos y después migration_lookup contra rick_and_migraty_character.

En la primera pasada, esas búsquedas todavía no pueden resolverse porque no existen los personajes. No es un fallo del YAML, sino parte del diseño. no_stub: true indica a Drupal que no cree personajes provisionales solo para satisfacer la relación antes de tiempo. Más adelante, cuando la migración de personajes haya creado las entidades reales, se ejecutará esta misma migración con --update para rellenar residents.

Por último, el destino es explícito: entity:rick_and_migraty_location. No creamos nodos, términos de taxonomía ni registros genéricos. Rellenamos la entidad personalizada definida por rick_and_migraty_api, con la validación activada para que las filas incorrectas fallen de forma visible durante la importación y no creen silenciosamente contenido incompleto.

Después, los episodios

Los episodios son el segundo contenedor estable del grafo. Los personajes pueden aparecer en muchos episodios y las páginas de episodios necesitarán enumerarlos, pero los propios episodios pueden crearse antes de que existan los personajes. Por eso podemos importarlos con seguridad antes de su migración.

• Punto de acceso: /api/episode.

La migración guarda tanto los datos originales del episodio como los valores normalizados que necesitaremos después.

Cargaremos:

• api_id
• name
• air_date_raw
• air_date
• episode_code
• season
• episode_number
• tvmaze_id
• tvmaze_url
• rating_average
• rating_source
• api_url
• api_created

Esta es la definición completa:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

id: rick_and_migraty_episode
label: 'Rick and Migraty episodes'
migration_group: rick_and_migraty

source:
  # Episodes are imported before character relationships are backfilled.
  plugin: rick_and_morty_api
  resource: episode
  # Avoid status/listing commands walking the public API just to count rows.
  skip_count: true
  # Cache each API page by URL so repeated imports and retries are gentle.
  cache: true
  cache_ttl: 86400
  # Keep this at 0 by default; raise it locally if the public API throttles.
  request_delay_ms: 0

process:
  api_id: id
  name: name
  air_date_raw: air_date
  air_date:
    plugin: format_date
    source: air_date
    from_format: 'F j, Y'
    to_format: 'Y-m-d'
    from_timezone: UTC
    to_timezone: UTC
  episode_code: episode
  season:
    plugin: rick_and_migraty_episode_part
    source: episode
    part: season
  episode_number:
    plugin: rick_and_migraty_episode_part
    source: episode
    part: episode
  tvmaze_id: tvmaze_id
  tvmaze_url: tvmaze_url
  rating_average: rating_average
  rating_source: rating_source
  characters:
    -
      # Episode rows contain an array of character URLs.
      plugin: rick_and_migraty_url_id
      source: characters
    -
      plugin: migration_lookup
      migration: rick_and_migraty_character
      no_stub: true
  api_url: url
  api_created:
    plugin: format_date
    source: created
    from_format: 'Y-m-d\TH:i:s.v\Z'
    to_format: 'Y-m-d\TH:i:s'
    from_timezone: UTC
    to_timezone: UTC
  uid:
    plugin: default_value
    default_value: 1

destination:
  plugin: 'entity:rick_and_migraty_episode'
  validate: true

migration_dependencies: {}

Lo primero que observamos es que el plugin de origen sigue siendo rick_and_morty_api, pero resource cambia a episode. Así conservamos la paginación, la caché y las pausas entre peticiones en un único plugin reutilizable, mientras el YAML describe la entidad concreta que queremos rellenar.

La sección de proceso realiza tres tipos de trabajo. Algunos campos son copias directas de la fila de origen: api_id, name, episode_code y api_url. Otros se interpretan o normalizan: air_date convierte una fecha legible como December 2, 2013 a Y-m-d; season y episode_number utilizan el plugin de proceso personalizado rick_and_migraty_episode_part para descomponer valores como S01E01.

Los campos de TVmaze ya están presentes en la fila de origen cuando se ejecuta el proceso. Con resource: episode, el plugin puede cargar los episodios de la serie 216 de TVmaze, construir una tabla de consulta por temporada y número de episodio y añadir tvmaze_id, tvmaze_url, rating_average y rating_source a la fila. Es un límite importante: TVmaze enriquece las filas canónicas, pero no crea episodios.

Por último, characters aparece en el YAML aunque los personajes aún no existan durante la primera pasada. La pareja rick_and_migraty_url_id + migration_lookup repite el mismo patrón de relaciones utilizado en las localizaciones. Con no_stub: true, las referencias no resueltas no se convierten en entidades provisionales. Después de crear los personajes, el proyecto vuelve a ejecutar esta migración con --update.

Los avatares antes que los personajes

Los avatares se gestionan deliberadamente en una migración de archivos separada. Puede parecer un paso adicional, pero mantiene una operación frágil fuera de la importación principal de personajes. Descargar archivos remotos es distinto de asignar campos JSON: puede ser lento, fallar o verse limitado por el servidor.

La migración lee las filas de /api/character, toma la URL remota image y descarga el archivo en el sistema público de archivos de Drupal, bajo:

public://rick-and-migraty/characters/

Esta es la migración de los archivos de avatar:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

id: rick_and_migraty_character_avatar
label: 'Rick and Migraty character avatars'
migration_group: rick_and_migraty

source:
  plugin: rick_and_morty_api
  resource: character
  skip_count: true
  cache: true
  cache_ttl: 86400
  request_delay_ms: 0
  constants:
    avatar_directory: 'public://rick-and-migraty/characters/'
    avatar_extension: '.jpeg'

process:
  filename:
    plugin: concat
    source:
      - id
      - constants/avatar_extension
  destination_uri:
    plugin: concat
    source:
      - constants/avatar_directory
      - id
      - constants/avatar_extension
  uri:
    plugin: download
    source:
      - image
      - '@destination_uri'
    file_exists: replace
  uid:
    plugin: default_value
    default_value: 1
  status:
    plugin: default_value
    default_value: 1

destination:
  plugin: 'entity:file'
  validate: true

El origen vuelve a ser rick_and_morty_api, ahora con resource: character, porque la URL del avatar está en los datos del personaje. El bloque constants define dos valores que no proceden de la API: el directorio de destino y la extensión del archivo. Mantenerlos en constants facilita leer la sección de proceso.

Los campos filename y destination_uri se construyen con concat. Un personaje con identificador de origen 1 se convierte en 1.jpeg, y la URI final será public://rick-and-migraty/characters/1.jpeg. Ese nombre determinista ayuda a repetir la operación: la misma fila apunta siempre a la misma ruta local.

La descarga se realiza en el proceso del campo uri. El plugin download recibe dos valores: la URL remota y la URI de destino calculada. Con file_exists: replace, las importaciones repetidas pueden actualizar el archivo en vez de fallar porque un intento anterior ya lo creó.

El destino es entity:file, no una de nuestras entidades de contenido de Rick and Migraty. Esta migración solo crea entidades de archivo reutilizables. Después, la migración de personajes resolverá avatar/target_id mediante migration_lookup.

Los personajes después de las localizaciones, los episodios y los avatares

Los personajes son el centro de la experiencia de navegación, pero llegan después de las localizaciones, los episodios y los archivos de avatar. El orden no es arbitrario: necesitan localizaciones para origin y last_location, episodios para episodes y una entidad de archivo para avatar.

El punto de acceso es /api/character, y la migración rellena:

• Campos básicos como api_id, name, status, species, character_type y gender.
• Referencias a localizaciones mediante origin y last_location.
• La URL remota image_url.
• El campo de imagen local avatar.
• Referencias a episodios mediante episodes.
• Campos de trazabilidad de la API y de propiedad de la entidad.

Esta es la migración implementada:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

id: rick_and_migraty_character
label: 'Rick and Migraty characters'
migration_group: rick_and_migraty

source:
  # Characters depend on locations and episodes for entity references.
  plugin: rick_and_morty_api
  resource: character
  # Avoid status/listing commands walking the public API just to count rows.
  skip_count: true
  # Cache each API page by URL so repeated imports and retries are gentle.
  cache: true
  cache_ttl: 86400
  # Keep this at 0 by default; raise it locally if the public API throttles.
  request_delay_ms: 0

process:
  api_id: id
  name: name
  status: status
  species: species
  character_type: type
  gender: gender
  origin:
    -
      # The API nests the origin URL under origin.url.
      plugin: rick_and_migraty_url_id
      source: origin/url
    -
      plugin: migration_lookup
      migration: rick_and_migraty_location
      no_stub: true
  last_location:
    -
      # The API nests the last known location URL under location.url.
      plugin: rick_and_migraty_url_id
      source: location/url
    -
      plugin: migration_lookup
      migration: rick_and_migraty_location
      no_stub: true
  image_url: image
  avatar/target_id:
    plugin: migration_lookup
    migration: rick_and_migraty_character_avatar
    source: id
    no_stub: true
  avatar/alt: name
  episodes:
    -
      # Character rows contain an array of episode URLs.
      plugin: rick_and_migraty_url_id
      source: episode
    -
      plugin: migration_lookup
      migration: rick_and_migraty_episode
      no_stub: true
  api_url: url
  api_created:
    plugin: format_date
    source: created
    from_format: 'Y-m-d\TH:i:s.v\Z'
    to_format: 'Y-m-d\TH:i:s'
    from_timezone: UTC
    to_timezone: UTC
  uid:
    plugin: default_value
    default_value: 1

destination:
  plugin: 'entity:rick_and_migraty_character'
  validate: true

migration_dependencies:
  required:
    - rick_and_migraty_character_avatar
    - rick_and_migraty_location
    - rick_and_migraty_episode

El primer grupo de asignaciones es directo: api_id, name, status, species, character_type y gender se copian de los datos del personaje. Observa que el campo type de la API pasa a llamarse character_type en Drupal. Así evitamos confundirlo con el concepto habitual de «tipo» en Drupal y conservamos su valor original.

Las asignaciones de origin y last_location muestran el proceso de resolución de relaciones en su forma más útil. La API anida las URL bajo origin/url y location/url. El plugin rick_and_migraty_url_id extrae su identificador numérico y migration_lookup lo resuelve mediante la tabla de correspondencias de rick_and_migraty_location.

El avatar es algo distinto porque apunta a la migración de archivos, no a una entidad de contenido personalizada. avatar/target_id busca la entidad creada por rick_and_migraty_character_avatar utilizando el mismo identificador de origen del personaje. avatar/alt se obtiene de su nombre para proporcionar un texto alternativo útil.

El campo episodes utiliza el mismo patrón de extracción del identificador de una URL, pero sobre un array de URL de episodios. Como estos ya se importaron, las búsquedas pueden resolverse en la primera pasada de personajes.

El bloque final de dependencias documenta explícitamente el orden de ejecución: los personajes requieren archivos de avatar, localizaciones y episodios. Así Migrate dispone de información suficiente para entender por qué esta migración ocupa una posición posterior en el proceso básico.

Relaciones inversas después del grafo básico

Llegados a este punto, ya existen las relaciones de ida:

• Los personajes apuntan a su origen y a su última localización conocida.
• Apuntan a los episodios en los que aparecen.
• Apuntan a su archivo local de avatar.

Pero quedan dos relaciones inversas útiles por completar:

• rick_and_migraty_episode.characters
• rick_and_migraty_location.residents

Estas asignaciones ya existen en los YAML de episodios y localizaciones. La razón por la que no se resuelven por completo en la primera pasada es temporal: ambos se importan antes que los personajes. Sus filas ya contienen las URL de los personajes, pero las entidades locales todavía no existen.

Por eso ambas asignaciones utilizan la misma pareja de plugins con precaución:

-
  plugin: rick_and_migraty_url_id
-
  plugin: migration_lookup
  migration: rick_and_migraty_character
  no_stub: true

El plugin personalizado extrae los identificadores de personajes de las URL. migration_lookup consulta la tabla de correspondencias de Migrate para averiguar dónde terminaron esos personajes en Drupal. no_stub: true evita crear personajes provisionales incompletos cuando la búsqueda todavía no puede resolverse.

Una vez ejecutada la migración de personajes, se realizan pasadas de actualización:

ddev drush migrate:import rick_and_migraty_episode --update
ddev drush migrate:import rick_and_migraty_location --update

Es entonces cuando el grafo se vuelve bidireccional en Drupal, sin obligar a la primera importación a conocerlo todo a la vez. El mismo YAML sirve para la importación inicial y para completar las relaciones más adelante.

Estrategia de origen: no fijar la paginación a mano

Todas las definiciones anteriores comparten un supuesto discreto: ninguna quiere saber cuántas páginas tiene hoy la API remota. El YAML debe indicar qué recurso necesita, no mantener manualmente una lista de URL.

En Drupal, esa responsabilidad vive en un módulo de migración dedicado:

rick_and_migraty_migrate

Este módulo contiene el plugin de origen, los YAML, los plugins de proceso y las utilidades Drush del proyecto. La pregunta interesante es cuánto comportamiento de la API debe vivir en PHP reutilizable y cuánto debería repetirse en cada archivo de migración.

La API de Rick and Morty devuelve respuestas paginadas. Cada respuesta incluye info.next y un array results. Un origen genérico url con un analizador JSON puede leer un punto de acceso, pero seguimos necesitando recorrer cómodamente todas las páginas y exponer cada elemento de results como una fila.

Una posibilidad sería utilizar un origen URL genérico y enumerar explícitamente todas las páginas:

source:
  plugin: url
  data_fetcher_plugin: http
  data_parser_plugin: json
  urls:
    - 'https://rickandmortyapi.com/api/location?page=1'
    - 'https://rickandmortyapi.com/api/location?page=2'
    - 'https://rickandmortyapi.com/api/location?page=3'
  item_selector: results

Puede funcionar en una pequeña demostración, pero es frágil. Si cambia el número de páginas, debemos cambiar la definición. Si necesitamos migraciones de personajes, localizaciones y episodios, el mismo problema de paginación se extiende a varios YAML. Y si queremos controles locales, como caché o limitar una prueba a una página, habrá que repetir la lógica o envolverla en otra capa.

El proyecto adopta una opción mejor: un plugin de origen personalizado de Migrate, llamado rick_and_morty_api.

Cada migración elige el recurso con un pequeño ajuste:

source:
  plugin: rick_and_morty_api
  resource: location

El mismo plugin puede leer character, location o episode. Internamente construye la primera URL a partir del recurso, obtiene la respuesta, reúne las filas de results, sigue info.next y se detiene cuando no hay más páginas o cuando un límite local dice «suficiente por esta vez».

En la práctica, el plugin realiza cuatro tareas por los archivos YAML:

1. Comienza por el primer punto de acceso.
2. Lee info.next.
3. Entrega cada elemento de results.
4. Se detiene cuando next es null.

Así las definiciones son más pequeñas y la paginación se convierte en código reutilizable. El YAML se centra en el contrato de la migración: recurso de origen, asignaciones de proceso, plugin de destino y dependencias.

El plugin incluye también controles para el desarrollo local. Importan porque las migraciones no son solo código: son operaciones que ejecutaremos una y otra vez mientras desarrollamos, depuramos y revertimos:

Para las pruebas locales, podemos sobrescribir varios ajustes mediante variables de entorno, sin editar los YAML versionados:

ddev exec env RICK_AND_MIGRATY_API_MAX_PAGES=1 \
  RICK_AND_MIGRATY_API_REQUEST_DELAY_MS=250 \
  drush migrate:import rick_and_migraty_location

La implementación permite sobrescribir la URL base de Rick and Morty, la pausa entre peticiones, el límite de páginas, la ruta de los archivos de prueba, la URL base de TVmaze y su identificador de serie. Las migraciones versionadas permanecen estables, mientras las ejecuciones locales pueden ser más rápidas, más lentas, basarse en archivos locales o apuntar a otro servidor.

Aquí es también donde encaja arquitectónicamente el enriquecimiento de TVmaze. El YAML de episodios asigna tvmaze_id, tvmaze_url, rating_average y rating_source, pero no necesita saber cómo se obtuvieron. El plugin enriquece las filas antes de entregarlas al proceso. Cuando se ejecuta el YAML, los datos de TVmaze se comportan como columnas adicionales de la fila canónica.

Es una decisión arquitectónica pequeña pero importante. Permite tratar con consideración a la API pública sin perder rapidez al probar cambios. También mantiene legibles las definiciones: localizaciones, episodios, avatares y personajes comparten el plugin, pero cada migración declara únicamente el recurso y los campos que le interesan.

Llegados aquí, el diseño ya no consiste simplemente en «importar JSON a Drupal». Es una secuencia:

1. Importar los contenedores canónicos.
2. Derivar campos normalizados.
3. Resolver referencias a partir de URL.
4. Descargar avatares con una migración de archivos ejecutable por lotes.
5. Enriquecer determinados registros desde fuentes secundarias.
6. Permitir almacenar en caché, limitar y repetir las peticiones remotas.
7. Completar las relaciones inversas mediante actualizaciones cuando ya exista el grafo.

Esta es la receta. Ahora podemos examinar los plugins que convierten esas decisiones en código reutilizable. Las definiciones implementadas están en el repositorio.

7. Definir plugins de migración (soluciones)

La sección anterior describe el orden de la migración. Esta trata sobre las pequeñas piezas de código personalizado que hacen legible ese orden.

Llega un momento en que una migración deja de ser solo YAML. No es un fallo de la API Migrate, sino una de sus virtudes. YAML es excelente para declarar cómo una fila se convierte en una entidad, pero las reglas específicas del proyecto necesitan nombres, límites y pruebas. En Rick and Migraty, los plugins son precisamente eso: soluciones con nombre para problemas que se repiten.

Aquí la implementación se vuelve más honesta. Si forzamos todas las reglas dentro del YAML, las definiciones se vuelven ruidosas y frágiles. Si trasladamos cada pequeña asignación a PHP, el YAML deja de documentar la importación. La pregunta útil no es «¿YAML o PHP?», sino «¿qué responsabilidad corresponde a cada lugar?».

El proyecto utiliza cuatro plugins personalizados:

Ninguno es especialmente grande. Esa es parte de la idea: resolver problemas pequeños y repetidos, y mantener las definiciones centradas en el modelo de contenido, no en los detalles de bajo nivel.

Aquí conviene hacer autocrítica: los plugins personalizados no deberían ser la respuesta por defecto. El núcleo y los módulos contribuidos ya ofrecen muchas herramientas. Utilizamos plugins estándar como format_date, concat, download, default_value y migration_lookup; además, migrate_plus aporta el origen genérico url, analizadores JSON y plugins de proceso como preg_match.

¿Por qué no usar migrate_plus:url para todo? En una prueba de concepto pequeña podríamos hacerlo. Pero la fuente canónica de Rick and Morty no es solo «un archivo JSON en una URL». Tiene paginación mediante info.next, caché, pausas entre peticiones, soporte para archivos locales, límites de páginas para pruebas y enriquecimiento de episodios con TVmaze. Si todo ese comportamiento vive en YAML, cada migración acaba describiendo políticas operativas además de asignaciones de datos.

La fuente de Fandom también tiene motivos para ser personalizada. Parte de entidades existentes, resuelve una página mediante identificadores, alias o coincidencias exactas, omite resultados ambiguos, analiza HTML de MediaWiki y genera filas de actualización para entidades de destino existentes. Un plugin URL genérico puede obtener JSON, pero no sabe que Fandom es una capa de enriquecimiento sobre registros que ya existen en Drupal.

El compromiso es este: los plugins de origen son personalizados porque definen contratos con las fuentes, no porque nos apeteciera escribir PHP. Los pequeños plugins de proceso merecen un examen más crítico. rick_and_migraty_url_id sigue teniendo sentido porque maneja tanto URL individuales como arrays en un paso legible. Sin embargo, rick_and_migraty_episode_part podría sustituirse por preg_match de migrate_plus:

season:
  plugin: preg_match
  source: episode
  pattern: '/^S(\d+)E(\d+)$/'
  group_index: 1

episode_number:
  plugin: preg_match
  source: episode
  pattern: '/^S(\d+)E(\d+)$/'
  group_index: 2

Esa sustitución reduciría el código propio. Mantener el plugin se justificaría por la legibilidad y la intención de los tipos, no por una necesidad técnica. Precisamente quiero hacer visible esa diferencia: el código personalizado es aceptable cuando da nombre a un contrato real del proyecto; resulta sospechoso cuando solo oculta una transformación que ya ofrecen el núcleo o los módulos contribuidos.

El plugin de la fuente canónica

rick_and_morty_api se ocupa de la fuente principal de datos. Recibe un nombre de recurso, comienza en su punto de acceso, sigue la paginación mediante info.next y entrega cada elemento de results como una fila de Migrate.

Por tanto, el YAML puede decir:

source:
  plugin: rick_and_morty_api
  resource: episode
  skip_count: true
  cache: true
  cache_ttl: 86400
  request_delay_ms: 0

Es mucho más fácil de mantener que enumerar todas las páginas a mano. Y, sobre todo, ofrece un único lugar para gestionar las cuestiones operativas:

Es uno de esos detalles modestos que cambian el día a día. Ejecutar una migración diez veces durante el desarrollo no debería implicar pedir diez veces las mismas páginas a una API pública.

El plugin completo está en RickAndMortyApi.php. Para este artículo importa menos cada línea de la clase que el contrato que ofrece al YAML: elige un recurso, recibe filas y mantén centralizada la relación con el sistema remoto.

El problema del lenguaje de las URL

La API de Rick and Morty expresa las relaciones como URL:

https://rickandmortyapi.com/api/location/20
https://rickandmortyapi.com/api/episode/1
https://rickandmortyapi.com/api/character/42

Las referencias a entidades de Drupal no necesitan esas URL. Necesitan identificadores locales de entidades de destino. El puente es el plugin de proceso rick_and_migraty_url_id.

Esta es su implementación:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

<?php

declare(strict_types=1);

namespace Drupal\rick_and_migraty_migrate\Plugin\migrate\process;

use Drupal\migrate\Attribute\MigrateProcess;
use Drupal\migrate\MigrateExecutableInterface;
use Drupal\migrate\ProcessPluginBase;
use Drupal\migrate\Row;

/**
 * Extracts numeric Rick and Morty API IDs from resource URLs.
 *
 * The API represents many relationships as URLs, for example
 * `https://rickandmortyapi.com/api/location/20`. Migrate lookup plugins need
 * the stable source ID (`20`), not the full URL, so this plugin converts either
 * a single URL or an array of URLs into integer IDs.
 *
 * Example:
 *
 * @code
 * process:
 *   origin:
 *     plugin: migration_lookup
 *     migration: rick_and_migraty_location
 *     source:
 *       plugin: rick_and_migraty_url_id
 *       source: origin/url
 * @endcode
 */
#[MigrateProcess('rick_and_migraty_url_id')]
final class RickAndMigratyUrlId extends ProcessPluginBase {

  /**
   * {@inheritdoc}
   */
  public function transform($value, MigrateExecutableInterface $migrate_executable, Row $row, $destination_property): mixed {
    if (is_array($value)) {
      // Relationship arrays such as episode.characters should stay arrays, but
      // empty or malformed URLs are filtered out before lookup.
      return array_values(array_filter(array_map(
        static fn (mixed $item): ?int => self::extractId($item),
        $value,
      )));
    }

    return self::extractId($value);
  }

  /**
   * Extracts the trailing numeric segment from an API URL.
   *
   * @param mixed $value
   *   A URL-like scalar value from the source row.
   *
   * @return int|null
   *   The numeric API ID, or NULL when the value cannot identify a resource.
   */
  private static function extractId(mixed $value): ?int {
    if (!is_scalar($value)) {
      return NULL;
    }

    $value = trim((string) $value);
    if ($value === '') {
      return NULL;
    }

    // The API uses resource URLs ending in the numeric ID. Matching only the
    // trailing segment keeps the plugin independent from the configured host.
    if (preg_match('/\/(\d+)$/', $value, $matches) !== 1) {
      return NULL;
    }

    return (int) $matches[1];
  }

}

Hace una sola cosa: extraer el segmento numérico final de una URL de la API de Rick and Morty. Si recibe una URL, devuelve un entero. Si recibe un array, aplica la misma operación a cada elemento y filtra los valores vacíos o mal formados.

Para una relación individual, el proceso es fácil de leer:

origin:
  -
    plugin: rick_and_migraty_url_id
    source: origin/url
  -
    plugin: migration_lookup
    migration: rick_and_migraty_location
    no_stub: true

El primer plugin extrae el identificador de origen. El segundo pregunta a la tabla de correspondencias de la API Migrate qué entidad local se creó a partir de ese identificador. El mismo patrón funciona con arrays como episode.characters, location.residents y character.episode.

Es un buen ejemplo de un plugin de proceso que hace lo justo. No sabe de personajes, localizaciones, episodios ni campos. Solo traduce el lenguaje de relaciones de la API a identificadores que Drupal puede buscar.

Convertir los códigos de episodio en estructura

Los códigos de episodio requieren otra transformación pequeña pero importante. La API proporciona valores como:

S03E07

Son útiles para las personas, pero insuficientes para ordenar, filtrar o cruzar los datos con TVmaze. El modelo guarda tanto el código original como sus partes estructuradas:

season:
  plugin: rick_and_migraty_episode_part
  source: episode
  part: season
episode_number:
  plugin: rick_and_migraty_episode_part
  source: episode
  part: episode

El plugin implementado es deliberadamente estricto:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

<?php

declare(strict_types=1);

namespace Drupal\rick_and_migraty_migrate\Plugin\migrate\process;

use Drupal\migrate\Attribute\MigrateProcess;
use Drupal\migrate\MigrateExecutableInterface;
use Drupal\migrate\MigrateException;
use Drupal\migrate\ProcessPluginBase;
use Drupal\migrate\Row;

/**
 * Extracts season or episode numbers from an API episode code.
 *
 * The source API stores episode position as a compact string like `S03E07`.
 * Drupal Views and filters are easier to build when season and episode number
 * are available as separate integer fields.
 *
 * Configuration keys:
 * - part: Required. Either `season` or `episode`.
 */
#[MigrateProcess('rick_and_migraty_episode_part')]
final class RickAndMigratyEpisodePart extends ProcessPluginBase {

  /**
   * {@inheritdoc}
   */
  public function transform($value, MigrateExecutableInterface $migrate_executable, Row $row, $destination_property): ?int {
    $part = $this->configuration['part'] ?? NULL;
    if (!in_array($part, ['season', 'episode'], TRUE)) {
      throw new MigrateException('The rick_and_migraty_episode_part plugin requires part: season or part: episode.');
    }

    if (!is_scalar($value) || preg_match('/^S(\d+)E(\d+)$/', (string) $value, $matches) !== 1) {
      return NULL;
    }

    // Match groups are stable because the expression is anchored to the whole
    // API code: group 1 is season, group 2 is episode number.
    return (int) ($part === 'season' ? $matches[1] : $matches[2]);
  }

}

Exige part: season o part: episode y acepta valores con la forma S03E07. Si el valor no encaja, devuelve NULL en vez de inventarse un número. Importa porque los valores incorrectos de origen no deberían convertirse silenciosamente en una estructura falsa.

El resultado es sencillo:

episode_code = S03E07
season = 3
episode_number = 7

Este tipo de transformación facilita el resto del proyecto. Views puede agrupar por temporada, las páginas pueden ordenar los episodios de forma natural y las puntuaciones de TVmaze pueden emparejarse por temporada y número, en lugar de por título.

Puedes consultar los plugins personalizados de origen y proceso en el repositorio.

8. Más información de las fuentes (enriquecimiento)

El proyecto utiliza tres fuentes externas, pero no todas tienen la misma autoridad.

La API de Rick and Morty es la fuente canónica del conjunto básico: personajes, localizaciones, episodios y su grafo de relaciones. TVmaze y Fandom añaden información que la fuente principal no proporciona, pero no deben redefinir silenciosamente qué considera el proyecto un personaje, una localización o un episodio.

Esa distinción mantiene la migración bajo control. Nos ofrece una regla que podemos repetir durante toda la implementación: las fuentes secundarias enriquecen registros existentes; no crean el conjunto canónico.

TVmaze enriquece las filas de episodios

La API de Rick and Morty proporciona la identidad del episodio, su código, la fecha de emisión y la lista de personajes que aparecen. No ofrece puntuaciones. TVmaze cubre esa carencia.

La decisión importante es evitar las búsquedas aproximadas durante las importaciones normales. La serie ya está seleccionada y su identificador de TVmaze es explícito:

El plugin puede cargar:

https://api.tvmaze.com/shows/216/episodes

Y construir una tabla de consulta por temporada y número de episodio. Así, cada fila de Rick and Morty llega al proceso enriquecida con:

process:
  tvmaze_id: tvmaze_id
  tvmaze_url: tvmaze_url
  rating_average: rating_average
  rating_source: rating_source

Fíjate en la clave de unión: temporada y número de episodio, no el título. Los títulos dependen demasiado de decisiones editoriales para ser claves seguras. Los cambios de puntuación, los títulos alternativos y las pequeñas diferencias de redacción pueden generar fallos que parecen inocentes durante demasiado tiempo.

La asociación queda así:

Rick and Morty API: S01E01
season: 1
episode_number: 1
TVmaze show: 216
TVmaze episode: season 1, number 1

Obtenemos puntuaciones mientras la API de Rick and Morty sigue siendo responsable de la identidad del episodio.

Fandom enriquece entidades existentes

Fandom es otra clase de fuente. Es rica, útil y editorial, pero también desordenada, como corresponde a una wiki. Los resultados de búsqueda pueden ser ambiguos, los títulos de las páginas pueden diferir de los nombres de la API y un episodio llamado Pilot no es precisamente una expresión única en Internet.

Por eso las migraciones de Fandom se ejecutan después de crear las entidades básicas:

rick_and_migraty_character_fandom
rick_and_migraty_location_fandom
rick_and_migraty_episode_fandom

Actualizan entidades existentes de Drupal. No crean registros canónicos nuevos.

El plugin de origen rick_and_migraty_fandom parte de las entidades de Drupal, resuelve una página de Fandom mediante un identificador explícito, un alias o una búsqueda exacta, lee la API de MediaWiki, extrae texto descriptivo útil y produce filas que contienen el identificador de la entidad existente y los metadatos de Fandom.

La migración de enriquecimiento de personajes es un ejemplo compacto:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

id: rick_and_migraty_character_fandom
label: 'Rick and Migraty character Fandom enrichment'
migration_group: rick_and_migraty

source:
  plugin: rick_and_migraty_fandom
  entity_type: rick_and_migraty_character
  skip_count: true
  page_id_map:
    1: 2073
    2: 2074

process:
  id: entity_id
  fandom_description: fandom_description
  fandom_page_id: fandom_page_id
  fandom_url: fandom_url
  fandom_source: fandom_source

destination:
  plugin: 'entity:rick_and_migraty_character'
  validate: true

migration_dependencies:
  required:
    - rick_and_migraty_character

El plugin está en RickAndMigratyFandom.php. Utiliza dos servicios de apoyo: FandomClient.php, para las peticiones a MediaWiki con caché, y FandomDescriptionExtractor.php, para convertir el HTML interpretado de la wiki en párrafos introductorios legibles.

El destino sigue siendo el mismo tipo de entidad:

destination:
  plugin: 'entity:rick_and_migraty_character'

Y las asignaciones actualizan los campos de enriquecimiento:

process:
  id: entity_id
  fandom_description: fandom_description
  fandom_page_id: fandom_page_id
  fandom_url: fandom_url
  fandom_source: fandom_source

La regla es deliberadamente conservadora: si la coincidencia es ambigua, se omite y se registra. Es más fácil corregir una descripción ausente que una equivocada que parece fiable.

El YAML hace visible ese contrato. Las entradas explícitas de page_id_map permiten fijar casos difíciles conocidos. aliases ayuda cuando el título de Fandom no coincide con la etiqueta de la API. La búsqueda exacta resuelve los casos sencillos. Y el destino sigue apuntando a la entidad personalizada existente mediante id: entity_id, por lo que el enriquecimiento llega al registro ya importado.

9. De los datos al contenido (navegar)

Una migración no termina cuando hay filas en las tablas. Se vuelve útil cuando las personas pueden recorrer, consultar y entender los datos importados.

Por eso importa el modelo de entidades. Una vez que personajes, localizaciones y episodios existen como entidades reales de Drupal, el sitio puede exponerlos como páginas, rutas, Views y navegación basada en relaciones.

Listado completo con filtros y cuadro de búsqueda

En una página de personaje, las preguntas útiles son inmediatas:

• ¿Quién es este personaje?
• ¿Cuál es su estado, especie y género?
• ¿De dónde procede?
• ¿Dónde fue visto por última vez?
• ¿En qué episodios aparece?
• ¿Qué contexto adicional aporta Fandom?

Ejemplo de personaje: Alien Rick

Para una localización, las preguntas cambian:

• ¿Qué clase de lugar es?
• ¿A qué dimensión pertenece?
• ¿Qué personajes residen allí?

Ejemplo de localización: los recuerdos de Birdperson

Y para un episodio:

• ¿A qué temporada pertenece y qué número tiene?
• ¿Cuándo se emitió?
• ¿Qué puntuación ofrece TVmaze?
• ¿Qué personajes aparecen?

Página del episodio Anatomy Park

Los mismos datos pueden convertirse en vistas: personajes por dimensión, episodios por temporada, localizaciones con muchos residentes o un pequeño explorador de personajes por estado. Aquí la migración deja de ser un ejercicio de backend y se convierte en un producto de contenido.

Las plantillas del tema muestran esa idea:

• rick-and-migraty-character.html.twig muestra las insignias del perfil, el avatar, la descripción de Fandom, los enlaces a episodios y los metadatos de origen.
• rick-and-migraty-location.html.twig muestra los metadatos de la localización, sus residentes y el contexto de Fandom.
• rick-and-migraty-episode.html.twig muestra temporada y episodio, las insignias de puntuación de TVmaze y las apariciones de personajes.

La migración no se limita a rellenar campos: alimenta una experiencia de navegación. Los campos elegidos se convierten en variables que el tema puede utilizar: avatar_url, episode_links, resident_cards, appearance_cards, fandom.description, profile.api_url, etc.

El proyecto también incluye una ruta de exploración:

rick_and_migraty_migrate.browse:
  path: '/browse-all-content'
  defaults:
    _controller: '\Drupal\rick_and_migraty_migrate\Controller\BrowseContentController::browse'
    _title: 'Browse all content'
  requirements:
    _access: 'TRUE'

Su controlador, BrowseContentController.php, hace dos cosas interesantes para este artículo. Primero, ofrece una matriz de entidades importadas con búsqueda mediante /browse-all-content. Segundo, expone pasos de migración y puntos de consulta de estado visibles desde el navegador, para mostrar la importación como una operación y no solo como un comando de terminal.

Esto explica también por qué reducir todo a campos de texto habría sido un mal atajo. Lo interesante del conjunto de datos es el grafo. Los personajes enlazan a episodios, estos vuelven a enlazar a personajes, las localizaciones enumeran residentes y los campos de enriquecimiento añaden contexto sin quitarle la identidad a la fuente canónica.

10. La migración como operación (ejecutar)

La implementación es una mitad de la migración. La operación es la otra mitad.

Esto resulta especialmente cierto cuando intervienen varios servicios remotos, se descargan archivos, se enriquecen entidades en pasadas posteriores y debemos repetir el proceso durante el desarrollo. Llegados ahí, necesitamos algo más que definiciones YAML: puntos de entrada repetibles.

El proyecto admite varias formas de ejecución, cada una con su finalidad:

El script está en scripts/rick-and-migraty-migrate.sh. Es el ejecutor local de más alto nivel: reconstruye cachés, elimina opcionalmente el contenido importado anterior, elige entre archivos locales y llamadas reales, importa el contenido básico, genera alias, ejecuta el enriquecimiento de Fandom e imprime los recuentos de validación.

Para una ejecución local con archivos de prueba existentes:

scripts/rick-and-migraty-migrate.sh --fixtures

Si primero hay que generarlos:

scripts/rick-and-migraty-migrate.sh --build-fixtures

Estos archivos viven en:

.ddev/.tmp-fixtures/rick-and-migraty-api

Permiten leer las filas JSON canónicas de Rick and Morty desde archivos locales estables, en lugar de hacerlo desde la API pública. Así separamos dos problemas que de otro modo se mezclan:

1. ¿Está fallando el código de la migración?
2. ¿O el servicio remoto está lento, limita peticiones, no está disponible o ha cambiado?

Para comprobar la estructura más deprisa, podemos omitir las fases costosas:

scripts/rick-and-migraty-migrate.sh --fixtures --no-avatars --no-fandom

El ciclo normal con Drush es intencionadamente breve:

ddev drush ramt:migrate:reset
ddev drush ramt:migrate:import

Estos comandos se implementan en RickAndMigratyMigrateCommands.php. La utilidad de importación sigue el orden diseñado: localizaciones, episodios, avatares, personajes, actualización de relaciones de episodios y actualización de relaciones de localizaciones.

El comando de reinicio es importante. Limpia las entidades importadas, las entidades de archivo de avatares, sus archivos físicos, los alias y las filas de correspondencias y mensajes de Migrate. Esto último importa porque borrar entidades desde la interfaz no limpia el seguimiento interno de la API Migrate. Drupal puede parecer vacío mientras migrate:status sigue considerando importadas las filas.

La limpieza se delega en MigrationResetter.php, que hace explícita la operación: eliminar entidades personalizadas, entidades de archivo y archivos físicos de avatares, borrar alias /rick-and-migraty/%, vaciar tablas migrate_map_* y migrate_message_* e invalidar cachés.

Las descargas de avatares se gestionan como una operación propia:

ddev drush ramt:migrate:avatars --batch-size=10 --sleep=12 --retries=3

La forma del comando refleja la naturaleza del trabajo. Descargar cientos de archivos remotos no equivale a asignar campos JSON: requiere lotes, reintentos y pausas. La utilidad importa avatares mediante rangos --idlist, añade una pausa local entre peticiones y reintenta los lotes fallidos antes de rendirse.

La separación ofrece una vía de recuperación práctica: si las descargas fallan a mitad del proceso, podemos repetir la fase de archivos sin dar por roto todo el modelo de migración.

Los límites de peticiones forman parte del diseño

Durante el desarrollo apareció un recordatorio muy concreto de que las API remotas no son infinitas: respuestas 429 Too Many Requests. Es fácil considerarlas una molestia, pero en una migración aportan información útil. Nos dicen que pedimos demasiado, demasiado deprisa o demasiadas veces a un servicio que no controlamos.

La respuesta no fue ocultar el error, sino convertir el límite de peticiones en una restricción de diseño:

• Las respuestas se almacenan en caché por URL para no pedir las mismas páginas en cada ejecución.
• Los archivos de prueba pueden sustituir las llamadas remotas cuando comprobamos la lógica de asignación.
• RICK_AND_MIGRATY_API_MAX_PAGES limita las pruebas básicas a un subconjunto pequeño.
• request_delay_ms ralentiza las peticiones que no tienen respuesta en caché.
• Las descargas de avatares se ejecutan por lotes con --sleep y --retries.
• Las importaciones de avatares usan rangos --idlist, de modo que podemos repetir un lote fallido sin repetir toda la migración.

Por eso la fase de avatares tiene su propia secuencia y no queda escondida dentro de la importación de personajes. Las descargas remotas son la parte más agresiva del proceso: cientos de peticiones HTTP, transferencias binarias, entidades de archivo locales, escrituras en disco y reintentos. Separarlas hace la migración más respetuosa y mucho más fácil de recuperar.

Dicho de otro modo: el 429 no fue solo un código de error; fue una revisión de diseño enviada por la API remota.

El navegador es un panel de control

El flujo del navegador resulta útil, pero no debería pretender ser el motor de migración.

La primera versión intentó realizar demasiado trabajo en una petición larga. Eso es frágil, porque PHP-FPM, nginx, los proxies y los navegadores tienen sus propias opiniones sobre las peticiones HTTP prolongadas, y ninguna es sentimental. 😉

El flujo actual utiliza pasos POST más pequeños:

/rick-and-migraty/run-migration-step/{step}

La ruta se declara en rick_and_migraty_migrate.routing.yml y la gestiona BrowseContentController.php.

Esta es la ventana modal:

Progreso y trazas de la migración en la ventana modal

Muestra el progreso, las trazas recientes y un resumen final. La misma traza se escribe en watchdog mediante el canal rick_and_migraty_migrate, de modo que un síntoma observado en el navegador puede investigarse con Drush:

ddev drush watchdog:show --type=rick_and_migraty_migrate --count=50

El trabajo de avatares se divide internamente en rangos como avatars-1, avatars-2, etc. El usuario ve una sola fase, «Procesando avatares», pero el backend recibe unidades de trabajo más pequeñas cuyos fallos, registros y recuperación son más claros.

La distinción importa: el navegador no sustituye a Drush. Es un panel guiado sobre los mismos pasos operativos, útil para observar el proceso y hacer visible la experiencia de migración.

11. Perder la cabeza (depurar)

Cuando falla una migración, resulta tentador mirar fijamente el YAML hasta que confiese. A veces funciona. A menudo solo conseguimos poner nervioso al YAML. 😬

Una rutina mejor es depurar de fuera hacia dentro.

• Primero, inspecciona el origen:

curl -s 'https://rickandmortyapi.com/api/character' | jq '.info'
curl -s 'https://rickandmortyapi.com/api/character' | jq '.results[0]'
curl -s 'https://rickandmortyapi.com/api/location' | jq '.results[0].residents'
curl -s 'https://rickandmortyapi.com/api/episode' | jq '.results[0].characters'
curl -s 'https://api.tvmaze.com/shows/216/episodes' | jq '.[0] | {id, name, season, number, rating}'

Todavía no pretendemos depurar Drupal. Antes hay que responder una pregunta más sencilla: ¿la fuente sigue teniendo la estructura que espera la migración? Si ha cambiado o un punto de acceso está lento o caído, el YAML no es el primer sospechoso.

• Después, inspecciona el estado de la migración:

ddev drush migrate:status
ddev drush migrate:messages rick_and_migraty_location
ddev drush migrate:messages rick_and_migraty_episode
ddev drush migrate:messages rick_and_migraty_character

migrate:status indica qué cree Drupal que se ha importado. Las tablas de mensajes explican qué filas fallaron y por qué. Aquí cobra sentido lo explicado sobre el reinicio: el estado de la API Migrate no equivale al contenido visible.

Si faltan relaciones inversas tras una ejecución parcial, repite directamente las pasadas de actualización:

ddev drush migrate:import rick_and_migraty_episode --update
ddev drush migrate:import rick_and_migraty_location --update

Estos comandos tienen un alcance limitado a propósito. No vuelven a descargar avatares, reconstruir archivos de prueba ni importar todo el grafo. Solo piden a las migraciones ya definidas que completen relaciones cuyos personajes de destino ahora sí pueden resolverse.

Si el problema está en el enriquecimiento de Fandom, depura esa fase sin repetir las importaciones básicas:

ddev drush migrate:messages rick_and_migraty_character_fandom
ddev drush migrate:messages rick_and_migraty_location_fandom
ddev drush migrate:messages rick_and_migraty_episode_fandom

Y repite únicamente las migraciones de enriquecimiento:

ddev drush migrate:import rick_and_migraty_character_fandom --update --feedback=50
ddev drush migrate:import rick_and_migraty_location_fandom --update --feedback=25
ddev drush migrate:import rick_and_migraty_episode_fandom --update --feedback=25

Esta es otra razón para ejecutar el enriquecimiento por separado. Un problema de análisis de Fandom no debería obligarnos a importar de nuevo todo el contenido canónico. El grafo básico y el enriquecimiento editorial son ámbitos de depuración distintos.

Cuando una fila se resiste, la lista de comprobación resulta familiar:

• Revisa la indentación del YAML.
• Inspecciona los selectores del origen.
• Inspecciona las tablas migrate_map_*.
• Inspecciona las tablas migrate_message_*.
• Confirma que las dependencias se ejecutaron en el orden esperado.
• Utiliza Xdebug en DDEV cuando sospeches de un plugin de proceso personalizado.

Para este proyecto añadiría unas comprobaciones:

• Confirma RICK_AND_MIGRATY_API_FIXTURE_BASE_PATH si utilizas archivos de prueba.
• Confirma que RICK_AND_MIGRATY_API_MAX_PAGES no limita inesperadamente la ejecución.
• Inspecciona las entradas de watchdog de rick_and_migraty_migrate.
• Determina si la fila fallida pertenece a la importación básica, la descarga de avatares, la cumplimentación de relaciones o el enriquecimiento de Fandom.

En los lugares aburridos suelen estar las pistas útiles: un selector, una tabla de correspondencias, una dependencia ausente, una cadena vacía o un valor que parecía un entero hasta que conoció los datos reales.

12. Decisiones que merece la pena destacar (decidir)

Hay varias decisiones que conviene documentar porque determinan la implementación más que cualquier YAML individual. Si alguien retoma el proyecto más adelante, me gustaría que las conociera antes de modificar las migraciones.

• En primer lugar, las relaciones circulares son previsibles. Los personajes apuntan a localizaciones y episodios, y estos vuelven a apuntar a personajes. No intentamos resolverlo todo de una pasada heroica: primero importamos el grafo básico y después completamos las referencias inversas mediante actualizaciones.

• En segundo lugar, la paginación forma parte del contrato del origen. Si una migración solo importa la primera página, no es una migración: es una demostración que se ha cansado. El plugin de origen se encarga de paginar porque todos los recursos canónicos necesitan el mismo comportamiento y al YAML no debería importarle cuántas páginas tiene hoy la API.

• En tercer lugar, los identificadores externos no son opcionales. El id de origen se guarda como api_id y se utiliza como puente estable entre registros remotos, tablas de correspondencias, archivos de prueba, actualizaciones y depuración. Los identificadores de entidad de Drupal son detalles locales de implementación; el de la API es la identidad que podemos explicar.

• En cuarto lugar, las imágenes merecen su propia fase. Los avatares se descargan mediante una migración separada y pueden procesarse por lotes. La entidad conserva image_url, pero gestionar archivos locales es una operación distinta de asignar campos y debe tratarse como tal.

• En quinto lugar, debemos tratar con consideración a las API públicas. La caché, los archivos de prueba, los límites de páginas y las pausas no son adornos. Los errores 429 Too Many Requests lo dejaron claro: la consideración no es solo una cuestión de educación; hace posible repetir la migración.

• Por último, las fuentes de enriquecimiento no son fuentes canónicas. TVmaze aporta puntuaciones. Fandom aporta descripciones. Ninguna puede redefinir el conjunto básico de Rick and Morty.

La lista no es solo documentación: también protege el diseño. Cuando el proyecto crezca, cada nueva migración debería contrastarse con estas decisiones:

• ¿Conserva la autoridad de cada fuente?
• ¿Mantiene explícitas las relaciones?
• ¿Sigue siendo repetible?
• ¿Evita que los servicios remotos se conviertan en un peaje constante para desarrollar?

13. Qué he aprendido (reflexionar)

Si tuviera que extraer algunos principios reutilizables de la experiencia Rick and Migraty, serían estos.

Elabora un perfil de la fuente antes de escribir demasiado YAML. Conoce sus páginas, campos, valores vacíos, formas de relación y casos difíciles antes de dar por evidente el modelo de Drupal. No hace falta un documento formal, pero sí responder preguntas prácticas: dónde están los identificadores, las relaciones, las fechas, los archivos y los valores vacíos, y qué campos son meras etiquetas de presentación.

Conserva el grafo cuando el valor está en el grafo. Personajes, localizaciones y episodios no son simplemente tres listas. Lo interesante son sus relaciones, así que el modelo de destino debe permitir consultarlas. Si las aplana hasta convertirlas en texto, la migración puede tener éxito técnico y, al mismo tiempo, perder el sentido del conjunto de datos.

Mantén acotadas las transformaciones. Un plugin extrae identificadores de URL. Otro obtiene la temporada o el episodio. Un plugin de origen se ocupa de la paginación. Las piezas pequeñas son más fáciles de explicar, probar y sustituir. Además, hacen el YAML más legible porque cada nombre expresa una intención.

Ordena las importaciones deliberadamente. Las localizaciones y los episodios deben existir antes de que los personajes puedan referenciarlos. Los personajes deben existir antes de completar las relaciones inversas. El orden no es un detalle de implementación, sino parte del modelo. Si resulta incómodo, probablemente el grafo está intentando decirnos algo.

Considera las operaciones parte del diseño. Reinicios, archivos de prueba, lotes de avatares, actualizaciones y trazas en el navegador no son extras simpáticos. Son lo que permite utilizar la migración después de la primera importación exitosa.

Y quizá lo más importante: no permitas que las fuentes secundarias difuminen el contrato. Podemos combinar datos de varios lugares sin volver ambiguo quién es responsable de cada información. Aquí, la API de Rick and Morty controla el grafo canónico; TVmaze enriquece las puntuaciones; y Fandom, el contexto narrativo.

Eso es lo que reutilizaría en otro proyecto aunque su temática fuera completamente distinta. Cambiarían los nombres, las API y los campos, pero se mantendría el patrón:

1. Elegir la fuente canónica.
2. Modelar el grafo.
3. Aislar los enriquecimientos.
4. Hacer que repetir la ejecución sea aburrido.

14. Próximos pasos (planificar)

Este proyecto ha reunido paginación, relaciones, enriquecimiento, avatares, archivos de prueba y ejecución repetible en una migración funcional de Drupal. Los próximos pasos parten de esa implementación:

• Mantener el artículo y la documentación de MkDocs alineados con el código a medida que evolucione el proyecto, actualizando ejemplos y capturas cuando cambie el comportamiento.
• Explorar la migración de avatares en otro artículo, porque la gestión de archivos remotos, los lotes y la recuperación merecen un examen más detallado.
• Revisar la cobertura del conjunto canónico y decidir cómo tratar episodios y personajes ausentes, conservando identificadores externos estables y responsabilidades explícitas de las fuentes.

También hay otro posible artículo a la vista: el panel de control del navegador. Conecta la ejecución, el estado de las trazas, la consulta periódica del progreso, los comandos Drush y la información que recibe el usuario. No forma parte estrictamente de la API Migrate, pero sí de conseguir que una migración resulte utilizable por personas.

Por ahora, lo importante es que el diseño sea visible. Tenemos una fuente canónica, un modelo de destino, un orden de importación por fases, plugins para problemas repetidos, pasadas de enriquecimiento, utilidades operativas y una rutina de depuración. Es suficiente para esta sexta parada de la serie.

Intentar incluir todos los detalles de implementación convertiría el artículo en un manual. La versión útil tiene un alcance más acotado: código suficiente para concretar el diseño, explicación suficiente para comprender los compromisos y detalle operativo suficiente para no fingir que las migraciones terminan cuando el YAML valida.

Nota sobre la documentación: La estructura y la intención de este artículo siguen los principios de Diátaxis, distinguiendo tutoriales, guías prácticas, explicaciones y material de referencia para situar las instrucciones y el contexto conceptual donde corresponden.

Nota sobre el idioma: Se utilizó asistencia de IA para revisar la gramática y pulir las expresiones del original inglés. Las decisiones técnicas, la implementación y la experiencia descrita siguen siendo propias del autor. Esta versión castellana también se ha preparado con asistencia de IA.

15. :wq!

Canción recomendada: Fabrizio De André - Ballata dell’amore cieco

Foto de Unsplash, de Neenu Vimalkumar, @dreamquest12610

Índice

• 1. Introducción a Xdebug
• 2. Xdebug en DDEV
• 3. Configurar el IDE paso a paso
• 4. Errores al ejecutar Drush en contenedores
• 5. :wq!

1. Introducción a Xdebug

Vamos a complementar las técnicas de la entrega anterior. Ya sabemos revisar archivos de configuración y utilizar plugins de proceso para obtener información. Ahora añadiremos la tercera pieza: depurar una migración desde el código que interviene en ella, siguiendo las clases PHP que hacen funcionar todo el mecanismo.

Xdebug es una extensión clásica de PHP que permite, entre otras cosas, seguir las variables y observar sus valores durante la ejecución del software. No explicaremos aquí su instalación y administración general; nos centraremos en un caso concreto. Para desplegar Drupal localmente y probar las migraciones podemos usar DDEV, una herramienta basada en contenedores Docker que ya incluye Xdebug preparado para utilizarlo.

DDEV evita tener que montar un entorno LAMP clásico: organiza redes de contenedores preconfigurados con las herramientas de desarrollo, incluido Xdebug. Encontrarás más información, artículos y recursos en awesome-ddev.

2. Xdebug en DDEV

Si partimos de un entorno DDEV, podemos activar Xdebug de dos maneras.

La primera es editar config.yaml, en your_project/.ddev/config.yaml, y activar Xdebug. En el archivo mostrado en la captura, la opción aparece en la línea 9:

La segunda es utilizar los comandos de DDEV desde fuera del contenedor:

ddev exec enable_xdebug
ddev exec disable_xdebug

O también:

ddev xdebug
ddev xdebug on
ddev xdebug off

Estos comandos permiten activar y desactivar el recurso. Por rendimiento, Xdebug está desactivado inicialmente. Como trabaja del lado del servidor, ya se encuentra en el contenedor web y, en este escenario, nos queda preparar el IDE.

En esencia, los IDE funcionan de forma parecida con Xdebug: escuchan en un puerto y reaccionan al recibir una conexión. En la configuración descrita en el artículo original, Xdebug utiliza habitualmente el puerto 9000. Puedes consultar ejemplos de configuración en:

• Depuración paso a paso con DDEV y Xdebug.
• Xdebug desde la línea de comandos con DDEV.

El equipo de PhpStorm ya explicó la técnica básica en este artículo sobre depuración remota de scripts PHP de consola. Utilizaremos PhpStorm para el ejemplo.

3. Configurar el IDE paso a paso

Veremos los pasos básicos en PhpStorm, aunque el enfoque es similar en otros editores como VSCode. Al activar Xdebug queda disponible para los scripts PHP ejecutados desde la línea de comandos. Esto lo hace especialmente útil para depurar Drush o Drupal Console —la antigua y abandonada Drupal Console, por cierto—. DDEV facilita además su activación automática, lo que simplifica la depuración de nuestra migración.

Sigamos estos pasos:

1. Servidor del proyecto

Abre File → Settings → Languages & Frameworks → PHP → Servers y crea un servidor nuevo. Asígnale un nombre; utilizar el nombre del proyecto DDEV facilita reconocerlo. Indica el puerto 80 y selecciona Xdebug como depurador.

2. Configuración inicial

Cuando el servidor no es local para PhpStorm, necesitamos definirlo como servidor externo y establecer las correspondencias de archivos. En un entorno Docker o DDEV, el código se ejecuta dentro de un contenedor. DDEV sirve la instalación desde /var/www/html/, mientras que los archivos del equipo pueden estar en una ruta como /home/user/folder/projects/my_project. Configuraremos la correspondencia entre ambas rutas.

3. Escuchar conexiones de depuración

Activa el botón de escucha de conexiones de depuración del IDE.

4. Cargar una variable de entorno en el contenedor

Tenemos dos opciones. Podemos definirla para cada sesión entrando en el contenedor con ddev ssh y ejecutando allí:

export PHP_IDE_CONFIG="serverName=your.project.name.ddev.site"

También podemos establecerla de forma persistente mediante un archivo complementario docker-compose.env.yaml en .ddev/, junto a los demás archivos de configuración de Docker Compose:

version: '3.6'
services:
 web:
   environment:
     - PHP_IDE_CONFIG=serverName=your.project.name.ddev.site

Al detener y arrancar la red de contenedores con ddev stop y ddev start, este archivo se combinará con los demás y la variable se cargará automáticamente.

5. Puntos de interrupción

Podemos colocar puntos de interrupción en el código que interviene en la migración. Cuando un campo solo pasa del origen al destino, sin transformaciones, sabemos que se utiliza el plugin de proceso predeterminado: la clase Get.php, situada en /core/modules/migrate/src/Plugin/migrate/process/Get.php.

Es un buen lugar para detener algunos ejemplos de migración. Podemos añadir un punto de interrupción en transform(), que en la versión de la captura aparece en la línea 106:

4. Errores al ejecutar Drush en contenedores

Con el IDE escuchando y los puntos de interrupción preparados, al ejecutar Drush en DDEV puede aparecer un error de correspondencia de archivos. El motivo es que se está ejecutando el lanzador global de Drush del contenedor, instalado en /usr/local/bin/drush, en lugar del ejecutable del proyecto.

Tenemos dos opciones.

Podemos ejecutar Drush directamente desde el directorio vendor del proyecto, que ya está incluido en el mapeo de rutas del servidor remoto. El original muestra estas formas:

• Desde fuera del contenedor: ddev exec /vendor/bin/drush migrate-status.
• Desde dentro, tras ddev ssh: /vendor/bin/drush migrate-status.

La otra opción la recomienda Randy Fay, @randyfay, uno de los creadores de DDEV, en este comentario de una incidencia de GitHub.

Consiste en aprovechar el comando de ejemplo del archivo drush.example, en /your-name-project/.ddev/commands/web/, y sustituir la llamada a Drush por la ruta del ejecutable del proyecto: pasar de drush $@ a /var/www/html/vendor/bin/drush $@.

Así podemos depurar las migraciones con Xdebug en DDEV. Encontrarás más información en:

• Configuración de la depuración con PhpStorm.
• Incidencia 127 de docker4drupal.
• Incidencia 2341 de DDEV.

¡Ahora puedes ejecutar tu migración cómodamente! Lanza los comandos Drush de la migración, comprueba que se alcanzan los puntos de interrupción y empieza a seguir su ejecución.

5. :wq!

Canción recomendada

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

Todavía quedan unos meses para el lanzamiento. Así que, para conservar un poco de salud mental y dar un sentido parcial a estas tareas, he pensado publicar aquí algunos artículos breves a partir de esas notas de trabajo.

De esa manera puedo compartir algo útil junto a las notas complementarias y, si la COVID-19 me alcanza antes de que salga el libro, al menos habré compartido algo antes. Supongo.

Bueno, ¿de qué quiero hablar en este artículo? Me gustaría elaborar una lista de módulos de Drupal relacionados con los procesos de migración: módulos contribuidos que añaden funcionalidades a una migración. Este artículo es solo una recopilación ligera de recursos básicos. Lo juro.

Este artículo se publicó originalmente en una versión anterior de mi cuaderno técnico personal y ahora forma parte de The Russian Lullaby.

Fotografía de Unsplash, del usuario Nils Nedel, @nilsnedel

Índice de contenidos

1- Introducción
2- Recursos básicos: módulos del núcleo
3- Otros recursos básicos: módulos contribuidos
4- Recursos adicionales: módulos contribuidos para plugins
5- Ejecutar migraciones: módulos relacionados con Drush
6- Autores que deberías conocer
7- :wq!

1- Introducción

No es fácil hablar de migraciones en general y, por supuesto, tampoco lo es en el contexto de Drupal. Para ejecutarlas necesitas conocer bien la tecnología, los modelos de datos de origen y destino, tener cierta experiencia con procesos ETL y manejarte con los plugins de Drupal. Las migraciones hacen un uso intensivo de estos plugins.

En cualquier caso, como el tema es amplio y ahora tengo poco tiempo, he planteado este artículo como un catálogo resumido, de consulta rápida, de herramientas y recursos básicos para trabajar con migraciones.

2- Recursos básicos: módulos del núcleo

• Migrate: la base de las migraciones. El módulo migrate proporciona la API fundamental para migrar en Drupal.

• Migrate Drupal: migrate_drupal se centra en las actualizaciones desde Drupal 6 o Drupal 7. Permite leer entidades de configuración en Drupal 8.

• Migrate Drupal Multilingual: migrate_drupal_multilingual. ¿Un módulo experimental del núcleo? Véase esta referencia.

• Migrate Drupal UI: migrate_drupal_ui ofrece una interfaz para realizar la actualización.

3- Otros recursos básicos: módulos contribuidos

• Migrate Plus: migrate_plus es un módulo contribuido esencial que amplía las funcionalidades y capacidades de Migrate con numerosos plugins y extensiones.

• Migrate Tools: migrate_tools es otro recurso imprescindible: proporciona numerosos comandos Drush para ejecutar y gestionar migraciones.

• Migrate Status: migrate_status. Este pequeño módulo permite obtener información sobre un proceso de migración. ¿Necesitas saber si una migración está ejecutándose? Ofrece un servicio al que puedes llamar para comprobarlo.

• Migrate Files: migrate_files. Una colección de plugins de proceso tan interesante que te entrarán ganas de mover archivos e imágenes con ella.

• Migrate Commerce: commerce_migrate. Un marco de propósito general que amplía el módulo Migrate del núcleo para trasladar datos en un escenario de Drupal Commerce.

4- Recursos adicionales: módulos contribuidos para plugins

En las migraciones de Drupal utilizamos distintos recursos para ejecutar el plan ETL. Uno de los fundamentales, como adelantaba en la introducción, son los plugins de Drupal, que requieren cierto conocimiento y práctica.

En una migración, los plugins ayudan a leer la información en la fase E, extracción desde el origen (plugins de origen); realizar la T, transformación o procesamiento (plugins de proceso); y guardar los datos en la L, carga en el destino (plugins de destino). Al combinar estas tres partes solemos obtener un proceso de migración funcional.

Muchos módulos del núcleo, como el de usuarios, ya incluyen sus propios plugins para facilitar las migraciones. Veamos algunos plugins distribuidos en módulos contribuidos.

Plugins de origen: Migrate Source Plugins

• Migrate Source CSV: migrate_source_csv. Módulo contribuido para migrar datos a Drupal 8 desde un sencillo archivo CSV de los de toda la vida.

• Migrate Source SQL: custom_sql_migrate_source_plugin. Como particularidad entre los plugins de base de datos, permite incluir consultas SQL directamente en el archivo .yml que describe la migración. Las consultas se ejecutan contra la base de datos de origen.

• Migrate Source YAML: migrate_source_yaml. Una herramienta sencilla para migrar contenido desde archivos YAML.

Plugins de proceso: Migrate Process Plugins

• Migrate Process Geofield: geofield. El módulo contribuido Geofield incluye un plugin de proceso personalizado para migraciones. Consulta su plugin de proceso.

• Migrate Process XML: migrate_process_xml. Proporciona plugins de proceso para xpath y xvalue.

• Migrate HTML to Paragraphs: migrate_html_to_paragraphs. Ayuda a transformar el HTML del origen en un elemento Paragraph, gestionado mediante un plugin de destino.

Plugins de destino: Migrate Destination Plugins & Examples

¿Qué clase de entidades de Drupal se crearán durante la migración? ¿Entidades de contenido? ¿Entidades de configuración? Echa un vistazo.

• Migrate Destination CSV: d8migrate. Un pequeño módulo personalizado creado por @jonathanfranks.

• Migrate Destination Config: clase Config.php. Ofrece un plugin para migrar configuración.

• Migrate Destination Block: clase EntityBlock.php. Como ejemplo de los recursos que puede ofrecer cada componente en una migración, al trasladar entidades de bloque —que son entidades de configuración— conviene consultar las clases PHP de origen, proceso y destino incluidas en su propio módulo.

5- Ejecutar migraciones: módulos relacionados con Drush

• Migrate Scheduler: migrate_scheduler. Ofrece integración con la API de cron de Drupal para ejecutar migraciones según una programación predefinida.

• Migrate Run: migrate_run. Comandos Drush para ejecutar migraciones de forma ligera. Es más sencillo que Migrate Tools, pero no ofrece soporte para grupos de migraciones. Tampoco depende de Migrate Plus. Va un poco por libre.

• Migrate Devel: migrate_devel. Proporciona opciones Drush para mostrar información de depuración durante la ejecución. También incorpora el plugin de proceso debug. Aquí puedes leer un artículo sobre él. Por cierto, en el contexto original del artículo, la compatibilidad con Drush 9 seguía sin resolverse, aunque parecía haber un parche disponible.

6- Autores que deberías conocer

• Mauricio Dinarte: desarrollador, consultor, formador y propietario de su propio negocio, Agaric. Escribió lo que probablemente sea una lectura obligatoria para cualquiera que quiera aprender a migrar con Drupal: 31 Days of Drupal Migrations, una colección de 31 artículos publicados en Understand Drupal, con los aspectos más importantes, ejemplos, ejercicios y descripciones para entender el mundo interno de las migraciones.

Un material formativo imprescindible. Además, el sitio de su empresa reúne muchos artículos muy buenos sobre el tema bajo la etiqueta migrate.

Algunos ejemplos de Mauricio Dinarte:

1. Introducción a las migraciones de Paragraphs en Drupal.
2. Utilizar grupos de migración para compartir configuración entre migraciones de Drupal.
3. ¿Cuál es la diferencia entre etiquetas y grupos de migración en Drupal?.

Su perfil en Drupal.org: dinarcon.

• Tess Flynn: oí hablar de ella leyendo artículos de Mauricio Dinarte. Así conocí a esta desarrolladora experta, ponente y divulgadora de la comunidad Drupal. En su sitio, deninet.com, encontré contenido variado y, sobre todo, una serie muy interesante sobre migraciones bajo la etiqueta drupal-migration.

Por el camino descubrí también que tiene varios módulos contribuidos relacionados con las migraciones y los plugins de proceso.

Algunos ejemplos de Tess Flynn:

1. Migrate Process URL: proporciona un plugin de proceso para migrar campos de enlace.
2. Migrate Process Vardump: ayuda a depurar migraciones.
3. Otros plugins de proceso: Migrate Process Array, Migrate Process Skip y Migrate Process Trim.

Su perfil en Drupal.org: socketwench.

• Danny Sipos: autor de una reconocida «biblia» de Drupal, Drupal 8 Module Development, por entonces en su segunda edición, y del sitio webomelette.com. Ponente, formador y asistente habitual a distintos encuentros internacionales de Drupal, también ha escrito artículos interesantes sobre migraciones que deberías leer.

Algunos ejemplos de Danny Sipos:

1. Tu primera migración en Drupal 8.
2. Migraciones dinámicas mediante «plantillas» en Drupal 8.
3. Generar rápidamente las cabeceras del plugin de origen CSV mediante Drush.

Su perfil en Drupal.org: upchuk.

7- :wq!

Canción recomendada