Upgrading from 6.2

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 guide outlines the steps to upgrade from DX-Core 6.2 to 6.4, including database considerations and repository migration.

Upgrading summary

Notes on Demo projects

  • Demo projects may encounter issues due to missing classes, as some were dropped or modified in newer versions.

  • Migration of demo webapps is not recommended, as new demo data is typically generated for 6.4.

Database considerations

  • The H2 database is not supported for this upgrade due to version incompatibility.

  • Use the Derby embedded database as a replacement for seamless migration.

  1. Prepare DX-Core 6.2 Environment

    • Ensure DX-Core 6.2 is running.

    • Zip the author and public repositories for migration.

  2. Set Up DX-Core 6.4 Environment

    • Install DX-Core 6.4.

    • Extract the zipped author and public repositories from 6.2 to their corresponding instances in 6.4.

  3. Migrate Keypairs

    • Copy the keypairs generated in DX-Core 6.2.

    • Paste them into the appropriate configuration in DX-Core 6.4.

  4. Verify Functionality

    • Launch all applications in DX-Core 6.4 to confirm they are operational.

    • Publish simple pages to validate basic functionality.

  5. Test New Features

    • Focus on testing the new deletion dialogs introduced in DX-Core 6.4, as this was the primary objective of the upgrade.

Upgrading in detail

  • Update to the latest maintenance release of Magnolia 6.2 first, then to the latest maintenance release of Magnolia 6.3, and finally to Magnolia 6.4.

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

Aspects to be aware of

  • 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. Convert select JCR definitions to YAML. YAML can no longer inherit from JCR-based definitions.

    2. Migrate CKEditor4 customizations.

    3. Obtain your new 6.4 license and set it in your instances before updating your bundle.

      If you’ve already obtained the license but forgot to set it, you can set it using a Groovy script.

    4. Review your site/multisite configurations as they may need some adjustment to work properly on 6.4 (changes started in 6.3).

    5. SSO module

      1. Remove the outdated SSO Login Extension incubator. The functionality is incorporated in version 4.0.0 of the SSO module.

      2. If you use SSO 3.1.x and upgrade to 4.0.0, you must change your configuration.

    6. Migrate Content Editor v2 and multi-language stories.

    7. Revalidate your 6.2 user group and role assignments for use in 6.4. Access control to JCR workspaces, URIs and apps has been updated to newer roles that your editors may not have. Make use of the new default groups in the product: editors, publishers, and developers.

    8. Check that your REST endpoint definitions work as intended. There are a few changes to optionality of REST properties in 6.4 (building on 6.3) that may have impact on the functionality of REST delivery in your webapps.

    9. If you’ve built advanced custom configuration sources or registries, adjust to reworked configuration sources in Magnolia 6.4 (introduced in 6.3).

    10. If you rely on MySQL, update the MySQL repository configuration.

    11. Adapt module app definitions to match the new App Launcher design.

    12. Update any decorations that overwrite or enhance the confirmDeletion action in the Pages or Assets app.

    13. Make sure that your decorating configuration files have config in the filename, for example, /rest-services/decorations/cache/config.contentCaching.yaml. This wasn’t required on the Magnolia 6.2 branch.

    14. Add new superusers to the publishers group if they need to publish.

    15. Update H2 from version 2.1.x to 2.3.x. For more details about the migration, see H2-upgrade.

    16. 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. (Note: Magnolia 6.3 required Java 17 but also ran on Java 21.)

Jakarta EE progression

To keep the updating process from 6.2 straightforward, Magnolia 6.3 remained on the Jakarta EE 8 baseline. However, Magnolia 6.4 upgrades to Jakarta EE 10, requiring Tomcat 10 (version 10.0.27 or higher).

In preparation for breaking updates, Magnolia 6.3 updated the Maven coordinates of the EE 8 API specifications. In 6.4, these are further updated to EE 10 equivalents.

Examples
javax.json:javax.json-api   >> jakarta.json:jakarta.json-api (in 6.3) >> jakarta.json:jakarta.json-api:2.0 (in 6.4)

To avoid duplicate (yet identical) classes on the classpath, we recommend you replace your Maven dependencies with javax group id, with their Jakarta EE 10 equivalents under the jakarta group id.

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

See also Certified stack.

