Migrating Data Upgrade Processes to the New Framework for Modules

When you make database changes to your application, you must use a data upgrade process to migrate users’ existing data to the new database schema. While the old framework required several classes, the new framework can orchestrate the upgrade steps from a single class. Managing the steps from one class facilitates developing upgrade processes. The data upgrade framework you use depends on your development framework. This tutorial shows you how to migrate to the new framework.

  • If your upgraded plugin is a traditional WAR, you don’t need to do anything special; existing upgrade processes adapted to Liferay DXP 7.1’s API work as is. The new data upgrade framework is for modules only.

  • If you converted your upgraded plugin to a module or you have an upgraded module, you must migrate any upgrade processes you want to continue using to the new data upgrade framework.

You can migrate any number of old upgrade processes (starting with the most recent ones) to the new framework. For example, if your module has versions 1.0, 1.1, 1.2, and 1.3, but you only expect customers on versions 1.2 and newer to upgrade, you might migrate upgrade processes for versions 1.2 and 1.3 only.

Before beginning, make sure you know how to create an upgrade process that uses the new framework.

First, you’ll review how Liferay Portal 6 upgrade processes work.

Understanding Liferay Portal 6 Upgrade Processes

Before getting started, it’s important to understand how Liferay Portal 6 upgrade processes are structured. As an example, you’ll use the Liferay Portal 6.2 upgrade process for the Knowledge Base Portlet.

In Liferay Portal 6 upgrade processes, the upgrade step classes for each schema version are in folders named after their schema version. For example, the Knowledge Base Portlet’s upgrade step classes are in folders named v1_0_0, v1_1_0, v1_2_0, and so on. Each upgrade step class extends UpgradeProcess and overrides the doUpgrade method. The code in doUpgrade performs the upgrade. For example, the Knowledge Base Portlet’s v1_0_0/UpgradeRatingsEntry upgrade step extends UpgradeProcess and performs the upgrade via the updateRatingsEntries() call in its doUpgrade method:

public class UpgradeRatingsEntry extends UpgradeProcess {

    protected void doUpgrade() throws Exception {


    protected void updateRatingsEntries() throws Exception {
        // Upgrade code



The upgrade process classes are on the same level as the folders containing the upgrade steps and are also named after their schema version. For example, the Knowledge Base Portlet’s upgrade process classes are named UpgradeProcess_1_0_0, UpgradeProcess_1_1_0, UpgradeProcess_1_2_0, and so on. Each upgrade process class also extends UpgradeProcess and runs the upgrade process in the doUpgrade method. It runs the upgrade process by passing the appropriate upgrade step to the upgrade method. For example, the doUpgrade method in the Knowledge Base Portlet’s UpgradeProcess_1_0_0 class runs the upgrade steps UpgradeRatingsEntry and UpgradeRatingsStats via the upgrade method:

protected void doUpgrade() throws Exception {

Now that you know how Liferay Portal 6 upgrade processes are defined, you’ll learn how to convert them to the new upgrade process framework in Liferay DXP 7.1.

Converting your Liferay Portal 6 Upgrade Process to Liferay DXP 7.1

So how do Liferay Portal 6 upgrade processes compare to those that use the new upgrade process framework? First, the upgrade step classes are the same, so you can leave them unchanged. Here are the big changes in the new upgrade processes:

Start your conversion by creating a registrator class.

Create a Registrator Class

The new data upgrade framework requires using registrator class instead of upgrade process classes. You must combine your upgrade process classes’ functionality into a single registrator class. Recall from the data upgrade process tutorial that registrators define an upgrade process that the upgrade process framework executes. Each registry.register call in the registrator registers the appropriate upgrade steps for each schema version. You must therefore transfer the functionality of your old upgrade process classes’ doUpgrade methods into a registrator’s registry.register calls.

For example, click here to see the Knowledge Base Portlet’s new Liferay DXP 7.1 upgrade process in GitHub.

Besides some additional upgrade step classes to handle changes made to the portlet for Liferay DXP 7.1, the only difference in this upgrade process is that it contains a single registrator class, KnowledgeBaseServiceUpgrade, instead of multiple upgrade process classes. The KnowledgeBaseServiceUpgrade class, like all registrators, calls the appropriate upgrade steps for each schema version in its registry.register calls. For example, the first registry.register call registers the upgrade process for the 1.0.0 schema version:

        "com.liferay.knowledge.base.service", "0.0.1", "1.0.0",
        new com.liferay.knowledge.base.internal.upgrade.v1_0_0.
        new com.liferay.knowledge.base.internal.upgrade.v1_0_0.

Compare this to the above doUpgrade method from the corresponding Liferay Portal 6 upgrade process class UpgradeProcess_1_0_0. Both call the same upgrade steps.

Next, create a Bundle Activator if your modularized plugin uses Service Builder.

Create a Bundle Activator

If your module implements Service Builder services, it needs a Bundle Activator to initialize a record in the release table. Creating a Bundle Activator is straightforward.

That’s it! For instructions on creating new upgrade processes for Liferay DXP 7.1, including complete steps on creating a registrator, click here.

Creating Data Upgrade Processes for Modules

Upgrading Plugins to Liferay DXP 7.1

From Liferay Portal 6 to 7

« Building Your Application's Module JARs for DeploymentIntroduction to From Liferay DXP 7.0 to 7.1 »
Was this article helpful?
0 out of 0 found this helpful