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 version | Migration Module version |
---|---|
4.5.15 or later | 1.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:
<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 originalcontentNodeIterator
. - 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:
- Start Magnolia CMS.
- 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.
16 Comments
Tomas Brimor
What version of the migration module should be used for 4.5.6?
Lars Fischer
The latest of the 1.1.x branch for versions below 4.5.7 (which has not been released yet).
Yann Roth
IMHO, the script is not correctly setup!
on line 38 it says:
migrationTask = new TemplateScriptMigrationTask(it.key, siteDefinitions, modulesMap, generateScripts);
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.value, siteDefinitions, 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"
]
// SITE DEFINITION
def siteDefinitions = [
"/path/in/magnolia/configuration/to/your/site/definition"
:
"/path/to/scripts/on/your/file/system"
,]
Yann Roth
And I guess there is a typo:
instead of
<version>
2.6
</version>
it should say:
<version>1.
2.6
</version>
Right?
Robert Šiška
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 http://wiki.magnolia-cms.com/pages/viewpage.action?pageId=56365547 for more details.
Michel Protocevich Koslovsky
Hi,
I cant see the page. Page Not Found.
Magnolia International
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!
Michel Protocevich Koslovsky
Thank you.
Yann Roth
Please, where is version 1.2.9? I can't find it on nexus...
Robert Šiška
Hello. It is on nexus but it is a maintenance release and therefore available only to the customers.
Yann Roth
thanx! So what's best to do?
Robert Šiška
You will have to compile it by yourself from our git repository.
Yann Roth
thanks
But:
info.magnolia:magnolia-core:jar:4.5.13
is required and I am working with 4.5.12 (last CE).
So, no chance??
Robert Šiška
Most likely not
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.
Yann Roth
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?
Robert Šiška
Well as I said, I'm not sure about the compatibility with 4.5.12. You will have to try it for yourself.
Regards.