Versions Compared

Old Version 123

changes.mady.by.user Martin Drápela

Saved on

compared with

New Version Current

changes.mady.by.user Martin Drápela

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: DEV-1375, unlink the H2 database link

This page contains the information you should be aware of when upgrading to Magnolia 5.6.x from any previous and currently supported version, see the End-of-Life policy.

Before commencing with starting the upgrade, please consult read the release notes for the version you are updating to and all intermediate versions, the general upgrade procedure and the specific aspects. If migrating from Magnolia 4.4/4.5, please have a look at the  read migration documentation first. You may can also contact us for migration support. 

Table of Contents
maxLevel3

General procedure

Info

Please note that depending Depending on the number of versions you have in the version workspace, the upgrade to 5.6.x from any version below may take from 20 to 30 minutes since all of the versions have to migrate to a new structure.

...

  1. Update to your latest minor release version first before upgrade to recent major release. A May 2017 example: a customer was considering an upgrade from 5.4.1 to 5.5.4 (latest release at that time). The correct sequence would have been: 5.4.1 → 5.4.12 → 5.5.4 instead of  5.4.1 → 5.5 → 5.5.4 .

    Info
    titleWhy we go that way?

    Because when a customer reports issues when migrating from 5.4.6 to 5.5, for instance, then we will support a workaround/patch and later release the fix also in 5.4.7. The fix of the issue in 5.4.6 when migrating is usually located in version handlers. Then at some point, we drop 5.4.x because of an outdated technology stack (such as Java versions and security support from third-party libraries), upgrade to 5.5.x, and the process repeats. So going with the latest release of each major release will free you from the issues and bring you the improvements.

  2. Update all external libraries required by the Magnolia release to which you intend to upgrade.
  3. Carefully look for "change" or "changes for ..." sections in the release notes since.
  4. Because the upgrade process takes time and is vulnerable to incidents, please minimize the risk by cleaning up your system, removing unused data, reindexing everything and doing a full backup first.

...

The default JCR persistency layer in Magnolia 5.6 is the H2 database, which is reflected in the following setting of the magnolia.repositories.jackrabbit.config property in the magnolia.properties file:

...

  1. Check if your modules contain Vaadin implementations.
  2. If they do:
    1. Obtain Get the Migration Tool for Converting Vaadin Framework 7 Projects to Vaadin Framework 8 from https://github.com/vaadin/framework8-migration-tool .
    2. While on the README at the URL, read how to install and use the tool and run it.
    3. The tool automatically changes the imports of the affected classes and thus – in the majority of cases – will make your module(s) compatible with Vaadin 8.
  3. As stated in Migrating to Vaadin 8, some dependencies need to be added in order to use the compatible classes from Vaadin 7 (such as TextField).

    Change the vaadin-server dependency from

    Code Block
    languagexml
    <dependency>
  <groupId>com.vaadin</groupId>
  <artifactId>vaadin-server</artifactId>
  <version>7.7.6</version>
</dependency>

    to 

    Code Block
    languagexml
    <dependency>
  <groupId>com.vaadin</groupId>
  <artifactId>vaadin-compatibility-server</artifactId>
  <version>8.1.5</version>
</dependency>


    The full list of compatibility packages available for Framework 8:

    • vaadin-compatibility-server
    • vaadin-compatibility-client
    • vaadin-compatibility-client-compiled
    • vaadin-compatibility-shared
    • vaadin-compatibility-themes

    (lightbulb) To be able to use the new Vaadin 8 features, add also the following dependency:

    Code Block
    languagexml
    <dependency>
  <groupId>com.vaadin</groupId>
  <artifactId>vaadin-server</artifactId>
  <version>8.1.5</version>
</dependency>

...

In Magnolia 5.6.x you can – optionally – define third-party dependencies in a different way. Previously, dependency management information about third-party modules was defined in the parent poms of magnolia.main and magnolia.ui . You may now use a software BOM (Bill of materials) project instead. The project can then be imported in all modules. This ensures that the versions of the third-party modules are the same.

...

