Upgrading to Magnolia 6.2

This page contains information about upgrading to Magnolia 6.2.x from any previous and currently supported version. Before starting the upgrade process, we recommend you read:

If you are upgrading from a Magnolia release that has already reached end of life, contact us for migration support.

Migration strategies for Magnolia 6.2

There are two different strategies for migrating to Magnolia 6.2, each with its advantages and disadvantages:

Advantages

Disadvantages

  • You do not need to update your definitions as they already work in 6 UI.

  • Faster upgrade (but additional effort remains as you migrate apps).

  • Reduced risk because of fewer initial changes.

  • New 6 UI features are not available.

  • You need to test your migration repeatedly.

  • More complex to maintain.

Advantages

Disadvantages

  • All new 6 UI features are available.

  • You only need to test your migration once.

  • Easier to maintain.

  • Significant effort needed initially to update all your definitions to 6 UI.

  • Slower upgrade because of more testing efforts.

What to update

pom.xml file

It is critical that you update the parent pom.xml file of your webapp, which manages all versions for both Magnolia modules and third-party libraries. For more details, see Upgrading Maven-managed webapps.

magnolia.properties file

When upgrading Magnolia, it is recommended that you compare your magnolia.properties file with the one from the newly released Magnolia bundles. Below are the latest versions of the magnolia.properties files for Magnolia 6.2.

Apache Tomcat

If you use Apache Tomcat, note that we have updated to version 9.0.31. We recommend this update since it fixes some possible security vulnerabilities.

If you use another servlet container, check out the certified stack for supported versions.

Server configuration with relaxedQueryChars

Tomcat 9 has become less tolerant of special characters when compared to some of its previous versions. To bring back support for special characters as it was in Tomcat 8 (for instance, to query the delivery endpoint API with filters), we have added the characters [, ] and | to the relaxedQueryChars attribute of the Connector element in the server.xml configuration file.

Third-party libraries

All changes in third-party libraries are managed via the BOM for third-party libraries. If you manage your bundles via Maven using the BOM, all updates will be handled automatically. Among the most notable third-party library updates in the Magnolia 6.2 release are:

  • Vaadin 8.9.4

  • Guava 28.2-jre

  • Tika 1.23

  • Jackrabbit 2.20.0

  • Ehcache 3.7.1

    Due to an incompatibility issue, the items that remain on disk will be deleted after updating.

New and updated modules

  • Advanced Cache 2.3

  • Backup 2.4

  • Barebones Tomcat Bundle 1.2

  • Blossom 3.3.1

  • Cache 5.9.0

  • Campaign Publisher 1.3.2

  • Categorization 2.7.1

  • Community Edition 6.2

  • Contacts App 1.8

  • Content Dependencies 2.0

  • Content Editor 1.3.3

  • Content Tags 2.0

  • Content Translation Support 2.4.2

  • Content Types 1.1.1

  • DAM 3.0

  • Definitions App 2.1

  • Demo Projects 1.5

  • Diff 2.2

  • DX Core 6.2

  • External Forms 1.5.1

  • Freemarker Templating Samples 6.0.2

  • Groovy 3.0

  • Icons 22

  • Language Bundles 1.1

  • Machine Learning 1.2

  • Magnolia 6.2

  • Mail 5.5.3

  • Marketing Tags Manager 1.4.3

  • Multisite 2.1

  • Observation 2.2

  • Pages 6.2

  • Password Manager 1.2.3

  • Periscope 1.2

  • Personalization 2.0

  • Privacy 2.0

  • Public User Registration 2.7.3

  • Publishing 1.2

  • Publishing Transactional 1.0.5

  • Resources 3.0

  • REST Client 2.0

  • REST Client UI 1.0

  • REST Framework 2.2

  • RSS Aggregator 2.6.3

  • Scheduler 2.3.3

  • Site 1.2.4

  • SiteMesh 1.2

  • Soft Locking 3.0

  • Task Management 1.2.7

  • Third-party library BOM 6.2

  • UI 6.2

  • Usage Metrics 1.1

  • Vaadin Compatibility Addons 1.3.3

  • Workflow 6.0

