Page tree
Skip to end of metadata
Go to start of metadata

This page contains the information you should be aware of when you are upgrading to Magnolia 6.1 from any previous and currently supported version. Upgrading from earlier versions to Magnolia 6.1 is a straightforward process. Before starting the upgrade process, we recommend you read:

If you are migrating from Magnolia 4.4/4.5, please contact us for migration support. 

What to update

 Click to see the list of all updated and new modules released with Magnolia 6.1.

  • Advanced Cache 2.2
  • Cache 5.8
  • Campaign Publisher 1.3.1
  • Categorization 2.7
  • Community Edition 6.1
  • Contacts 1.7.1
  • Content Dependencies 1.9.1
  • Content Editor 1.3.1
  • Content Tags 1.2.1
  • Content Translation Support 2.4
  • Content Types 1.1
  • DAM 2.6
  • Definitions app 2.0
  • Demo Projects 1.4.1
  • Enterprise Edition 6.1
  • Form 2.5.2
  • Icons 21
  • LDAP support 1.10.2
  • License 1.7.1
  • Machine Learning 1.1
  • Magnolia 6.1
  • Mail 5.5.2
  • Marketing Tags Manager 1.4.2
  • Maven Archetypes 1.2.5
  • Multisite 2.0
  • Pages 6.1
  • Password Manager 1.2.2
  • Periscope 1.1
  • Personalization 1.8
  • Privacy 1.1.1
  • Public User Registration 2.7.2
  • Publishing 1.1
  • Publishing Transactional 1.0.1
  • Resources 2.7
  • REST Client 1.7
  • RSS Aggregator 2.6.2
  • Scheduler 2.3.2
  • Site 1.2.3
  • Task Management 1.2.6
  • Templating Samples 6.0.1
  • Third-party library BOM 6.1
  • UI 6.1
  • Vaadin Compatibility Addons 1.3
  • Workflow 5.7.3

Hello DX Core, farewell Enterprise Editions

(info) With the release of Magnolia 6.1, product packaging has changed. DX Core is a new edition that replaces the former Enterprise Standard and Enterprise Pro editions.

This repackaging is reflected not only in the structure of our preconfigured bundles and webapps, but also in the values for Maven groupId and artifactId elements.

For an overview of the new product packaging approach, see the Product packaging section of Magnolia 6.1 release notes.

Magnolia UI 6.1

Compared to Magnolia 5.7, Magnolia UI 6.1 contains the new design of the admin interface. See Changes in Magnolia UI 6.1 for an overview.

In Magnolia 6.1, the UI framework has been released as DEVELOPER PREVIEW.

Developer preview features may still change as their public API is not final. Try them out and send us your suggestions.

If you follow the How to update steps below on this page, the UI project is also updated automatically.

If you have custom modules that rely on UI modules of version 5.7:

  • Already built .jar files of your custom modules are binary compatible with Magnolia 6.0, you can add them to your WEB-INF/libs folder without further changes.
  • If you want to compile and rebuild your custom modules:
    The composition of submodules of the UI project has changed, some submodules have been removed. But we have created Maven relocations for the removed modules; you do not have to change the dependencies to removed modules within your custom modules.

Check the magnolia.properties file

When upgrading Magnolia, it is always worth comparing your magnolia.properties file with the one from the newly released Magnolia bundles. Below are the latest versions of the magnolia.properties files for the Magnolia 6.1 series.

Magnolia CE

ce/magnolia-empty-webapp/src/main/webapp/WEB-INF/config/default/magnolia.properties
#--------------------------------------------
# Here we define some properties not
# configured in the config repository.
# They are used in common before the initialization
# of the repositories.
#
# WARNING: on Windows systems, either use the /
# to separate path elements, or escape the \ with
# another \, i.e C:\\magnolia\\data\\repositories
# or c:/magnolia/data/repositories
#--------------------------------------------
magnolia.home=${magnolia.app.rootdir}
# The directory to expose file system resources from
magnolia.resources.dir=${magnolia.home}/modules
# Pattern to define which resources should be observed by ClasspathScanner
magnolia.resources.classpath.observation.pattern=.*\\.(ftl|yaml)$
# Directories relative to magnolia.resources.dir which will be excluded from FileResourceOrigin observation.
# Also see info.magnolia.resourceloader.file.FileSystemResourceOrigin#EXCLUDED_DIRECTORIES
#magnolia.resources.filesystem.observation.excludedDirectories=META-INF,WEB-INF,cache,docroot,logs,repositories,tmp
magnolia.cache.startdir=${magnolia.home}/cache
magnolia.upload.tmpdir=${magnolia.home}/tmp
magnolia.exchange.history=${magnolia.home}/history
magnolia.repositories.config=WEB-INF/config/default/repositories.xml
magnolia.repositories.home=${magnolia.home}/repositories
magnolia.repositories.jackrabbit.config=WEB-INF/config/repo-conf/jackrabbit-bundle-h2-search.xml

