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

In this step, you are working in your IDE. Update the dependencies in your pom.xml so that they depend on 4.5 code. Next, in order for your own Java code to compile against the 4.5 dependencies, you need to do a minimal code update to 4.5 level.


Compile your own project code against Magnolia 4.5 code.


10 minutes per model class. 

Update configuration

Update your project pom.xml file:

  • Change the Magnolia version to 4.5.13 (or later)
  • Change the Magnolia module versions to 4.5.13 compatible versions according to the release notes.
  • Remove magnolia-module-templating module from the pom file and from your project.
  • Remove tag lib dependencies from the webapp.
  • Add magnolia-templating-compatibility
  • If you use deprecated code from STK (see STKUtil methods migration for 4.5 and STK API Changes in 4.5), add the new magnolia-module-standard-templating-kit-compatibility module.
  • Remove the javax.servlet.jsp artifact
  • Add a dependency to magnolia-4-5-migration. This is the Migration module that will assist in the process. It consists of update tasks and a few Groovy scripts.
  • During the migration process the cmsUtilTaglib taglib will be added to your template scripts (Freemarker and JSP) automatically. If you use JSP templates, add a dependency to magnolia-templating-jsp manually.

Update Maven dependencies

Depending on how your project is currently built, you might need to change, or add, a few dependencies:

  • If you are depending on magnolia-module-templating, you will need to replace that dependency to either, or all, of: 
    • magnolia-rendering
    • magnolia-templating
    • magnolia-templating-editor
    • and optionally magnolia-templating-jsp if you use JSP in your templates.
  • Taglib artifacts have also been renamed; they are now part of the compatibility package: 
    • magnolia-taglib-cms is now magnolia-templating-compatibility-taglib-cms
    • magnolia-taglib-utility is now magnolia-templating-compatibility-taglib-utility.
  • If you are using deprecated STK code add a dependency for:
    • magnolia-module-standard-templating-kit-compatibility


Dependency in POM

Update Module descriptor

Your modules must likely extend Magnolia module on version 4.4.x.

Module descriptor


Align these dependencies with the version used for Maven. 

Module descriptor


Update code

A lot of changes were also done on Magnolia CMS APIs. You need to update your Java code.

Update of the code:

  • Use deprecated classes when possible. You don't need to update your Java code immediately unless you are forced to. Use the deprecated code to start the migration and optimize later.
  • Update the model. When necessary use Node.getJCRNode or ContentUtil.asContent(Node) in order to avoid the updates of many methods.

Here is a list of pages that explain the code changes that happened in 4.5:

Update version handler

Create a new delta in the module version handler. In the delta, add an update task provided by the Migration module. This task will update your configuration and code.

Add dependency to the Migration module in the POM

In order to use the tasks provided by the Migration module you need to add a dependency to the module. 

Add a reference to the migration module into your pom.xml or import the Migration module JAR into your project classpath. This module contains all main migration tasks and subtasks needed to migrate your module.

Dependency in POM

Create and configure your migration task

Now you have to adapt your module version handler, and if necessary (complex modules that need unplanned migration tasks) create a new migration task. For simple modules you have to choose between one of the three predefined migration tasks:

  •   TemplatingRelatedModuleMigrationTask: Simple Template module. For modules that don't use or extend STK.
  • SimpleSTKRelatedModuleMigrationTaskSTK Template module. For modules that extend or use STK.
  • ContentModuleMigrationTaskContent migration for site content migration for STK and non-STK based sites).

Register and configure a new DeltaBuilder calling the Content Migration task during the update process:

CustomContent version handler
register(DeltaBuilder.update("1.5", "")
   .addTask(new SimpleSTKRelatedModuleMigrationTask(
	"Migration task: Migrate Config", 
	"Migrate Configuration", "moduleName", false, 
   .addTask(new ContentModuleMigrationTask(
	"Migration task: Migrate Content", 
	"Migrate websiteContent",  "moduleName", "website",
	Arrays.asList("/site1", "/site2"), 
	null, false, true)));

It's important to notice that while on the SimpleSTKRelatedModuleMigrationTask task you are expected to provide the full path to your module on ContentModuleMigrationTask you only have to use the site name. An example configuration of the task would be:

final Delta deltaFor1019 = DeltaBuilder.update("1.0.19", "All updates for 1.0.19")
    .addTask(new SimpleSTKRelatedModuleMigrationTask("Migration task: Migrate Config", "Migrate Configuration", "acme-website", false, Arrays.asList("/modules/extended-templating-kit/config/sites/home")))
    .addTask(new ContentModuleMigrationTask("Migration task: Migrate Content", "Migrate websiteContent",  "acme-website", "website", Arrays.asList("/home"), false, true));

See Migration task classes for the attributes.

Next step

4. Update repository and webapp


  1. Is there a typo here? See last chapter: Create and configure your migration task.

    ContentModuleMigrationTask seems to have 3 parameters after Arrays.asList(): null, false, true.

    But in the last example, Arrays.asList() is followed by 2 parameters only: false, true.


    1. Hi Yann,

      Both examples are correct. The ContentModuleMigrationTask  has two constructors: one with and another without the blacklist parameter.

      This means the parameter is optional. A comment in code says:

      The blacklist can contain ids (or names) of templates, that will be skipped. ["module:path/to/customController1", "customController2"]

      In the first usage example we pass the value null (first constructor). In the second example we don't pass anything (second constructor). In practice, neither example has a blacklist.