How to upgrade

General recommendations

  • We recommend you first upgrade to the latest release in every intermediate Magnolia branch before upgrading to the latest release in the Magnolia 6.2 branch. For example, if you are on Magnolia 5.6.3, the upgrade path should ideally be 5.6.3 → 5.6.14 → 5.7.9 → 6.1.7 → 6.2.6.
    Read the release notes for the version you are upgrading to as well as for all intermediate versions.

  • Update all external libraries required by the Magnolia release to which you intend to upgrade.

  • Because the upgrade process takes time and is vulnerable to incidents, we recommend you minimize the risk by cleaning up your system, removing unused data, reindexing everything and doing a full backup first.

  • Once Magnolia is running, check the Definitions app for deprecated or problematic definitions.

Compatibility layer and automatic conversions

To provide a smooth transition from Magnolia 5 to Magnolia 6 UI, Magnolia 6.2.x comes with ItemProviderStrategy (magnolia-ui-framework-compatibility). With the compatibility layer, you can:

  • Reference 5 UI dialog definitions using 6 UI app actions.

  • Use 5 UI apps.

5 UI and 6 UI app definitions differ considerably. Compare, for example, the following snippets of the Contacts app, including the addContact action definition:

  • Magnolia 5 UI

  • Magnolia 6 UI

appClass: info.magnolia.ui.contentapp.ContentApp
class: info.magnolia.ui.contentapp.ConfiguredContentAppDescriptor
icon: icon-people
subApps:
  browser:
    class: info.magnolia.ui.contentapp.browser.BrowserSubAppDescriptor
    subAppClass: info.magnolia.ui.contentapp.browser.BrowserSubApp
    actions:
      addContact:
        appName: contacts
        class: info.magnolia.ui.contentapp.detail.action.CreateItemActionDefinition
        icon: icon-add-item
        nodeType: mgnl:contact
        subAppId: detail
        availability:
          root: true
          writePermissionRequired: true
          nodeTypes:
            folder: mgnl:folder
          rules:
            IsNotDeletedRule:
              implementationClass: info.magnolia.ui.framework.availability.IsNotDeletedRule
icon: icon-contacts-app
class: info.magnolia.ui.contentapp.configuration.ContentAppDescriptor
appClass: info.magnolia.ui.framework.app.BaseApp
label: Contacts V8
datasource:
  $type: jcrDatasource
  workspace: contacts
  includeProperties: true
  previewDefinition:
    nodeName: photo
  allowedNodeTypes:
    - mgnl:contact
    - mgnl:folder
    - mgnl:content
    - mgnl:contentNode
subApps:
  browser:
    class: info.magnolia.ui.contentapp.configuration.BrowserDescriptor
    actions:
      add:
        label: Add contact
        icon: icon-people
        $type: openDetailSubappAction
        appName: contacts-v8
        subAppName: detail
        viewType: add

Compare also the 5 UI and 6 UI definitions of the following dialog:

5 and 6 UI dialog definition

  • Magnolia 5 UI

  • Magnolia 6 UI

label: Dialog
form:
  tabs:
    tab:
      fields:
        fooField:
          fieldType: text
          label: Text field
actions:
  commit:
    class: info.magnolia.ui.dialog.action.SaveDialogActionDefinition
  cancel:
    class: info.magnolia.ui.dialog.action.CancelDialogActionDefinition
label: Dialog
form:
  properties:
    fooField:
      $type: textField
      label: Text field

If you decorate, include, inherit or override definitions, make sure that you do not mix 5 UI and 6 UI definitions.

Fields and validators

A number of field converters have been introduced with the Magnolia 6.2 release. For more details, see Field converters.

Migrate definitions or use converters?

There is no simple answer. Using definition converters can be a short-term solution for the move from Magnolia 5 to Magnolia 6 UI. The definition converters that we ship just adapt the old definitions to the new format at runtime.