The Standard Templating Kit (STK) was deprecated on September 15, 2017, reaching the end of life on December 31, 2018. The replacement for STK is the Magnolia Templating Kit (MTK), first released with Magnolia with Magnolia 5.4 on 4 on July 3, 2015. MTK is quicker to learn than STK and requires fewer skills.

...

The 5.6 branch brings the Publishing module pack (see  publishing on Git) , which is intended to replace replaces the Activation module ( /modules/activation ) and the Transactional Activation module ( /modules/exchange-transactional ). Besides giving a more logical ordering to the publishing functions in Magnolia, the new module pack also sets all workspaces as publishable by default. For an overview and comparison please see Publishing and activation.

...

  • Remove both the activation modules.
  • Add all modules from If you do not currently use transactional activation, add all modules from the magnolia-publishing-parent to  (See Publishing module) to your bundle, either manually as pre-built jars or as dependencies.
  • If you currently use transactional activation to manage multiple public instances, add the modules from the magnolia-publishing-transactional-parent (See Publishing Transactional module) reactor. 
  • Check that after the upgrade the subscribers were correctly migrated from /server/activation to /modules/publishing-core/config/receivers.
  • (warning) Rewrite your custom activation commands to be compatible with the modules of the new publishing module pack.

...

  • Remove all the publishing JARs from the ../WEB-INF/lib folders of your author and public instances. Add the activation JAR files in their place.

  • Exclude the publishing dependencies from the POM and add the old activation dependencies.

See also Publishing and activation.

Tags vs marketing tags

The introduction of content tagging in Magnolia 5.6 has had an effect on node type and workspace names:

  • Any marketing tag, used by the Marketing Tags app, is a marketing-tag node type and is stored in the marketing-tags workspace.
  • Any content tag, used by the Tags app, is a tag node type and is stored in the tags workspace.

The magnolia.properties file

Check your magnolia.properties file for the presence of the following lines which configure a directory for loading file system resources and the file types Magnolia should observe in the classpath and reload on-change:

Code Block
magnolia.resources.dir=${magnolia.home}
magnolia.resources.classpath.observation.pattern=.*\\.(ftl|yaml)$

Jackrabbit configuration

In order to enable getting an HTML excerpt in a query result, you should update the configuration files of your Jackrabbit instances. Add the two <param/> directives within your <SearchIndex> block.

...

languagexml

...

  • Code Block
    languagexml
    titleexclusion example....
    collapsetrue
    <dependency>
    <groupId>info.magnolia.eebundle</groupId>
    <artifactId>magnolia-enterprise-pro-demo-webapp</artifactId>       
    <version>${magnoliaBundleVersion}</version>
    <type>pom</type>
    <!-- declare

...

  • the

...

  • exclusions here -->

...

  •

...

  •

...

  •

...

  •

...

  • <exclusions>

...

  •

...

  •

...

  •

...

  •

...

  •

...

  •  <exclusion>

...

  •

...

  •

...

  •

...

  •

...

  •

...

  •

...

  •

...

  •

...

  •

...

  •  <groupId>info.magnolia.publishing</groupId>
            <artifactId>magnolia-publishing-core</artifactId>
        </exclusion>
        <exclusion> 
             <groupId>info.magnolia.publishing</groupId> 
             <artifactId>magnolia-publishing-transactional-core</artifactId>              
        </exclusion>
        <exclusion>
            <groupId>info.magnolia.publishing</groupId>
            <artifactId>magnolia-publishing-sender</artifactId>
        </exclusion>
        <exclusion> 
             <groupId>info.magnolia.publishing</groupId>
             <artifactId>magnolia-publishing-transactional-sender</artifactId> 
        </exclusion>
        <exclusion> 
              <groupId>info.magnolia.publishing</groupId>
              <artifactId>magnolia-publishing-receiver</artifactId> 
        </exclusion>
        <exclusion>
            <groupId>info.magnolia.publishing</groupId>
            <artifactId>magnolia-publishing-transactional-receiver</artifactId>
         </exclusion>
         <exclusion>
             <groupId>info.magnolia.publishing</groupId>
             <artifactId>magnolia-publishing-app</artifactId>
         </exclusion>
         <exclusion>
             <groupId>info.magnolia.publishing</groupId>
             <artifactId>magnolia-publishing-transactional-app</artifactId>
         </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>info.magnolia.activation</groupId>
    <artifactId>magnolia-module-activation</artifactId>
