6.0 Migration Guide

In this document, we will see the major steps to migrate from 5.x to 6.0.

Please check the change log for detailed list of fixes, changes and improvements introduced in 6.0

Java 8 to Java 11

JAVA 11 is now our minimal version to build and run applications.

Install JAVA 11 and then increase the Java version number in the build.gradle file:

build.gradle
allprojects {

  java {
    toolchain {
      languageVersion = JavaLanguageVersion.of(11)
    }
  }

}

Also make sure to use JDK 11 in the IDE as well as in your terminal (if needed).

In JAVA 8, JAXB was part of standard JDK. It has been removed in JDK 11. To use JAXB API in Java 11, you need to use separate libraries: javax.xml.bind:jaxb-api, com.sun.xml.bind:jaxb-core, com.sun.xml.bind:jaxb-impl and javax.activation:activation

See the JDK 11 migration guide for details.

Tomcat 8.5 to Tomcat 9

Apache Tomcat version 8.5 is no more supported. You need to upgrade to Apache Tomcat 9.

PostgreSQL 9 to PostgreSQL 12+

Minimal PostgreSQL 12 is now required to run applications.

Please check the PostgreSQL 12 upgrade guide for details.

Gradle 5 to Gradle 7

./gradlew wrapper --gradle-version 7.4.2

Dependencies

Many transitive dependencies are removed. If you use them, you need to add them in each affected module.

The compile configuration is deprecated. Use the api configuration to declare dependencies which are exported, and the implementation configuration to declare dependencies which are internal to your module.

Example:

build.gradle
dependencies {
  api project(":modules:axelor-base")
  implementation libs.commons_lang3
}

Axelor plugin

The Axelor Gradle plugins com.axelor.app and com.axelor.app-module are merged.

There is now a single com.axelor.app plugin, ie. all Axelor modules are Axelor apps. All modules should use the app plugin only.

See the Gradle upgrade guides for details:

Groovy 2 to Groovy 3

Groovy 3 improves compatibility with Java and has many other improvements.

Nashorn to GraalVM JavaScript

Nashorn is replaced by the Graal JavaScript Engine.

The Nashorn script engine is deprecated in Java 11 and has some incompatible changes compared to Java 8. The new implementation uses the GraalVM JavaScript Engine, which supports the latest ECMAScript features.

The collection helpers listOf, setOf, and mapOf are removed as corresponding native JavaScript objects are passed with appropriate Java equivalent wrapper to the Java calls.

OpenCSV to Commons CSV

Dependency to OpenCSV has been removed. For ease of migration, you may manually add the dependency in your own module if you wish to continue using it. The desirable end goal is to fully migrate to Commons CSV.

Reserved keywords

With upgraded database support, more keywords ar now reserved. So you need to rename database column of any affected fields.

Some notable new reserved keywords:

  • condition

  • file

  • key

  • message

  • rank

  • signal

  • size

  • uid

  • lead

Dropped removable modules

The feature is not used by any axelor apps and had many technical issues.

Run the following SQL script to drop unnecessary columns:

ALTER TABLE meta_module DROP COLUMN installed;
ALTER TABLE meta_module DROP COLUMN removable;
ALTER TABLE meta_module DROP COLUMN pending;

Also, ModuleChanged event associated to this feature has been removed.

Dropped deprecated features

Features that were marked as deprecated in AOP v5 are now dropped.

Notable Changes:

  • Context.getParentContext()Context.getParent()

  • new ActionHandler(ActionRequest)ActionExecutor.newActionHandler(ActionRequest)

  • LoginRedirectExceptionWebUtils.issueRedirect()

  • hashKey/hashAll (hashCode) → equalsInclude/equalsIncludeAll (equals)

  • cachablecacheable

  • Form widgets <notebook>, <break>, <group>, <portlet>, and <include> but also cols and colWidths form attributes used for legacy form layout → Use panel layout instead

Other removed/renamed features

  • ActionResponse.setFlash()ActionResponse.setInfo()

Application configuration

Internal configuration file application.properties has been renamed to axelor-config.properties. YAML format is also supported.

See Application configuration for details.

