OpenCms Logo

Navigation: 6.0 b 3 notes | 6.0 b 2 notes | 6.0 b 1 notes | 6.0 a 3 notes | 6.0 a 2 notes | 6.0 a 1 notes | 5.0 final release notes | 5.0 rc 2 notes | 5.0 rc 1 notes | 5.0 beta 2 notes | Installation | 4.x to 5.0 upgrade info | Mailing list | Welcome to OpenCms

How to upgrade to OpenCms 5.0.0

In case you have created a website with OpenCms 4.x, this page provides you with some simple steps how to upgrade your website to OpenCms 5.0.0. If you are already using one of the 5.0 beta or release canditade versions, most of these steps will not be necessary.

This document only describes how to upgrade templates and pages created in OpenCms 4.x. Not described here is how to upgrade OpenCms 4.x "traditional" style modules. Very few OpenCms installations have so far made use of the module mechanism. OpenCms 5.0 features a new "simple" style module type which is much easier to use, more powerful, and also better documented. We recommend using only the new "simple" type module style for all new OpenCms 5.0 installations.

The upgrade process

Upgrading should be easy if you just follow these simple steps:

  1. Check out required settings for OpenCms 5.0 in your 4.x installation (see below).
  2. Export your website root folder "/" on your OpenCms 4.x installation.
  3. If you have written your own Java classes for OpenCms, these need to be re-compiled against the 5.0.0 opencms.jar.
    No changes should be required, only re-compilation.
  4. Install OpenCms 5.0.0.
    Make sure you have turned on the "Directory translation" feature.
  5. Adjust the required settings in of your 5.0 installation (see below).
  6. If you have written  your own Java classes for OpenCms, these must be placed in the standard/classes or /lib folders of the web application.
    The /occlasses and /oclib folders of the 4.x versions do not longer exist.
  7. Restart your OpenCms 5.0 server so that the new settings and classes are read.
  8. Import the content you exported from the 4.x installation.
  9. Check if everything works.

This should be it.

Adjustments in

The file /WEB-INF/config/ is where OpenCms stores most of the system settings. Some settings deal with upgrading content from OpenCms 4.x to 5.0.0. Here's a copy of that section in the file with the default values:

# Backward compatibility flags.
# This should be set to true ONLY if you are migrating from 4.x to 5.0 versions of OpenCms.

# "Old style" module locale backward compatibility support
# Enables supports for proprietary 4.x module XML locales
# Must be set to true only if old modules are used

# Convert file content from 4.x to 5.x style during import
# This is needed for the correct content conversion of the import.
# Enter the URL of the OpenCms web application from which the content was exported,
# e.g. http://localhost:8080/opencms/opencms/ for a standard local Tomcat installation.

# List of the resource properties which should be removed when resources are imported.

# List of old web application names for conversion in editor and in import bodies.
# Example for a standard web application name: /opencms/opencms/

Depending on the OpenCms version you use, you will have to adjust the values of and/or OpenCms 4.x did place some hard coded server and context information in your page files. This will be replaced by OpenCms 5.0 with variables. To see what information you have to provide, open the body file of a page in your OpenCms 4.x installation. In OpenCms installations prior to 5.0 beta 2, these files where located in the /content/bodys/ folder. Open a file in this folder that contains images you have edited with the source code editor. This will show you the page XML. What to look for will depend on your OpenCms version:

  • If you use OpenCms 4.6 (the last official stable release), you will see a <template> section that is the exact copy of the source code you can edit with the WYSIWYG / Source code editor. Find an image tag (img src) and check out the path given there. It should be a full path with a server name. Let's say it's In that case, your old webapp URL is and your webapp name is /opencms/opencms/. Place this values in the file.
  • If you use OpenCms 4.7.7 or one of the 5.0 pre-release versions, your will find a <template> and a <edittemplate> tag in the page XML file. Check out the <template> section of the file first. Find an image tag (img src) and check out the path given there. It should have the web application context hard coded, e.g. /opencms/opencms/somepath/imagename.gif. Use this as webapp name for . You might also find a full path with a server name. Let's say it's In that case, your old webapp URL is If you don't see such a full path in any of your page files, just use the default setting for webapp URL.

Things to check if something does not work

The steps described here should happen automatically during the import to the OpenCms 5.0 version. However, if an imported page does not work as expected, you might check out this list to see how you can repair your page manually.

  1. OpenCms 5.0 has a different directory structure then the 4.x versions. All system files are now located under the /system/ folder. The directory translation feature (enabled by default in the setup wizard) will automatically translate a request to an old path to the new path. For example, /content/bodies/ will be translated to /system/bodies/. This is also true for the import, so files exported form one of the old directories will be imported in the new ones. Please note that some path information in page or template files will still be pointing to the old path after the import in the 5.0 system. This is o.k. as long as the directory trnaslation feature is turned on.
  2. The encoding will be added to the XML of every page file. Old OpenCms versions did not specify the encoding with the XML tag but start with <?xml version="1.0"?> only. The OpenCms default encoding will be added to all of this files. A valid XML start tag looks like this: <?xml version="1.0" encoding="ISO-8859-1"?>. If your templates did not specify the encoding and the import does not correct that problem for you, you must add this manually.
  3. OpenCms 4.x "frametemplate" files are analyzed if they have a <meta http-equiv="content-type" ... > setting. This will be either added or changed to use the encoding form the OpenCms server by placing a call to the getEncoding XMLTemplate method. In the end this line should look like this:
    <meta http-equiv="content-type" content="text/html; charset=]]><method name="getEncoding"/><![CDATA[">
    Please note that this applies only to OpenCms 4.x "frametemplate" files.
  4. If a page file has no <edittemplate> (always true if it was exported by a 4.6 version), this will be added automatically during import.

In case a page or template does not work after import, check the XML of the page file and of the template used by the page. Check all path information in the page / template and check if the replacements of the XML encoding and the "content-type" did work. Ensure the settings you have made in for the webapp name and webapp URL where correct. If not, you must correct the settings, drop the database, and repeat the setup.

Please login:

Alkacon Software © 2002-2005 Alkacon Software
The OpenCms experts