« Back to Upgrade Instructions

Upgrade Instructions from 4.2 to 4.3

Upgrading an existing installation #

Note: Only upgrades from 4.2.2 are supported. If you are using a previous installation upgrade to 4.2.2 first.

  1. Stop the application (app server or servlet container process)
  2. Backup the database! This is very important in case you need to revert back to your original setup and configuration!
  3. Substitute the existing installation
    1. If deploying using the bundle unzip to a new directory
    2. If deploying using the EAR or WAR substitute the installed one(s) and update the dependent libraries in the global classpath
  4. If you modified the configuration through portal-ext.properties or sytem-ext.properties, copy the configuration from the old server to the new one
    1. You might have to adapt the configuration to the new version. Check the new versions of portal.properties and system.properties to see if any of the properties whose values you've overridden have changed.
  5. Run the server. The first time it should run the automatic Upgrade Processes (as can be seen in the logs).
    1. Note: Liferay 4.3 includes significant changes to the db schema. All of those will be applied automatically when Liferay first start (note that this is a new feature of Liferay 4.3, previously this had to be done by hand)

Theme developers #

The themes infrastructure has improved greatly in 4.3 and now it will be much easier to create and maintain new themes.

Unfortunately that has required making a lot of changes that make existing themes incompatible.

Instructions for upgrading included in the Themes page.

Portlet developers #

FriendlyURLs within portlets #

Now it is possible to use the friendly URL extensions provided by Liferay also for portlets that are developed outside of the ext environment. To do that write a class that extends from:


And reference it from the definition of the portlet in liferay-portlet.xml:


Upgrade Note: developers using the previously existing feature within the ext environment will have to upgrade. The process is easy:

  1. Update your class to implement com.liferay.portal.kernel.portlet.FriendlyURLMapper instead of the old com.liferay.portal.servlet.FriendlyURLPortletPlugin
  2. Update your liferay-portlet.xml and use the element friendly-url-mapper-class instead of the old friendly-url-plugin-class

Extension environment #

the ext/ext-ejb Folder was renamed to ext/ext-impl, so one has to move all the classes to the new directory. Hermann|Hermann 03:26, 1 August 2007 (PDT)

Upgrading foreign keys in custom data tables #

If you had created any of your own custom data tables, and those tables reference any primary keys in any of the core Liferay tables (such as user Id, company Id, group Ids, location/organization Ids, etc.), note that those keys have all changed from VARCHAR to BIGINT in 4.3, and thus your data will need to be converted.

  1. In portal.properties (or portal-ext.properties for extension users), modify/add to the upgrade.processes entry to register a custom class that extends com.liferay.portal.upgrade.UpgradeProcess
  2. Use the services of com.liferay.portal.upgrade.v4_3_0.util.AvailableMappersUtil
  3. Use any of the pre-existing com.liferay.portal.upgrade.v4_3_0. classes as an example.

Note that AvailableMappersUtil contains a series of 'in memory' mappers (com.liferay.portal.upgrade.util.MemoryValueMapper). Bottom line: you've got ONE shot at upgrading the database, and you have to do it while the other parts are upgrading. And you have to write custom Java code to do it.

Here's an code example that upgrades references to portal primary keys in a custom table. Before you run the portal for the first time you need to update all your service.xml files to the new column definitions (change String to long) and run ext-build-service for each and every service.

  public class UpgradeCustomData extends UpgradeProcess {
    public int getThreshold() {
        return ReleaseInfo.RELEASE_4_3_0_BUILD_NUMBER;
    public void upgrade() throws UpgradeException {
        try {
        catch (Exception e) {
            throw new UpgradeException(e);
    protected void doUpgrade() throws Exception {
        UpgradeColumn upgradeCompanyIdColumn = new SwapUpgradeColumnImpl(
            "companyId", new Integer(Types.VARCHAR),
        UpgradeColumn upgradeGroupIdColumn = new SwapUpgradeColumnImpl(
            "groupId", AvailableMappersUtil.getGroupIdMapper());
        UpgradeColumn upgradeUserIdColumn = new SwapUpgradeColumnImpl(
            "userId", new Integer(Types.VARCHAR),
        UpgradeColumn upgradeImageGalleryIdColumn = new SwapUpgradeColumnImpl(
        UpgradeTable upgradeTable = new DefaultUpgradeTableImpl(
                MyCustomModelImpl.TABLE_NAME, MyCustomModelImpl.TABLE_COLUMNS,
               upgradeCompanyIdColumn, upgradeLocationIdColumn, upgradeGroupIdColumn, upgradeUserIdColumn,

Be sure to insert the getThreshold Method. This Method is called by the StartUp Action of the portal. It checks the Treshold of every UpgradeProcess class to find out if the particular class needs to be executed.

Ant upgrade and patching Eclipse #

Starting with Liferay 4.3 developers will have to use ant versions >= 1.7.0.

Eclipse users can patch their environment to use later versions of ant by doing the following:

  1. Download ant >= 1.7.0 from http://ant.apache.org/
  2. Unzip ant
  3. Set/Update your ANT_HOME environment variable to the location where you unzipped ant
  4. Run Eclipse
  5. Go to Window > Preferences > Ant > Runtime
  6. Select the Classpath tab
  7. Push the Ant Home button
  8. Browse to ANT_HOME and select that folder

Portlet, Theme and Layout templates developers and distributors #

Liferay 4.3 includes 'Plugin Infrastructure' that allows the portal administrator (omniadmin) to install new portlets, themes and layout templates from the UI, be notified when a new version is available and update to new versions.

To make this possible each WAR that contains plugins (portlets, themes or layout templates) must have a new XML file called liferay-plugin-package.xml that provides information about the package name, version and contents. Here is an example of such an XML file:

   <?xml version="1.0"?>
   <!DOCTYPE plugin-package PUBLIC "-//Liferay//DTD Plugin Package 4.3.0//EN" "http://www.liferay.com/dtd/liferay-plugin-package_4_3_0.dtd">
   	<name>Liferay Core Plugins</name>
   		Portlets, themes, and layout templates included with Liferay Portal.
   		Adapted to the latest version of Liferay
   	<author>Liferay, Inc.</author>
   		<license osi-approved="true">MIT</license>

All the fields are pretty straight forward. Probably the one that might require more information is module-id. This field follows the conventions popularized by maven. The format is:


Which mean:

  • product-group: usually identifies the company or organization that develops the product or a family of products within that company or organization.
  • product-name: the name of the product. In the case of Liferay's plugins it can be the name of a portlet, or the name of an application composed of several portlets that are included in the package
  • version: use a numeric scheme such as 4.2.2, 5.0, etc. Liferay will use this to detect availability of new versions
  • file-type: in this case it will always be war

Configuration changes #

  • A new prefix for private personal communities has been added and can be configured through a new property: layout.friendly.url.private.user.servlet.mapping
  • layout.friendly.url.private.servlet.mapping has been renamed as layout.friendly.url.private.group.servlet.mapping
0 Attachments
Average (0 Votes)
The average rating is 0.0 stars out of 5.