Configurations naming

To improve and uniform the configuration naming, a lot of them as been updated. Here is a list of all changes :

Old name

New name

view.single.tab

view.single-tab

view.tabs.max

view.max-tabs

view.confirm.yes-no

view.confirm-yes-no

view.customization

view.allow-customization

view.adv-search.export.full

view.adv-search.export-full

view.grid.editor.buttons

view.grid.editor-buttons

view.toolbar.titles

view.toolbar.show-titles

application.baseUrl

application.base-url

application.multi_tenancy

application.multi-tenancy

application.config.provider

application.config-provider

domain.blacklist.pattern

application.domain-blocklist-pattern

axelor.ScriptCacheSize

application.script.cache.size

axelor.ScriptCacheExpireTime

application.script.cache.expire-time

application.disable.action.permission

application.permission.disable-action

application.disable.relational.field.permission

application.permission.disable-relational-field

axelor.report.dir

reports.design-dir

reports.fonts.config

reports.fonts-config

template.search.dir

template.search-dir

file.upload.dir

data.upload.dir

file.upload.size

data.upload.max-size

file.upload.filename.pattern

data.upload.filename-pattern

file.upload.whitelist.pattern

data.upload.allowlist.pattern

file.upload.whitelist.types

data.upload.allowlist.types

file.upload.blacklist.pattern

data.upload.blocklist.pattern

file.upload.blacklist.types

data.upload.blocklist.types

cors.allow.origin

cors.allow-origin

cors.allow.credentials

cors.allow-credentials

cors.allow.methods

cors.allow-methods

cors.allow.headers

cors.allow-headers

cors.expose.headers

cors.expose-headers

cors.max.age

cors.max-age

quartz.threadCount

quartz.thread-count

user.password.pattern.title

user.password.pattern-title

encryption.algorithm.old

encryption.old-algorithm

encryption.password.old

encryption.old-password

mail.smtp.pass

mail.smtp.password

mail.smtp.connectionTimeout

mail.smtp.connection-timeout

mail.imap.pass

mail.imap.password

mail.imap.connectionTimeout

mail.imap.connection-timeout

Authentication configuration

Reflection is now used to configure authentication clients. The new syntax is auth.provider.<providerName>.<configurationName>. You may use any of the built-in providers (google, facebook, azure, keycloak, apple, oauth, oidc, saml, cas) or configure any other clients supported by pac4j using your own custom provider name. You may even create and use your own custom authentication clients.

Example using a built-in provider:

axelor-config.properties
auth.provider.google.key = 127736102816-tc5mmsfaasa399jhqkfbv48nftoc55ft.apps.googleusercontent.com
auth.provider.google.secret = qySuozNl72zzM5SKW-0kczwV

Built-in providers come with preconfigured settings. The above is equivalent to:

axelor-config.properties
auth.provider.myprovider.client = org.pac4j.oauth.client.Google2Client
auth.provider.myprovider.configuration = org.pac4j.oauth.config.OAuth20Configuration
auth.provider.myprovider.title = Google
auth.provider.myprovider.icon = img/signin/google.svg
auth.provider.myprovider.exclusive = false

auth.provider.myprovider.key = 127736102816-tc5mmsfaasa399jhqkfbv48nftoc55ft.apps.googleusercontent.com
auth.provider.myprovider.secret = qySuozNl72zzM5SKW-0kczwV

Charts

Adding buttons on chart menu was working using the following syntax:

<chart ...>
  ...
  <config name="onAction" value="some-action"/>
  <config name="onActionTitle" value="some-title"/>
</chart>

This syntax has been updated to the following:

<chart ...>
  ...
  <actions>
    <action name="myBtn1" title="My action 1" action="some-action1"/>
    <action name="myBtn2" title="My action 2" action="some-action2"/>
  </actions>
</chart>

PreRequest/PostRequest events

PreRequest/PostRequest events are now fired outside of transactions. This fixes accessing the created/update records in a multithreaded process from PostRequest observers. However you can no longer rollback the request process in a PostRequest observer.

Others

  • com.axelor.event.Priority annotation has been removed in favor of javax.annotation.Priority.