Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
please see
Jira | ||||||||
---|---|---|---|---|---|---|---|---|
|
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 | ||
---|---|---|
|
Info |
---|
Please note that depending Depending on the number of versions you have in the |
WEB-INF/lib
folder of your old Magnolia instances with new JARs from the bundle.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.magnolia.properties
files, compare the changes to the file in the new bundle. Properties may have been added and removed.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 .
The default JCR persistency layer in Magnolia 5.6 is H2, which is reflected in the following setting of the magnolia.repositories.jackrabbit.config
property in the magnolia.properties
file:
Code Pro |
---|
magnolia.repositories.jackrabbit.config=WEB-INF/config/repo-conf/jackrabbit-bundle-h2-search.xml |
Info | ||
---|---|---|
| ||
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. |
The default JCR persistency layer in Magnolia 5.6 is the H2 database, which is reflected in the following setting of the If you used a different database before upgrading to Magnolia 5.6, make sure you keep your magnolia.repositories.jackrabbit.config
setting. For Apache Derby, for example this would be: property in the magnolia.properties
file:
Code Pro |
---|
magnolia.repositories.jackrabbit.config=WEB-INF/config/repo-conf/jackrabbit-bundle-derbyh2-search.xml n your magnolia.properties file. |
...
If you are upgrading from a pre-5.6 branch to the used a different database before upgrading to Magnolia 5.6 branch, please follow the steps below to make sure that your custom modules are compatible with the UI in the 5.6 branch. The first Magnolia release in this branch uses Vaadin 8.1.5 (see Vaadin 8.1.5 release notes and API docs).
...
make sure you keep your magnolia.repositories.jackrabbit.config
setting. For Apache Derby, for example this would be:
Code Pro |
---|
magnolia.repositories.jackrabbit.config=WEB-INF/config/repo-conf/jackrabbit-bundle-derby-search.xml n your magnolia.properties file. |
With Magnolia 5.6 we have removed the old content API in some of our modules. For more details see the Removal of old Content API subpage.
If you are upgrading from a pre-5.6 branch to the 5.6 branch, please follow the steps below to make sure that your custom modules are compatible with the UI in the 5.6 branch. The first Magnolia release in this branch uses Vaadin 8.1.5 (see Vaadin 8.1.5 release notes and API docs).
TextField
).Change the vaadin-server
dependency from
Code Block | ||
---|---|---|
| ||
<dependency>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-server</artifactId>
<version>7.7.6</version>
</dependency> |
to
Code Block | ||
---|---|---|
| ||
<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
To be able to use the new Vaadin 8 features, add also the following dependency:
Code Block | ||
---|---|---|
| ||
<dependency>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-server</artifactId>
<version>8.1.5</version>
</dependency> |
Please see also the links in the Further reading section for additional information on upgrading from Vaadin 7 to Vaadin 8.
If you have your own widgetset, then you need to inherit the Vaadin7WidgetSet
:
@Widgetset("com.vaadin.v7.Vaadin7WidgetSet")
,Or do it in your GWT configuration file by adding <inherits name="com.vaadin.v7.Vaadin7WidgetSet" />
.
If you had Enterprise Edition Pro 5.4.x or previous and are installing Enterprise Edition Pro 5.6.x, you have to replace the widget set in the magnolia.properties
file due to component personalization bringing in new features to the page editor. Either replace or add (depending on the update path):
Code Pro |
---|
magnolia.ui.vaadin.widgetset=info.magnolia.widgetset.MagnoliaProWidgetSet |
Both the Enterprise Edition Standard and the Community Edition use the MagnoliaWidgetSet
:
Code Pro |
---|
magnolia.ui.vaadin.widgetset=info.magnolia.widgetset.MagnoliaWidgetSet |
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 BOM feature was made available for the first time in Magnolia 5.5.7. For further information on how to use a BOM in your project, please see the BOM for third-party modules page.
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 5.4 on July 3, 2015. MTK is quicker to learn than STK and requires fewer skills.
MTK is aimed at the increasing number of front-end developers who looked for something leaner and less time-consuming. It is front-end framework agnostic, which means that you can integrate it with any modern framework such as Bootstrap or Foundation.
Since the release of Magnolia 5.6 we no longer produce preconfigured bundles and webapps with the STK based demo. If you still rely on the STK, see how to add STK to your bundle.
The 5.6 branch brings the Publishing module pack (see publishing
on Git) which 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.
The publishing and activation modules cannot be used side-by-side in Magnolia.
If you used activation before the upgrade and wish to use the new publishing module pack, you have to:
magnolia-publishing-parent
(See Publishing module) to your bundle, either manually as pre-built jars or as dependencies.magnolia-publishing-transactional-parent
(See Publishing Transactional module) reactor. subscribers
were correctly migrated from /server/activation
to /modules/publishing-core/config/receivers
.For further information about configuring the new publishing-core
module see the Publishing module page.
Using activation in the 5.6 branch is still possible, but only after replacing the bundled Publishing and Publishing Transactional modules with the Activation module and the Transactional Activation module, respectively. You can do this in two ways:
../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.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<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.
The introduction of content tagging in Magnolia 5.6 has had an effect on node type and workspace names:
marketing-tag
node type and is stored in the marketing-tags
workspace.tag
node type and is stored in the tags
workspace.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)$ |
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 | ||
---|---|---|
| ||
<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> |
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.
log4j2.xml
that Magnolia provides and customize it to your needs.Update your magnolia.properties (log4j.config) to point to the new file.
Tip |
---|
We recommend the new file be called |
Do a basic library check:
log4j-1.2.17.jar
or similar in WEB-INF/lib anymore.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 |
If in doubt about your config, you may set the level of Log4j's status-logger to debug as follows:
Code Block | ||
---|---|---|
| ||
<Configuration status="DEBUG">
... |
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.
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 | ||||
---|---|---|---|---|
|
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" />
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.
If you get the following error,
Code Block | ||
---|---|---|
| ||
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 | ||
---|---|---|
| ||
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 | ||
---|---|---|
| ||
mvn dependency:resolve |
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
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.
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. This issue only affects the upgrades to Magnolia 5.6.6.
See
Jira | ||||||||
---|---|---|---|---|---|---|---|---|
|
For other known issues please see the
...
Change the vaadin-server
dependency from
Mgnl mini code snippet | ||
---|---|---|
| ||
<dependency> |
to
Mgnl mini code snippet | ||
---|---|---|
| ||
<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
To be able to use the new Vaadin 8 features, add also the following dependency:
Mgnl mini code snippet | ||
---|---|---|
| ||
<dependency> |
Please see also the links in the Further reading section for additional information on upgrading from Vaadin 7 to Vaadin 8.
Normally, you won't need to do this since you have a Magnolia running for you. However, in case you are demoing your module as a custom Vaadin application, then you have to include Vaadin7WidgetSet
:
@Widgetset("com.vaadin.v7.Vaadin7WidgetSet")
,Or do it in your GWT configuration file by adding <inherits name="com.vaadin.v7.Vaadin7WidgetSet" />
.
If you had Enterprise Edition Pro 5.4.x or previous and are installing Enterprise Edition Pro 5.6.x, you have to replace the widget set in the magnolia.properties
file due to component personalization bringing in new features to the page editor. Either replace or add (depending on the update path):
Code Pro |
---|
magnolia.ui.vaadin.widgetset=info.magnolia.widgetset.MagnoliaProWidgetSet |
Both the Enterprise Edition Standard and the Community Edition use the MagnoliaWidgetSet
:
Code Pro |
---|
magnolia.ui.vaadin.widgetset=info.magnolia.widgetset.MagnoliaWidgetSet |
Following the release of Magnolia 5.5.7, Magnolia 5.6.x allows you optionally to 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.
To use a BOM in your project, include the following code snippet as the very first dependency in the dependency management section of the parent poms and adjust the version number accordingly (the number is in sync with the bundle version):
Code Block | ||
---|---|---|
| ||
<dependencyManagement>
<dependencies>
<dependency>
<groupId>info.magnolia.boms</groupId>
<artifactId>magnolia-external-dependencies</artifactId>
<version>5.6</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement> |
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 5.4 on July 3, 2015. MTK is quicker to learn than STK and requires fewer skills.
MTK is aimed at the increasing number of front-end developers who looked for something leaner and less time-consuming. It is front-end framework agnostic, which means that you can integrate it with any modern framework such as Bootstrap or Foundation.
Since the release of Magnolia 5.6 we no longer produce preconfigured bundles and webapps with the STK based demo. If you still rely on the STK, see how to add STK to your bundle.
The 5.6 branch brings the Publishing module pack (see magnolia-publishing-parent
on nexus), which is intended to replace 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.
If you wish you may still continue using the original Activation modules in the 5.6 branch, but opting for the new publishing module pack means that you have to:
magnolia-publishing-parent
to your bundle, either manually as pre-built jars or as dependencies.subscribers
were correctly migrated from /server/activation
to /modules/publishing-core/config/receivers
.Please note that the publishing and activation modules cannot be used side-by-side. Use either only Activation or only Publishing. For further information about configuring the new publishing-core
module see the Publishing module page. See also Publishing and activation.
The introduction of content tagging in Magnolia 5.6 has had an effect on node type and workspace names:
marketing-tag
node type and is stored in the marketing-tags
workspace.tag
node type and is stored in the tags
workspace.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)$ |
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 | ||
---|---|---|
| ||
<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> |
TODO: update after MAGNOLIA-6794
Add the log configuration for org.reflections
Code Block | ||
---|---|---|
| ||
...
<category name="org.apache.jackrabbit">
<priority value="WARN" />
</category>
<!-- Reflections library spoils logs with hundreds of harmless warnings; tries to look into native libs but none of its DefaultUrlTypes can handle them. -->
<category name="org.reflections">
<priority value="ERROR" />
</category>
<category name="com">
<priority value="WARN" />
</category>
... |
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
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.
For other known issues please this the Known issues page.