MicroProfile Config

Magnolia 6.3 embraced MicroProfile Config, adding state-of-the-art flexibility for external instance configuration. This is applied first to publishing receivers config, and requires a project update.

Publishing receivers config must be migrated.

Vaadin upgrade: If you have a custom code

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

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

    mvn org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta

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

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

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

Reworked configuration sources

In 6.3 (and carried forward to 6.4), we have overhauled internals of our definition Registries and ConfigurationSources, effectively inverting dependency between the two:

  • Registries now pull definitions from ConfigurationSources.

  • Previously, ConfigurationSources needed to push definitions into Registries.

This enables greater flexibility to add custom configuration sources (including fetching from remote backends) and manage dependent definition types. It also streamlines definition observation.

As a consequence, YAML can no longer inherit from JCR-based definitions through the !inherit directive. You have to inline or migrate the JCR definitions into YAML instead.

I18nAuthoringSupport

This change affects customers using Live Copy with custom i18n implementations, as well as several incubator modules.

The I18nAuthoringSupport interface and the default implementations have been consolidated. Deprecated methods have been removed.

It is no longer configured as an observed component at /server/i18n/authoring in JCR, but as a regular component mapping in module descriptor.

MultiSiteI18nAuthoringSupport is already reconfigured this way.

If you have a custom I18nAuthoringSupport class configured in JCR, you have to provide it via module descriptor instead.

<component>
  <type>info.magnolia.ui.api.i18n.I18NAuthoringSupport</type>
  <implementation>com.custom.i18n.CustomI18nAuthoringSupport</implementation>
  <scope>singleton</scope>
</component>

CKEditor 4 customizations

If you have customized your CKEditor 4, you may continue using it in Magnolia 6.4 (as in 6.3). For this, you must set the new rich text field field property ckEditorVersion to CKEDITOR_4.

By default, the property is set to CKEDITOR_5.

CKEditor 4 migration to CKEditor 5

Magnolia 6.2 uses CKEditor 4 in its rich text field. Magnolia 6.3 is released with CKEditor 5. While most field properties from Magnolia 6.2 are supported, CKEditor 4 and CKEditor 5 are very different in their core architecture. For this reason, Magnolia recommends previewing any content transferred from CKEditor 4 in Magnolia 6.2 and checking that the content is published as you want it.

In particular, you should check their compatibility tables for configuration and plugins to determine which content might be affected. Furthermore, follow their migration guidelines to ensure a smooth transition of any content.

Plugins in the Magnolia ckeditor5-build

For a list of plugins included in the Magnolia ckeditor5-build, see ckeditor5.ts.

See also Migration from CKEditor 4 (ckeditor.com/docs/).

Old module packs, new extensions

The modules listed in the table below were previously incubator modules but are now fully-supported extensions in Magnolia 6.4 (introduced in 6.3).

Module New license? Notes

AI Accelerator

Requires a license renewal and is no longer free.


If you are already using any of these modules, contact your Magnolia account manager. We will provide you with the required license key(s).

Cloudinary External DAM module

Requires a license renewal and is no longer free.


If you are already using any of these modules, contact your Magnolia account manager. We will provide you with the required license key(s).

Campaign Manager

Upgrade the module to its latest 6.4-compatible version and benefit from a full SLA.

Content Translation Support Ext

Upgrade the module to its latest 6.4-compatible version and benefit from a full SLA.

Content Translation Support Ext: DeepL

Upgrade the module to its latest 6.4-compatible version and benefit from a full SLA.

UI Framework JavaScript

Upgrade the module to its latest 6.4-compatible version and benefit from a full SLA.

REST Proxy

Upgrade the module to its latest 6.4-compatible version and benefit from a full SLA.

CDP Integration Framework: Segment

Upgrade the module to its latest 6.4-compatible version and benefit from a full SLA.

Previously bundled modules

Some of the modules in the new "Extension" category are previously bundled modules that are now unbundled, meaning you need to install them individually.

  • Campaign Publisher

  • LDAP Connector module

  • Privacy module

For the latest information about module bundling, see the List of modules on the Modules page.

Multisite definitions in YAML

In Magnolia 6.4 (introduced in 6.3), sites work like any other definition type:

  • They are collected into a conventional registry.

  • They support YAML definitions natively.

  • They are displayed in the Definitions app.

