Upgrading to Magnolia 6.2
This page contains information about upgrading to Magnolia 6.2.x from any previous and currently supported version. Before starting the upgrade process, we recommend you read:
-
The release notes for the version you are upgrading to as well as for all intermediate versions.
-
The certified stack.
If you are upgrading from a Magnolia release that has already reached end of life, contact us for migration support.
Migration strategies for Magnolia 6.2
Magnolia 6.2 brings significant changes to the UI framework, including changes to app and dialog configuration.
There are two different strategies for migrating to Magnolia 6.2, each with its advantages and disadvantages:
-
Migrate apps, dialogs and fields gradually and use the compatibility layer.
Advantages |
Disadvantages |
|
|
-
Migrate everything upfront (see Changes in Magnolia 6 UI).
Advantages |
Disadvantages |
|
|
What to update
pom.xml
file
It is critical that you update the parent pom.xml
file of your webapp, which
manages all versions for both Magnolia modules and third-party libraries.
For more details, see Upgrading Maven-managed webapps.
magnolia.properties
file
When upgrading Magnolia, it is recommended that you 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.2.
Apache Tomcat
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.
|
Third-party libraries
All changes in third-party libraries are managed via the BOM for third-party libraries. If you manage your bundles via Maven using the BOM, all updates will be handled automatically.
How to upgrade
General recommendations
-
We recommend you first upgrade to the latest release in both your current branch and every intermediate Magnolia branch still maintained before upgrading to the latest release in the Magnolia 6.2 branch. For example, if you are on Magnolia 5.7.3, the upgrade path should ideally be 5.7.3 → 5.7.33 (the last maintenance release in the 5.7 branch) → 6.2.52.
Read the release notes for the version you are upgrading to as well as for all intermediate versions.In the 5.7 branch of Magnolia, the maintenance releases since the release of Magnolia CORE 5.7.20 (inclusive) were Extended end-of-life (EEoL) releases.
If your contract does not cover these EEoL releases, you would ignore them in the upgrade path.
For example, if you are on Magnolia 5.7.3, the upgrade path should then ideally be 5.7.3 → 5.7.19 (the last release under regular maintenance) → 6.2.52.
-
Update all external libraries required by the Magnolia release to which you intend to upgrade.
-
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.
-
Once Magnolia is running, check the Definitions app for deprecated or problematic definitions.
Compatibility layer and automatic conversions
To assist in the transition from Magnolia 5 UI to Magnolia 6 UI, Magnolia 6.2.x comes with a compatibility layer.
Compatibility features
-
6 UI apps are used by default, but 5 UI apps can be restored.
-
5 UI dialogs and fields can be used with 5 UI apps.
-
5 UI dialog definitions can be referenced using 6 UI app actions. Attempts will be made to convert the definitions on the fly.
-
Most 5 UI fields can still be used in the 6 UI Pages app.
Migration guidelines
-
Custom fields, field validators, field transformers and link previews in 5 UI cannot be converted to 6 UI.
-
If you have custom fields in 5 UI, you will need to do one of the following:
-
Remove them or replace them with Magnolia stock 6 UI fields.
-
If they are only used in component dialogs, use the 5 UI Pages app instead of the default 6 UI app.
-
Migrate them to 6 UI along with any dialogs and apps that use them.
-
Create field converters for them (not recommended).
-
-
If you change your content model due to dialog migrations, you will need to migrate your content as well. Content migrations can be done with update tasks in a module version handler (Java) or via the Groovy app.
-
If you have other customizations of the Magnolia stocks apps (such as custom actions or configuration decorations), you will need to either migrate your customizations or use 5 UI apps.
-
If you have custom modules, use pre-built JARs or rebuild your modules.
-
When your system is functioning properly, you can go into production or perform additional migration.
-
Whenever possible, migrate your remaining 5 UI app and dialog definitions to get rid of all deprecated items and have consistent 6 UI definitions.
To migrate your dialog definitions, you can use the Migration Tool module. If you still need help with your migration project, contact our Services team. |
Migrating dialogs
With the compatibility layer, most 5 UI dialogs will continue to work properly in 6 UI. However, you may need to migrate a 5 UI dialog if it uses a custom field or if you want to have a field validator (which the compatibility layer does not support).
If you have a custom field and do not want to migrate your 5 UI dialog, you can also create a converter for that field.
See the following dialog and its 5 UI and 6 UI configurations:
label: Dialog
form:
tabs:
tab:
fields:
fooField:
fieldType: text
label: Text field
actions:
commit:
class: info.magnolia.ui.dialog.action.SaveDialogActionDefinition
cancel:
class: info.magnolia.ui.dialog.action.CancelDialogActionDefinition
label: Dialog
form:
properties:
fooField:
$type: textField
label: Text field
6 UI dialogs require no action definitions. A number of layout options are now available at the form level.
If you decorate, include, inherit or override definitions, make sure that you do not mix 5 UI and 6 UI definitions. |
Migrating fields and validators
Since Magnolia 6.2, a number of field converters have been introduced to convert 5 UI field definitions at runtime to 6 UI. For more details, see Field converters.
Custom fields cannot be converted to 6 UI. To migrate a custom field, it is recommended that you reconfigure it in 6 UI.
Compare how the following implementations differ in both frameworks:
To create field validators in 6 UI, see Field validators.
Migrating field transformers
Magnolia 5 UI field transformer classes no longer exist in the Magnolia 6 UI framework. Their functionality is now distributed among different components. For more details, see Magnolia 6 UI ports of 5 UI field transformer classes.
Migrating block and custom content editor definitions, internationalization
Custom content editor and block definitions created in the Magnolia 5 UI framework must be migrated for use with
the Content Editor module (version 2.1
and later).
Similarly, Internationalization (i18n) of content in the Content Editor module and the Stories app is fully supported since version 2.1
of the module. For more details about migration, see Content Editor module: Content internationalization (i18n).
Migrating content apps
5 UI and 6 UI app definitions differ considerably. Compare,
for example, the following snippets of the Contacts app,
including the addContact
action definition:
appClass: info.magnolia.ui.contentapp.ContentApp
class: info.magnolia.ui.contentapp.ConfiguredContentAppDescriptor
icon: icon-people
subApps:
browser:
class: info.magnolia.ui.contentapp.browser.BrowserSubAppDescriptor
subAppClass: info.magnolia.ui.contentapp.browser.BrowserSubApp
actions:
addContact:
appName: contacts
class: info.magnolia.ui.contentapp.detail.action.CreateItemActionDefinition
icon: icon-add-item
nodeType: mgnl:contact
subAppId: detail
availability:
root: true
writePermissionRequired: true
nodeTypes:
folder: mgnl:folder
rules:
IsNotDeletedRule:
implementationClass: info.magnolia.ui.framework.availability.IsNotDeletedRule
icon: icon-contacts-app
class: info.magnolia.ui.contentapp.configuration.ContentAppDescriptor
appClass: info.magnolia.ui.framework.app.BaseApp
label: Contacts V8
datasource:
$type: jcrDatasource
workspace: contacts
includeProperties: true
previewDefinition:
nodeName: photo
allowedNodeTypes:
- mgnl:contact
- mgnl:folder
- mgnl:content
- mgnl:contentNode
subApps:
browser:
class: info.magnolia.ui.contentapp.configuration.BrowserDescriptor
actions:
add:
label: Add contact
icon: icon-people
$type: openDetailSubappAction
appName: contacts-v8
subAppName: detail
viewType: add
For a step-by-step guide on how to migrate an app, see Migrating an app to Magnolia 6 UI.
Migrating content-type based apps
In Magnolia 6.2.x, the !content-type
directive generates a 6 UI
app. This means that any overriding or decoration of the app needs to be updated to 6 UI.
!content-type:tourGuide
name: tourGuides-app
As an alternative, you
can use the new !content-type-m5
directive to generate a 5 UI
app.
!content-type-m5:tourGuide
name: tourGuides-app
In this case, the app will be interpreted as a 5 UI app and you do not have to update its app definition to 6 UI.
As of Magnolia 6.2.3, the
|
Migrating customized Magnolia apps
With the 6.2 release, several Magnolia apps have been migrated to the 6 UI framework. Update any existing app decorations to 6 UI.
If in code you refer to the Pages or Assets app using the app ID, be aware that the ID is different in 6 UI.
App name | 5 UI ID | 6 UI ID |
---|---|---|
Assets |
|
|
Pages |
|
|
Migrating Blossom dialogs
The Blossom module is generally compatible with Magnolia 6 UI apps, including the 6 UI Pages app. For more details, see Blossom module: Updating to Magnolia 6.2.
Definition builders
The 6 UI framework no longer provides definition builders. Use plain definitions via constructors and setters. The following third-party library provides builders for 6 UI definitions:
|
Restoring 5 UI apps
Due to module dependencies, most of the 5 UI apps are still included
in our webapps but are
hidden in
the UI. They are now part of the
/modules/ui-admincentral/config/appLauncherLayout/hiddenApps
group.
An exception is the 5 UI Pages app, which has been removed from the CE
webapps. To bring it back, you need to add
magnolia-pages-app-compatibility
to your webapp project.
If you want to allow authors to use, for example, the 5 UI instead of the 6 UI Pages app, the most straightforward way is:
-
In the Configuration app, go to
/modules/ui-admincentral/config/appLauncherLayout/groups/edit/apps/
. -
Create a new
pages
item. -
Go to
/modules/ui-admincentral/config/appLauncherLayout/hiddenApps/
. -
Delete the
pages
item.
If you want to use 5 UI apps during migration development, often side by side with 6 UI apps, here are some options:
-
Configure a role-based setup.
-
Rename or decorate an app with a different label. See Changing the title and icon of an app.
-
Reconfigure the App launcher layout of groups through
/modules/ui-admincentral/config/appLauncherLayout/groups
. For example, add a new Edit group for 5 UI apps.=== Migrating custom modules
If you have custom modules that rely on 5 UI modules:
-
Pre-built JAR files of your custom modules are binary compatible with Magnolia 6.2.x. You can add them to your
WEB-INF/libs
folder without any changes. -
If you want to compile and rebuild your custom modules:
-
The composition of UI submodules has changed, and some submodules have been removed.
-
Several Magnolia stock apps have already been migrated to 6 UI. Many of the 5 UI apps have been moved to the
-compatibility
modules (for example,magnolia-pages-app-compatibility
).
-
Upgrading webapps
Upgrading Maven-managed webapps
Upgrading your Maven-managed (custom) webapp depends on how you have organized your POM files.
Inherited BOM files
The most common use case is that your custom webapp is based on one of Magnolia’s preconfigured webapps. The structure of the Maven project that manages your webapp may look like this:
custom-project/
├── custom-project-webapp
│ ├── pom.xml (3)
│ └── src
└── pom.xml
Line 3: custom-project/custom-project-webapp/pom.xml
is the POM file
of your custom webapp.
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>com.example</groupId>
<artifactId>custom-project</artifactId> (5)
<version>1.0-SNAPSHOT</version>
<relativePath>../pom.xml</relativePath>
</parent>
<artifactId>custom-project-webapp</artifactId>
<name>custom-magnolia: webapp</name>
<packaging>war</packaging>
<dependencies>
<dependency>
<groupId>info.magnolia.dx</groupId>
<artifactId>magnolia-dx-core-webapp</artifactId>
<type>war</type>
</dependency>
<dependency>
<groupId>info.magnolia.dx</groupId>
<artifactId>magnolia-dx-core-webapp</artifactId>
<type>pom</type>
</dependency>
<!-- More custom modules here -->
<dependency>
<groupId>com.example</groupId>
<artifactId>foobar-module</artifactId>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<artifactId>maven-war-plugin</artifactId>
<configuration>
<!-- exclude jars copied "physically" from the webapp overlay - so we only get those resolved by Maven's dependency management -->
<dependentWarExcludes>WEB-INF/lib/*.jar</dependentWarExcludes>
</configuration>
</plugin>
</plugins>
</build>
</project>
Line 5: custom-project/pom.xml
is the parent POM file of your custom
webapp. This file manages the dependencies and their versions.
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>custom-project</artifactId>
<name>custom-magnolia (parent pom)</name>
<version>1.0-SNAPSHOT</version>
<packaging>pom</packaging>
<properties>
<magnoliaBundleVersion>6.2</magnoliaBundleVersion>
<foobarModuleVersion>1.2</foobarModuleVersion>
<javaVersion>1.8</javaVersion>
</properties>
<scm>
<connection/>
<developerConnection/>
<url/>
</scm>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>info.magnolia.dx</groupId>
<artifactId>magnolia-dx-core-parent</artifactId>
<version>${magnoliaBundleVersion}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<!-- More dependencies for your custom modules here -->
<dependency>
<groupId>com.example</groupId>
<artifactId>foobar-module</artifactId>
<version>${foobarModuleVersion}</version>
</dependency>
</dependencies>
</dependencyManagement>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.7.0</version>
<configuration>
<source>${javaVersion}</source>
<target>${javaVersion}</target>
</configuration>
</plugin>
</plugins>
<!-- default resources configuration which will filter your module descriptors -->
<resources>
<resource>
<directory>src/main/resources</directory>
<includes>
<include>**/*</include>
</includes>
</resource>
<resource>
<filtering>true</filtering>
<directory>src/main/resources</directory>
<includes>
<include>META-INF/magnolia/*</include>
</includes>
</resource>
</resources>
</build>
<repositories>
<repository>
<id>magnolia.public</id>
<url>https://nexus.magnolia-cms.com/repository/public</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
<repository>
<id>magnolia.enterprise.releases</id>
<url>https://nexus.magnolia-cms.com/repository/enterprise</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
<repository>
<id>vaadin-addons</id>
<url>https://maven.vaadin.com/vaadin-addons</url>
</repository>
</repositories>
<modules>
<module>custom-project-webapp</module>
</modules>
</project>
Note that the parent POM (custom-project/pom.xml
) manages all versions
for both Magnolia modules and third-party libraries. It imports
info.magnolia.dx:magnolia-dx-core-parent
, which manages Magnolia DX Core
module versions and imports the following:
-
info.magnolia.bundle:magnolia-bundle-parent
to manage Magnolia CE module versions. -
info.magnolia.boms:magnolia-external-dependencies
to manage third-party library versions.
If the POM files for your custom webapp are organized as shown above,
you will only need to change one property. In the <properties>
tag
of your parent POM, change the version of the magnoliaBundleVersion
property:
<properties>
<magnoliaBundleVersion>6.2</magnoliaBundleVersion> (2)
<foobarModuleVersion>1.2</foobarModuleVersion>
<javaVersion>1.8</javaVersion>
</properties>
Line 2: Set magnoliaBundleVersion
to your required version.
Maven dependency tree
Regardless of how your Maven project is organized, building the Maven dependency tree helps you analyze the versions of all the Magnolia modules and third-party libraries of your custom webapp.
Open a shell, go to the directory of your webapp and execute the Maven command for the dependency tree:
cd /Users/jdoe/dev/repo/custom-mgnl-webapps/custom-project/custom-project-webapp
mvn dependency:tree
Upgrading manually
-
Stop the application server.
-
Extract the new Magnolia bundle.
-
Replace the JAR files in the
WEB-INF/lib
folder of your old Magnolia instances with the new ones from the bundle. -
Remove any module JARs you previously removed from your instances. Add any module JARs you previously added.
-
Add new Magnolia modules.
-
Optional: delete the
index
folder in each workspace directory (repositories/magnolia/workspaces/<workspace>/index
). Indexes are re-created on startup, which might take a while depending on the size of your repository. -
If you customized your
magnolia.properties
file, compare the changes to the file in the new bundle. Properties may have been added or removed. -
Read the release notes for all intermediate versions for any additional update tasks. See the Releases page.
-
Restart the application server.
-
In your browser, go to the Magnolia instances and run the web update.
Things to consider
Updating Personalization module
- Updating
-
Updating to Personalization 2.1.x is only possible from the 2.0.x module versions. To update from the Magnolia 5 UI Personalization module (1.6.x versions), you need to update to Personalization 2.0 first.
- Bundling
-
Magnolia 6.2 webapps are shipped with the Personalization 2.0.x module versions.
- Personalization and Delivery API
-
Personalization support for the Delivery API is only available in Personalization 2.1.0 or higher.
Updating magnolia-dam-app-jcr
Updating magnolia-dam-app-jcr
(a submodule in the Digital Asset Management module) to version 3.0.6 or later involves fixing possibly corrupted nodes in the dam
workspace, which may take a long time if the workspace is large.
For this, a faster but possibly less reliable executor (QueryTask
) has been implemented. In case of any inconsistencies, run the update task manually. For more details about this issue, see MGNLDAM-939.
Additional dependency for older versions of Solr module
If you are migrating from Magnolia 5.x and are using version 5.2.2 or earlier of the Solr module, you need to add the following dependency to your bundle:
<dependency>
<groupId>info.magnolia</groupId>
<artifactId>magnolia-core-compatibility</artifactId>
</dependency>
Changes in REST Client module
With the Magnolia 6.2 release, the RESTEasy Client module
has been deprecated and merged into the REST Client module 2.0.
magnolia-resteasy-client
has been relocated to magnolia-rest-client
(see the POM file).
If your projects have a dependency on magnolia-resteasy-client
, we
recommend that you either:
-
Update and rebuild the projects without the dependency or
-
Add an older version of the dependency.
As of the REST Client module 2.0, ClientServiceDefinition
has also been deprecated. ProxyDefinition
should now be used instead.
FreeMarker built-in ?children
in ContentMapModel
As part of MAGNOLIA-7156, the built-in ?children
function in info.magnolia.freemarker.models.ContentMapModel
now returns List<ContentMap>
instead of Collection<Node>
.
This may cause an error in info.magnolia.templating.functions.TemplatingFunctions#asContentMap
if the retrieved items are already converted to ContentMap
in an earlier version.
Server push
in Admincentral
Server-side push
functionality is now provided in Admincentral. For
this to work, you must update your WEB-INF/web.xml
file. It must
declare async support on Magnolia’s main filter.
<filter>
<display-name>Magnolia global filters</display-name>
<filter-name>magnoliaFilterChain</filter-name>
<filter-class>info.magnolia.cms.filters.MgnlMainFilter</filter-class>
<async-supported>true</async-supported>
</filter>
Since Magnolia does not support push
operations over WebSockets, you
must also add the following new context parameters:
<!-- The following two parameters prevent the Atmosphere Framework from attempting to install -->
<!-- JSR-356 is not needed and causes issues with our servlet setup -->
<context-param>
<param-name>org.atmosphere.cpr.AtmosphereConfig.getInitParameter</param-name>
<param-value>true</param-value>
</context-param>
<context-param>
<param-name>org.atmosphere.websocket.suppressJSR356</param-name>
<param-value>true</param-value>
</context-param>
Issues in H2 1.4.199 and 1.4.200
Our Certified stack page sets 1.4.200 as a baseline for the H2 database in Magnolia 6.2. While 1.4.200 fixes a consistency issue found in 1.4.199, it introduces another issue that may affect the structure of tables and the ability of H2 to read previously stored data.
To keep your systems and data secure, we recommend that you consider taking the following measures when upgrading to the Magnolia 6.2 branch:
-
Avoid using H2 1.4.199. This version was introduced with the following maintenance releases: 5.5.16, 5.6.13, 5.7.6 and 6.1.3.
-
If you are still running H2 1.4.192, do not upgrade to any of the maintenance releases mentioned above. Try updating to 1.4.200 and see if you experience any issues. If you come across some issues after the update, contact our support.
Ensure that the H2 database is not exposed through your custom code modifications (for example, by accessing the database directly and exposing a query or by other payload going directly to it through your application). If you follow these recommendations, your installation will not be affected by the security issue. -
If you have already upgraded to H2 1.4.199, downgrading is not possible due to upstream data structure changes that are incompatible with previous versions. Try updating to 1.4.200 and see if you experience any issues. If you come across some issues after the update, contact our support.
-
If you are using H2 only in development, you can either:
-
Delete the local database and downgrade to 1.4.192 or
-
Switch to another database (for example, Derby) and reinstall your local version.
-
Known issues
See the Known issues page.