« Back

How to Upgrade to Liferay 7.0+

General Blogs February 23, 2018 By David H Nebinger

So the question comes up how to do Liferay upgrades.

I'm not talking here about the technical details of how you upgrade one particular plugin to another type of plugin, what kinds of API changes have to be made, etc.

Instead, I'm thinking more about the general process of how to upgrade, what choices you're presented with and what the ramifications are for making certain choices.

Upgrades Are Projects

The first thing to remember is that upgrades are projects. You should totally build them out as projects, you should have a project plan, you should have a project team, ... Having a full project plan forces you to define scope for the upgrade and time box all activities so you will know how the project is proceeding.

As a project, you also should have a risk assessment/mitigation plan. Know in advance what you will do if the project runs long or runs into issues. Will you just stretch the timeline? Will you seek help from Liferay GS or a Liferay Partner? Are you sending your development team to Liferay training in advance or only if they seem to struggle? Will you rely on LESA tickets, Liferay documentation, community support via the forums or slack?

Liferay GS offers an Upgrade Assessment package where an experienced Liferay GS consultant will come onsite to review your environment and build a customized report outlining what your upgrade effort will be. This assessment can become the foundation of your project planning and can help set your upgrade in the right direction.

Upgrades Have Scopes

Upgrading from Liferay 6.2 to Liferay DXP 7.1, there will be scope to this project and the project is susceptible to scope creep.

For example, you might decide going in that your project is simply to get what you currently have migrated and running under DXP. During the upgrade project, though, you might decide to add some backlogged features or refactor your codebase or rework legacy portlet wars into OSGi portlet modules. Each of these things would be considered scope creep. Each change like these that the team takes on will negatively impact your project plan and schedule.

Upgrades Expose Bad Practices

The one thing I've found is that upgrades tend to expose bad practices. This could be bad practices such as using an ORM package instead of Service Builder for data access. It could be a non-standard way of decoupling code such as making all service calls via remote web services where a local service implementation would have been an easier path. It can expose when standard design practices such as design by interface were not fully leveraged. It could be as simple as having used an EXT plugin to do something that should have been handled by a JSP hook or a separate custom implementation.

Exposing bad practices may not seem very important, but upgrading bad practices will always add to a project plan. Something done initially as a shortcut or a hack, these things get difficult to carry forward in an upgrade.

The one thing I've found in 10+ years of experience with Liferay, it is often better to do things "The Liferay Way". It is not always easy and may not seem like the right way, but it usually ends up being the better way generally to develop for the platform.

Upgrade Project Recommendations

To facilitate your upgrade project, I offer the following recommendations:

  • Limit scope. As far as the upgrade is concerned, limit the project scope to getting what you currently have running under the later version. Do not consider refactoring code, do not consider reworking portlet wars as OSGi modules, etc. Limit the scope to just get on the new version. If you want to refactor or rework wars as OSGi modules, save that for a later project or phase.


  • Leave portlet wars as portlet wars. I can't say this strongly enough. It is absolutely not necessary for your legacy portlet wars to be refactored as OSGi modules. Your legacy portlet wars can be deployed to DXP (after necessary API changes) and they will automagically be converted into an OSGi WAB for you. Do not spend your upgrade cycles reworking these into OSGi bundles yourself, it is a complete waste of your time and effort.


  • Only rework what you have to rework. You'll have to touch legacy hooks and EXT plugins, there is no way around that. But that is where your upgrade cycles need to be spent. So spend them there.


  • Rethink upgrading bad practices. I know, I said limit scope and migrate what you have. The one exception I make to this rule is if you have exposed some really bad practices. In the long run, it can often be a smaller level of effort to rework the code to eliminate the bad practice first or as part of the upgrade. Cleaner code is easier than spaghetti to upgrade.


  • Use Liferay IDE tooling. The Liferay IDE comes with a built-in upgrade assistant tool. While the tool is not perfect, it can help you upgrade your Maven and Plugin SDK projects to be compatible with the later version, including suggesting and making necessary API changes for you. If you do not use the upgrade assistant, you are willfullly missing out on an automated way to start your upgrade.


  • Have a Backup Plan. Know in advance if you are going to leverage Liferay GS or a Liferay Partner to help complete your upgrade in case you are seeing delays. If you wait until you are behind the eight-ball before mitigating your risk, you will be less prepared to get the project back on track if it is going off the rails.


  • Get a Liferay Upgrade Assessment Package. Even if you are going to do all of the work in house, an upgrade assessment can highlight all of the aspects you and your team will need to consider.

That's pretty much it.  Have any horror stories or suggestions you'd like to share? Please add them below...

Threaded Replies Author Date
+1 to "Leave portlet wars as portlet wars." :-D Jorge Díaz February 27, 2018 1:30 AM

+1 to "Leave portlet wars as portlet wars." :-D
Posted on 2/27/18 1:30 AM.