Upgrading from 6.3

Magnolia CMS 6.4-beta - Hardening Phase

Magnolia CMS 6.4-beta is currently in the hardening phase and is intended for testing and evaluation by experienced Magnolia partners and customers only. While we’ve provided initial Release Notes and Upgrading Guide documentation, please note that all documentation, including these guides, may be updated as we finalize features and incorporate feedback during the beta period.

Ready to share your insights?

Your feedback during this beta phase is invaluable in helping us deliver the best possible experience. Please share your thoughts and suggestions with us at 6.4-beta feedback.

Magnolia CMS 6.4 GA is coming soon with complete documentation and full production support.

This page has information about upgrading to Magnolia 6.4 from earlier Magnolia 6.3 supported versions. Before starting the upgrade process, we recommend you:

Update to the latest maintenance release of Magnolia 6.3 first.
Read the release notes for the version you are upgrading to as well as for all intermediate versions.
Read the certified stack.

If you are upgrading from a Magnolia release that has already reached its EoL (End of life), contact us for migration support.

DX Cloud customers

You must update your helm chart to the latest version.

Summary

You must not:

Override (hotfix) JCR resources in the Resource Files app before upgrading to Magnolia 6.4.
You must:
1. As always, update dependency management in your project. Use the 6.4 version of the dx-core-bundle-parent.
  - If you use extensions, import the new extensions BOM.
2. Update the publishing receivers configuration.
You might also have to:
1. Obtain your new 6.4 license and set it in your instances before updating your 6.3 bundle.
  
  If you’ve already obtained the license but forgot to set it, you can set it using a Groovy script.
2. Migrate assets from DAM 4 to DAM 6 for consistency (optional).

Platform updates

Java 17 and later

Magnolia 6.4 is built on Java 17, but also runs on the latest LTS releases, Java 21 and Java 25.

Jakarta EE 10

Magnolia 6.4 is a Jakarta EE 10 web application, requiring Tomcat 10 (version 10.0.27 or higher).

To keep the updating process from 6.3 straightforward, Magnolia 6.4 has upgraded to Jakarta EE 10, aligning with the latest EE specifications.

Examples

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 (yet identical) classes on the classpath, we recommend replacing your Maven dependencies with javax group IDs with their Jakarta EE 10 equivalents under the jakarta group ID.

Versions of these dependencies are provided in the Magnolia third-party library BOM, through the jakarta.jakartaee-bom import.

Vaadin upgrade: If you have a custom code

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.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, refer to the following resource: How to Integrate Vaadin MPR with Maven for Vaadin 8.

Changes in forms: From Vaadin to Warp forms

Magnolia 6.4 introduces Warp forms, a new UI for forms based on React and a custom front-end design system built for accessibility.

Possible issues

Your Vaadin forms will be rendered using Warp forms in 6.4, provided all fields in the form declaration have Warp counterparts.

If any Vaadin field in your form lacks a Warp counterpart, the entire form will fall back to rendering with Vaadin.

To identify unsupported fields or properties, use the Definitions app’s Problems subapp. Filter by Problem type UNSUPPORTED to see fields causing the fallback, or IGNORED for properties ignored by Warp forms.

Not all Vaadin fields and properties are supported in Warp forms. Check the Definitions app for issues and consider updating form definitions to ensure compatibility with Warp forms.

Example: Tours app - Detail subapp

This model definition, together with one decoration from the travel-demo-content-tags module (to add a TagsField), creates the Tours subapp you can see on the online demo.

model:
  nodeType: mgnl:content
  properties:
    - name: name
      required: true
    - name: description
      i18n: true
    - name: isFeatured
      type: Boolean
    - name: image
      required: true
      type: asset
    - name: tourTypes
      multiple: true
      type: reference:tourCategory
    - name: destination
      multiple: true
      type: reference:tourCategory
    - name: location
    - name: date
      type: Date
    - name: duration
      options:
        2-days:
          name: 2-days
          value: 2
        7-days:
          name: 7-days
          value: 7
        14-days:
          name: 14-days
          value: 14
        21-days:
          name: 21-days
          value: 21
      type: Long
    - name: author
    - name: body
      i18n: true
      type: richText

