Upgrading a Liferay Portal: How to Migrate a Lower Version to the Higher One

When it comes to maintaining your business operations on point, timely migration to the Liferay latest version is not just a good practice — it’s a necessity. It gives you access to enhanced security features, improved performance, and new tools that can enable operational efficiency. 

This blog post will help you explore how timely migration helps mitigate security vulnerabilities, ensure compliance with industry standards, and optimize system performance. From assessing your current system’s readiness to creating a thorough migration plan, we cover every key step in detail. We’ll share with you the knowledge that we’ve acquired as a result of providing Liferay development services for over 20 years and help you prevent potential pitfalls and ensure data integrity throughout the migration. 

By the end of this article, you’ll have a clear roadmap for upgrading your Liferay solution and gain confidence in completing your migration journey successfully.

Reasons to upgrade your Liferay portal

Liferay portal migration is the process of Liferay upgrade from a lower version to a higher one. But why do you need that? Why not just stick to the same version if it’s stable? Here is how Vitaliy Koshelenko, Senior Liferay Architect at Aimprosoft, explains reasons to consider migration:

• New features: Liferay as a platform is constantly evolving in terms of feature set, user experience, configuration, and customization options (especially in the last several years). Thus, to use the newest features, you need to be on the newest version;
• Improved development: Developing custom applications became more standardized and straightforward due to the new modular architecture in Liferay 7.x and modern developer tools;
• Easier customization: Liferay customization became easier due to new extension points provided by the latest Liferay versions;
• Better content editing: The recent Liferay CMS versions ensure that the content editing process is intuitive and seamless, which you can benefit from if content management is one of your crucial activities. You can build Liferay pages and set content yourself using out-of-the-box (OOTB) and custom components and inline editing capabilities;
• Faster development: Low-code/no-code Liferay capabilities decrease development efforts;
• Flexible integration: With new approaches like Headless APIs and Client Extensions, you can use different technologies and involve developers with (almost) no Liferay knowledge;
• Faster content setup: Modern features like AI-powered auto-tagging, translations, or text/image generation significantly speed up content setup on the portal and provide unique experiences for end users with segmentation and personalization capabilities;
• Enhanced security: The latest Liferay versions usually use the latest technologies stack and come with the latest bug fixes and security updates, which makes your portal more secure and stable.

This is not the entire list, but just some of the key benefits of embracing the newest Liferay version. By migrating to a newer version, your company can take full advantage of Liferay’s evolving capabilities.

When do you need to migrate your Liferay portal?

While the reasons to migrate described in the section above may sound tempting to upgrade your solution, the question of the right timing may still be something unclear. Let’s consider 5 key signs that will tell you that this is the right time to migrate: 

1. Growth demands: Your company’s growth or increasing data volume requires enhanced scalability features that are available in newer versions. If your portal is still on the Liferay 6.2.x version (or even below), it definitely makes sense to migrate. If you’re on Liferay 7.x already (but not the latest one), migration to the latest version might still be useful, as long as your portal is growing, new features appear, and you simply want to stay up-to-date with the latest capabilities and security updates provided by the vendor.
2. Official support termination: Your current Liferay version is no longer supported, meaning you won’t receive critical updates or security patches.
3. Degraded performance: You’re experiencing performance issues or slowdowns that cannot be resolved with the current version, impacting user experience and productivity.
4. Compatibility problems: New third-party tools or technologies are incompatible with your current Liferay version, limiting your ability to integrate with modern systems.
5. Missing functionality: Your version lacks essential features or enhancements available in the latest release, hindering your ability to meet your current business needs.

Recognizing the right time to migrate your Liferay portal is crucial for maintaining optimal performance and leveraging the latest features. If you’re facing issues such as end-of-support, security vulnerabilities, performance slowdowns, compatibility challenges, or missing essential functionality, it’s a clear sign that upgrading to a newer version could provide significant benefits. 

Which Liferay version do we recommend migrating to?

Choosing the right Liferay version for migration may seem straightforward — migrate to the latest release. However, the decision becomes more nuanced when considering the release frequency and associated factors.

Historically, Liferay followed a weekly release schedule, with new versions coming out every Friday. This approach meant that the tech team had to handle frequent updates, including bug fixes, new features, and occasionally new bugs. Such a rapid release cycle could make constant updates challenging and resource-intensive, often requiring weekend work to keep the portal stable.

