Liferay migration 6.2 to 7.1

Liferay migration.  Real examples. Step-by-step instructions. Screens and code snippets. Best practices. 

Vitaliy Koshelenko
Vitaliy Koshelenko
8 Minute Read

Introduction

 
In this blog I'll describe how to migrate data and code from Liferay 6.2 to 7.1.

Blog overview:

I. Prerequisites - description of demo project and data/content to be migrated.
II. Prepare for migration - recommendations for Liferay 6.2 preparation for migration, Liferay 7.1 installation/configuration, tools and instruments to use for migration.
III. Database migration - steps and advises for database migration.
IV. Code migration - steps and advises for database migration.
V. Post migration issues - steps required after migration completed.
VI. Common errors during migration - possible errors, which may occur during migration process, and solutions to fix them.
 
If you need to migrate to 6.2 - see also my previous post:

I. Prerequisites

For Liferay migration to 7.1 I have created a demo project (with custom theme, layout, portlet and hook), and also configured a set of pages and web contents on portal.

Original 6.2 code is available in repository: https://bitbucket.org/aimprosoft/liferay-migration-6.2-ce-ga4

Below is description of modules to be migrated:

  • aimprosoft-portlet - custom portlet for displaying a list of web contents, documents, wiki pages, documents and blogs from the portal;
  • aimprosoft-theme - custom theme (based on classic one) with 2 color schemes (orange and blue) and 2 theme settings ('split-dockbar' and 'navigation-enabled');
  • 1-3-column-layouttpl - custom layout;
  • aimprosoft-hook - JSP hook for sign in portlet to display greeting message.
Web content structures list:
  • "Technology", fields: "header", "logo", "description"
  • "Portfolio", fields: "header", "icon", "description", "link"
Portal pages list below.

Public pages:

1. Welcome:


2. Portfolio


3. Technologies



Private pages:

1. Wiki


2. Forum


3. Blog


4. Content Viewer

 

II. Prepare for migration

Liferay 6.2 adjustments before migration.

Remove unused objects

To speed up migration process, and also to increase the performance of portal after migration - we need to remove unused objects (for example, Layouts, Users, Documents, etc.). Also we need to remove intermediate versions for web contents and documents. For example, if we have updated web content 3 times - we have 4 different versions:



, but we need only the latest one (1.3). Three previous ones can be removed.

Remove duplicated structure names

If you have different web content structures in your portal - there is possibility, that different structured have fields with the same name. It's OK for Liferay 6.2, but migration to 7.x will fail.

Thus, we need to rename structure fields, so they are unique overall the portal.
 

Liferay 7.1 installation/configuration

First of all, download Liferay 7.1:

https://sourceforge.net/projects/lportal/files/Liferay%20Portal/7.1.0%20GA1/



You may also download Liferay sources here.
Unpack Liferay archive, but do not start it for now.
 

Tools/instruments 

There are different tools/plugins to work with Liferay 7.x. It depends on which IDE you work with, which tool to use.
Personally I prefer Intellij IDEA.  If you use IDEA also - you can install Liferay IntelliJ Plugin for it.
It allows you to setup Liferay worskspace, configure Liferay server, create different modules from templates, deploy them, etc.

For those ones, who work in Eclipse - there is Liferay Developer Studio and Liferay IDE. Although I'm not a fan of Eclipse, need to admin that it has better integration with Liferay and more opportunities, even for code migration process. Will touch this topic later.

III. Database migration

Prepare database for migration

Create a separate database for migration in MySQL:
 

create database lr_migration_dxp character set utf8;

Create a database dump from 6.2 database and load it to new one:

  
mysqldump -uroot -p1 lr_migration > lr_migration.sql 
mysql -uroot -p1 lr_migration_dxp < lr_migration.sql
 

Specify database connection properties 

Create file 'portal-setup-wizard.properties' with the DB connection properties inside:

jdbc.default.driverClassName=com.mysql.jdbc.Driver
jdbc.default.url=jdbc:mysql://localhost:3306/lr_migration_dxp
jdbc.default.username=root
jdbc.default.password=1

