Page tree
Skip to end of metadata
Go to start of metadata

Your Rating: Results: 1 Star2 Star3 Star4 Star5 Star 111 rates


The goal is to perform the migrations needed in order to update from

  • Magnolia 4.4.6 to 5.x
  • Magnolia 4.5.x to 5.x

In case of a fresh installation of Magnolia 5.x, no migration tool is needed.

A bit of History

Let first introduce the migration modules used for 4.5.x.

Migration Module 1.1.x

Used to migrate from Magnolia 4.4.6 to 4.5.0 until 4.5.6

Key features

  • Migration task configured and run by calling Groovy scripts
  • Migration tasks written in Groovy
  • Migration run manually once the Magnolia was updated from 4.4.6 to 4.5.x.
    This migration had to 
    • Migrate Magnolia Modules (SKT, FORM, ....)
    • Custom modules

Steps to run

  1. Install the new version of Magnolia (4.5.x)
  2. From the Admin Central Tools menu, configure the Groovy Script.
    1. Set modules to migrate (Installed Magnolia Modules, Customs modules, Template migration,...)
    2. Set references properties (Path to templates, path to custom/magnolia site definition, ...)
  3. From the same place, run the Migration by calling a Groovy Script
  4. Restart Magnolia in order to complete the migration.

Issues faced

Hard to configured
Hard to isolate issues (All migration was performed at once)
Hard to view the result of the migration.

Migration Module 1.2.x

Used to migrate from Magnolia 4.4.6 to 4.5.7 or higher


Migrate to Java (All groovy tasks are now translated to Java tasks)
Add a new Reporting mechanism
Isolate tasks in order to be able to run a migration for single module

Each Magnolia module is now responsible for his own migration. The end user has only to take car for his migration.

Key Features

  • Creation of 4 main migration tasks and 22 sub migration tasks
    • Main configuration migration tasks
      • Migrate Content : Site migration
      • Migrate simple template : Migrate configuration for modules using only the Magnolia template module
      • Migrate STK base template: Migrate configuration for modules using/extending STK for templating.
    • Main template migration task
      • Migrate Templates: Perform FTL's/JSP's migration.
    • Sub tasks are used by the main tasks and perform logical steps like changing node type of content, review/introduce extends mechanism...
  • Creation of a reporting tool allowing to generate better report in an HTML / Text form.
  • Enforce the Exception/Session handling.

Step to run

  1. Create a new version handler for custom module (using one of the 3 main configuration migration task)
  2. Install the new version of Magnolia (4.5.x)
    At this point all magnolia modules are migrated without a specific user action.
  3. Configure the Groovy script responsible to run the Java Template migration task
  4. Run the Template migration task
  5. Create the report.

Important improvements

  • Creation of a reporting service
  • Creation of an ID map service (Storing key/pair values into JCR)

M5 migration

Used to migrate from

  • Magnolia 4.4.6 to 5.x or higher
  • Magnolia 4.5.x to 5.x or higher

Like for the migration module 1.2, modules will be responsible to perform the appropriate migrations (DAM module will provide migration task in order to move content from DMS to DAM workspace, Handle content,...).

The big change is that we will no more use a Migration module, but App's

  • Report App
  • Template/Configuration migration App


M5 migration will have to support the following scenarios:

  1. Previous Magnolia Instance is 4.4.6 and Magnolia (and custom modules) was already migrated to 4.5.1 .
    1. The update from 4.4.6 to 4.5.1 was performed using the 1.1.x migration tool.
    2. Update from 4.5.1 to 4.5.x is normally done with the module's version handler (Normal magnolia life cycle).
    3. Update from 4.5.x to 5.x will be performed using  M5 migration modules
  2. A Magnolia instance (with custom module) is updated from 4.4.6 to 4.5.7 .
    1. The Update from 4.4.6 to 4.5.7 is performed using the 1.2.x migration tool.
    2. Update from 4.5.x to 5.x is done by using  M5 migration modules
  3. Magnolia update from 4.4.6 to 5.x with custom module.
    1. Update from 4.4.6 to 5.x is done by using  M5 migration modules
  4. A fresh installation of Magnolia 4.5.x was performed. (Equivalent to 1.c.).

So we clearly see that the new M5 migration tool has to be able to handle:

  • Migration form 4.5.x to 5.0
  • Migration from 4.4.6 to 5.0.

Big pictures



The current migration module will become a M5 App (Template/Configuration Migration App).
This App will have:

  • User interface allowing to configure and run the Template migration.
  • All main and sub configuration migration task in order to handle the migration from 4.4.6 to 4.5.x.