Fortunately, starting in late 2023, Liferay adopted a quarterly release model. Now, new versions are released every three months. This change makes ongoing updates more manageable, as minor updates (e.g., moving from 2024.Q1 to 2024.Q2) typically require less effort and planning.

When deciding which Liferay version to migrate to, consider the following:

1. Stability vs. latest features: While migrating to the latest version offers access to the newest features and improvements, it’s essential to evaluate the stability and maturity of that version. Newer releases might introduce new functionalities, but may also come with unforeseen issues.
2. Support and compatibility: Ensure the chosen version aligns with your organization’s needs and technology stack. Pay attention to the Java versions supported by different Liferay releases to avoid compatibility issues.
3. Upgrade path: If you are on an older version, consider moving to a more recent stable release rather than jumping directly to the latest version. This phased approach can help mitigate risks and reduce the complexity of the migration process.
4. Organizational needs: Evaluate the new features and improvements offered by the latest versions. If these align with your business goals and requirements, upgrading to a newer version may be beneficial. For example, if enhanced scalability or advanced functionalities are needed, newer versions may provide those benefits.
5. Liferay Enterprise Edition (EE) or Community Edition (CE): When deciding between Liferay DXP and Liferay CE for migration, focus on three main factors: price, features, and support. Pricing is clear—CE is free, while DXP is a paid service, typically costing tens of thousands annually based on your needs. Features differ significantly; DXP includes advanced tools like Enterprise Search and Kaleo Designer, which CE lacks. If these are crucial for your portal, DXP is worth considering.
   
   Support is another key point: DXP offers official Liferay support, while using CE, you’ll have to ask for help in the Liferay community (Slack/forum/etc.) or Liferay services company like Aimprosoft. Also, DXP supports enterprise databases like Oracle, whereas CE only supports community databases. Finally, if you’re on CE, you can upgrade to either CE or DXP; if on DXP, you can only upgrade to a newer DXP version.

Also, when choosing the target Liferay version, be aware that the provider is currently working on updating the supported Java version. Take a look at the Liferay 7.4 compatibility matrix below with Java versions per release:

DXP (EE) Version	CE Version	Minimum Java version supported	Maximum Java version supported
2024. Q1 Release	Liferay 7.4 GA 112	Java 8	Java 11
2024. Q2 Release	Liferay 7.4 GA 120	Java 11	Java 17/Java 21
[Next version]	[Next version]	Java 17	Java 21

While upgrading to the latest Liferay version is generally advisable, it’s crucial to balance the benefits of new features with the stability and support provided by the release. The quarterly release cycle simplifies the process, making regular updates more feasible and allowing you to plan your migrations strategically. Always evaluate the specific needs of your portal and the compatibility requirements to make an informed decision.

Liferay migration process in 6 simple steps

Migrating to a new Liferay version involves a series of critical steps to ensure a smooth and successful transition. In this Liferay tutorial, we will outline each phase of the migration process, providing a clear roadmap from planning to execution.

Step 1: Discovery phase

In this Liferay tutorial, we will describe our approach to digital platform migration, outlining each phase of the process. By doing so, we want to help you avoid common pitfalls while getting a clear picture of the entire flow from planning to execution. Before starting the migration process, we recommend having a preparation/discovery phase. This pre-migration stage usually includes several aspects that need to be carefully analyzed:

• Documentation
• Database
• Code

Analyzing documentation

Apart from the Liferay dump (export or backup of the data and configuration from a Liferay portal instance) and sources that you provide, we also need to check and analyze supporting documentation on the project to understand better the features and functionality of an app being migrated. If you hire Liferay developers at Aimprosoft, and such documentation is missing, we organize calls, demos, or Q&A sessions with you to learn about the portal we need to migrate and then compose documentation based on the obtained information.

Analyzing database 

There is a rule in Liferay: do not edit the database manually. But when we receive a dump, we can’t be sure this rule has been followed for the whole period of the portal’s life. Thus, it makes sense to check whether databases are consistent and whether no orphan records are left there (e.g., content that belongs to a non-existing site). If we find such records, it’s important to make sure they are not transferred to a newer Liferay version since it may lead to errors during a content management migration process or unstable work of the migrated application.

Also, it’s important to check whether the database does not contain redundant data, e.g., old web content or document versions, not required system or audit information, etc. This way, the migration process will be faster, and the resulting database will be smaller.

Analyzing code 

