Enonic CMS to XP migration tool

This repository contains the code for the CMS to XP migration tool.

The migration works from CMS 4.7 to XP 6.x.

Download

Download the latest version: 0.10.12

Releases

Change log

See change log for the released versions here

Building

Before trying to build the project, you need to verify that the following software is installed:

• Java 8 for building and running.
• Gradle 2.x build system.

Build all code and run all tests including integration tests:

gradle build

A distribution zip, containing all the required files for running the tool, will be generated in build/distributions/cms2xp-0.10.12.zip

Running

There is just one script command to execute the CMS to XP migration tool. The script takes one parameter: the path to a config.xml file.

Note that the tool must be executed from a computer with file access to the CMS blobs and resources directories, normally located in the CMS_HOME directory of the CMS installation. It also needs direct connection access to the database where the CMS data is stored. The CMS itself does not need to be running.

To run the script, extract the distribution zip file to an empty directory and execute the script from the command line:

• ./bin/cms2xp <path_to_config.xml> - (on Linux / OS X)
• bin\cms2xp.bat <path_to_config.xml> - (on Windows)

If the config.xml parameter is omitted, it will print out an example of config XML. See also Configuration below.

Before running this tool, the SQL driver to the CMS database must be copied to the lib directory. This is normally a .jar file specific to a database version, like postgresql-9.3-1104.jdbc4.jar.

Configuration

The configuration is divided in two parts:

• <source>: parameters to access the data from the CMS.
• <target>: parameters to specify the output locations and format for the generated XP data.

Example of config.xml:

<config>
  <!-- Source (CMS) -->
  <source>
    <jdbcDriver>org.h2.Driver</jdbcDriver>
    <jdbcUrl>jdbc:h2:~/cms-home/data/h2/cms</jdbcUrl>
    <jdbcUser>sa</jdbcUser>
    <jdbcPassword>***</jdbcPassword>
    <blobStoreDir>./cms-home/data/blobs</blobStoreDir>
    <resourcesDir>./cms-home/data/resources</resourcesDir>
    <exclude>
      <site>old_site</site>
      <site>42</site>
      <contentPath>/old_content</contentPath>
      <contentPath>/images/not_in_use</contentPath>
      <userStore>legacyUserStore</userStore>
    </exclude>
    <include>
      <!-- specify either exclude or include, but not both at the same time -->
    </include>
  </source>

  <!-- Target (XP) -->
  <target>
    <exportDir>./export</exportDir>
    <userExportDir>./export_user</userExportDir>
    <applicationDir>./application</applicationDir>
    <applicationName>com.enonic.xp.app.myApp</applicationName>
    <applicationRepo>starter-vanilla</applicationRepo>
    <exportApplication>true</exportApplication>
    <exportMenuMixin>true</exportMenuMixin>
    <moveHomeContentToSection>true</moveHomeContentToSection>
    <exportCmsKeyMixin>false</exportCmsKeyMixin>
    <exportCmsMenuKeyMixin>true</exportCmsMenuKeyMixin>
    <exportCmsImageMixin>true</exportCmsImageMixin>
    <exportCmsStatusMixin>true</exportCmsStatusMixin>
    <logFile>cms2xp.log</logFile>
  </target>
</config>

Source parameters

The source parameters include the details necessary for connecting to the CMS database, and the path to the blobs and resources from the CMS.

Target parameters

The target parameters include the desired path where to generate XP export directories. Two different exports will be generated, one with CMS content and the other with user store data.

There are also parameters to specify path and name for generating an XP application. This application will contain content types, mixins, parts and pages, converted from CMS. There are also some optional switches for altering the output.

How to use

The process of migrating CMS data to XP includes some additional actions after running the CMS2XP tool.

These are the suggested steps for migrating CMS data:

1. Create and fill in a config.xml file according to the details above.

2. Execute the cms2xp script:

   ./bin/cms2xp config.xml

3. If all goes well 3 directories will be created with: content data, user store data, and an XP application.

4. Build and deploy the application:

   <applicationDir>$ gradle clean deploy

5. Move the content export to XP export directory:

   mv <exportDir> $XP_HOME/data/export/cms_content

6. Move the user store export to XP export directory:

   mv <userExportDir> $XP_HOME/data/export/cms_users

7. Import user store export into XP:

   $XP/toolbox/toolbox.sh import -a su:pwd -t system-repo:master:/identity -s cms_users/identity

8. Import content export into XP:

   $XP/toolbox/toolbox.sh import -a su:pwd -t cms-repo:draft:/content -s cms_content/content

9. Reprocess the imported content to update the metadata in media content:

   $XP/toolbox/toolbox.sh reprocess -a su:pwd -s draft:/

See XP documentation for more details about the import and reprocess commands.

Notes

There are some remarks and limitations on the exported data:

• The source CMS data must be from Enonic CMS version 4.7. To convert from an older installation (e.g. 4.5.x, 4.4.x) it is necessary to first upgrade to the latest CMS 4.7 version.
• Only the 'main' version of each content is exported (not its whole version history).
• The Menu tree of the sites is exported maintaining the same structure. CMS page templates are converted to XP page-template, and portlets are converted to XP fragments. But the parts and pages generated in the app are placeholders. The xsl logic and datasources from CMS is currently not converted to XP.
• CMS section does not have an equivalent in XP. Content published in a section is referenced in a "sectionContents" property of the section content type. In addition, if <moveHomeContentToSection> is set to true in the cms2xp config, the published content will be placed under the section content.
• CMS global groups is currently converted to roles in XP. But due to roles not allowing to be member of other roles in XP, the memberships of global groups are skipped on the exported data.

For questions, feature requests, or reporting issues, please use the Enonic Discuss forum.