</dependency>
<dependency>
    <groupId>info.magnolia</groupId>
    <artifactId>magnolia-module-exchange-transactional</artifactId>
</dependency>

See also Publishing and activation.

Tags vs marketing tags

The introduction of content tagging in Magnolia 5.6 has had an effect on node type and workspace names:

  • Any marketing tag, used by the Marketing Tags app, is a marketing-tag node type and is stored in the marketing-tags workspace.
  • Any content tag, used by the Tags app, is a tag node type and is stored in the tags workspace.

The magnolia.properties file

Check your magnolia.properties file for the presence of the following lines which configure a directory for loading file system resources and the file types Magnolia should observe in the classpath and reload on-change:

Code Block
magnolia.resources.dir=${magnolia.home}
magnolia.resources.classpath.observation.pattern=.*\\.(ftl|yaml)$

Jackrabbit configuration

In order to enable getting an HTML excerpt in a query result, you should update the configuration files of your Jackrabbit instances. Add the two <param/> directives within your <SearchIndex> block.

Code Block
languagexml
<SearchIndex>
  <!-- more params here -->

  <!-- needed to highlight the searched term -->
  <param name="supportHighlighting" value="true"/>
  <!-- custom provider for getting an HTML excerpt in a query result with rep:excerpt() -->
  <param name="excerptProviderClass" value="info.magnolia.jackrabbit.lucene.SearchHTMLExcerpt"/>
</SearchIndex>

log4j2.xml update

Apache Log4j 2 is an upgrade to Log4j that brings in significant improvements for logging configurations. If you currently have a customized log4j config you must migrate your log4j configuration.

  1. Choose an approach for migration.
    • Start with the new log4j2.xml that Magnolia provides and customize it to your needs.
    • Or take you current configuration file and follow the official guide.

  2. Update your magnolia.properties (log4j.config) to point to the new file.

    Tip

    We recommend the new file be called log4j2.xml to avoid confusion.

  3. Do a basic library check:

    • Make sure you don't have log4j-1.2.17.jar or similar in WEB-INF/lib anymore.
    • There should be only:
      • log4j-api-2.8.2.jar
      • log4j-core-2.8.2.jar

      • log4j-slf4j-impl-2.8.2.jar (the slf4j implementation is now provided by Log4j 2)

        Warning

        Make sure you don't have slf4j-log4j12-1.7.7.jar. Having both installed leads to unpredictable behavior.

  4. If in doubt about your config, you may set the level of Log4j's status-logger to debug as follows:

    Code Block
    languagexml
    <Configuration status="DEBUG">
  ...

ClientErrorInterceptor not available

Since ClientErrorInterceptor does not exist in RESTeasy 3, its capabilities were removed from our client implementation, the REST client module. If you have been relying on such objects, you have to handle it in a different way.

Refine parent pom - when updating to Magnolia 5.6.3 or higher

Please be aware that the version numbers for the Magnolia main and UI projects are not in sync with the version number of the bundles starting with release 5.6.3.

If you are updating from an earlier version:
Projects based on an older maven archetype may not build correctly starting with Magnolia 5.6.3 - because the version of the Magnolia main modules is not the same as the Magnolia bundle anymore. If you experience a problem, please update your project parent pom.

Anchor
anc-known-issues
anc-known-issues

Known issues

H2 does not accept more than one connection

Our default configuration does not use server mode. Therefore, if you try to initiate a backup call using CLI or REST, it fails because H2 does not allow more than one connection at a time. This is a new issue in Magnolia (most likely due to H2 or Jackrabbit updates).

A temporary workaround is to make H2 run in server mode and adding AUTO_SERVER=TRUE in the URL parameters: 

<param name="url" value="jdbc:h2:${wsp.home}/db;AUTO_SERVER=TRUE" />

