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.

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

Summary

  • 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 a new license for the 6.3 Extensions.

    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.

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 smallrye.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 -Dsmallrye.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

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

Some modules that were previously incubator modules are now fully-supported extensions in Magnolia 6.3.

The following modules now require a license renewal and are no longer free:

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

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

Multisite definitions in YAML

In Magnolia 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. 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.

Site app removed

The Site App module and app are no longer available in Magnolia 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. 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.3 ships only with v2 of the Content Editor. 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).

Pages and Assets app definition changes

Due to the new search experience, notably the return of in-app search functionality, the Pages and Assets app definition files have changed significantly. 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.3 and 6.2 app definitions.

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

User group and role changes

The system of user roles has been updated in Magnolia 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).

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

Roles removed

  • contact-base

  • rss-aggregator-base

New group

  • developer

Removed compatibility modules

The following Magnolia compatibility modules were removed from the DX Core webapp:

  • 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

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

Details of select implementation aspects aren’t reported

To minimize the risk of introducing a faulty configuration into your instance, the Definitions app no longer displays specific deprecations and other implementation details (implementation classes, field types, or converter classes).

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.

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.

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 latest release in the 6.3 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.3.

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.3</magnoliaBundleVersion>
  <foobarModuleVersion>1.2</foobarModuleVersion>
  <javaVersion>1.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.

Related topics
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
6.3 beta
X

Magnolia 6.3 beta

Magnolia 6.3 is in beta. We are updating docs based on development and feedback. Consider the 6.3 docs currently in a state of progress and not final.

We are working on some 6.3-beta known issues during this phase.