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.
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.
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:
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:
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.
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.
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:
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 .
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:
Subfolders of | Change to resource type |
pics | Image gallery |
download | Download gallery |
externallinks | External link gallery |
htmlgalleries | HTML gallery |
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"
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.
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.
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.
]]>