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.

Update to the latest maintenance release of Magnolia 6.3 first. You can find this at Magnolia 6.3 releases.
Read the Magnolia 6.4 Release notes.
Read the Magnolia 6.4 Certified stack and confirm that your environment matches.
Back up your system.
Verify that all custom modules are compatible with 6.4.

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

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.
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-beta2</magnoliaBundleVersion>
  <foobarModuleVersion>1.2</foobarModuleVersion>
  <javaVersion>25</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

Update dependency management to use the 6.4 version of dx-core-bundle-parent
Update the Extensions BOM if you use Extension modules.
Update your environments or Docker images to the latest Tomcat.
Update all javax dependencies to their Jakarta EE 10 equivalents.
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-beta2</magnoliaBundleVersion> (1)
  <javaVersion>17</javaVersion> (2)
</properties>

1	Ensure you’re on the latest available 6.4 release. Currently, this is `6.4.0-beta2`.
2	Java 17 (LTS) is the build base for Magnolia 6.4.

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:

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

+ . 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: * Change vaadin-server to vaadin-server-mpr-jakarta. * Change vaadin-compatibility-server to vaadin-compatibility-server-mpr-jakarta.

+ .. 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 (Digital Asset Management) 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:

Uninstall the dam-focal incubator module.
Update dependency management to use the image-focal extension version 2.0.x.

Existing focal point data is preserved when switching modules.