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.

Magnolia CMS versionMigration Module version
4.5.15 or later1.2.6 or later

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:


Updating template scripts

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

(warning) 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"]
    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!} --]

An example of migration report:


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



  1. What version of the migration module should be used for 4.5.6? 

  2. The latest of the 1.1.x branch for versions below 4.5.7 (which has not been released yet). 

  3. IMHO, the script is not correctly setup!

    on line 38 it says:

    migrationTask new TemplateScriptMigrationTask(it.keysiteDefinitionsmodulesMapgenerateScripts);

    But reading the constructor method, the second parameter requires a String, and the third is the siteDefinition, not the moduleMap. Thus it should say:

    migrationTask new TemplateScriptMigrationTask(it.key, it.valuesiteDefinitions, generateScripts);

    Worked fine for me...

    Or am I wrong?

    Another point

    The documentation in Updating template scripts says:

    // MODULE_NAME : PATH to FTL's / JSP's
    def modulesMap = ["myModule""/path/to/scripts/on/your/file/system"]
    def siteDefinitions = ["/path/in/magnolia/configuration/to/your/site/definition""/path/to/scripts/on/your/file/system",]
    the word scripts in this context seems a little ambiguous to me. I'd suggest to use templates or even better templateScripts. I would also use on/your/local/file/system.

  4. And I guess there is a typo:

    instead of <version>2.6</version>

    it should say: <version>1.2.6</version>


  5. Hi.

    If you can, please use version 1.2.9 or latter. We completely changed the mechanism in MAGNOLIA-6027

    and now the tool is controlled through it's own tool page. See for more details.

    1. Hi,

      I cant see the page. Page Not Found.

      1. Hi,

        I moved this page here, you can use this link instead: Running the migration tool (Since 1.2.X)

        Thanks for reporting this issue!

    2. Please, where is version 1.2.9? I can't find it on nexus...

      1. Hello. It is on nexus but it is a maintenance release and therefore available only to the customers.

        1. thanx! So what's best to do?

          1. You will have to compile it by yourself from our git repository.

            1. thanks



              is required and I am working with 4.5.12 (last CE).

              So, no chance??

              1. Most likely not (sad) You can try it with 4.5.12, though. I don't remember what was the reasoning for 4.5.13 dep. but it seems to compile fine.

                1. compiled, but had some test errors:

                  Failed to execute goal org.apache.maven.plugins:maven-surefire-plugin:2.12:test (default-test) on project magnolia-4-5-migration: There are test failures.

                  should be ok, though, right?

                  1. Well as I said, I'm not sure about the compatibility with 4.5.12. You will have to try it for yourself.