Note: DO NOT START Liferay instance right now. Otherwise, you'll get error like this:

2018-09-26 13:44:57.402 ERROR [main][MainServlet:273] java.lang.RuntimeException:
You must first upgrade to Liferay Portal 7100
java.lang.RuntimeException:
You must first upgrade to Liferay Portal 7100
at com.liferay.portal.tools.DBUpgrader.checkRequiredBuildNumber(DBUpgrader.java:87)

(see errors list in the end)

 

Copy data

Copy document_library and images folders inside data folder from liferay 6.2 to liferay 7.1 to transfer document library files to new environment. 
 

Disable indexer and autoUpgrade:

Add file com.liferay.portal.search.configuration.IndexStatusManagerConfiguration.config to  [Liferay Home]/osgi/configs with content: 
indexReadOnly="true"
Add file  com.liferay.portal.upgrade.internal.configuration.ReleaseManagerConfiguration.config to  [Liferay Home]/osgi/configs with content: 
autoUpgrade="false"
 

Configure upgrade tool

Unlike previous Liferay versions, where we had just to specify database configuration properties, and Liferay performed upgrade process during startup, Liferay 7.x comes with dedicated tool for database upgrade - 'portal-tools-db-upgrade-client' in LR/tools folder.
We need to configure the following files before running the upgrade:
 

Check release build number:


(it should be 62xx before you run the upgrade)

Run upgrade tool:

./db_upgrade.sh -l "db_upgrade.log"

This will update Liferay core, and output this message after finishing:



After this run

upgrade:executeAll

command in appeared Gogo Shell.

After updating all the modules - appropriate message will appear:
 

Verify build number to ensure portal has been updated:

 

Enable indexer 

Modify file

com.liferay.portal.search.configuration.IndexStatusManagerConfiguration.config in  [Liferay Home]/osgi/configs with content: 
indexReadOnly="false"
 

Start Liferay

Start Liferay and ensure, that database has been updated successfully. Code migration will take place in next chapter.

Database migration should be finished at this point.

 

Migration process automation

Although there is not to much steps to perform the migration - it still requires a lot of manual work with configuration files, creation/restore dumps, copying files, etc. And if there are any errors during migration - you need to perform all these actions again and again from the beginning.

To automate this process I have created a bash script, which performs all the actions above. It's available here:

https://bitbucket.org/aimprosoft/liferay-migration-ce-7.1.0-ga1/src/master/scripts/migrate.sh

You just need to specify your properties:

######## Properties ################

#MySQL
db_user=root
db_password=1

#LR 6.2
lr62_path=/home/vitaliy/Work/Liferay/migration/liferay-6.2-ce-ga4/liferay-portal-6.2-ce-ga4
lr62_db_name=lr_migration

#LR 7.1
lr71_path=/home/vitaliy/Work/Liferay/migration/liferay-ce-7.1.0-ga1
lr71_archive=liferay-ce-portal-tomcat-7.1.0-ga1-20180703012531655.zip
lr71_dir=liferay-ce-portal-7.1.0-ga1
lr71_db_name=lr_migration_dxp

and run the script

./migrate.sh

After finishing script database and data should be already migrated. You can start your Liferay 7.1 instance and check the results.

In my case here they are:

Although there is still no custom theme, layout, hook changes - all the data (pages, content, etc.) is in place, and we can start with code migration.

IV. Code migration

For code migration you need to setup project environment. I use IntelliJ IDEA IDE with Liferay IntelliJ Plugin, Liferay 7.1 bundled with tomcat, Maven for assembling, and MySQL as database. All the instructions below are relevant for this stack. 
 

IDE setup

Create new Liferay project, using Liferay Maven Plugin:

The following structure should appear:

Configure Liferay server in IDE:

 
Now you can start Liferay 7.1 portal from IDE.
 
 

Theme migration

