This documentation is still in progress. We are working hard to update all our screenshots to the new Magnolia 6 style. Please bear with us.

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.0.x from any previous and currently supported version.

Upgrading from Magnolia 5.7 (and earlier versions) to Magnolia 6.0 is a straightforward process.

Changes on the APIs are marginal and backwards compatibility is provided.

(warning) Please be aware that to upgrade to and use Magnolia 6 you need to obtain a new license if you are using an Enterprise edition. 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.

Before starting the upgrade process, we recommend you read:

If you are migrating from Magnolia 4.4/4.5, read the migration documentation first. You can also contact us for migration support. 

What to update

In summary, Magnolia 6.0 changes and new features are delivered in UI 6.0, some updated modules and some new modules:

 Click here to see the list of all updated and new modules

  • Barebones Magnolia Tomcat Bundle 1.1.2
  • Categorization 2.6.1
  • CLI npm 3.0.4
  • Community Edition 6.0
  • Contacts 1.7.0
  • Content Editor 1.3
  • Content Tags 1.2
  • Content Translation Support 2.2.1
  • Content Types 1.0
  • DAM 2.5
  • Definitions app 1.2
  • Demo Projects 1.4
  • Enterprise Edition 6.0
  • Form 2.5.1
  • Groovy 2.8
  • Image Recognition 1.0
  • Imaging 3.4.2
  • Jcr Tools 1.3
  • License 1.7
  • Log Tools 1.1.2
  • Magnolia 6.0
  • Machine Learning 1.0
  • Multisite 1.3.5
  • Pages 6.0
  • Periscope 1.0
  • Personalization 1.7
  • Privacy 1.1
  • Public User Registration 2.7.1
  • Publishing 1.0.6
  • Resources 2.6.3
  • REST Client 1.5.3
  • RSS Aggregator 2.6.1
  • Task Management 1.2.5
  • Templating Samples 6.0
  • Third-party library BOM 6.0
  • Tools 1.9.1
  • UI 6.0
  • Vaadin Compatibility Addons 1.2
  • Websphere 1.5
  • Workflow 5.7.2

Adding new modules

Periscope module for Find Bar

The Find Bar is delivered by the UI module. However, to use the Find Bar you also must add the Periscope module and, optionally, the (EE) Periscope Result Ranker module.

 Click to see how to install the Periscope module

<dependency>
  <groupId>info.magnolia.periscope</groupId>
  <artifactId>magnolia-periscope-core</artifactId>
  <version>1.0</version>
</dependency>

<dependency>
  <groupId>info.magnolia.periscope</groupId>
  <artifactId>magnolia-speech-recognition</artifactId>
  <version>1.0</version>
</dependency>

Pre-built jars are also available for download. See Installing a module for help.

 Click to see how to install the Periscope Result Ranker module

<dependency>
  <groupId>info.magnolia.periscope</groupId>
  <artifactId>magnolia-periscope-result-ranker</artifactId>
  <version>1.0</version>
</dependency>

Pre-built jars are also available for download. See Installing a module for help.

Image recognition

If you have an Enterprise license, add the new Image Recognition module.

 Click to see how to install the Image Recognition module

<dependency>
  <groupId>info.magnolia.ai.image</groupId>
  <artifactId>magnolia-image-recognition-parent</artifactId>
  <version>1.0</version>
</dependency>

Pre-built jars are also available for download. See Installing a module for help.

Content types

The Magnolia Content Types module is currently available as a Developer Preview. The full version is still under development.

This developer preview brings several powerful features. Please try it out and feel free to send us your feedback and suggestions based on your experience.

We are working to finalize the module as soon as possible.

 Click to see how to install the Content Types module

Maven is the easiest way to install the module. Add the following to your bundle:

<dependency>
  <groupId>info.magnolia.types</groupId>
  <artifactId>magnolia-content-types</artifactId>
  <version>1.0</version>
</dependency>

Pre-built jars are also available for download. See Installing a module for help.

UI version 6.0.x

Magnolia UI 6.0 contains the new design of the admin interface as well as some changes on the Magnolia UI framework 6.0, for instance for content apps.

