(888) 685-3101 ext. 2

Liferay released its latest DXP 7.1 in Q2 2018; this release comes with a wide array of new features and updates designed to put more useful tools in the hands of users. You can find out more about new features in DXP 7.1 from this excellent blog Top New Features in Liferay 7.1.

In this article, we will upgrade our existing portal on Liferay DXP 7.0 to 7.1. In order to do that, we will break down the tasks into 6 broad categories:

  1. Prerequisites before the upgrade
  2. Setup Liferay DXP 7.1
  3. Upgrading the Portal Database
  4. Upgrading the Theme
  5. Upgrading Application Display Templates
  6. Upgrading Plugins i.e. upgrading portlets, jsp overrides, Liferay rest extenders etc

1. Prerequisites before the Upgrade

Take a backup of your production portal database and the Liferay document_library folder. Never run the Liferay DB upgrade tool directly against your production database! Once you have taken the backup, the best practice to follow would be to create a new schema, load the back up into the newly created schema, and use that schema to run the upgrade. Download the latest version of Liferay DXP 7.0 bundle, point this temporary installation to the new schema and the backed up document_library folder, and then start the server. This step is needed to verify that the database backup that we took is a working version, and that no problems occurred while taking the backup. Also, make sure you have the latest fix pack installed in your Liferay Server before proceeding ahead.

2. Setup Liferay DXP 7.1

Download the latest version of Liferay DXP 7.1 from the Liferay Customer Portal. Make sure you have the most recent version of the JDK 8 installed on your machine. Unpack Liferay DXP 7.1 and point it to the new schema with the database dump we created in the last step. Take the portal-ext.properties from your old Liferay DXP 7.0, and put it in the <liferay-home> folder. Take document_library folder dump from 7.0 and put it in your <liferay-home>/data folder. Note that if you start your 7.1 servers now, you will get an error on your server logs saying that the Release_ table contains data for an older version of Liferay.

3. Upgrading the Portal Database

In your Liferay DXP 7.1 you will find a directory named portal-tools-db-upgrade-client inside of the <liferay-home>/tools folder. One thing you can do before running the DB upgrade tool is to delete any unnecessary data from the tables; smaller tables mean a quicker and easier update process. Before we proceed, we need to set up 3 properties files:

  1. app-server.properties: This file contains details about the app server.
  2. dir=<liferay-home>/tomcat-9.0.6
    extra.lib.dirs=/bin
    global.lib.dir=/lib
    portal.dir=/webapps/ROOT
    server.detector.server.id=tomcat

    Table 3.0: Entries in app-server.properties

    If you are running a different app server, you can find the relevant entries for your app server in the default app-server.properties file in the DB upgrade tool directory.

  3. portal-upgrade-database.properties: This file contains details about the database schema that the tool will try to upgrade to 7.1.
  4. jdbc.default.driverClassName=com.mysql.jdbc.Driver
    jdbc.default.url= <jdbc-url>
    jdbc.default.username=*******
    jdbc.default.password=*******

    Table 3.1: Entries in portal-upgrade-database.properties

  5. portal-upgrade-ext.properties: This file contains the Liferay home directory path
  6. liferay.home=<liferay-home>

    Table 3.2: Entries in portal-upgrade-ext.properties

Once you have set up the 3 properties files, you can go ahead and run the DB upgrade tool using the .bat file in windows or .sh file in Linux environment. While the tool runs, it will log both success and error messages so you will be aware of what is going on. You can find a lot more details about the DB upgrade tool on Liferay Developer Site.

Once the DB upgrade tool finishes, start your Liferay DXP 7.1 server. If any issue occurs during Liferay startup, delete the database schema, delete the bundle, and restart the upgrade process by creating a new schema as mentioned in the Prerequisites step. This time, make sure that you have the latest fix pack for Liferay DXP 7.0 before proceeding forward. If it fails again, try disabling the Non Core Modules auto upgrade steps. Once the upgrade is successful, start the server. You should be able to access all your sites, users and contents. Finally, you should be certain to reindex the contents of the site in the portal search indexes after the upgrade process and validation has been completed.

4. Upgrading Theme

In order to upgrade a theme for use on Liferay DXP 7.1, one should follow this tutorial on Liferay developer site. It lists all the required steps in order to get your theme up and running on 7.1. If your theme was created using the Liferay Theme generator, then you can easily upgrade it using the command gulp upgrade; before running the upgrade, make sure you are using the latest version of liferay-theme-tasks. You can obviously upgrade the theme tasks by running npm install liferay-theme-tasks@8.0.0-beta.5 –save in your themes folder (8.0.0-beta.5 was the latest version of liferay-theme-tasks when this blog was written).

