Content Migration

Content migration from OpenCms 5 to OpenCms 6 is mostly done automatically. The OpenCms import/export function will convert the content so that it is directly available in the new OpenCms 6 installation. Due to the new internal structure of the xml pages and the way how those pages are connected with their templates, some additional actions have to be made after the import in OpenCms 6.

What to do?

In the following steps, we assume that the name of the OpenCms 5 webapplication is "opencms5" while the name of the OpenCms 6 webapplication is "opencms6". You might have to adjust the folder names below if your OpenCms applications are running under different names.

How to export the content from OpenCms 5

To export the content from OpenCms 5, go to the Adminstration view and select "Database management" -> "Export". In the following dialog you can select the resources and the export file:

• Resources to export: Add the root folder "/" here (either by entering in the "add" input field and pressing the blue arrow, or by opening the explorer tree with the folder icon and select it there).
• Please note: If you are exporting a lot of resources (several thousands), you should not export all resources in one export file due to memory restrictions in OpenCms 5. You then should make several export files, each of them containing a part of your existing website.
• Keep the "exclude system folder" checkbox checked.
• Choose a name for your export file ("content.zip" in this example).

After pressing "Ok", OpenCms will now export all your content pages into a zip file of your server which can be found at [location of your tomcat]/webapps/opencms5/WEB_INF/packages/[name of your export file].

If you used the galleries in your system as well, you should do a second export containing the galleries:

• Resources to export: Add the folder "/system/galleries/" here (either by entering in the "add" input field and pressing the blue arrow, or by opening the explorer tree with the folder icon and select it there).
• Uncheck the "exclude system folder" checkbox.
• Choose a name for your export file ("galleries.zip" in this example).

Importing the content in OpenCms 6

To import the exported contents in OpenCms 6, you should copy the export files into the packages folder on the server where your OpenCms 6 is running: [location of your tomcat]/webapps/opencms6/WEB_INF/packages/.

It is important to switch to your working site in OpenCms before starting the import (e.g. /sites/default/). Do never initiate the content import in the root site!

From there it can be imported via the database adminstration of the OpenCms Adminstration view by selecting "Database Management" -> "Import File from Server".

The import process will start, the resources will be imported and the necessary conversions will be done. For more details about the conversion, see the chapter "Technical Background" below.

Importing User Data

To migrate user data from OpenCms version 5 to 6, by importing a module or database including user data into the new installation, you have to edit the "opencms-system.xml" and edit the passwordhandler element. Set the parameter "compatibility.convert.digestencoding" to "true", so that the node looks like that:

<passwordhandler class="org.opencms.security.CmsDefaultPasswordHandler">
    <encoding>UTF-8</encoding>
    <digest-type>MD5</digest-type>
    <param name="compatibility.convert.digestencoding">true</param>
</passwordhandler>

You have to restart tomcat for the changes to take effect. Don't forget to reset the parameter to "false" after the data is imported.

Setting the correct templates

After the import and conversion has been completed, the content pages must be connected with the correct template. The content pages are still connected to the old templates they used in the OpenCms 5 system. Since the structure of the templates has been changed in OpenCms 6, this must be changed.

In OpenCms 6, the information which template should be used is stored in the "template" property. The values of those properties can be changed with the content tools in the Adminatration view.

Select "Content Tools" -> "Change Property Values" to get to the change property value dialog:

• "Change resources in folder": Enter the root folder"/" here.
• Set "Include all subfolders" to checked.
• "Property": Select "template" here
• "Old property value": Enter the path of the old template here. (e.g. "/system/modules/com.alkacon.mytemplates/templates/maintemplate"). If you want to set all old templates to the same new template, enter ".*" here.
• "Change value to": Enter the path of the new template here (e.g. "/system/modules/com.alkacon.mytemplates/templates/maintemplate_jsp").

By selecting "OK", the template properties are set to the new values.

If you had more than one template in your old OpenCms 5 application, you have to redo this step for each of the old templates used. For this, use the list of templates you had created here .

Setting the correct folder types

If you had included the galleries in your OpenCms5 export, you have to modify the types of the gallery folder to make them usable in OpenCms 6 again. Assuming you have not added any folder translation rules as described here , you will find your imported galleries in the /system/galleries/ folder. There you have to modify the resource type of the folders within the main gallery folder like that:

Changing the type of those folders can be done with thew "change type" function in the context menu.

After all template properties and folder types are adjusted, continue with the next step "JSP modifications"

Technical Background

While the converted content pages can be used the same way as before in the old OpenCms application, their internal structure, especially the one of xml pages has changed completely. For those interested in the internal changes, here is what is modified during the import process.

XML Pages

In OpenCms 5, a xml page always consisted of two components, a control file and the content file. The control file was the "clickable" file in the VFS tree, for example "/myfolder/index.html". This file did not contain the content itself, but control information which template to be used and where the real content for this file was found:

<?xml version="1.0" encoding="ISO-8859-1"?>
<PAGE>
	<class>com.opencms.template.CmsXmlTemplate</class>    
	<masterTemplate>system/modules/com.alkacon.mytemplates/templates/maintemplate</masterTemplate>
 
	<ELEMENTDEF name="body">
		<CLASS>com.opencms.template.CmsXmlTemplate</CLASS>    
		<TEMPLATE>/system/bodies/myfolder/index.html</TEMPLATE> 
	</ELEMENTDEF>
</PAGE>

The content file itself was always found at "/system/bodies/[path to the control file]", so as can be seen in the example above, the content file was located at "/system/bodies/myfolder/index.html". The content file itself looked like this:

<?xml version="1.0" encoding="ISO-8859-1"?>

<XMLTEMPLATE>

<TEMPLATE><![CDATA[Hello World!]]></TEMPLATE> 
<edittemplate><![CDATA[Hello World!]]></edittemplate>


</XMLTEMPLATE>

This approach has several disadvantages. For one content page, two files in the OpenCms VFS were created. The content file itself had to store the content in two versions, one for displaying in the editor and one for displaying on the website. The handling of the contol file and content file made all file operations in OpenCms 5 more complex than they should have been.

In OpenCms 6 the structure of the xml pages has changed completely. There is only the content file left, which is now the clickable one. The information which template to be used for display is stored in the "template" property of the content file. When importing an old OpenCms 5 xml page, the control file and content file are automatically merged into the new structure wich looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<pages xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.opencms.org/dtd/6.0/xmlpage.xsd">
  
<page language="en">
    <element name="body">     
      <links/>
      <content><![CDATA[Hello World!]]></content>
    </element>
</page>
</pages>

As an additional result, you will not have any files in the /system/bodies/ folder anymore.

Pointers

OpenCms 5 had the concept of the pointer resource type, which could either point to an external URL or to another resource in the OpenCms VFS. During the import conversion, pointers to external URLs are modified into resources of the type "External Link". Pointers to internal resources will be turned into siblings of those resources where the original pointers pointed to.