<param name="url" value="jdbc:h2:${rep.home}/version/db;AUTO_SERVER=TRUE" />

Green screen applauncher

If after upgrade or installation you experience a "green-screen" upon login (i.e. all apps are missing from the launcher) then most likely you have a module in your classpath which has not been migrated as part of the Vaadin 8 upgrade. In the log you will see "Definition not found" warnings due to the UI Framework not being able to start normally. This can be an issue when using third-party or add-on modules. Please read Vaadin 8 and custom modules.

Cannot access magnolia.nexus

If you get the following error,

Code Block
languagebash
Cannot access magnolia.nexus (https://nexus.magnolia-cms.com/content/groups/staff) and the artifact info.magnolia.boms:magnolia-external-dependencies:pom:5.6-SNAPSHOT has not been downloaded from it before. -> [Help 1]

please do the following, which will remove the snapshot artifacts from your local maven directory:

Code Block
languagebash
mvn dependency:purge-local-repository -DmanualInclude="info.magnolia:magnolia-module-content-dependencies,info.magnolia.javascript-models:magnolia-module-javascript-models,info.magnolia:magnolia-module-forum,info.magnolia:magnolia-module-rssaggregator,info.magnolia.definitions:magnolia-definitions-app,info.magnolia.restclient:magnolia-rest-client-parent,info.magnolia.restclient:magnolia-rest-client-app,info.magnolia.restclient:magnolia-rest-client,info.magnolia.restclient:magnolia-resteasy-client,info.magnolia.publishing:magnolia-publishing-parent,info.magnolia.publishing:magnolia-publishing-app,info.magnolia.publishing:magnolia-publishing-core,info.magnolia.publishing:magnolia-publishing-receiver,info.magnolia.publishing:magnolia-publishing-sender"

Now, you have to fetch the dependencies from Nexus. The easiest way would be to do

log4j2.xml update

Apache Log4j 2 is an upgrade to Log4j that brings in significant improvements for logging configurations. If you currently have a customized log4j config you must migrate your log4j configuration.

  1. Choose an approach for migration.
    • Start with the new log4j2.xml that Magnolia provides and customize it to your needs.
    • Or take you current configuration file and follow the official guide.

  2. Update your magnolia.properties (log4j.config) to point to the new file.

    Tip

    We recommend the new file be called log4j2.xml to avoid confusion.

  3. Do a basic library check:

    • Make sure you don't have log4j-1.2.17.jar or similar in WEB-INF/lib anymore.
    • There should be only:
      • log4j-api
      • log4j-core

      • log4j-slf4j-impl (the slf4j implementation is now provided by Log4j 2)

        Warning

        Make sure you don't have slf4j-log4j12-1.7.7.jar. Having both installed leads to unpredictable behavior.

  4. If in doubt about your config, you may set the level of Log4j's status-logger to debug as follows:

    Code Block
    languagexml
    <Configuration status="DEBUG">
  ...

ClientErrorInterceptor not available

Since ClientErrorInterceptor does not exist in RESTeasy 3, its capabilities were removed from our client implementation, the REST client module. If you have been relying on such objects, you have to handle it in a different way.

Known issues

H2 doesn't accept more than one connection

Our default configuration is not using the server mode and therefore if one tries to initiate a backup call via CLI or REST, it will be failing due to the fact that H2 doesn't allow more than one connection at a time. We didn't have this issue in Magnolia before but for some reason (most likely due to H2 or Jackrabbit updates) we experience it now. A temporary workaround is to make H2 run in the server mode, by removing DB_CLOSE_ON_EXIT=FALSE from the value of the url parameters and adding AUTO_SERVER=TRUE :

<param name="url" value="jdbc:h2:${wsp.home}/db;AUTO_SERVER=TRUE" />

<param name="url" value="jdbc:h2:${rep.home}/version/db;AUTO_SERVER=TRUE" />

Green screen applauncher

If after upgrade or installation you experience a "green-screen" upon login (i.e. all apps are missing from the launcher) then most likely you have a module in your classpath which has not been migrated as part of the Vaadin 8 upgrade. In the log you will see "Definition not found" warnings due to the UI Framework not being able to start normally. This can be an issue when using third-party or add-on modules. Please read Vaadin 8 and custom modules.

Cannot access magnolia.nexus

If you get the following error,

Code Block
languagebash
Cannot access magnolia.nexus (https://nexus.magnolia-cms.com/content/groups/staff) and the artifact info.magnolia.boms:magnolia-external-dependencies:pom:5.6-SNAPSHOT has not been downloaded from it before. -> [Help 1]

please do the following, which will remove the snapshot artifacts from your local maven directory:

Code Block
languagebash
mvn dependency:purge-local-repository -DmanualInclude="info.magnolia:magnolia-module-content-dependencies,info.magnolia.javascript-models:magnolia-module-javascript-models,info.magnolia:magnolia-module-forum,info.magnolia:magnolia-module-rssaggregator,info.magnolia.definitions:magnolia-definitions-app,info.magnolia.restclient:magnolia-rest-client-parent,info.magnolia.restclient:magnolia-rest-client-app,info.magnolia.restclient:magnolia-rest-client,info.magnolia.restclient:magnolia-resteasy-client,info.magnolia.publishing:magnolia-publishing-parent,info.magnolia.publishing:magnolia-publishing-app,info.magnolia.publishing:magnolia-publishing-core,info.magnolia.publishing:magnolia-publishing-receiver,info.magnolia.publishing:magnolia-publishing-sender"

Now, you have to fetch the dependencies from Nexus. The easiest way would be to do:

Code Block
languagebash
mvn dependency:resolve

Allocate more JVM memory

Magnolia 5.6 ee-bundle may require you to allocate more memory the Java Virtual Machine (JVM). If you see a java.lang.OutOfMemoryError in the startup log or the system stops responding during installation, increase the Java heap size. The default maximum heap size is 512M. Try a higher amount such as 1024M. We are working on uncovering the root cause for the increased memory need.

See: Java out of memory

The Show action in the Configuration app doesn't open the correct location

When selecting properties in a definition that are actually extended from another node in the config workspace, opening the definition in the Configuration app will not work correctly, as the underlying node/property doesn't exist. For example,

resolve


Allocate more JVM memory

Magnolia 5.6 ee-bundle may require you to allocate more memory the Java Virtual Machine (JVM). If you see a java.lang.OutOfMemoryError in the startup log or the system stops responding during installation, increase the Java heap size. The default maximum heap size is 512M. Try a higher amount such as 1024M. We are working on uncovering the root cause for the increased memory need.

See: Java out of memory

The Show action in the Configuration app doesn't open the correct location

When selecting properties in a definition that are actually extended from another node in the config workspace, opening the definition in the Configuration app will not work correctly, as the underlying node/property doesn't exist. For example,

/.magnolia/admincentral#app:definitions-app:;app~site@subApps/browser/actions/addFolder/icon:treeview 
points to config:/modules/site-app/apps/site/subApps/browser/actions/addFolder/icon .
but all the actions are inherited from /modules/ui-admincentral/apps/configuration/subApps/browser via extends.

XML exports open directly in the browser instead of offering a download

When you click the Export button in a content app or from the JCR Tools app, the XML opens directly in the browser, replacing the AdminCentral instead of showing the usual Download dialog from the browser. (warning) This issue only affects the upgrades to Magnolia 5.6.6.

See 

Jira
serverMagnolia - Issue tracker
columnskey,summary,type,created,updated,due,assignee,reporter,priority,status,resolution
serverId500b06a6-e204-3125-b989-2d75b973d05f
keyMAGNOLIA-7310
/.magnolia/admincentral#app:definitions-app:;app~site@subApps/browser/actions/addFolder/icon:treeview 
points to config:/modules/site-app/apps/site/subApps/browser/actions/addFolder/icon .
but all the actions are inherited from /modules/ui-admincentral/apps/configuration/subApps/browser via extends.

Other issues

For other known issues please see the Known issues page.

Further reading