Converters do not work with custom fields and custom validators, which must be configured using Magnolia 6 UI.

Field transformers

Magnolia 5 UI field transformer classes no longer exist in the Magnolia 6 UI framework. Their functionality is now distributed among different components. For more details, see Magnolia 6 UI ports of 5 UI field transformer classes.

Custom modules

If you have custom modules that rely on 5 UI modules:

  • Pre-built JAR files of your custom modules are binary compatible with Magnolia 6.2.x. You can add them to your WEB-INF/libs folder without any changes.

  • If you want to compile and rebuild your custom modules:

    • The composition of UI submodules has changed, and some submodules have been removed.

    • Several Magnolia stock apps have already been migrated to 6 UI. Many of the 5 UI apps have been moved to the -compatibility modules (for example, magnolia-pages-app-compatibility).

Content-type based definitions

In Magnolia 6.2.x, the !content-type directive generates a 6 UI app. This means that any overriding or decoration of a content-type based app needs to be updated to 6 UI. As an alternative, you can use the new !content-type-m5 directive to generate a 5 UI app.

/content-type-examples/apps/tourGuides-app.yaml
!content-type-m5:tourGuide
name: tourGuides-app

In this case, the app will be interpreted as a 5 UI app and you do not have to update its descriptor to 6 UI.

As of Magnolia 6.2.3, the type: reference property of a 6 UI app can be used for a 6 UI or 5 UI content type.

Customized Pages and Assets apps

With the 6.2 release, the Pages and Assets apps have been migrated to the Magnolia 6 UI framework. If in code you refer to any of them using the app ID, be aware that the ID is different in 6 UI.

App name 5 UI ID 6 UI ID

Assets

assets

dam

Pages

pages

pages-app

Due to module dependencies, most of the 5 UI apps are still included in our webapps but are hidden in the UI. They are now part of the /modules/ui-admincentral/config/appLauncherLayout/hiddenApps group.

An exception is the 5 UI Pages app, which has been removed from the CE webapps. To bring it back, you need to add magnolia-pages-app-compatibility to your webapp project.

Restoring 5 UI apps

If you want to allow authors to use, for example, the 5 UI instead of the 6 UI Pages app, the most straightforward way is:

  1. In the Configuration app, go to /modules/ui-admincentral/config/appLauncherLayout/groups/edit/apps/.

  2. Rename pages-app to pages.

  3. Go to /modules/ui-admincentral/config/appLauncherLayout/hiddenApps/.

  4. Delete the pages item.

If you want to use 5 UI apps during migration development, often side by side with 6 UI apps, here are some options:

  • Configure a role-based setup.

  • Rename or decorate an app with a different label. See Changing the title and icon of an app.

  • Reconfigure the App launcher layout of groups through /modules/ui-admincentral/config/appLauncherLayout/groups. For example, add a new Edit group for 5 UI apps.

    5 UI Edit group

Upgrading Maven-managed webapps

Upgrading your Maven-managed (custom) webapp depends on how you have organized your POM files.

Inherited BOM files

The most common use case is that your custom webapp is based on one of Magnolia’s preconfigured webapps. The structure of the Maven project that manages your webapp may look like this:

custom-project/
├── custom-project-webapp
│ ├── pom.xml (3)
│ └── src
└── pom.xml

Line 3: custom-project/custom-project-webapp/pom.xml is the POM file of your custom webapp.

