Upgrading to Magnolia 6.4

Upgrading to Magnolia 6.4 introduces important platform updates, new features, and compatibility changes that require careful planning. This guide helps you through the upgrade process based on your current Magnolia version, highlighting mandatory steps, potential pitfalls, and recommended best practices.

If you are currently running on Magnolia 6.2 and wish to upgrade to Magnolia 6.4, please follow the instructions on the Upgrading to Magnolia 6.3 page first and then return here.

Upgrading for the first time? Click to see more guidance.

Because the upgrade process takes time and is vulnerable to incidents, we recommend you minimize the risk:

  • Clean up your system

  • Remove unused data

  • Reindex everything

  • Do a full backup first

Latest maintenance release

  1. First, upgrade to the latest maintenance release of your current Magnolia version.

    For example, if you are on Magnolia 6.3.6, the upgrade path should ideally be 6.3.6 → the last maintenance release on the 6.3 branch → the latest release on the 6.4 branch.

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

Maven-managed webapps

  • Parent POM

    Update the parent pom.xml file of your webapp. In the <properties> tag of your parent POM, change the version of the magnoliaBundleVersion property:

    ...
<properties>
  <magnoliaBundleVersion>6.4.0-rc3</magnoliaBundleVersion>
  <foobarModuleVersion>1.2</foobarModuleVersion>
  <javaVersion>21</javaVersion>
</properties>
...

  • Magnolia Extensions

    Magnolia extensions are managed using a separate BOM, see the extensions-bom file.

  • Servlet container

    If you use Apache Tomcat, we recommend that you always update to the latest supported Tomcat version. For other servlet containers, check out the certified stack.

The magnolia.properties file

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

Required changes

  1. Update dependency management to use the 6.4 version of dx-core-bundle-parent

  2. Update the Extensions BOM if you use Extension modules.

  3. Update your environments or Docker images to the latest Tomcat.

  4. Update all javax dependencies to their Jakarta EE 10 equivalents. This includes any extension versions; you must update everything at the same time before initiating the upgrade.

  5. Migrate your custom code for Jakarta EE 10 compatibility and Java dependencies.

Update your Magnolia bundle version

Update the Magnolia bundle version in your project’s parent pom.xml:

<properties>
  <magnoliaBundleVersion>6.4.0-rc3</magnoliaBundleVersion> (1)
  <javaVersion>17</javaVersion> (2)
</properties>
1 Ensure you’re on the latest available 6.4 release. Currently, this is 6.4.0-rc3.
2 Java 17 (LTS) is the build base for Magnolia 6.4.

IP security filter

From Magnolia 6.4 and later, new instances don’t bootstrap the ipConfig configuration for the ipSecurity filter. If you add the filter configuration without providing the corresponding MicroProfile Config, your instance can become temporarily inaccessible.

If your environment uses IP-based access control, review and update your configuration as part of the upgrade:

  1. In the Configuration app, check whether /server/filters/ipSecurity exists. By default, on fresh 6.4 instances, it isn’t present, and no IP restriction is enforced out of the box.

  2. If you rely on the ipSecurity filter, add the filter configuration and define its ipConfig for the necessary allow/deny lists via MicroProfile Config.

  3. Restart your instance to ensure MicroProfile Config values are applied.

  4. Verify that access behaves as expected from both allowed and disallowed IP addresses.

For more details, see IP security.

Jakarta EE 10

Magnolia 6.4 is a Jakarta EE 10 web application.

You must:

  • Use the latest supported Tomcat release.

    For other servlet containers, see the Certified stack.

  • Update Maven dependencies from javax group IDs to their Jakarta equivalents.

    Example dependency changes
    javax.inject:javax.inject:1 >> jakarta.inject:jakarta.inject-api:2.0
javax.json:javax.json-api   >> jakarta.json:jakarta.json-api:2.0
    To avoid duplicate classes on the classpath, replace all javax dependencies with their Jakarta EE 10 equivalents.

    Versions of these dependencies are provided in Magnolia’s third-party library BOM via the jakarta.jakartaee-bom import. For more details, see Certified stack: Maven coordinates.

To upgrade to Vaadin 6.4 with custom code, follow these steps:

  1. Add the following to your pom.xml under <build><plugins> to declare the rewrite-maven-plugin:

          <plugin>
        <groupId>org.openrewrite.maven</groupId>
        <artifactId>rewrite-maven-plugin</artifactId>
        <version>6.8.1</version>
        <dependencies>
          <dependency>
            <groupId>org.openrewrite.recipe</groupId>
            <artifactId>rewrite-migrate-java</artifactId>
            <version>3.11.0</version>
          </dependency>
        </dependencies>
      </plugin>

  2. Run the following Maven command to migrate from javax to jakarta:

    mvn org.openrewrite.maven:rewrite-maven-plugin:run -Drewrite.activeRecipes=org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta

  3. If your project depends on vaadin-server or vaadin-compatibility-server, update the artifactId by appending -mpr-jakarta to ensure compatibility with Jakarta EE.

    For example:

    1. Change vaadin-server to vaadin-server-mpr-jakarta.

    2. Change vaadin-compatibility-server to vaadin-compatibility-server-mpr-jakarta.

  4. Verify that no non-Jakarta Vaadin dependencies are included by running:

    mvn dependency:tree -Dincludes=com.vaadin:vaadin-server,com.vaadin:vaadin-compatibility-server -Dverbose=true

    For additional details on integrating Vaadin MPR with Maven for Vaadin 8, see Vaadin: How to Integrate Vaadin MPR with Maven for Vaadin 8.

