Migrar entre versiones mayores de Liferay DXP no es simplemente actualizar una dependencia en el build.gradle. Cada versión introdujo cambios arquitectónicos significativos que afectan desde la capa de persistencia hasta el frontend, pasando por el modelo de despliegue y la infraestructura de temas. He participado en migraciones desde 7.1 hasta 7.4 en proyectos de distintas escalas, y la experiencia me ha enseñado que entender el contexto de cada versión es tan importante como conocer los pasos técnicos.
Liferay 7.1 fue la versión que consolidó la transición de Liferay 6.x al modelo OSGi. Sus características definitorias:
Temas FreeMarker: los temas se construían con plantillas FreeMarker. Velocity quedó deprecado en 7.0 y su soporte en temas se eliminó justamente en 7.1, así que todo proyecto que llegara desde 6.x con plantillas .vm tenía que convertirlas a .ftl como parte de la migración. El Theme SDK generaba la estructura de archivos y las plantillas base. La personalización requería editar archivos .ftl y entender el sistema de template context variables de Liferay.
Portlets JSP dominantes: aunque la plataforma ya soportaba módulos OSGi, la mayoría de portlets custom se escribían con JSP como tecnología de vista. Los MVCPortlets con JSP eran el patrón estándar. Los taglibs de Liferay (<liferay-ui:search-container>, <aui:form>) eran omnipresentes.
AlloyUI: la librería JavaScript propia de Liferay, construida sobre YUI3 de Yahoo y apoyada en Bootstrap 3 para el HTML/CSS. Proporcionaba componentes de UI, manejo de eventos y utilidades DOM, y en 7.1 seguía siendo el camino más transitado para el JavaScript custom, aunque Liferay ya la había puesto en modo sunset en 7.0 y Metal.js empezaba a ganar terreno.
Service Builder como opción principal: para entidades personalizadas con persistencia en Java, Service Builder era la herramienta. Sin escribir código quedaban las Dynamic Data Lists y los campos personalizados de Expando, pero nada equiparable a lo que después serían Objects.
Personalización fuera del core: la segmentación y la personalización venían de la app Audience Targeting de Marketplace, no del producto base; solo en 7.2 se integran en el core como Segmentation and Personalization. Tampoco había pruebas A/B: llegan en 7.2 apoyadas en Liferay Analytics Cloud.
La versión 7.2 marcó un punto de inflexión en la estrategia frontend de Liferay:
Front-end Toolkits: 7.2 puso los toolkits de frontend en primera línea —resuelven los conflictos de paquetes JavaScript y empaquetan la aplicación como módulo OSGi listo para desplegar—. No era la primera vez que se podía escribir un portlet con React, Angular o Vue: el JS Toolkit funciona desde 7.0 y los widgets React ya estaban disponibles en 7.1 con el JS Portlet Extender 1.1.0. Lo que cambió en 7.2 es que Liferay lo asumió como camino oficial, y eso abrió la puerta a que equipos frontend trabajaran con tecnologías modernas.
SPA Navigation mejorado: Liferay 7.2 mejoró significativamente la navegación SPA (Single Page Application) integrada. Las transiciones entre páginas eran más fluidas y el sistema de carga parcial de portlets se optimizó.
Segment-based Personalization: se introdujo un motor de segmentación de usuarios más sofisticado. Podías definir segmentos basados en múltiples criterios (rol, organización, datos custom) y personalizar la experiencia de cada página según el segmento.
Content Sets: precursores de las Collections de 7.3/7.4. Permitieron agrupar contenido web y mostrarlo de forma dinámica basada en criterios.
Convivencia de AlloyUI y Metal.js: AlloyUI llevaba en modo sunset desde 7.0 —Liferay dejó de añadirle funcionalidad, aunque siguió incluida y mantenida— y Metal.js, basado en incremental-dom, nació en esa misma versión como su relevo. Lo que se vive en 7.1 y 7.2 es la etapa de transición en la que ambas coexisten; a partir de 7.3 el movimiento real ya es de Metal.js y Soy hacia React.
La versión 7.3 introdujo cambios fundamentales en cómo se construyen las páginas:
Content Pages consolidadas: las Content Pages y el editor visual drag-and-drop existen desde 7.1, pero es en 7.3 cuando pasan a ser la forma principal de construir páginas: llegan los layouts anidables y flexibles, los flujos de aprobación para Content Pages y la conversión automática de Widget Pages a Content Pages. Los Widget Pages quedan en segundo plano.
Master Pages: plantillas maestras que definen la estructura común de las páginas (header, footer, layout), asegurando consistencia visual sin modificar el tema.
Fragmentos, ya maduros: los fragmentos —piezas de UI reutilizables con HTML, CSS, JavaScript y configuración— se introdujeron en 7.1 junto con las Content Pages, no en 7.3. Lo que aporta 7.3 son mejoras que los vuelven realmente utilizables a escala: un fragmento out-of-the-box para mostrar contenido individual, permisos de widgets dentro de páginas de fragmentos y despliegue automático de fragmentos soltando un ZIP en la carpeta deploy. Con ellos se cubren muchos casos de uso donde antes necesitabas un portlet custom.
App Builder: herramienta low-code para crear aplicaciones de datos sin código. Fue el precursor directo de Objects en 7.4.
Collections y Collection Display: evolución de Content Sets con filtros avanzados y templates personalizables.
La versión 7.4, especialmente con sus actualizaciones trimestrales, representó el salto más grande:
Client Extensions (CEs): el cambio de paradigma más significativo. Las CEs permiten extender Liferay sin desplegar código dentro de la plataforma. El objetivo: desacoplar las personalizaciones del core.
Objects: permite definir entidades de datos, relaciones, validaciones y APIs REST sin escribir Java. Para CRUD simple, elimina la necesidad de Service Builder.
StyleBooks: sistema de variables CSS (tokens) para controlar la apariencia visual desde un panel centralizado sin tocar CSS. Este punto pertenece a la sección de 7.3: los Style Books llegaron con Liferay 7.3, no con 7.4.
Remote Applications: mecanismo para registrar aplicaciones externas como widgets disponibles en el Page Builder.
Headless APIs mejoradas: APIs REST auto-generadas para Objects y GraphQL mejorado. El Batch Engine para operaciones masivas no es de 7.4 sino de 7.3, donde apareció como operaciones batch en las Headless APIs.
Cada salto de versión introduce cambios que rompen compatibilidad. Los más impactantes que he encontrado en migraciones reales:
7.1 a 7.2:
com.liferay.portal.kernel.util.ThemeHelper y com.liferay.taglib.util.ThemeUtil. Si tu tema aún renderizaba con JSP, hay que pasarlo a FreeMarker.Liferay.Loader.addModules del liferay-amd-loader (febrero de 2019) y AlloyEditor v2.0 pasó a una versión mayor de React: los editores o módulos JavaScript custom que dependían de esas APIs necesitan adaptación.UserLocalService es de 7.4, no de 7.2: addDefaultGroups, addDefaultRoles y addDefaultUserGroups pasaron de void a devolver boolean (LPS-134096, julio de 2021). Lo que sí rompe en el salto de 7.1 a 7.2 es, como se menciona arriba, la eliminación del soporte de plantillas JSP en los temas.7.2 a 7.3:
liferay.frontend como ProgressBar y Slider (el Liferay.Loader.addModules ya se había eliminado en el salto anterior, como se vio arriba). Lo que no ocurrió en este salto es la migración a webpack: liferay-npm-bundler está inspirado en webpack pero no es compatible con él y sigue apuntando al AMD loader; su deprecación llega en 2024.Q4 / 7.4 GA129.7.3 a 7.4:
styled, classic y admin: o la reactivas al actualizar el tema o actualizas el marcado. (Ojo con jQuery: no se retiró en 7.4 sino en 7.3, donde window.$ y AUI.$ quedan undefined; si vienes de 7.1 o 7.2 te lo encuentras un salto antes.)@Component y @Reference es el estándar en Liferay desde 7.0, no una novedad de 7.4. Y @BeanReference no fue reemplazado ni eliminado —sigue en portal-kernel y ya estaba en 6.2— porque resuelve otra cosa: inyectar beans Spring del core de Liferay, no servicios OSGi.content de JournalArticle (LPS-129058, mayo de 2021): el contenido pasa a almacenarse mediante los servicios de Dynamic Data Mapping, así que si tu código lo leía o escribía directamente hay que pasar por los métodos update de JournalArticleLocalService.He visto ambos enfoques en proyectos reales, y cada uno tiene su contexto:
Migración incremental (versión por versión): cada salto es más pequeño y los problemas son más fáciles de diagnosticar, pero multiplicas el esfuerzo de testing.
Migración directa (7.1 a 7.4): Liferay lo soporta oficialmente. Solo haces un ciclo de testing, pero diagnosticar fallos es más difícil con más variables en juego.
Mi recomendación: la migración directa es viable pero requiere análisis previo exhaustivo. Siempre ejecuto el upgrade en un ambiente de prueba primero y documento cada problema antes de tocar producción.
El proceso de upgrade de la base de datos sigue un patrón consistente entre versiones:
Backup completo: base de datos, Document Library (filesystem o S3), y configuración de portal. Esto no es negociable.
Ejecutar la herramienta de upgrade: ubicada en [Liferay Home]/tools/portal-tools-db-upgrade-client/. Configuras las propiedades de conexión a base de datos y del portal, y ejecutas db_upgrade_client.sh (db_upgrade_client.bat en Windows); en bundles anteriores a 7.4 U82/GA82 ese script se llamaba db_upgrade.sh. La herramienta procesa todos los upgrade steps secuencialmente.
Verificación post-upgrade: revisar el log de upgrade buscando errores. Los warnings son normales; los errores requieren atención.
Limpieza: ejecutar los procesos de limpieza de datos deprecados que Liferay recomienda para cada versión.
La migración frontend es frecuentemente la parte más costosa porque implica cambios en la experiencia de usuario visible:
AlloyUI a JavaScript moderno: si tienes código JavaScript que usa AUI(), Liferay.fire() con AlloyUI, o componentes AUI, necesitas reescribirlo. No hay herramienta de migración automática. En mi experiencia, este es el trabajo más intensivo en migraciones desde 7.1 o 7.2.
JSP Portlets a Fragmentos o Client Extensions: los portlets JSP que renderizan UI simple (formularios, listas, tarjetas) pueden reemplazarse con fragmentos. Los que tienen lógica compleja pueden convertirse en Client Extensions con React o Angular.
Temas FreeMarker a temas con StyleBooks: los temas de 7.4 deben exponer las variables CSS (tokens) que los StyleBooks controlan. Un tema traído de 7.1 no entra intacto: además de adaptar esa estructura, en 7.4 desapareció la capa de compatibilidad de Bootstrap 3 y 4 de los temas styled, classic y admin, así que o la reactivas al actualizar el tema o actualizas el marcado.
Basado en mi experiencia con migraciones reales, estos son los puntos más importantes:
No saltes el análisis de compatibilidad: antes de migrar, ejecuta el Upgrade Planner de Liferay —viene incluido en Liferay Dev Studio desde la versión 3.6, y también puedes instalarlo sobre un Eclipse propio con los plugins de Liferay IDE—. Identifica el código afectado por cambios de API, explica cada cambio y en algunos casos ofrece adaptarlo automáticamente.
Prioriza el testing automatizado: si no tienes tests, escríbelos antes de migrar. Necesitas una forma de verificar que la funcionalidad crítica sigue funcionando después del upgrade.
Planifica la migración frontend por separado: el upgrade de base de datos y backend es un proyecto; la modernización del frontend es otro. Pueden hacerse en fases distintas.
El futuro es Cloud y CEs: Liferay está moviendo su estrategia hacia Liferay Cloud (PaaS con actualizaciones automáticas) y Client Extensions como modelo de personalización. Si estás en 7.1 o 7.2, migrar a 7.4 no es solo una actualización técnica: es posicionarte para la siguiente década de la plataforma.
Las migraciones de Liferay son proyectos complejos que requieren planificación, conocimiento profundo de la plataforma y paciencia para resolver los problemas inevitables que surgen en el camino. Pero el resultado es una plataforma más moderna, con mejor rendimiento y un modelo de desarrollo significativamente más productivo.