Migrating From Liferay 6.2 to Digital Experience Platform (DXP)

Going digital in business is now the norm of the day with lean (and successful) startups leading the way, and conventional brick-and-mortar stores jumping on the bandwagon. Every decent business must have a website. But those who truly reap the benefits of going digital are organizations who stay ahead in terms of delivering unique, innovative and customer-friendly digital experiences. That’s where Liferay comes as a life saver – a Digital eXperience Platform that enables businesses to not just manage, but deliver consistent, connected and holistic customer experiences across mobile, desktop, kiosk and other touch points.

An upgrade to Liferay DXP is an important step in this direction, as it allows for significant changes and benefits over the existing version, that is, Liferay 6.2. Though the migration is easier said than done, this is a crucial investment to reap the full benefits of Liferay. A systematic approach such as the one outlined below can optimize the upgrade process:


The preparation stage involves setting a timeline and seeking answers to the following key questions to better manage risks while making major modifications to data, code or infrastructure:

What version am I on?

How much data do I have?

How much of my existing web content, templates and structures will I need to upgrade?

How many portlets will I need to upgrade?

Am I overriding many JSPs?

Do I have an EXT to upgrade?

Am I planning to convert to OSGi bundles?


The Liferay DXP compatibility matrix provides an easy way to test the compatibility of your environment, to ensure that you are running on a supported environment (and not one which has gone out of date) to receive continuous support. Currently, all app servers are JDK8 compatible on this matrix.

Secondly, configuring your search server is one of the most important changes with DXP. While Liferay DXP is configured to use an embedded Elasticsearch, it may not be supported by your production servers.

Thirdly, with the introduction of the OSGi container in Liferay DXP, a new deployment plan must be charted out in accordance with the way you would like to deploy your plugins. With DXP, it is recommended to use bundles/modules and WABs for new development and legacy applications respectively. On the contrary, it not recommended to use WARs because, although you can still access Liferay’s core services, access to services deployed to the OSGi container will be lost.

We have developed what we call the Cluster Deployment Helper which is a tool to bundle any number of files into a WAR, which are in turn, copied into Liferay’s deploy folder. The WAR then uninstalls itself and can be used with any app server administration tool.


The next step is to ensure a proper backup in case of any failures, applying all database indexes correctly and disabling search indexing to avoid any issues and slowdowns during this process. The data upgrade then involves: a) the core upgrade which is similar to how it was in the past, and b) upgrading the OSGi modules.


Crucial to this step is knowing what’s changed in DXP. Broadly speaking, the chronological list of changes that break existing functionality, APIs or contracts with third-party Liferay developers or users are:

  • Functionality that is removed or replaced.
  • API incompatibilities – Changes to public Java or JavaScript APIs.
  • Changes to context variables available to templates.
  • Changes in CSS classes available toLiferay themes and portlets.
  • Configuration changes – Changes in configuration files, like portal.properties, system.properties, etc.
  • Execution requirements – Java version, J2EE Version, browser versions, etc.
  • Deprecations or end of support – For example, warning that a certain feature or API will be dropped in an upcoming version.
  • Recommendations – For example, recommending using a newly introduced API that replaces an old API, in spite of the old API being kept in Liferay for backwards compatibility.

Although there are limitations, you can use the Plugins SDK for Liferay DXP. However, we recommend moving to our latest project structure called Liferay Workspace, as it not only takes full advantage of the new theme tooling in Liferay DXP, but also integrates with Liferay Developer Studio. A new command line tool called Blade allows for creation of applications, extensions, etc. similar to how it was done in a Plugins SDK, but withan added feature – automatic deployment of projects as changes are made.

Migrating a 6.2 WAR to a Liferay DXP-supported WAR

It is important to update a 6.2 portlet to a Liferay DXP portlet, even if you plan to convert your portlet to OSGi modules, otherwise debugging and troubleshooting will be marred by confusions as to which issues are related to API changes and which ones to the migration process. After readying the DXP supported WAR, you’ll need to decide whether or not to convert your portlet into an OSGi module. This decision is based on a number of factors such as application size, type of plugin and legacy web framework/application.

Leave a comment