Analyzing code is also one of the most important steps in preparing for migration: here, we can define the structure and architecture of a project for a new Liferay version, the main components and interactions between them, and finally, compose a migration plan.

Codebase and functionality should be analyzed considering new features available in Liferay: some parts can be migrated as-is, others can be replaced with new Liferay functionality (e.g., fragments instead of widgets), or a mixed approach can be used.

Note: Often, during a discovery phase, we define a database as having some issues that need to be fixed, such as inconsistency, duplicated or redundant data, etc.

As manual updates to a database are risky and not recommended by Liferay, we can develop a small utility application for an original Liferay version that can make database updates using safe Liferay APIs. The application can be implemented as a widget with some configuration options and a ‘Submit’ button or as a tool that makes updates automatically on deployment. Regardless of the choice, the goal is to make a database ready for migration.

As each portal migration is individual, there is no universal tool for this, but our Liferay specialists can implement one specifically to meet your needs.  

Step 2: Database migration

After the discovery phase is done, you have a plan and a database ready for a transfer, and we can proceed with the database migration step.

During this step, you update the underlying database schema, performing special Liferay portal upgrade steps to accommodate the target version: creating tables, adding or updating columns, migrating data, etc.

This process is quite straightforward: we just need to configure a newer Liferay to use the old database and run it. It will detect that the database schema is old and does not match the current Liferay version and perform all the necessary updates. Migration to a newer Liferay version is smarter now: if it fails for some reason, you can restart Liferay (after fixing the issue), and migration will go on; you don’t need to load an original dump again anymore. However, it’s still recommended to make backups though.

The upgrade status can be checked in Gogo Shell (a command-line tool for integrating with an OSGi environment), and the current portal version can be checked in the database’s Relase_ table. 

Important: Backups are an integral part of the migration process, so do not forget to do them. Firstly, when you deal with an original backup, keep it in a safe place so you can restore it if needed. Next, make a database backup before any changes to a database (even using Liferay APIs) and after those changes have been successfully applied. Finally, create a backup after the database migration step is completed. 

Step 3: Properties and configuration

Liferay has many configuration properties that can be used to customize the portal’s behavior and appearance. As Liferay evolves, some of these properties become deprecated or completely removed, and new ones appear.

It’s important to check all customized properties in the original Liferay (portal-ext.properties or portal-setup-wizard.properties file) and make sure they are still supported by a target Liferay version. If not, we recommend finding a replacement or a workaround for them. During migration from 6.x to 7.x, some configuration properties might have been moved to portal configuration — System Settings in the Control Panel. In this case, such properties don’t need to be added to a target Liferay; instead, configuration should be defined.

When there are custom application-specific properties, it’s also recommended to replace them with UI configuration to allow setting updates without resetting the portal.

Step 4: Theme migration

In previous Liferay versions (6.x and early 7.x releases), themes were the only way to define a site’s appearance, which is the structure and styling of a portal page. That’s why theme migration is a regular part of almost all migration projects.

However, migrating a theme is not easy and straightforward since there were significant changes in Liferay’s underlying technologies, architecture, and build tools, and there is no automated migration process like with databases.

Usually, migration of a Liferay theme is a process of creating a new theme for the target Liferay version and adopting styling/templates from a previous one on top of it. There might be slightly different steps depending on the project, but in general, to migrate a theme, you need:

1. Create a new Liferay Theme with the same name and settings. Check our blog post on theme development to get valuable insights;
2. Copy configuration files and adjust them to be compatible with target Liferay; 
3. Copy CSS files and update them according to the target portal’s requirements, e.g., Bootstrap version, Clay components, SCSS syntax, etc.;
4. Copy images and fonts;
5. Copy custom JavaScript files, and make changes if required by the target portal version;
6. Copy templates and rewrite them from Velocity (VM) to Freemarker (FTL) – in case of migration from 6.x to 7.x (as Velocity is no longer supported by Liferay);
7. Deploy and test.

This is a general process for a theme migration, but there might be exceptions, of course. During a discovery phase, we might discover that we can eliminate some parts of the theme, e.g., replace templates defined in a theme with brand-new Master Templates, or get rid of a theme completely using the theme-less approach and new features provided by Liferay. 

Step 5: Template Migration

Liferay always had low-code capabilities and provided content editors with the option to define custom templates and update portal content dynamically. For example, such templates can be used to style displayed web content (Web Content Template) or to customize the appearance of a widget (Widget Templates, former Application Display Templates).