Configuration sources and paths

The sources of site definitions have changed considerably since Magnolia 6.3.0 (and apply to 6.4). Sites can no longer be configured by decorating the Multisite module configuration.

  • You must move site configuration to <module-name>/sites/ in your light module, as shown in the travel-demo-multisite example.

  • You should provide your own fallback site configuration in <module-name>/sites/fallback.yaml. Otherwise, the system infers one automatically, with either the English or German locale.

Sites in multisite/config/sites are still loaded (for backward compatibility) but can’t be decorated.
In Magnolia 6.2, a fallback site could be a folder. In Magnolia 6.3, it has to be a node.

Site app removed

The Site App module and app are no longer available in Magnolia 6.4 (removed in 6.3.0). Site definitions, including their source locations, can be verified in the Definitions app.

Site definitions see in the Definitions app

SSO changes

SSO 4.0.x module introduces several important updates and requirements (introduced in 6.3, applies to 6.4). This includes compatibility adjustments, mandatory configuration changes, removal of certain classes, optional enhancements like JCR-based fallback login, and considerations for users of the SSO Login Extension module.

For specific actions and modifications needed to ensure a smooth upgrade, see Upgrading from SSO 3.1.x to 4.0.0.

Content Editor definitions

Magnolia 6.4 ships only with v2 of the Content Editor (as in 6.3). If you use the Content Editor or a Content Editor-based app, you must migrate your custom v1 Content Editor definitions to the scheme used in v2.

For more details about migration, see Content i18n and migration to version 2.1 (and higher).

Password module dependency in Marketing Automation module

There is an issue when using the Marketing Automation module. Since module version 2.0.0, Marketing Automation has a dependency on magnolia-password-manager-core instead of magnolia-module-password-manager.

Use the following dependency exclusion as a workaround if you want to use the Marketing Automation module:

...
    <dependency>
      <groupId>info.magnolia.marketingautomation</groupId>
      <artifactId>magnolia-marketing-automation</artifactId>
      <version>${marketing-automation.version}</version>
      <exclusions>
        <exclusion>
          <groupId>info.magnolia.passwordmanager</groupId>
          <artifactId>magnolia-module-password-manager</artifactId>
        </exclusion>
      </exclusions>
    </dependency>
...

Pages and Assets app definition changes

This section applies if you are upgrading through 6.3.0. If you are upgrading through 6.3.1, disregard this section and refer to Upgrading to Magnolia 6.3.1 and later instead. The remainder of this page remains relevant when upgrading to 6.4.

In 6.3.1, the filteringWorkbench introduced in 6.3.0 for Pages and Assets apps is deprecated. The in-app search and filter functionality becomes the default for all browser subapps as part of the standard workbench definition instead.

Due to the new search experience, notably the return of in-app search functionality, the Pages and Assets app definition files have changed significantly (introduced in 6.3, applies to 6.4). This may impact you if you customized the configuration of columns or filters in these apps.

For more information about how to configure in-app filters, see Configuring search in Magnolia.

Click to see 6.4 (aligned with 6.3) and 6.2 app definitions.

  • 6.4 app definition

  • 6.2 app definition

workbench:
  $type: filteringWorkbench # Introduced filteringWorkbench, currently supported only in Pages and Assets apps, with the following sub-configuration options
  sortFilterOptions: true # Sorts the filters by their labels from A-Z; by default, it gets the order from the definition mapping
  searchEnabled: true # Enables the full-text-search field; true by default
  searchPlaceholder: Type to search... # Placeholder for the full-text-search field
  filters: # Default configured filter fields
    - name: mgnl:createdBy
      icon: icon-user-public
      filterOperator: EQUALS
      $type: dropdownMultiselect
      datasource:
        name: available-filtering-users
    - name: jcrPublishingStatus
      icon: icon-spinner-full
      $type: dropdownMultiselect
      datasource:
        $type: enumDatasource
        enumeration: info.magnolia.ui.contentapp.configuration.column.StatusColumnDefinition$PublicationStatus
    - name: mgnl:template
      icon: icon-view
      $type: dropdownMultiselect
      datasource:
        name: available-filtering-page-templates
  contentViews:
    - name: tree # Content view now enables a single view; by default, the tree view
      dropConstraint:
        class: info.magnolia.pages.app.TemplateTypeRestrictionDropConstraintDefinition
      multiSelect: true
      rowStyleGenerator: info.magnolia.ui.contentapp.row.StatusRowStyleGenerator
      $type: treeView
      filterableColumns: false # Add this property to disable the column filter; this is for backwards compatibility
      columns:
        jcrName:
          $type: jcrComponentColumn
          nodeTypeToComponents:
            mgnl:page:
              showPath: true
        title:
          name: title
        mgnl:template:
          editable: false
          class: info.magnolia.pages.app.column.TemplateNameColumnDefinition
          sortable: false
        jcrPublishingStatus:
          $type: jcrStatusColumn
          width: 130
        mgnl:lastModified:
          $type: dateColumn
          editable: false
          width: 200
