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

Magnolia 6.2 brings significant changes to the UI framework, including changes to app and dialog configuration.

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, we recommend that you always update to the latest supported version. For other servlet containers, check out the certified stack.

Server configuration with relaxedQueryChars

Advanced query filters in the Delivery API require extra Tomcat configuration, namely setting relaxedQueryChars="[]|".

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.

How to upgrade

General recommendations

  • We recommend you first upgrade to the latest release in both your current branch and every intermediate Magnolia branch still maintained before upgrading to the latest release in the Magnolia 6.2 branch. For example, if you are on Magnolia 5.7.3, the upgrade path should ideally be 5.7.3 → 5.7.33 (the last maintenance release in the 5.7 branch) → 6.2.44.
    Read the release notes for the version you are upgrading to as well as for all intermediate versions.

    In the 5.7 branch of Magnolia, the maintenance releases since the release of Magnolia CORE 5.7.20 (inclusive) were Extended end-of-life (EEoL) releases.

    If your contract does not cover these EEoL releases, you would ignore them in the upgrade path.

    For example, if you are on Magnolia 5.7.3, the upgrade path should then ideally be 5.7.3 → 5.7.19 (the last release under regular maintenance) → 6.2.44.

  • 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 assist in the transition from Magnolia 5 UI to Magnolia 6 UI, Magnolia 6.2.x comes with a compatibility layer.

Compatibility features

  • 6 UI apps are used by default, but 5 UI apps can be restored.

  • 5 UI dialogs and fields can be used with 5 UI apps.

  • 5 UI dialog definitions can be referenced using 6 UI app actions. Attempts will be made to convert the definitions on the fly.

  • Most 5 UI fields can still be used in the 6 UI Pages app.

Migration guidelines

  • Custom fields, field validators, field transformers and link previews in 5 UI cannot be converted to 6 UI.

  • If you have custom fields in 5 UI, you will need to do one of the following:

    • Remove them or replace them with Magnolia stock 6 UI fields.

    • If they are only used in component dialogs, use the 5 UI Pages app instead of the default 6 UI app.

    • Migrate them to 6 UI along with any dialogs and apps that use them.

    • Create field converters for them (not recommended).

  • If you change your content model due to dialog migrations, you will need to migrate your content as well. Content migrations can be done with update tasks in a module version handler (Java) or via the Groovy app.

  • If you have other customizations of the Magnolia stocks apps (such as custom actions or configuration decorations), you will need to either migrate your customizations or use 5 UI apps.

  • If you have custom modules, use pre-built JARs or rebuild your modules.

  • When your system is functioning properly, you can go into production or perform additional migration.

  • Whenever possible, migrate your remaining 5 UI app and dialog definitions to get rid of all deprecated items and have consistent 6 UI definitions.

To migrate your dialog definitions, you can use the Migration Tool module. If you still need help with your migration project, contact our Services team.

Migrating dialogs

With the compatibility layer, most 5 UI dialogs will continue to work properly in 6 UI. However, you may need to migrate a 5 UI dialog if it uses a custom field or if you want to have a field validator (which the compatibility layer does not support).

If you have a custom field and do not want to migrate your 5 UI dialog, you can also create a converter for that field.

See the following dialog and its 5 UI and 6 UI configurations:

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

6 UI dialogs require no action definitions. A number of layout options are now available at the form level.

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

Migrating fields and validators

Since Magnolia 6.2, a number of field converters have been introduced to convert 5 UI field definitions at runtime to 6 UI. For more details, see Field converters.

Custom fields cannot be converted to 6 UI. To migrate a custom field, it is recommended that you reconfigure it in 6 UI.

Compare how the following implementations differ in both frameworks:

To create field validators in 6 UI, see Field validators.

Migrating 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.

Migrating block and custom content editor definitions, internationalization

Custom content editor and block definitions created in the Magnolia 5 UI framework must be migrated for use with the Content Editor module (version 2.1 and later).

Similarly, Internationalization (i18n) of content in the Content Editor module and the Stories app is fully supported since version 2.1 of the module. For more details about migration, see Content Editor module: Content internationalization (i18n).

Migrating content 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

For a step-by-step guide on how to migrate an app, see Migrating an app to Magnolia 6 UI.

Migrating content-type based apps

In Magnolia 6.2.x, the !content-type directive generates a 6 UI app. This means that any overriding or decoration of the app needs to be updated to 6 UI.

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

As an alternative, you can use the new !content-type-m5 directive to generate a 5 UI app.

/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 app definition 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.

Migrating customized Magnolia apps

With the 6.2 release, several Magnolia apps have been migrated to the 6 UI framework. Update any existing app decorations to 6 UI.

If in code you refer to the Pages or Assets app 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

Migrating Blossom dialogs

The Blossom module is generally compatible with Magnolia 6 UI apps, including the 6 UI Pages app. For more details, see Blossom module: Updating to Magnolia 6.2.

Definition builders

The 6 UI framework no longer provides definition builders. Use plain definitions via constructors and setters.

The following third-party library provides builders for 6 UI definitions:

merkle-open/magnolia-definition-builders

Restoring 5 UI apps

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.

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. Create a new pages item.

  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.

    === Migrating 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).

Upgrading webapps

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/repository/public</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
    <repository>
      <id>magnolia.enterprise.releases</id>
      <url>https://nexus.magnolia-cms.com/repository/enterprise</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

Updating Personalization module

Updating

Updating to Personalization 2.1.x is only possible from the 2.0.x module versions. To update from the Magnolia 5 UI Personalization module (1.6.x versions), you need to update to Personalization 2.0 first.

Bundling

Magnolia 6.2 webapps are shipped with the Personalization 2.0.x module versions.

Personalization and Delivery API

Personalization support for the Delivery API is only available in Personalization 2.1.0 or higher.

Updating magnolia-dam-app-jcr

Updating magnolia-dam-app-jcr (a submodule in the Digital Asset Management module) to version 3.0.6 or later involves fixing possibly corrupted nodes in the dam workspace, which may take a long time if the workspace is large.

For this, a faster but possibly less reliable executor (QueryTask) has been implemented. In case of any inconsistencies, run the update task manually. For more details about this issue, see MGNLDAM-939.

Additional dependency for older versions of Solr module

If you are migrating from Magnolia 5.x and are using version 5.2.2 or earlier of 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.

FreeMarker built-in ?children in ContentMapModel

As part of MAGNOLIA-7156, the built-in ?children function in info.magnolia.freemarker.models.ContentMapModel now returns List<ContentMap> instead of Collection<Node>. This may cause an error in info.magnolia.templating.functions.TemplatingFunctions#asContentMap if the retrieved items are already converted to ContentMap in an earlier version.

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.

Known issues

See the Known issues page.

Related topics
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules