Upgrading to Magnolia 6.3

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

Update to the latest maintenance release of Magnolia 6.2 first.
Read the release notes for the version you are upgrading to as well as for all intermediate versions.
Read the certified stack.
Be aware that breaking changes affecting browser subapp definitions were introduced in 6.3.1. If you’re upgrading to 6.3.1 or later, after reading this page (notably the section on Pages and Assets app definition changes), make sure you also refer to Upgrading to Magnolia 6.3.1 and later.

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. For more, see Magnolia 6.3 Helm version.

Summary

You must not:

Override (hotfix) JCR resources in the Resource Files app before upgrading to Magnolia 6.3.
You must:
1. As always, update dependency management in your project. Use the 6.3 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.3 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.
4. Review your site/multisite configurations as they may need some adjustment to work properly on 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.3. 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.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.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. Add new superusers to the publishers group if they need to publish.
14. Update H2 from version 2.1.x to 2.3.x. For more details about the migration, see H2 database.

Platform updates

Java 17

Magnolia 6.3 requires Java 17, but also runs on Java 21 (latest LTS).

Jakarta EE 8

To keep the updating process from 6.2 straightforward, Magnolia 6.3 remains on the Jakarta EE 8 baseline.

However, in preparation for the upcoming breaking update to Jakarta EE 9+, we have updated the Maven coordinates of the EE 8 API specifications.

Examples

javax.inject:javax.inject:1 >> jakarta.inject:jakarta.inject-api:1.0
javax.json:javax.json-api   >> jakarta.json:jakarta.json-api

To avoid duplicate (yet identical) classes on the classpath, we recommend you do the same by replacing your Maven dependencies with javax group id, with their Jakarta EE 8 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.

MicroProfile Config

Magnolia 6.3 embraces 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 (see immediately below).

Configuring publishing receivers

Publishing receivers are configured using MicroProfile Config. You can supply MicroProfile configurations using:

properties files
YAML files
system properties or environment variables (and more)

To point to your config file, you must pass the magnolia.config.locations as a system property (for example, using Tomcat VM options in the setenv.sh configuration file), pointing to the directory where your config file resides (for example -Dmagnolia.config.locations=/opt/magnolia/mounted-config).

microprofile-config.properties
microprofile-config.yaml

magnolia.publishing.receivers[0].name=magnoliaPublic-0
magnolia.publishing.receivers[0].url=http://dev-magnolia-helm-public-0-svc:8080
magnolia.publishing.receivers[1].name=magnoliaPublic-1
magnolia.publishing.receivers[1].url=http://dev-magnolia-helm-public-1-svc:8080

magnolia:
  publishing:
    receivers:
      - name: magnoliaPublic-0
        url: http://dev-magnolia-helm-public-0-svc:8080
      - name: magnoliaPublic-1
        url: http://dev-magnolia-helm-public-1-svc:8080

The default receiver for local development (magnoliaPublic8080) has been removed.

Receiver example for local development

magnolia.publishing.receivers[0].name=magnoliaPublic
magnolia.publishing.receivers[0].url=http://{host}:{port}/magnoliaPublic (1)

1	Put the path `magnoliaPublic` in the URL for local development.

Previous (Magnolia 6.2) definition in JCR

In Magnolia 6.2, publishing receivers were configured in JCR, under the publishing-core module. This made it difficult to provision instances across multiple environments and configure receivers during installation or startup through various JCR bootstrapping techniques.

Node name	Value
📁 modules
📁 publishing-core
📁 config
⸬ receivers
⸬ magnoliaPublic8080
⬩ url	http://localhost:8080/magnoliaPublic
⬩ enabled	true

Node name

Value

📁 modules

📁 publishing-core

📁 config

⸬ receivers

⸬ magnoliaPublic8080

⬩ url

http://localhost:8080/magnoliaPublic

⬩ enabled

true

Reworked configuration sources

In 6.3, 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.3. For this, you must set the new 6.3 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.

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

Module	New license?	Notes
AI Accelerator 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).
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 module		Upgrade the module to its latest 6.3-compatible version and benefit from a full SLA.
Content Translation Extended module		Upgrade the module to its latest 6.3-compatible version and benefit from a full SLA.
CTSX DeepL Translator		Upgrade the module to its latest 6.3-compatible version and benefit from a full SLA.
JavaScript UI module		Upgrade the module to its latest 6.3-compatible version and benefit from a full SLA.
REST Proxy module		Upgrade the module to its latest 6.3-compatible version and benefit from a full SLA.
Segment CDP extension		Upgrade the module to its latest 6.3-compatible version and benefit from a full SLA.

Module

New license?

Notes

AI Accelerator 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).

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 module