log4j.config=WEB-INF/config/default/log4j2.xml
magnolia.logs.dir=${magnolia.home}/logs

# The directories in which the bootstrap files are searched
magnolia.bootstrap.dir=WEB-INF/bootstrap/author WEB-INF/bootstrap/common

# This is only used for the initial installation afterward the configuration in the config repository is used
# The value is saved in /server/admin
magnolia.bootstrap.authorInstance=true

# Some modules contain optional sample content. They will check this property to decide if they should install
# the sample data
magnolia.bootstrap.samples=true

# Activate UTF-8 support to pages
magnolia.utf8.enabled=false

# Switch to false to enhance the performance of the javascript generation and similar
magnolia.develop=false

# Change to point at your custom Vaadin widgetset and theme
# Your widgetset should always inherit magnolia's default widgetset (info.magnolia.widgetset.MagnoliaWidgetSet)
# Your theme should always include magnolia's default theme (admincentral)
magnolia.ui.vaadin.widgetset=info.magnolia.widgetset.MagnoliaWidgetSet
magnolia.ui.vaadin.theme=admincentral

# Contact details displayed in the footer of the login form
#magnolia.service.contact=

#--------------------------------------------
# Repository connection
#--------------------------------------------
magnolia.connection.jcr.userId = admin
magnolia.connection.jcr.password = admin

# Set it to true if bootstrapping/update should be performed automatically
magnolia.update.auto=false

# Location of the file containing both the private and the public keys used to verify authenticity of activation requests
# This file is generated if not present
magnolia.author.key.location=${magnolia.home}/WEB-INF/config/default/magnolia-activation-keypair.properties

Magnolia DX Core
dx-core/magnolia-dx-core-webapp/src/main/webapp/WEB-INF/config/default/magnolia.properties
#--------------------------------------------
# Here we define some properties not
# configured in the config repository.
# They are used in common before the initialization
# of the repositories.
#
# WARNING: on Windows systems, either use the /
# to separate path elements, or escape the \ with
# another \, i.e C:\\magnolia\\data\\repositories
# or c:/magnolia/data/repositories
#--------------------------------------------
magnolia.home=${magnolia.app.rootdir}
# The directory to expose file system resources from
magnolia.resources.dir=${magnolia.home}/modules
# Pattern to define which resources should be observed by ClasspathScanner
magnolia.resources.classpath.observation.pattern=.*\\.(ftl|yaml)$
# Directories relative to magnolia.resources.dir which will be excluded from FileResourceOrigin observation.
# Also see info.magnolia.resourceloader.file.FileSystemResourceOrigin#EXCLUDED_DIRECTORIES
#magnolia.resources.filesystem.observation.excludedDirectories=META-INF,WEB-INF,cache,docroot,logs,repositories,tmp
magnolia.cache.startdir=${magnolia.home}/cache
magnolia.upload.tmpdir=${magnolia.home}/tmp
magnolia.exchange.history=${magnolia.home}/history
magnolia.repositories.config=WEB-INF/config/default/repositories.xml
magnolia.repositories.home=${magnolia.home}/repositories
magnolia.repositories.jackrabbit.config=WEB-INF/config/repo-conf/jackrabbit-bundle-h2-search.xml

log4j.config=WEB-INF/config/default/log4j2.xml
magnolia.logs.dir=${magnolia.home}/logs

# The directories in which the bootstrap files are searched
magnolia.bootstrap.dir=WEB-INF/bootstrap/author WEB-INF/bootstrap/common

# This is only used for the initial installation afterward the configuration in the config repository is used
# The value is saved in /server/admin
magnolia.bootstrap.authorInstance=true

# Some modules contain optional sample content. They will check this property to decide if they should install
# the sample data
magnolia.bootstrap.samples=true

# Activate UTF-8 support to pages
magnolia.utf8.enabled=false

# Switch to false to enhance the performance of the javascript generation and similar
magnolia.develop=false

# Change to point at your custom Vaadin widgetset and theme
# Your widgetset should always inherit magnolia's Pro widgetset (info.magnolia.widgetset.MagnoliaProWidgetSet)
magnolia.ui.vaadin.widgetset=info.magnolia.widgetset.MagnoliaProWidgetSet
# Your theme should always include magnolia's default theme (admincentral)
magnolia.ui.vaadin.theme=admincentral

# Contact details displayed in the footer of the login form
#magnolia.service.contact=

#--------------------------------------------
# Repository connection
#--------------------------------------------
magnolia.connection.jcr.userId = admin
magnolia.connection.jcr.password = admin

# Set it to true if bootstrapping/update should be performed automatically
magnolia.update.auto=false

# Location of the file containing both the private and the public keys used to verify authenticity of activation requests
# This file is generated if not present
magnolia.author.key.location=${magnolia.home}/WEB-INF/config/default/magnolia-activation-keypair.properties