Liferay 6.x was using Velocity (VM) as the template engine, but Liferay 7.4 had already switched to Freemarker (FTL) due to its flexibility, capabilities, and performance. Even though templates are stored in a database and migrated during the database migration phase, they are still on Velocity (assuming you migrate from 6.x) and are not compatible with Liferay 7.4.

Thus, such templates need to be converted to Freemarker. Due to different syntax and language capabilities, there is no automatic migration tool from VM to FTL, so such a transformation requires manual work.

Step 6: Portlet migration

Portles (also called “widgets” for 7.x) are usually the core of the project’s functionality and the main (also most important and time-consuming) part of Liferay migration. As Liferay’s architecture has been changed to a modular one, and the underlying technologies have changed as well (the OSGi framework has been integrated), migration of widgets might also be tricky.

Liferay 6.2 projects usually have big monolith modules (with dozens of portlets), which are assembled into a single WAR file and deployed to Liferay. For Liferay 7.4, the best practice is to create a separate module for each piece of functionality: usually a single widget per module or a couple of related ones. These modules are then assembled as tiny JARs and deployed to an OSGi container inside Liferay.

For migration from 6.2 to 7.4, there are two options:

1. Leverage Liferay’s backward compatibility capability and deploy old-style monolith WAR files (making sure they are compiled and assembled for the target version).
2. Leverage a new modular approach and transform portlets code to OSGi modules during the migration process.

According to our Software Architect, the 2nd option is the more optimal one. Even though it may take more time, the resulting codebase would become more flexible and better integrated with Liferay’s internal frameworks. 

If the final goal is not solely the migration but also extending functionality and implementing new features after migration, it is better to proceed with a modular approach; otherwise, the old-style way can be used, at least during the migration process.

Leveraging new Liferay features

The migration itself doesn’t make sense unless new features in the target Liferay version are used. Thus, during the discovery phase, you need to analyze the code/features of the portal being migrated while keeping in mind the new Liferay technology capabilities. This way, you can map them together and replace certain parts with OOTB Liferay features instead of migrating them. Take a look at the most popular examples below.

Portlets to fragments

Fragments is a new Liferay 7.x feature that allows content editors to create reusable and configurable UI elements. This feature was not present in Liferay 6.x. Thus, even for simple scenarios like data output, Liferay experts often create custom portlets. If that’s the case, such portlets can be converted to fragments instead of being migrated to widgets.

Portlets to client extensions

If a portlet has more complex logic and can’t be converted to a fragment and has front-end code that communicates with the back-end, it can be converted to a Custom Element Client Extension — an external application that calls Liferay APIs and is rendered on a page as a widget. Both fragments and client extensions are more flexible and preferred options than widgets.   

Theme templates to master pages

A new Liferay 7.x Master Templates feature provides an option to define a template for pages with a static part defined in the template itself and a dynamic part (“dropzone”), which can be edited on each individual page.

In Liferay 6.x and early 7.x versions, the only way to customize the “static” part was to put appropriate code to theme templates. For newer Liferay versions, it’s preferred to proceed with Master Pages instead of theme templates. 

This can be taken into account before the migration process, and some template parts like header/footer can be converted to separate fragments to be used in Master Pages, instead of being converted together with the theme.

Color schemes to style books

Liferay themes have the option to define Color Schemes, which are some kind of “sub-themes” with customized styling options (e.g., “light” or “dark”). Liferay 7.4 has a new Style Books feature that can replace color schemes. With Style Books, changes can be done directly on the portal, and no theme redeploy is needed.

Layout templates to grids/fragments

Liferay 6.2 had only widget pages, and widgets could be placed in one of the columns defined in the layout templates. For more advanced arrangements, developers created custom layout templates. 

Even though such layout templates are still supported in Liferay 7.4, they are no longer necessary, as with a new type of page (content pages) and elements like Grids/Containers, content editors can compose any layout they need on the portal. 

To enable this feature, widget pages need to be converted to content pages after migration. By following this approach, we can ensure the migrated portal is up-to-date with features set, flexible, and easily configurable.

Potential risks and pitfalls during Liferay migration

Understanding the potential risks and challenges of upgrading from a lower version of Liferay to a higher one is essential for a smooth and successful transition. Explore common issues during such upgrades and get practical recommendations to address and mitigate these challenges effectively.

1. Data volume and custom feature migration challenges

