Using the migration tool

This page describes how to use the Migration module and belongs to the Migration, valid for Magnolia CMS 4.4.6 to 4.5 (or higher).

Installing the Migration module

Ensure that you have the correct version of the Migration module.

Copy the .jar files from /magnolia-enterprise-4.5.x/add-ons/magnolia-4-5-migration-1.x folder to the WEB-INF/lib folder.

If you build your project using Maven, add the following dependency:

<dependency>     
   <groupId>info.magnolia</groupId>
   <artifactId>magnolia-4-5-migration</artifactId>
   <version>2.6</version>
</dependency>

Updating template scripts

Template scripts are updated with a Groovy script (uses ANTLR library to parse).

 The script only updates the template scripts, not the related configuration. The script writes code snippets in the migration report that tell you how to change the template configuration correspondingly.

This is what happens in the script:

• Migrates template scripts.
• Comments out old, unsupported code.
• Adds comments with new alternatives or suggestions.
• Removes old contentNodeIterator tag from areas and creates new area scripts if needed (usually not).
• Writes an area tag in place of the original contentNodeIterator.
• Finds available components and creates a code snippet that is written into the report, containing how to change the configuration.
• Most of the changes needed are listed in  Tags migration for 4.5 and STKUtil methods migration for 4.5. See also the Migration FAQ and Migrating template scripts.

To update template scripts:

1. Start Magnolia CMS.
2. Edit the MigrateTemplateExecuteScripts Groovy script. Define the template scripts to migrate.

    // Configuration part
    // Generate Script ?
    def generateScripts = true;
    // MODULE_NAME : PATH to FTL's / JSP's
    def modulesMap = ["myModule": "/path/to/scripts/on/your/file/system"]
    // SITE DEFINITION
    def siteDefinitions = ["/path/in/magnolia/configuration/to/your/site/definition": "/path/to/scripts/on/your/file/system",]

Save the script and run it.

Example result

An example output of migrated template script looks like this:

[#--OLD [#assign  cms = JspTaglibs["cms-taglib"]] --]
[#--OLD Functionality provided previously by taglib is now available via functions. --]

[#if [#--OLD mgnl.editMode --]cmsfn.editMode]
  [#--OLD ${stk.decode(content).text!} --]
  ${cmsfn.decode(content).text!}
[/#if]

An example of migration report:

TO DO

Carefully go through the templates, removing all old blocks that are commented out.