Apache Tomcat

Version 9.0.10

If you use Apache Tomcat, note that we have upgraded to Apache Tomcat 9.0.10. We recommend this update since it fixes some possible security vulnerabilities.

If you use another servlet container, check the certified stack for supported versions.

Server configuration with relaxed query chars

Tomcat 9 has become less tolerant of special characters when compared to some of its predecessor versions. To bring back support for special characters as it was on Tomcat 8 - for instance, to query the Delivery endpoint API with filters - we have added the characters [], and | to the relaxedQueryChars attribute on the Connector element in the server.xml configuration file. 

Third-party libraries

All changes in third-party libraries are managed via the BOM for third-party modules . If you manage your bundles via Maven using the BOM, all updates are handled automatically. Among the most notable third-party library updates in the Magnolia 6.1 release are:

  • Vaadin 8.8.2
  • Guava 27.1
  • Tika 1.20
  • Jackrabbit 2.18.1
  • Ehcache 3.7.1
    Note: Due to an incompatibility issue, the items that are persisted on disk will be deleted after updating.

How to upgrade

Recommendations

  • You should be able to upgrade to the latest release in the 6.1 branch of Magnolia directly from any previous Magnolia release that has not reached End-of-Life. Only if you have UI or style customizations, we recommend that you first update to the latest release in the Magnolia 5 branch and then to the latest release in the Magnolia 6 branch. For example: 5.6.8 → 5.7.4 → 6.1.

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

Licensing

(warning) The former Enterprise licenses used in pre-6.1 Magnolia Enterprise editions are not compatible with DX Core edition.

The holders of Enterprise licenses are required to request new licenses for DX Core.

To obtain the license, get in touch with the contact person assigned to you in your contract or contact us directly via info@magnolia-cms.com. See also the License page for more information.

Upgrading manually

  1. Stop the application server.
  2. Extract the new Magnolia bundle.
  3. Replace JAR files in the WEB-INF/lib folder of your old Magnolia instances with new JARs from the bundle. Also replace modules coming from the add-ons bundle (magnolia-enterprise-addons-bundle), in case you are using any of these.
    Magnolia 6.1 updates numerous 3rd-party libraries, see Third-party libraries.
  4. Remove any module JARs you had previously removed from your instances. Add any modules you may have previously added.
  5. Add new Magnolia modules.
  6. Optional: Delete all indexes to give them a boost. Delete the index folder under each workspace directory: repositories/magnolia/workspaces/<workspace>/index. Indexes are recreated on startup, which might take a while depending on the size of your repository.
  7. If you customized your magnolia.properties files, compare the changes to the file in the new bundle. Properties may have been added or removed.
  8. Read the release notes for all intermediate versions for any additional update tasks. See the Releases page.
  9. Restart the application server.
  10. In your browser, go to the Magnolia instances and run the web update.

Upgrading Maven-managed webapps

In this section, we assume that you use Maven to manage your (custom) webapp. How you do this depends on how you have organized your pom files.

Upgrading the versions of inherited BOM files

The most typical 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
│   └── src
└── pom.xml
Line 3: custom-project/custom-project-webapp/pom.xml is the pom file of your custom webapp.

 Click to see an example

custom-project/custom-project-webapp/pom.xml
<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>
    <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. 

 Click to see an example

custom-project/pom.xml
<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.1</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/content/groups/public</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
    <repository>
      <id>magnolia.enterprise.releases</id>
      <url>https://nexus.magnolia-cms.com/content/repositories/magnolia.enterprise.releases</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 Magnolia modules as well as for third-party libraries.

It imports info.magnolia.dx:magnolia-dx-core-parent, which manages Magnolia Enterprise module versions and imports the following:

  • info.magnolia.bundle:magnolia-bundle-parent – manages Magnolia CE module versions.
  • info.magnolia.boms:magnolia-external-dependencies – manages third-party library versions.

If the pom files for your custom webapp are organized as shown in this example, you only need to change one property. In the <properties> section of your parent pom, change the version of the magnoliaBundleVersion property:

<properties>
  <magnoliaBundleVersion>6.1</magnoliaBundleVersion>
  <foobarModuleVersion>1.2</foobarModuleVersion>
  <javaVersion>1.8</javaVersion>
</properties>
Line 2: Set the magnoliaBundleVersion to your required version. That is all you need to change in the pom files of your webapp.

Checking the 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 all the 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

Other aspects

Use the !content-type directive

In app descriptors, if you refer to content type definitions, use the !content-type directive. For example:

!content-type:tourGuide
name: tourGuides-app

This should be of concern to you if you are upgrading from Magnolia 6.0 or 5.7.2+, where the directive was !with-type:

!with-type:tourGuide
name: tourGuides-app

Known issues

See the Known issues page.

  • No labels