Before starting theme migration, we need to consider the main points, which had changed in Liferay 7.1:
  • Velocity templates are no longer supported in favor of FreeMarker;
  • Dockbar has been replaced with different menus: Product Menu, Control Menu, User Personal Bar.
Ways to update theme:
1. Run Gulp upgrade task to upgrade theme
  
yo liferay-theme:import
Note: this way works only for themes, created with Ant-base Liferay plugin SDK.
Otherwise, such exception will apeear:
 
2. Use Liferay IDE's Code Upgrade Tool:
While upgrade tool automates the migrations process - there are still restrictions for theme structure.
 
3. Manual theme creation and code transfer.
Although it's not automatic process, and needs some efforts - sometimes it's easier to create theme from scratch in 7.1, and apply appropriate styling from 6.2, considering changes in Liferay between those versions.
So, create new theme using Liferay plugin:
Empty, but working theme will be created. After this we can apply changes from 6.2 theme considering changes in 7.1.
As in 6.2, we can also use classic theme as example, and overwrite required sections (ftl templates, css files, etc.)
 
 
 
 
 
 

Portlet migration

For portlet code migration we can use Code Upgrade Tool within Liferay Developer Studio (Project -> Liferay Code Upgrade Tool menu). After importing project we can click "Find breaking changes" button, and a list of code problems will appear:
 
 
Each of them contains API changes explanation, which affect custom code, reasons for it, links to Liferay JIRA tickets, examples and recommendations to fix code issues. Some of code problems can be fixed automatically using Liferay IDE, other ones need manual actions.
After fixing all the issues, you can try to build the portlet for Liferay 7.1.
If you work in IntelliJ IDEA - you can copy migrated code to it from Liferay IDE.
 
 

Hook migration

For hook migration (especially for JSP hooks) it's better to create hook module from scratch, and overwrite the required JSP page. As Liferay's JSP pages have changed significantly from Liferay 6.x to 7.x, using old 6.2 JSP pages for new 7.1 Liferay may break some functionality. 

So, you need to create a hook module, find appropriate JSP, and overwrite it in hook, copying changes from 6.2.

To find what exactly was  changed in hook, you can compare 2 JSP files in your Liferay 6.2 instance - xxx.jsp (hooked one) and xxx.portal.jsp (original one). In my example:

Then just apply these changes to your Liferay 7.1 page and deploy the hook. 

 

Layout migration

For layout migration we can create a new layout with Liferay IntelliJ plugin:
 
After that we can adjust FTL template according to the 6.2 code, for example:
Also change icon for layout, deploy layout, and use it.
 
 

V. Post-migration issues.

 

After migration to 7.1 make sure, indexer is enabled. Modify file

com.liferay.portal.search.configuration.IndexStatusManagerConfiguration.config in  [Liferay Home]/osgi/configs with content: 
indexReadOnly="false"

 

Also you need to setup a standalone Elasticsearch instance. Default embedded one can be used for local development, bit not for production. See instructions here:

https://dev.liferay.com/en/discover/deployment/-/knowledge_base/7-1/installing-elasticsearch 

 

VI. Common errors during migration.

Here is a list of errors, which may occur during migration to 7.1

 

1. You must first upgrade to Liferay Portal 7100

Name java.lang.NullPointerException at com.liferay.portal.events.ThemeServicePreAction
   
StackTrace 
    
ERROR [main][MainServlet:273] java.lang.RuntimeException:  You must first upgrade to Liferay Portal 7100
    at com.liferay.portal.tools.DBUpgrader.checkRequiredBuildNumber(DBUpgrader.java:87)
Description Exception is thrown, when Liferay 7.x is started with 6.x database before running upgrade tool 
Fix Run upgrade tool before starting Liferay 7

 

2.  NullPointer, when upgrading DDM.

Name com.liferay.portal.kernel.upgrade.UpgradeException: java.lang.NullPointerException
StackTrace 
com.liferay.portal.kernel.upgrade.UpgradeException: java.lang.NullPointerException
   at com.liferay.portal.kernel.upgrade.UpgradeProcess.upgrade(UpgradeProcess.java:97)
   at com.liferay.portal.kernel.upgrade.UpgradeProcess.upgrade(UpgradeProcess.java:134)
   ...
