Migrando a Drupal: una guía práctica

En el artículo anterior de esta serie hicimos un recorrido por los conceptos claves y la arquitectura base de Drupal. Ahora abordaremos una de las tareas más desafiantes —y también más comunes— en proyectos reales: migrar contenido desde otros sistemas a Drupal.

Ya sea desde un CMS heredado, una base de datos externa o incluso un conjunto de hojas de cálculo, la necesidad de conservar estructura, integridad y relaciones entre datos es crítica.

Este artículo te guiará a través de los fundamentos del sistema de migración de Drupal, con un enfoque eminentemente práctico: veremos ejemplos reales, buenas prácticas y enlaces que puedes explorar por tu cuenta para poner en marcha tu primer proceso de migración.

¿Qué es el sistema de migración de Drupal?

Desde Drupal 8, el núcleo del sistema incluye el módulo Migrate, que ofrece una arquitectura robusta y extensible para importar datos desde múltiples orígenes hacia entidades de Drupal (como nodos, usuarios, taxonomías o archivos).

Se basa en tres conceptos clave:

• Source: el origen de los datos (CSV, base de datos, XML, JSON, etc.).
• Process: cómo se transforman o adaptan los datos al nuevo modelo.
• Destination: la entidad de Drupal donde se almacenarán los datos.

Esta arquitectura permite importar de forma declarativa (vía YAML) o programática, y es compatible tanto con migraciones simples como con escenarios complejos.

El ecosistema de módulos enfocados a tareas de migración es muy amplio, pero hay dos módulos que no te pueden faltar:

• Migrate Plus: extiende el soporte de nativo de Migrate agregando plugins muy útiles de orígenes, procesamiento y almacenamiento de los datos.
• Migrate Tools: provee una interfaz y comandos Drush para gestionar y ejecutar las migraciones.

El punto de partida: analizando el origen

Antes de escribir una sola línea de configuración, el primer paso es entender la estructura del sistema de origen. ¿Tienes acceso a una base de datos? ¿O te han pasado un Excel? ¿Es un CMS antiguo que exporta en XML?

Algunos ejemplos típicos:

• Migrar desde WordPress: puedes usar el plugin WP All Export para generar archivos XML o CSV y luego procesarlos desde Drupal.
• Desde Drupal 7: existe soporte completo para migraciones automatizadas de entidades básicas.
• Desde archivos CSV: uno de los casos más comunes, ideal para comenzar.

Escribiendo una migración simple

Supongamos que tenemos un archivo CSV con una lista de artículos y queremos convertirlos en nodos del tipo «Noticia». Lo primero es definir el archivo .yml correspondiente (por ejemplo, migrate_plus.migration.articulos.yml).

Aquí un ejemplo de una migración de CSV:

id: articulos_csv
label: Artículos desde CSV
migration_group: migracion_csv
source:
  plugin: csv
  path: modules/custom/migracion_csv/data/articulos.csv
  header_row_count: 1
  keys:
    - id
  column_names:
    - id
    - titulo
    - cuerpo
process:
  title: titulo
  body/value: cuerpo
destination:
  plugin: entity:node
  default_bundle: noticia

Este archivo indica cómo leer el archivo CSV, cómo procesar sus columnas y a qué tipo de entidad en Drupal volcar el resultado.

Migraciones más avanzadas: relaciones y transformaciones

En proyectos reales, rara vez los datos son planos. Es común tener que relacionar contenidos con categorías, referenciar usuarios o archivos, o simplemente limpiar y transformar datos en el proceso para ajustarlos a nuestro modelo.

Para esto, puedes usar plugins de transformación. Algunos ejemplos comunes son:

• get: para acceder a un campo concreto.
• concat: para combinar cadenas.
• callback: para aplicar funciones personalizadas.
• migration_lookup: para enlazar con otros registros previamente importados.

Ejecutar, depurar, repetir

Una vez que tienes definida tu migración en archivos .yml, es hora de ponerla en marcha. Para esto, Drupal ofrece una integración muy sólida con Drush, la herramienta de consola por excelencia en el ecosistema Drupal.

Los comandos más habituales para gestionar migraciones son:

drush migrate:status

Este comando muestra un resumen de todas las migraciones disponibles, su estado (pendiente, importada, fallida) y si están habilitadas.

drush migrate:import articulos_csv

Ejecuta la migración con el ID indicado. Si todo está correcto, verás cómo se importan los registros uno por uno.

drush migrate:rollback articulos_csv

Revierte los registros que fueron importados, útil para probar diferentes configuraciones sin llenar la base de datos de duplicados.

drush migrate:reset-status articulos_csv

A veces una migración se queda «bloqueada» si se interrumpe a mitad de ejecución. Este comando la desbloquea para volver a intentarlo.

Durante la ejecución puedes encontrarte errores como:

• Columnas faltantes.
• Tipos de dato incorrectos.
• Referencias a entidades inexistentes.

En esos casos, contar el módulo Migrate Devel para obtener más información detallada del proceso, incluyendo los valores procesados, los mapeos de ID, y los errores específicos de cada fila.

Y si estás desarrollando tus propios plugins de transformación, es muy útil combinar Drush con herramientas de depuración como xdebug, o incluso watchdog y dpm() para imprimir valores en tiempo de ejecución.

Estrategias para proyectos reales

En entornos reales, la migración rara vez es un proceso de “una sola vez”. Los datos evolucionan, los errores aparecen con el tiempo, y los orígenes pueden ser inconsistentes o inestables. Por eso, más que ejecutar una migración, lo que necesitas es diseñar un proceso de migración mantenible y repetible.

Aquí algunos enfoques y buenas prácticas:

• Desarrollo iterativo: comienza con un conjunto de datos reducido y campos esenciales. Haz pruebas frecuentes, documenta decisiones y permite a los usuarios revisar los primeros resultados antes de importar todo.
• Migraciones encadenadas: divide el contenido en migraciones lógicas: usuarios, taxonomías, nodos, archivos, relaciones. Usa migration_lookup para conectar entre ellas. Esto permite aislar errores y reusar componentes.
• Importaciones incrementales: si el sistema de origen sigue activo, puedes diseñar migraciones que sólo actualicen los registros nuevos o modificados, usando claves primarias (keys) y campos de control como updated_at.
• Entornos separados: ejecuta la migración primero en local, luego en staging, y finalmente en producción. Mantén los archivos YAML versionados con Git y crea scripts automatizados que documenten cada paso.
• Control de calidad: valida los resultados importados con tests manuales y automatizados. Verifica relaciones, integridad de campos y comportamiento editorial.
• Mantenimiento: si tu sitio necesita importar contenido periódicamente, considera usar módulos como Migrate Cron o tareas personalizadas que reimporten desde el origen con un cron programado.

Migrando, que es gerundio

Migrar contenido a Drupal puede parecer complejo, pero el sistema Migrate ofrece una base sólida y flexible para abordar cualquier escenario. Lo importante es entender la fuente, planificar bien los datos de destino y apoyarse en la comunidad: hay documentación, módulos y ejemplos disponibles para casi todos los casos imaginables.