If you add a static field definition to the form definition of the detail subapp, the whole form falls back to Vaadin fields, as shown in the example below:

/tours/apps/tours.yaml

...
  detail:
    form:
      properties:
        name:
          i18n: true
        static: (1)
           $type: staticField
           label: Description
           value: You cannot edit this field - it's static.

1	Unsupported static field definition.

a form falling back to Vaadin fields due to the unsupported static field in form definition

Configuring Find Bar search

In Magnolia 6.4, the Find Bar has been completely overhauled. It remains the central tool for searching across all content in Magnolia, offering powerful full-text search capabilities.

The updated Find Bar in 6.4 delivers faster performance, improved result organization, and seamless integration with the Search API, designed to handle large datasets efficiently and provide relevant results quickly and intuitively.

Configuration moved to `periscope-core` module

The configuration for the Find Bar has moved from the Admincentral module to the periscope-core module in 6.4.

This is a breaking change, requiring updates to any existing decorations.

Previously, the Find Bar configuration was located at /admincentral/config.yaml. Example:

/admincentral/config.yaml

findBar:
  suggestionCountPerSupplier: 3
  defaultCountPerSupplier: 10
  minimumSearchLength: 3
...

In Magnolia 6.4, the default configuration is now located at /periscope-core/config.yaml.

/periscope-core/config.yaml

resultRankerConfiguration:
  disabled: false
globalSearchConfiguration:
  defaultCountPerSupplier: 50
  supplierOrder:
    - pages-app
    - stories
    - dam
    - tours

If you decorated the Find Bar configuration, for example:

<my-module>/decorations/admincentral/config.yaml

findBar:
  defaultCountPerSupplier: 3

You must update the decoration to target the new periscope-core module configuration in 6.4:

<my-module>/decorations/periscope-core/config.yaml

findBar:
  globalSearchConfiguration:
    defaultCountPerSupplier: 3

Deletion action changes

Deletion actions (mark for deletion, permanently delete, request permanent deletion, and content dependency warnings) have been updated to show new dialogs by default.

For most users, no configuration changes are needed and the existing actions and dialogs are automatically updated. This automatic replacement applies to the following apps:

Pages app
Assets app
All content apps (custom or Magnolia-native)

However, if you have customized deletion-related actions, some changes may affect you:

Custom DeleteNodesConfirmationAction with overridden execute method

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.
Custom DeleteNodesConfirmationAction with overridden getConfirmationMessage method

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

The following fields 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 fields no longer affect the action.
Enabling permanent deletion

If you are using ConfirmationAlertActionDefinition with successActionName set to publishDeletion or activateDeleted, the following fields 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 fields no longer apply: populate, alwaysOnTop, and any fields inherited from its parent class.

Digital Asset Management (DAM) changes

The following changes affect how you work with assets in Magnolia 6.4. Review these updates to ensure your custom implementations continue to work correctly.

Migrate assets from DAM 4 to DAM 6

In DAM 6, you can choose to store both asset metadata and binaries in JCR or to externalize binary storage to S3. In both cases, we recommend you migrate your assets.

Although migration is optional when storing asset binaries in JCR with DAM 6, the migration process updates existing assets with a property introduced in DAM 5 (mgnlBinaryReference). This property is added to all assets, regardless of storage choice, uploaded when using DAM 6. Therefore, for consistency, we recommend running the migration script when moving from DAM 4 to DAM 5 or 6 with JCR storage. Magnolia provides a migration script that you can run to update your assets.

See the DAM migration documentation for details.

Deprecation of `Asset.getContentStream()`

Instead of Asset.getContentStream(), developers should use BinaryManagementRead#streamContent(BinaryReference) from info.magnolia.dam.binary.api.

The streamContent handles retrieving the actual binary data, abstracting away the underlying storage provider (like S3).

For more information, see the DAM API documentation.

Image recognition class changes

The ImageRecogniser.recognise method signature changes from byte[] to ImageBinary.

Custom implementations of the ImageRecogniser interface will fail to compile or run unless updated to use the new ImageBinary parameter.

Third-party libraries

Third-party libraries are primarily managed using the BOM for third-party libraries.

Third-party libraries for extensions

Third-party libraries for 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 version. For other servlet containers, check out the certified stack page.

Feedback

DX Core