statusBar: # Status bar can now be configured
  implementationClass: info.magnolia.ui.filteringapp.browser.FilteringStatusBar----
workbench:
  contentViews:
    - name: tree
      dropConstraint:
        class: info.magnolia.pages.app.TemplateTypeRestrictionDropConstraintDefinition
      multiSelect: true
      $type: treeView
      columns:
        jcrName: &jcrNameColumn
          $type: jcrTitleColumn
          nodeTypeToIcon:
            mgnl:page: icon-webpages-app
        title: &titleColumn
          filterComponent:
            $type: textField
        mgnl:template: &templateColumn
          editable: false
          class: info.magnolia.pages.app.column.TemplateNameColumnDefinition
          filterComponent:
            $type: comboBoxField
            emptySelectionAllowed: true
            textInputAllowed: true
            filteringMode: CONTAINS
            datasource:
              name: available-page-templates
        jcrPublishingStatus: &activationStatusColumn
          $type: jcrStatusColumn
          width: 130
        mgnl:lastModified: &lastModifiedColumn
          $type: dateColumn
          editable: false
          width: 200
    - name: list
      $type: listView
      multiSelect: true
      columns:
        jcrName: *jcrNameColumn
        jcrPath:
          $type: jcrPathColumn
        title: *titleColumn
        mgnl:template: *templateColumn
        jcrPublishingStatus: *activationStatusColumn
        mgnl:lastModified: *lastModifiedColumn
The new search experience configuration changes only apply to the Pages and Assets apps. Other apps are unaffected.

Deletion workflow

In addition to the search experience-related definition changes, two definition changes support the usability improvements in the deletion workflow. Namely, the new action confirmMarkDeletion replaces confirmDeletion, and the delete action is renamed markDeleted.

Any decorations that overwrite or enhance the confirmDeletion action in the Pages or Assets app won’t work in Magnolia 6.4 because it uses the new confirmMarkDeletion action.
confirmDeletion is unchanged, so its use in custom modules is unaffected.

User group and role changes

The system of user roles has been updated in Magnolia 6.4 (introduced in 6.3).

In the core of the system is now a unified role naming convention of type <module>-<privilege> (for example pages-publisher, admincentral-editor).

Superuser role modified

By default, the superuser role doesn’t grant publishing permissions. In particular, a user assigned the superuser role doesn’t get messages in the Tasks app unless the user is also added to the publishers group.

Publishers group modified

We have added several new roles to the publishers group. This includes roles with permissions to read and write on pages and assets.

If you do not want your publishers to have these permissions, update your groups.

New roles

  • admincentral-developer

  • admincentral-editor

    (New role that can block access to URLs.)

  • asset-editor

  • category-editor

  • dam-app-core-editor

  • dam-app-jcr-editor

  • definitions-app-developer

  • diff-viewer

  • graphql-developer

  • imaging-editor

  • marketingTag-editor

  • page-editor

  • pages-app-editor

  • resources-editor

  • story-editor

  • tour-editor

  • tourCategory-editor

Renamed roles

  • workflow-editor from editor

  • workflow-publisher from publisher

Removed roles

  • contact-base

  • rss-aggregator-base

New group

  • developer

Removed compatibility modules