Caused by: java.lang.NullPointerException
   at com.liferay.dynamic.data.mapping.internal.upgrade.v1_1_2.UpgradeDynamicDataMapping$SelectDDMFormFieldValueTransformer.transform(UpgradeDynamicDataMapping.java:356)
   at com.liferay.dynamic.data.mapping.util.DDMFormValuesTransformer.performTransformation(DDMFormValuesTransformer.java:58)
   at com.liferay.dynamic.data.mapping.util.DDMFormValuesTransformer.traverse(DDMFormValuesTransformer.java:78)
    ...
Description Exception is thrown when there are orphaned templates (w/o structures)
Fix Delete such templates in 6.2 before migration to 7.1, run verification process for DDM in 6.2
LPS

https://issues.liferay.com/browse/LPS-73485 , https://issues.liferay.com/browse/LPS-69800 , https://issues.liferay.com/browse/LPS-69921

If issue still exists after migration - you can prevent the NPE, if you start Liferay from IDEA in debug mode, then run upgrade process from Felix Gogo Shell, and change the value in evaluator:

 


 

3.  NullPointer, when missing theme.

Name java.lang.NullPointerException at com.liferay.portal.events.ThemeServicePreAction
Screen
StackTrace 
com.liferay.portal.kernel.events.ActionException: java.lang.NullPointerException
   at com.liferay.portal.events.ThemeServicePreAction.run(ThemeServicePreAction.java:46)
   at com.liferay.portal.kernel.events.Action.processLifecycleEvent(Action.java:34)
   at java.lang.Thread.run(Thread.java:748)
   ... 
Caused by: java.lang.NullPointerException
   at com.liferay.portal.model.impl.LayoutImpl.getColorScheme(LayoutImpl.java:358)
   at com.liferay.portal.events.ThemeServicePreAction.servicePre(ThemeServicePreAction.java:72)
   at com.liferay.portal.events.ThemeServicePreAction.run(ThemeServicePreAction.java:43)
   ... 113 more
Description Null pointer is thrown, when there is missing theme
Fix Deploy missing theme

 

 

4.  PwdEncryptorException: invalid keyLength value

Name PwdEncryptorException: invalid keyLength value
StackTrace 
com.liferay.portal.kernel.exception.PwdEncryptorException: invalid keyLength value
com.liferay.portal.kernel.exception.PwdEncryptorException: invalid keyLength value
    at com.liferay.portal.security.pwd.PBKDF2PasswordEncryptor.encrypt(PBKDF2PasswordEncryptor.java:90)
    at com.liferay.portal.security.pwd.CompositePasswordEncryptor.encrypt(CompositePasswordEncryptor.java:51)
    at com.liferay.portal.kernel.security.pwd.PasswordEncryptorUtil.encrypt(PasswordEncryptorUtil.java:74)
    at com.liferay.portal.security.pwd.PwdAuthenticator.authenticate(PwdAuthenticator.java:44)
    at com.liferay.portal.service.impl.UserLocalServiceImpl.authenticate(UserLocalServiceImpl.java:5789)
    at com.liferay.portal.service.impl.UserLocalServiceImpl.authenticateByEmailAddress(UserLocalServiceImpl.java:1255)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
Description Exception is thrown when there is specified incorrect password encryption algorithm 
Fix

Add this property

passwords.encryption.algorithm.legacy=SHA

into portal-setup-wizard.properties file.
   

 

See full article at: 

https://www.aimprosoft.com/blog/liferay-migration-6-2-to-7-1-comprehensive-guide

 

Vitaliy

 

Page Comments

Related Assets...

No Results Found

More Blog Entries...

Ben Turner
October 21, 2025
Michael Wall
October 14, 2025
YOGESH CHANDRA
October 08, 2025