Migrating from a lower version of Liferay to a higher one may involve challenges related to data volume and custom features. The complexity increases with the size of the database and the extent of customizations made in the lower version. Custom features, such as widgets or portlets, may not be directly compatible with the newer version.

How to avoid:

• Conduct a thorough audit of the existing data and custom features to understand their structure and dependencies.
• Assess compatibility with the higher version’s OOTB features and identify necessary customizations.
• Develop migration plans for custom features, including potential redevelopment or adaptation to align with the new version’s framework.
• Implement a robust testing phase to ensure data integrity and functionality of custom features post-migration.

2. Inefficient resource allocation

Upgrading from a lower to a higher version of Liferay can be a time-consuming process due to several factors. The complexity of the upgrade often involves not just applying the update but also adapting existing configurations, customizations, and integrations to be compatible with the new version. Depending on the size of your system and the extent of custom features, this process can take significant time, potentially impacting daily business operations and leading to operational delays. 

How to avoid:

• Develop a comprehensive project plan that outlines each step of the upgrade process, including realistic timelines and key milestones. This plan should account for all stages of the upgrade, from preparation and testing to final deployment.
• Assign dedicated resources specifically for the upgrade project. This ensures that the migration team can focus on the task without being diverted by other responsibilities, reducing the risk of delays and ensuring that ongoing business operations are less affected.

3. Compatibility issues

Upgrading from a lower version of Liferay to a higher one can lead to compatibility issues due to changes in the platform’s features, architecture, or APIs. The new version may introduce enhancements, deprecate old features, or change how certain functionalities work. This can affect existing customizations, integrations with other systems, and third-party modules.

For instance, custom portlets or widgets developed for the older version might not work as expected if they rely on deprecated APIs or have not been updated to align with new standards. Additionally, integrations with external systems may need to be adjusted to ensure seamless communication with the updated version of Liferay.

How to avoid:

• Set up a staging environment to test existing customizations, third-party modules, and integrations with the new version. Identify and address any issues that arise during testing.
• Collaborate with Liferay support or a Liferay consulting company like Aimprosoft to get expert advice on addressing compatibility issues and ensuring a smooth transition.

4. Worsened performance

Upgrading to a higher version of Liferay can impact system performance if the new version introduces changes that affect how the system operates. For example, the new version may come with additional features, more demanding system requirements, or different architectural changes that could strain existing infrastructure. This can lead to slower response times, increased load times, or other performance-related issues if not properly managed.

The new version might also include updates that require reconfiguring settings or optimizing existing processes. If these adjustments are not made, suboptimal performance can result and potentially disrupt your business operations.

How to avoid:

• Thoroughly test the system’s performance both before and after the upgrade. This should include load testing, stress testing, and benchmarking to identify potential issues and ensure that it meets performance expectations.
• Review and adjust system configurations based on the new version’s requirements. This includes tuning the database, server settings, and application configurations to align with the updated version.
• Implement continuous monitoring tools to track performance metrics and quickly identify and address any performance degradation post-upgrade.

4. Underestimating complexity and scope

Underestimating the complexity and scope of upgrading Liferay versions can lead to significant issues, including inadequate planning and resource shortages. Upgrading requires a thorough understanding of the new version’s features, potential impacts on existing customizations, and integration points with other systems. If these aspects are not properly evaluated, it can lead to project delays, increased costs, and incomplete or problematic implementations.

How to avoid:

• Conduct an in-depth analysis of your current system, including customizations, integrations, and dependencies. Based on this analysis, define clear and detailed upgrade requirements. This will help you understand the full scope of the upgrade and identify any potential challenges.
• Ensure that adequate resources, including time, budget, and personnel, are allocated for the upgrade’s planning, execution, and risk management phases. Proper resource allocation helps address unexpected issues and ensures a smoother transition.

Wrapping up

Migrating to a higher version of Liferay is a strategic move that can significantly enhance your solution’s digital capabilities. By opting for the latest version, you not only benefit from advanced features, improved user experience, and robust security but also streamline development and customization processes. 

As you consider when and how to undertake this migration, remember that a well-planned upgrade will help you fully use Liferay’s evolving tools and innovations. If you need assistance with planning the migration or executing it securely, you can always contact us and choose our Liferay migration and upgrade services (including CMS to CMS migration, CMS upgrade, and others). Our certified Liferay developers will ensure your migration objectives are completed precisely.

FAQ