The following Magnolia compatibility modules were removed from the DX Core webapp (in 6.3, applies to 6.4):

  • info.magnolia.categorization:magnolia-categorization-app-compatibility

  • info.magnolia.contenttags:magnolia-content-tags-ui-compatibility

  • info.magnolia.dam:magnolia-dam-app-compatibility

  • info.magnolia.dependencies:magnolia-content-dependencies-ui-compatibility

  • info.magnolia.diff:magnolia-diff-compatibility

  • info.magnolia.personalization:magnolia-personalization-compatibility

  • info.magnolia.workflow:magnolia-workflow-compatibility

Changes in REST Delivery API

Updated REST packages

Make sure you are using the updated packages in REST version 3.0.0 and later, not the deprecated ones.

Examples

  • info.magnolia.rest.delivery.DeliveryContext (deprecated: info.magnolia.rest.delivery.jcr.v2.DeliveryContext)

  • info.magnolia.rest.delivery.OutputStreamWrapper (deprecated: info.magnolia.rest.delivery.jcr.OutputStreamWrapper)

Check your endpoint definitions

You should check your REST endpoint definitions to make sure they work as expected, even if you aren’t using custom values in the definitions.

$type property required in endpoint definitions

The $type property is now required in endpoint definitions.

Set it to either jcrDeliveryEndpoint_v2, or to the recently introduced jcrPagesDeliveryEndpoint_v2 on your project’s delivery endpoint definitions.

Default value for depthInReferencedNode

Since Magnolia 6.3.0 (and in 6.4), the default value for the depthInReferencedNode property is 1, not -1 as before in Magnolia 6.2.x.

Default value for maxLimit

The default value for the maxLimit property is 100. Before, it was 1000.

Deprecations from Magnolia code not reported

To minimize the risk of introducing a faulty configuration into your instance, the Definitions app no longer displays select deprecations and other implementation details, specifically those whose origin is in Magnolia code (introduced in 6.3, applies to 6.4).

Click to see which error messages are now suppressed.

5 UI framework (deprecated)

  • info.magnolia.ui.form.field.definition.

  • info.magnolia.ui.workbench.column.definition.

  • info.magnolia.ui.framework.tools.

  • info.magnolia.ui.api.action.ConfiguredActionDefinition

    • (implementationClass)

  • info.magnolia.ui.api.app.launcherlayout.ConfiguredAppLauncherGroupDefinition

    • (color)

  • info.magnolia.ui.api.availability.ConfiguredAvailabilityRuleDefinition

    • (implementationClass)

  • info.magnolia.ui.contentapp.configuration.column.ColumnDefinition

    • (filterComponent)

  • info.magnolia.ui.contentapp.configuration.column.ConfiguredColumnDefinition

    • (renderer, type, valueProvider)

  • info.magnolia.ui.ConfiguredViewDefinition

    • (implementationClass)

  • info.magnolia.ui.field.MultiFieldDefinition

    • (propertyNameDecorator, entryResolution, orderHandler)

  • info.magnolia.ui.field.CompositeFieldDefinition

    • (propertyNameDecorator)

  • info.magnolia.ui.field.ConfiguredFieldDefinition

    • (factoryClass, converterClass)

  • info.magnolia.ui.field.ConfiguredSwitchableFieldDefinition

    • (propertyNameDecorator)

Diff module (deprecated)

  • info.magnolia.module.diff

    The Diff module is still injectable for compatibility.

MySQL

The default MySQL repository configuration has changed to the Connector/J (in 6.3, applies to 6.4).

For MySQL Connector/J 8.x (and later), use the configuration is called jackrabbit-bundle-mysql8-search.xml and is available in /WEB-INF/config/repo-conf/.

If you rely on MySQL, you must update this.

App Launcher design

The Magnolia 6.3 App Launcher uses a modern naming and groupings. The original Magnolia 6.2 classic naming and grouping is no longer available in Magnolia 6.3.

If you used a custom configuration of the App Launcher in Magnolia 6.2, you must migrate your definition for the 6.3 App Launcher.

For more, see App-Launcher-migration-guide.

General upgrading procedure

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

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

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

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

magnolia.properties file

When upgrading Magnolia, 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.

  • Magnolia CE

  • Magnolia DX Core

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</magnoliaBundleVersion>
  <foobarModuleVersion>1.2</foobarModuleVersion>
  <javaVersion>17</javaVersion>
</properties>
...

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

×

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