The Reporting mechanism currently defined into the migration tool, will become an own M5 App (Reporting App)
This App will have:

  • User interface allowing to configure and run the Report generation.

Current utility defined in the migration module will be migrated to the main module:

  • Service map ID
  • Some utilities


Report App


The generated report should look as designed (SCRUM Ticket)

User interface should have the following availabilities:

  • "Generate report" button + selects to choose the report format (single HTML / ZIP) and desired level of messages included to the report (error/warning/info/system/debug);
  • "Delete button" to allow delete old report records;
  • Show the date and time of the last added record and the last report generation -> i.e. whether there are new messages since the last time report has been generated;
  • The Single-HTML report should allow "folding" of tasks/modules/scripts, i.e. when task/script is "folded", then only its main data (name, result, timestamp, and general info) are displayed, not the messages; similarly for the module;
  • The Single-HTML report should allow to show only errors, user-action requests and/or code snippets, i.e. to hide general "info" messages; (I am not sure we can make it reasonably using the CSS+Javascript, perhaps this should be an option for the report generation);

M5 Migration App


User interface should have the following availabilities:

  • The configuration performed via Groovy script should be moved into a configuration screen/dialog.
  • The Template migration should be rerun as often as needed
  • Implement/migrate these requirements (SCRUM Ticket)


Report App

  • Create a new Report App
    • Adapt the code from the current Migration Report page
    • Add the "timestamp" information (last added message, last report generated)
    • Add the Delete button
  • Add styles and javascript to the generated report to allow "folding"
  • Explore the possibility to hide/show different kind of messages using CSS/Javascript

M5 Migration app:

  • Create a new M5 App
    • Create a sub app for Template migration configuration and execution
  • Extract current Code from the Migration project to the new App
    • For Template migration
    • For Configuration migration
    • Review the Migration class hierarchy and implementation (SCRUM Ticket
  • Extract all relevant code to the main module
    • Id service
    • Generic JCR utility methods
  • Use the new Report app to log user information
  • Adapt code of migrated modules to point now to the new Configuration migration tasks (STK/Form/PUR/....)
  • Review the implemented M5 migration tasks (DAM/Node)


Already implemented migration task (M5)

DAM migration

DAM migration tasks

TODO ehe: Review Reference migration for Bookmark & Images links.


MetaData as mixin


TODO ehe: Add Doc

Data Module

TODO ehe: Add Doc


MultiSite has a migration task which moves old ETK site configs


to the new config node of MultiSite

See: info.magnolia.multisite.setup.MigrateETKSitesTask

TODO: Whenever Migration from 4.5 to 5.x is available this has to be tested.


Modules not planned to be migrated to M5


Workflow will not be migrated. As OpenWFE is not supported anymore, we encourage costumers to migrate their workflows to our new JBPM based workflow.

There have been ideas how to make this step easier for customers, but so far no definite decision has been made:

  • Support them actively by actually doing it for them.
  • Write a legacy OpenWFE based workflow module.
  • ... ?
  • No labels


  1. Thanks for this very comprehensive overview.

    Few extras:

    • metadata are different in m5 so all metadata manipulation done by migration tasks needs to be rewritten since it will get executed after core task for migrating those subnodes to mixing
    • reporting service storage mechanism has serious shortcomings when it comes to migrating bigger projects (1K+ pages) - it needs to be better structured and optimize saving
    • service maps suffer from similar problem, they can lead to OOME due to loading mapping for all pages and all templates to memory
  2. Could you also list the changes that wont be handled by a migration task or script, like for example Workflow.

    Partners and Clients want to know the effort on their side when they update to M5.

  3. I'd be interested in some ideas on "data" workspace migration. Will we just tell the customers they'll have to put the data in own repos now and that they'll need to create some simple content app at least for viewing purposes, or could we provide something with the migration tool (probably not within the scope of the first release I guess). Yep, and I saw the TODO for that (tongue) just saying that this might be one of the time consumers for customers.

    1. Migration should be possible for data - export from data module, create special workspace, import there ... whatever we will have for dialog for websites should work for redoing dialogs as well. As long as we are splitting files on export (We have tool for that) we should not run into any big issues apart from this task taking some time.

      Manual part in this kind of migration I could see is need to update all templates/models previously going into data module to go into this new workspace to retrieve data, otoh in most cases it would be just replacing "data" in  MgnlContext.getJCRSession("data") or MgnlContext.getHierarchyManager("data") with whatever name of new workspace will have (name of the type i guess? ). Queries will need the same.