5. Upgrading Application Display Templates

With Liferay 7.1, Liferay has changed the way Documents and Media references are stored in Web Content Articles. For Liferay DXP 7.0, the content XML for a web content article containing a Documents and Media structure field in the journalArticle table would look like the following:

<?xml version="1.0"?>

<root available-locales="en_US" default-locale="en_US">
	<dynamic-element name="LargeImage" type="document_library" index-type="keyword" instance-id="wezd">
		<dynamic-content language-id="en_US"><![CDATA[/documents/27215/0/processes_v1-2.jpg/46d8cd2b-e076-aee2-b8b2-ebdb946d25b6?t=1517857043378]]></dynamic-content>
	</dynamic-element>
	<dynamic-element name="Title" type="text" index-type="keyword" instance-id="pmdg">
		<dynamic-content language-id="en_US"><![CDATA[Continuing Education]]></dynamic-content>
	</dynamic-element>
	<dynamic-element name="Body" type="text_box" index-type="text" instance-id="fkmj">
		<dynamic-content language-id="en_US"><![CDATA[Continuing Education]]></dynamic-content>
	</dynamic-element>
	<dynamic-element name="LinkURL" type="text" index-type="keyword" instance-id="fugv">
		<dynamic-content language-id="en_US"><![CDATA[#]]></dynamic-content>
	</dynamic-element>
	<dynamic-element name="LinkText" type="text" index-type="keyword" instance-id="tbpa">
		<dynamic-content language-id="en_US"><![CDATA[Learn More]]></dynamic-content>
	</dynamic-element>
</root>

Fig 5.1 Web Content XML Liferay DXP 7.0

As you can see from the highlighted lines in the figure above, the dynamic-content reference is a Relative URL which points to the document; you can put that Relative URL in an img tag source or an anchor tag href in your ADT, and the document will be displayed as expected. In Liferay 7.1, though, they have updated the way that this reference is stored in the database.

<?xml version="1.0"?>

<root available-locales="en_US" default-locale="en_US">
	<dynamic-element name="LargeImage" type="document_library" index-type="keyword" instance-id="wezd">
		<dynamic-content language-id="en_US"><![CDATA[{"groupId":"27215","title":"processes_v1-2.jpg","type":"document","uuid":"46d8cd2b-e076-aee2-b8b2-ebdb946d25b6"}]]></dynamic-content>
	</dynamic-element>
	<dynamic-element name="Title" type="text" index-type="keyword" instance-id="pmdg">
		<dynamic-content language-id="en_US"><![CDATA[Continuing Education]]></dynamic-content>
	</dynamic-element>
	<dynamic-element name="Body" type="text_box" index-type="text" instance-id="fkmj">
		<dynamic-content language-id="en_US"><![CDATA[Continuing Education]]></dynamic-content>
	</dynamic-element>
	<dynamic-element name="LinkURL" type="text" index-type="keyword" instance-id="fugv">
		<dynamic-content language-id="en_US"><![CDATA[#]]></dynamic-content>
	</dynamic-element>
	<dynamic-element name="LinkText" type="text" index-type="keyword" instance-id="tbpa">
		<dynamic-content language-id="en_US"><![CDATA[Learn More]]></dynamic-content>
	</dynamic-element>
</root>

Fig 5.2 Web Content XML Liferay DXP 7.1

As you can see, the new storage format utilizes a JSON object rather than a relative link. So, in your ADT, you cannot use the CDATA value directly anymore; the figure below illustrates a reference ADT implementation using the new storage scheme:

<#assign color_scheme = themeDisplay.getColorScheme().getCssClass()>
<#assign dlAppLocalServiceUtil = staticUtil["com.liferay.document.library.kernel.service.DLAppLocalServiceUtil"] >
<#assign dlUtil = staticUtil["com.liferay.document.library.kernel.util.DLUtil"] >
<#assign 
    Image       = ""
    Title       = ""
    Tagline     = ""
    LinkURL     = ""
    LinkText    = ""
>
<div class="wrapper wrapper--media">
    <div class="container-block">
        <div class="carousel" data-carousel="hero">
            <#if entries?has_content>
                <#list entries as curEntry>
                    <#assign renderer = curEntry.getAssetRenderer()>
                    <#assign className = renderer.getClassName()>
                    <#assign journalArticle = renderer.getArticle()>
                    <#assign document = saxReaderUtil.read(journalArticle.getContentByLocale(locale))>
                    <#assign rootElement = document.getRootElement()>
                    <#assign imageJson = document.valueOf("//dynamic-element[@name='Image']/dynamic-content/text()")>
		<#if imageJson?has_content>
		  <#assign imageJson = imageJson
                               uuid = imageJson.uuid
	                   groupId = imageJson.groupId 
	                   dlFile = dlAppLocalServiceUtil.getFileEntryByUuidAndGroupId(uuid,groupId?number)
			Image =  dlUtil.getPreviewURL(dlFile, dlFile.getFileVersion(),themeDisplay,'')
                      >
	     </#if> 
                    <#assign TitlexPathSelector = saxReaderUtil.createXPath( "dynamic-element[@name='Title']")>
                    <#assign Title = TitlexPathSelector.selectSingleNode(rootElement).getStringValue()>
                    <#assign LinkURLxPathSelector   = saxReaderUtil.createXPath( "dynamic-element[@name='LinkURL']")>
                    <#assign LinkURL = LinkURLxPathSelector.selectSingleNode(rootElement).getStringValue()>
        
                        <div class="carousel__hero-slide">
                            <a href="${LinkURL}">
                                <div class="carousel__hero-slide__image-container hero-carousel-image-${curEntry_index}"
                                     style="background-image: url(${Image});">
                                    <h3 class="carousel__hero-slide__mobile-title">${Title}</h3>
                                </div>
                            </a>
                            <div class="carousel__custom-page-indicator">
                                <button type="button">${Title}</button>
                            </div>
                        </div>


                  <#-- </#if> -->
                </#list>
            </#if>
        </div>
    </div>
</div>

Fig 5.3 Sample ADT in Liferay DXP 7.1

Highlighted portions in Fig 4.3 show the changes necessary to extract Documents and Media references from the Web Content XML.

If you are getting an error when accessing staticUtil from your templates, make sure that staticUtil is removed from the restricted variables list. To verify that this configuration change is in place, go to the Control Panel > Configurations > System Settings > Template Engines > FreeMarker Engine. If staticUtil is listed in the restricted variables list, remove it from the list and restart the Liferay server.

6. Upgrading Plugins

Upgrading portlets from 7.0 to 7.1 is fairly straightforward. One of the items you need to take care of is the dependencies in the build.gradle file. Update the Liferay dependencies to Liferay 7.1 versions, otherwise custom plugin modules will remain in the Installed state in OSGi container. For example, in 7.0 the dependency for the portal kernel jar was as follows:

compileOnly group: 'com.liferay.portal', name: 'com.liferay.portal.kernel', version: '2.45.0'

You need to upgrade it in 7.1 to this:

compileOnly group: 'com.liferay.portal', name: 'com.liferay.portal.kernel', version: '3.0.0'

You can check out the latest version of the jar files from the Central Maven Repo. Make sure to remove any deprecated classes and replace them with appropriate updated classes. For example, the com.liferay.portal.kernel.util.StringPool class has been deprecated and must be replaced with com.liferay.petra.string.StringPool from the Petra String jar.

In addition, you should read the Breaking Changes list, to determine what other changes are required by your plugins.

One item of particular note; there are some breaking changes for any REST services that you have created on Liferay DXP 7.0. For these to function on Liferay DXP 7.1, you need to delete the following files from the src/main/resources/configuration directory:

  • com.liferay.portal.remote.cxf.common.configuration.CXFEndpointPublisherConfiguration-cxf
  • com.liferay.portal.remote.rest.extender.configuration.RestExtenderConfiguration-rest
  • You also need to delete the entries from the following locations:

  • Control Panel > Configuration > System Settings > Web API > CXF Endpoints
  • Co'Panel > Configuration > System Setting > Web API > Rest Extender.

Once these tasks have been completed, you can follow the instructions given on Liferay’s developer site for JAX-RS services to make changes to your existing REST service code. As you will find on the JAX-RS link, for version 7.1 Liferay has tied the REST services to their OAuth framework, which makes it impossible to call the service without an OAuth access token. Follow the documentation to find out how to generate an access token and invoke the service. For more details about OAuth in Liferay 7.1, you can check the article on the Liferay developer network.

Summary

Liferay is constantly upgrading and updating the development approaches to make it easier for developers coming from varied backgrounds. Also, they are incorporating modern security frameworks like OAuth 2.0 to make your applications more secure.

If you have questions or need help with your Liferay DXP implementation, please engage with us via comments on this blog post, or reach out to us at https://www.xtivia.com/contact/ or info@xtivia.com .

Share This