custom-project/custom-project-webapp/pom.xml
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>com.example</groupId>
    <artifactId>custom-project</artifactId> (5)
    <version>1.0-SNAPSHOT</version>
    <relativePath>../pom.xml</relativePath>
  </parent>
  <artifactId>custom-project-webapp</artifactId>
  <name>custom-magnolia: webapp</name>
  <packaging>war</packaging>

  <dependencies>
    <dependency>
      <groupId>info.magnolia.dx</groupId>
      <artifactId>magnolia-dx-core-webapp</artifactId>
      <type>war</type>
    </dependency>
    <dependency>
      <groupId>info.magnolia.dx</groupId>
      <artifactId>magnolia-dx-core-webapp</artifactId>
      <type>pom</type>
    </dependency>
    <!-- More custom modules here -->
    <dependency>
      <groupId>com.example</groupId>
      <artifactId>foobar-module</artifactId>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <artifactId>maven-war-plugin</artifactId>
        <configuration>
          <!-- exclude jars copied "physically" from the webapp overlay - so we only get those resolved by Maven's dependency management -->
          <dependentWarExcludes>WEB-INF/lib/*.jar</dependentWarExcludes>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Line 5: custom-project/pom.xml is the parent POM file of your custom webapp. This file manages the dependencies and their versions.

custom-project/pom.xml
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>custom-project</artifactId>
  <name>custom-magnolia (parent pom)</name>
  <version>1.0-SNAPSHOT</version>
  <packaging>pom</packaging>

  <properties>
    <magnoliaBundleVersion>6.2</magnoliaBundleVersion>
    <foobarModuleVersion>1.2</foobarModuleVersion>
    <javaVersion>1.8</javaVersion>
  </properties>

  <scm>
    <connection/>
    <developerConnection/>
    <url/>
  </scm>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>info.magnolia.dx</groupId>
        <artifactId>magnolia-dx-core-parent</artifactId>
        <version>${magnoliaBundleVersion}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
      <!-- More dependencies for your custom modules here -->
      <dependency>
        <groupId>com.example</groupId>
        <artifactId>foobar-module</artifactId>
        <version>${foobarModuleVersion}</version>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.7.0</version>
        <configuration>
          <source>${javaVersion}</source>
          <target>${javaVersion}</target>
        </configuration>
      </plugin>
    </plugins>

    <!-- default resources configuration which will filter your module descriptors -->
    <resources>
      <resource>
        <directory>src/main/resources</directory>
        <includes>
          <include>**/*</include>
        </includes>
      </resource>
      <resource>
        <filtering>true</filtering>
        <directory>src/main/resources</directory>
        <includes>
          <include>META-INF/magnolia/*</include>
        </includes>
      </resource>
    </resources>
  </build>

  <repositories>
    <repository>
      <id>magnolia.public</id>
      <url>https://nexus.magnolia-cms.com/content/groups/public</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
    <repository>
      <id>magnolia.enterprise.releases</id>
      <url>https://nexus.magnolia-cms.com/content/repositories/magnolia.enterprise.releases</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
    <repository>
      <id>vaadin-addons</id>
      <url>https://maven.vaadin.com/vaadin-addons</url>
    </repository>
  </repositories>

  <modules>
    <module>custom-project-webapp</module>
  </modules>
</project>

Note that the parent POM (custom-project/pom.xml) manages all versions for both Magnolia modules and third-party libraries. It imports info.magnolia.dx:magnolia-dx-core-parent, which manages Magnolia DX Core module versions and imports the following:

  • info.magnolia.bundle:magnolia-bundle-parent to manage Magnolia CE module versions.

  • info.magnolia.boms:magnolia-external-dependencies to manage third-party library versions.

If the POM files for your custom webapp are organized as shown above, you will only need to change one property. In the <properties> tag of your parent POM, change the version of the magnoliaBundleVersion property:

<properties>
  <magnoliaBundleVersion>6.2</magnoliaBundleVersion> (2)
  <foobarModuleVersion>1.2</foobarModuleVersion>
  <javaVersion>1.8</javaVersion>
</properties>

Line 2: Set magnoliaBundleVersion to your required version.

Maven dependency tree

Regardless of how your Maven project is organized, building the Maven dependency tree helps you analyze the versions of all the Magnolia modules and third-party libraries of your custom webapp.

Open a shell, go to the directory of your webapp and execute the Maven command for the dependency tree:

cd /Users/jdoe/dev/repo/custom-mgnl-webapps/custom-project/custom-project-webapp
mvn dependency:tree

Upgrading manually

  1. Stop the application server.

  2. Extract the new Magnolia bundle.

  3. Replace the JAR files in the WEB-INF/lib folder of your old Magnolia instances with the new ones from the bundle.

  4. Remove any module JARs you previously removed from your instances. Add any module JARs you previously added.

  5. Add new Magnolia modules.

  6. Optional: delete the index folder in each workspace directory (repositories/magnolia/workspaces/<workspace>/index). Indexes are re-created on startup, which might take a while depending on the size of your repository.

  7. If you customized your magnolia.properties file, compare the changes to the file in the new bundle. Properties may have been added or removed.

  8. Read the release notes for all intermediate versions for any additional update tasks. See the Releases page.

  9. Restart the application server.

  10. In your browser, go to the Magnolia instances and run the web update.

Things to consider

Additional dependency for Solr module

If you are migrating from Magnolia 5.x and are using the Solr module, you need to add the following dependency to your bundle:

<dependency>
  <groupId>info.magnolia</groupId>
  <artifactId>magnolia-core-compatibility</artifactId>
</dependency>

Changes in REST Client module

With the Magnolia 6.2 release, the RESTEasy Client module has been deprecated and merged into the REST Client module 2.0. magnolia-resteasy-client has been relocated to magnolia-rest-client (see the POM file).

If your projects have a dependency on magnolia-resteasy-client, we recommend that you either:

  • Update and rebuild the projects without the dependency or

  • Add an older version of the dependency.

As of the REST Client module 2.0, ClientServiceDefinition has also been deprecated. ProxyDefinition should now be used instead.

Server push in AdminCentral

Server-side push functionality is now provided in AdminCentral. For this to work, you must update your WEB-INF/web.xml file. It must declare async support on Magnolia’s main filter.

<filter>
  <display-name>Magnolia global filters</display-name>
  <filter-name>magnoliaFilterChain</filter-name>
  <filter-class>info.magnolia.cms.filters.MgnlMainFilter</filter-class>
  <async-supported>true</async-supported>
</filter>

Since Magnolia does not support push operations over WebSockets, you must also add the following new context parameters:

<!-- The following two parameters prevent the Atmosphere Framework from attempting to install -->
<!-- JSR-356 is not needed and causes issues with our servlet setup -->
<context-param>
  <param-name>org.atmosphere.cpr.AtmosphereConfig.getInitParameter</param-name>
  <param-value>true</param-value>
</context-param>
<context-param>
  <param-name>org.atmosphere.websocket.suppressJSR356</param-name>
  <param-value>true</param-value>
</context-param>

Issues in H2 1.4.199 and 1.4.200

Our Certified stack page sets 1.4.200 as a baseline for the H2 database in Magnolia 6.2. While 1.4.200 fixes a consistency issue found in 1.4.199, it introduces another issue that may affect the structure of tables and the ability of H2 to read previously stored data.

To keep your systems and data secure, we recommend that you consider taking the following measures when upgrading to the Magnolia 6.2 branch:

  • Avoid using H2 1.4.199. This version was introduced with the following maintenance releases: 5.5.16, 5.6.13, 5.7.6 and 6.1.3.

  • If you are still running H2 1.4.192, do not upgrade to any of the maintenance releases mentioned above. Try updating to 1.4.200 and see if you experience any issues. If you come across some issues after the update, contact our support.
    Ensure that the H2 database is not exposed through your custom code modifications (for example, by accessing the database directly and exposing a query or by other payload going directly to it through your application). If you follow these recommendations, your installation will not be affected by the security issue.

  • If you have already upgraded to H2 1.4.199, downgrading is not possible due to upstream data structure changes that are incompatible with previous versions. Try updating to 1.4.200 and see if you experience any issues. If you come across some issues after the update, contact our support.

  • If you are using H2 only in development, you can either:

    • Delete the local database and downgrade to 1.4.192 or

    • Switch to another database (for example, Derby) and reinstall your local version.

Feedback