If you follow the How to update steps 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

The magnolia.properties file has not changed between Magnolia 5.7.x and Magnolia 6.0.

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.0.x series.

Magnolia CE / Magnolia EE Standard 

Note that Magnolia CE and Magnolia EE Standard use the same magnolia.properties file.

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 EE Pro
ee/magnolia-enterprise-pro-webapp/src/main/webapp/WEB-INF/config/default/magnolia.properties
#--------------------------------------------
# Enterprise Pro webapp properties, currently only difference is Pro Widgetset.
#
# 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 are managed via BOM for third-party modules. If you manage your bundles via Maven using the BOM, all updates are handled automatically.

  • Vaadin 8.5.2  (BUILD-326)
    • Updated in all modules that use the UI.
  • Apache Commons Compress 1.14 (MAGNOLIA-7398)

  • Bouncy Castle encryption libraries 1.60 (BUILD-327)

  • jQuery 3.3.1 (MGNLUI-4727)
    • This jQuery update only concerns the Admincentral. jQuery 3.3.1 for Admincentral is included via the Magnolia UI project.  If you rely on jQuery for the front-end, for instance in a template, this change does not affect your front-end code. We also added a jQuery Migration Plugin to facilitate the update to jQuery 3.
  • Lombok 1.18.4 (BUILD-325)
  • Java Streaming API for XML (MGNLGS-145)

    • We removed javax.xml.stream:stax-api and  org.apache.geronimo.specs:geronimo-stax-api_1.0_spec from our builds. Both artifacts enable "Java Streaming API for XML" as described in JSR-173. The functionality is provided by the JDK since version 1.6.

How to update

Recommendations

  • Update to the latest minor release version first before upgrading to the most recent major release.
    A November 2018 example: a customer is considering an upgrade from 5.6.8 to 6.0. The correct upgrade sequence is: 5.6.8 → 5.7.1 → 6.0.x

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

Updating 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.
    (warning) Magnolia 6.0 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.
  9. Restart the application server.
  10. In your browser, go to the Magnolia instances and run the web update.

Updating 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 Magnolias preconfigured webapps. The structure of the Maven project that manages your webapp may look like this:

custom-ee/
├── custom-ee-webapp
│   ├── pom.xml
│   └── src
└── pom.xml
Line 3: custom-ee/custom-ee-webapp/pom.xml is the pom file of your custom webapp.

 Click to see an example

custom-ee/custom-ee-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-ee</artifactId>
    <version>1.0-SNAPSHOT</version>
    <relativePath>../pom.xml</relativePath>
  </parent>
  <artifactId>custom-ee-webapp</artifactId>
  <name>custom-ee: webapp</name>
  <packaging>war</packaging>

  <dependencies>
    <dependency>
      <groupId>info.magnolia.eebundle</groupId>
      <artifactId>magnolia-enterprise-pro-webapp</artifactId>
      <type>war</type>
    </dependency>
    <dependency>
      <groupId>info.magnolia.eebundle</groupId>
      <artifactId>magnolia-enterprise-pro-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-ee/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-ee/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-ee</artifactId>
  <name>custom-ee (parent pom)</name>
  <version>1.0-SNAPSHOT</version>
  <packaging>pom</packaging>

  <properties>
    <magnoliaBundleVersion>6.0</magnoliaBundleVersion>
    <foobarModuleVersion>1.2</foobarModuleVersion>
    <javaVersion>1.8</javaVersion>
  </properties>

  <!-- Fill the following in, so you can use the release plugin -->
  <scm>
    <connection/>
    <developerConnection/>
    <url/>
  </scm>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>info.magnolia.eebundle</groupId>
        <artifactId>magnolia-enterprise-bundle-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>true</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-ee-webapp</module>
  </modules>
</project>

Note that the parent pom (custom-ee/pom.xml) manages all versions for Magnolia modules as well as for third-party libraries.

It imports info.magnolia.eebundle:magnolia-enterprise-bundle-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.0</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-ee/custom-ee-webapp
mvn dependency:tree

Known issues

See Known issues.

  • No labels