New UI Forms

Magnolia 6.4 introduces New UI Forms, a React-based forms UI built for accessibility and consistency. Vaadin-based forms are rendered with New UI Forms only when every field in the form declaration has a New UI Forms counterpart; otherwise, the entire form falls back to Vaadin.

Migration notes

  • If you don’t want to use the New UI Forms yet, add the $type property to the existing form definition and set it to vaadinForm:

    ...
    detail:
        form:
            $type: vaadinForm
            properties:
...

  • Not all Vaadin fields and properties have New UI Forms equivalents. Expect to update some form definitions.

  • Update custom field implementations to provide New UI counterparts where possible, or replace usages with supported fields.

  • Test complex or decorated forms (subapps, decorated definitions). Decorations can introduce unsupported fields.

  • Use the Definitions app Problems tab as your primary diagnostic tool. Resolve UNSUPPORTED fields first to avoid unexpected Vaadin fallbacks; review IGNORED properties to understand changes in behaviour.

  • removePreviouslySelected is not supported:

    In 6.4 Switchable fields, setting removePreviouslySelected=false is not supported in New UI Forms.

    If you rely on this property in your templates, see how to migrate removePreviouslySelected.

For more details, see Migrating to New UI Forms.

Global Search

In Magnolia 6.4, Global Search takes center stage, replacing the Magnolia 6.3 Find Bar. Global Search is the central tool for searching across all content in Magnolia. It’s designed to handle large datasets efficiently and provide relevant results quickly and intuitively.

Global Search is optimized for most use cases, so you typically don’t need to modify the default search settings.

If you need to update the configuration, note it has moved from the Admincentral module to the periscope-core module in 6.4 (now located in /periscope-core/config.yaml).

Deletion action changes

Label and message properties in deletion actions are no longer supported. Deletion actions (mark for deletion, permanently delete, request permanent deletion, and content dependency warnings) are updated to show the new dialogs by default.

For most users, no configuration changes are needed and the existing actions and dialogs are automatically updated. If you have extended default actions, you may have to revalidate behavior.

This automatic replacement doesn’t apply to the following apps: Campaign Publisher, Configuration, Cookies, External DAM, JCR, Security, and Tags.

Click to see details of cases requiring configuration updates

  • DeleteNodesConfirmationAction

    • If you have extended DeleteNodesConfirmationAction and overridden the execute method without calling super.execute();, the new 6.4 confirmation dialogs will not appear automatically. Update or remove your customization.

    • If you have overridden getConfirmationMessage, your custom message no longer applies. The 6.4 dialogs don’t support customization.

    • The following properties in DeleteNodesConfirmationActionDefinition no longer apply: confirmationHeader, confirmationMessage, successActionName, cancelActionName, proceedLabel, cancelLabel, defaultCancel.

  • Marking items for deletion with dependency warnings enabled

    If you are using DependencyAwareConfirmationActionDefinition (which extends DeleteNodesConfirmationActionDefinition), the same limitations as above apply. Inherited properties no longer affect the action.

  • Enabling permanent deletion

    If you are using ConfirmationAlertActionDefinition with successActionName set to publishDeletion or activateDeleted, the following properties no longer apply: confirmationHeader, confirmationMessage, cancelActionName, proceedLabel, cancelLabel, defaultCancel.

  • Requesting permanent deletion

    If you are using OpenDialogActionDefinition with dialogId set to workflow-pages:publishDeletion, the following properties no longer apply: populate, alwaysOnTop, and any properties inherited from its parent class.

Digital Asset Management (DAM) changes

In Magnolia 6.4, you can decouple asset binary storage to an external system while managing metadata in Magnolia’s native DAM. This reduces the size of the JCR, speeds up publishing, and improves search performance by optimizing metadata storage. See the DAM documentation for details about implementing external binary storage. Migration scripts are provided to move assets from JCR to S3.

DAM module 5.0 and DAM module 6.0 provide almost identical functionality and code. The deciding factor for which version to use is the Magnolia version you are running.

  • DAM 5.0 is compatible with Magnolia 6.3 and requires an opt-in approach. In Magnolia 6.3, DAM 4.x remains the default.

  • DAM 6.0 is compatible with Magnolia 6.4, is the default in version 6.4, and follows the 6.4 lifecycle.

Upgrade from Hybrid Assets incubator

This step applies only if you used the Hybrid Assets incubator module.

The functionality offered by the incubator module is replaced by DAM 5.0 and later. If you used the incubator module, use the migration scripts to move your assets to the new implementation.

The DAM module offers out-of-the-box integration with AWS S3. To use other providers, you must write a custom implementation.

Upgrade from the DAM Focal incubator

This step applies only if you used the DAM Focal incubator module (dam-focal).

In 6.2 and 6.3, DAM Focal was provided as an incubator module. In 6.4, it is promoted to a DX Core extension with a new module name: image-focal. The Magnolia 6.4-compatible version of this extension is 2.0.

To upgrade:

  1. Uninstall the dam-focal incubator module.

  2. Update dependency management to use the image-focal extension version 2.0.x.

Existing focal point data is preserved when switching modules.

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