Upgrading Code to the new DXP version

Upgrading to the new DXP version involves migrating your installation and code (your custom apps) to the new version. You’ll learn how to upgrade your code in this section.

These tutorials assume you’re using the Liferay Upgrade Planner. To follow along with this section, install the planner and step through the upgrade instructions. You can also use the planner to upgrade your data; this is a separate process that must be done independently from the code upgrade process.

For convenience, this tutorial section also references documentation and outlined steps to aid those opting to upgrade their code manually.

Here are the code upgrade steps:

1. Upgrade Your Development Environment

   Legacy project environments should be upgraded to the latest version of Liferay Workspace to ensure you leverage all available features.

   1. Set Up Liferay Workspace

      A Liferay Workspace is a generated environment that is built to hold and manage your Liferay projects. Create/import a workspace to get started.

      1. Create New Liferay Workspace

         If you don’t have an existing 7.x Liferay Workspace, you must create one. Skip to the next step if you have an existing workspace.

      2. Import Existing Liferay Workspace

         Import an existing Liferay Workspace. If you don’t have one, revisit the previous step.

   2. Configure Liferay Workspace Settings

      Set the Liferay DXP version in workspace’s configuration you intend to upgrade to.

      1. Configure Workspace Product Key

         Configure your workspace by setting a product key.

      2. Initialize Server Bundle

         Download the Liferay DXP bundle you’re upgrading to.

      3. Migrate .cfg Files to .config Files

         Convert .cfg files to .config files.

2. Migrate Plugins SDK Projects

   Copy your Plugins SDK projects into workspace and convert them to Gradle/Maven projects.

   1. Import Existing Plugins SDK Projects

      Import your existing Plugins SDK projects.

   2. Migrate Existing Plugins to Workspace

      Migrate your existing plugins to workspace. This involves moving the plugin to workspace and converting it to the workspace’s build environment.

3. Upgrade Build Dependencies

   Optimize your workspace’s build environment for the most efficient code upgrade experience.

   1. Update Repository URL

      Update your repository URL to Liferay’s frequently updated CDN repository.

   2. Update Workspace Plugin Version

      Update your Workspace plugin version to leverage the latest features of Liferay Workspace.

   3. Remove Dependency Versions

      Remove the project’s dependency versions since it’s leveraging target platform.

4. Fix Upgrade Problems

   Fix common upgrade problems dealing with your project’s dependencies and breaking changes.

   1. Auto-Correct Upgrade Problems

      Auto-correct straightforward upgrade problems.

   2. Find Upgrade Problems

      Find upgrade problems. These are problems that cannot be auto-corrected; you can update them manually according to the breaking changes documentation.

   3. Resolve Upgrade Problems

      Mark upgrade problems as resolved after addressing them.

   4. Remove Problem Markers

      After fixing your upgrade problems, remove the problem markers.

   5. Resolving a Project’s Dependencies

   6. Resolving Breaking Changes

5. Upgrade Service Builder Services

   Upgrade your Liferay Service Builder services.

   1. Remove Legacy Files

      Remove legacy files that are no longer leveraged by Service Builder.

   2. Migrate from Spring DI to OSGi Declarative Services

      Leverage OSGi Declarative Services in your Service Builder project.

   3. Rebuild Services

      Rebuild your project’s services to persist your updates.

6. Upgrade Customization Plugins

   Upgrade your customization plugins so they’re deployable to the new DXP version.

   1. Upgrade Customization Modules

   2. Upgrade Core JSP Hooks

   3. Upgrade Portlet JSP Hooks

   4. Upgrade Service Wrapper Hooks

   5. Upgrade Core Language Key Hooks

   6. Upgrade Portlet Language Key Hooks

   7. Upgrade Model Listener Hooks

   8. Upgrade Event Action Hooks

   9. Upgrade Servlet Filter Hooks

   10. Upgrade Portal Properties Hooks

   11. Upgrade Struts Action Hooks

7. Upgrade Themes

   Upgrade your themes so they’re deployable to the new DXP version.

   1. Upgrade 6.2 Themes to 7.2

   2. Upgrade 7.0 Themes to 7.2

   3. Upgrade 7.1 Themes to 7.2

8. Upgrade Layout Templates

   Upgrade your layout templates so they’re deployable to the new DXP version.

9. Upgrade Frameworks & Features

   1. Upgrade JNDI Data Source Usage

      Use Liferay DXP’s class loader to access the app server’s JNDI API.

   2. Upgrade Service Builder Service Invocation

      For Service Builder logic remaining in a WAR, you must implement a service tracker to call services. For logic divided into OSGi modules, you can leverage Declarative Services.

   3. Upgrade Service Builder

      Adapt your app to account for Service Builder-specific changes.

   4. Migrate Off of Velocity Templates

      Velocity template usage is deprecated for the new DXP version. You should convert your template to FreeMarker.

10. Upgrade Portlets

    Upgrade your portlets so they’re deployable to the new DXP version.

    1. Upgrade Generic Portlets

    2. Upgrade Liferay MVC Portlets

    3. Upgrade JSF Portlets

    4. Upgrade Servlet-based Portlets

    5. Upgrading Spring Portlet MVC Portlets

    6. Upgrade Struts 1 Portlets

11. Upgrade Web Plugins

    Upgrade web plugins previously stored in the webs folder of your legacy Plugins SDK.

12. Upgrade Ext Plugins

    Attempt to leverage an extension point instead of upgrading your Ext plugin. If an Ext plugin is necessary, you must review all changes between the previous Liferay Portal instance you were using and the new DXP version, and then manually modify your Ext plugin to merge your changes with Liferay DXP’s.

Once you’ve finished the code upgrade steps, your custom apps will be compatible with the new DXP version!