Because Axon.ivy 8.0 uses a lot of new technologies like Java 11, PrimeFaces 7.0 and the new Portal 8.0 we recommend that you first check that your deployed projects work correctly in the designer. Do the necessary migration steps in the projects before migrating the Engine.
You need a new licence file for Axon.ivy Engine 8.0. Your old 7.x licence will no longer work. The new licence is no longer bound to the hostname where an Axon.ivy Engine runs but on the public URLs end users communicate with it.
Furthermore, we have removed the Demo Licence file
demo.lic from the
[engineDir]/configuration directory. The Axon.ivy Engine 8.0 is running in demo mode by default without a valid licence file.
Rich Dialog (ULC) technology has been removed completely. Axon.ivy 7.0 LTS is the last version where Rich Dialogs (ULC) are fully supported.
You must convert Rich Dialogs (ULC) to HTML Dialogs (JSF) in all your projects or stay with version 7.0 LTS. For this reason the ULC based Admin UI was replaced with the web based Engine Cockpit.
Axon.ivy now runs with a Java 11 runtime environment:
sunclasses are no longer available
We updated many shared project libraries to a Java 11 compatible version. Be aware that more APIs could have been deprecated by these libraries which could have side effects to projects built upon them.
Many prominent Java libraries released new version for Java 11. Check your projects for custom libraries and verify its compatibility with the latest Java LTS JRE.
Known issues with third-party libraries:
PowerMock: is known to produce NoClassDefFoundErrors as it accesses JDK classes in a non-standard way. However, you can configure PowerMock to avoid loading the problematic classes by setting the
For years internal Sun API was packed and accessible through the JRE. Now these packages can no longer be imported, which leads to compile and runtime failures.
Many developers imported these classes by accident. Therefore, check your projects for compile errors and fix them to avoid runtime errors for users.
In most cases there is an equivalent replacement class available. E.g.:
sun.misc.BASE64Encoder: can be replaced by
java.util.Base64.getEncoder()which is available since Java 8.
Openjdk-11-jre's are pre-installed on many recent Linux distributions. Unfortunately as of today, with OpenJDK 11.0.5, these JREs are known to crash when using legacy AWT UIs of the Designer [see Bug #1838740]. For instance, when using the configuration editor to add new environments.
However, AdoptOpenJDK releases seem not to be touched by these issues. Therefore, a switch to these VMs is recommended to use the Designer. Execute the
installDependencies.sh script in the root of the Designer to do so.
The User Dialog widget library PrimeFaces has been upgraded from 6.1 to 7.0.
Here is a list of the most common problems we encountered or changes we had to make:
pm:) widgets you will need to replace them, the Axon.ivy Designer will underline them with a warning. These widgets were used by default in mobile and offline dialogs.
setBoldWeight()anymore. You can directly call
!importantfor relative positioning.
autoUpdateattribute was removed from outputPanel, fragment, messages and growl. Use
jQueryhas been updated from version 1.11 to 3.3. Check your jQuery code if it is still valid.
org.primefaces.context.RequestContextis now deprecated.
Portal version 7 and earlier are no longer compatible with Axon.ivy 8.0. If you have used the Portal in your projects, you have to migrate your projects also to Portal 8.0.
The engine deploys the Axon.ivy Portal to an application that is called
DemoPortal if the engine runs in demo mode only.
In older versions the Axon.ivy Portal was deployed to an application called
Portal, not only in demo mode but in production mode also. If you migrate from an older version, you will still have the application
Portal, but the Axon.ivy Portal projects are now missing. If you did not use the
Portal application, you are safe to delete it. If you used the
Portal application for productive workflows, you need to migrate it.
Portalapplication, you need to do the following steps:
Portalapplication and that depend on the Portal to the new Portal 8.0.
Portalapplication. This can be done by writing an app-Portal.yaml file to the [[EngineDir]/configuration directory and set the
Data.FileDirectoryproperty. See below.
Portalapplication by using the Engine Cockpit.
Example app_Portal.yaml file:
Data: FileDirectory: applications/Portal
The Axon.ivy Engine Configuration binaries have been removed. Namely
bin/AxonIvyEngineConfigC.exe and its Linux equivalent
To initially setup an Axon.ivy Engine start the normal engine binary (e.g.
bin/AxonIvyEngine.exe). The engine is then started in Demo Mode and you can use the new Setup Wizard to do the initial setup of the engine. Use the new Engine Cockpit to change the configuration of your engine after the initial setup. If the engine is misconfigured so that it no longer starts then use the new Maintenance Mode to fix configuration problems.
Many engine configuration aspects were hitherto stored in the system database and managed by the Admin UI. During the system database conversion many configurations will be ported from the database into the
After the database conversion, the configuration files should be reviewed manually for their correctness. Most configurations in these files can be configured using the new Engine Cockpit UI.
Removed Properties from System Database
System-, Application- & Cluster-Properties are now read directly from the yaml configuration files. The properties of your system database are written to your
ivy.cache.properties file during the database conversion. Only a few internal properties will stay stored in the database. Cluster Properties are not supported any longer. For cluster usage you need to define a separate
ivy.yaml file for every node.
Please check the
ivy.yaml file if the converted values are valid.
Removed Security System Configuration from System Database
The security system configuration is now read directly from the yaml configuration files. The configuration in your system database is written to your
ivy.yaml file during database conversion.
Please check the
ivy.yaml file if the converted values are valid.
We removed the serverconfig.xml file in the configuration folder. The system database settings are now stored in the
We have updated Elasticsearch from 5.5 to 7.3.
If you operate the Axon.ivy Engine with an external Elasticsearch server, you must now upgrade this instance to an Elasticsearch server in version 7.3.
After upgrading you must remove your
elasticsearch/data folder for reindexing.
If you have queried boolean fields with
ivy.repo.search(Dossier.class).numberField("person.male").isEqualTo(1) this will no longer work. We have introduced a new
booleanField api with 8.0.16 to filter by boolean fields e.g.
The OS specific launch configuration files
bin/AxonIvyEngine.conf (Linux) and
bin/AxonIvyEngine.ilc (Windows) are now streamlined into the platform independent file
If you made any specific launch configuration in the old launcher files you need to manually migrate your settings to the new
Due to platform-independent configuration setup we no longer consider the following launch configurations:
We introduced the platform-independent
configuration/jvm.options. You must migrate the settings in your
*.conf files to the JVM settings in this file.
Windows In the
Example.ilc file you find a documentation which JVM flags are modified by each setting. You need to set these JVM flags now in the
jvm.options file accordingly.
Linux All settings in the
AxonIvyEngine.conf file can be transparently moved to the
The Keystore and Truststore format has changed and existing stores are no longer compatible.
Default Key- and Truststore
The default store type has changed from
You are affected by this if you have installed custom certificates or private keys in
keystore.jks of the
Import keys to the new
pkcs12 store or configure Axon.ivy to use the legacy key- and truststore.
Migrate to pkcs12
Preferred solution is to use the new pkcs12 key- and trustore located in
Export the existing certificates and private keys from
truststore.jks and import them into
You can adapt this command to convert a store from
jks format into
keytool -importkeystore -srckeystore truststore.jks -destkeystore truststore.p12 -srcstoretype JKS -deststoretype PKCS12 -deststorepass changeit
If you still want to use the legacy
jks based stores you can configure Axon.ivy to accept them.
These configuration changes can be made either in
ivy.yaml or by using the Engine Cockpit.
Set store type to
jks format for the following keys:
Furthermore, keys that define a keystore path must be re-located to
configuration/truststore.jks The following keys must be adjusted:
Legacy default keystore path
The legacy default keystore path (Axon.ivy 5.0 and prior) is not supported anymore.
Rename your existing keystore file in
keystore.jks. Afterwards legacy JKS type must be enabled (see previous).
The name of the default log file has changed from
We have changed how the paths of files attached to workflows or cases are stored in the database. In earlier versions, the file paths were stored as an absolute path, now the stored paths are relative to the application file folder.
IWA_UploadedFile) during an upgrade. It is possible that not all file paths can be converted automatically. If any conversion fails, the process will log a warning, listing all files that could not be converted (
Could NOT convert all file paths. The following files could NOT be converted:). All logged file paths need to be changed manually in the database, and the actual files need to be manually moved into the application file folder.
If you have several applications with the same name (case sensitive) installed, these duplicated applications must be removed before an update. Example: Applications
MyApp are installed. Remove one of the two applications.
The engine is now able to execute projects in packed zip or iar files. If you deploy a new project to the engine, the new Process Model Versions will now contain a packed file instead of an expanded project directory by default.
The packed projects are read-only projects. If you try to change the contents of such a project at runtime it will fail with a
Get write access
If write access is necessary, for instance because the
ivy.cms write API is used, the related project must be made writable. This can be done by deploying the project as an expanded project:
project-build-plugin, the configuration parameter deployTargetFileFormat must be set to
deploydirectory, it can be enforced by providing an
options.yamlfile with the following content
target fileFormat : EXPANDED
EXPANDEDFile Format Option in the deployment dialog.
To prevent from the Session Fixation attack Axon.ivy renews / changes the session ID after login. If you have any trouble with it (e.g. in combination with Mobile App) you can disable this by changing the configuration property
false. If you migrate from 7.0.4 the feature is per default disabled and stays disabled after migration. We highly recommend enabling this feature by changing the configuration property
CSRF-protection is now enabled by default on all REST services provided by Axon.ivy (including services provided by the mobile workflow API and services provided by custom Axon.ivy projects).
DELETEthe caller needs to provide a HTTP Header called
X-Requested-Bywith any value e.g. ivy. This is the Jersey provided protection of REST services against cross-site request forgery (CSRF). If the CSRF header is not provided on a modifying REST request the request will fail with an HTTP Status
400(Bad Request). Custom REST services via
OPTIONSshould therefore be implemented in a way that they don't modify data.
The CSRF protection for REST services can be server-wide disabled by setting the configuration property
REST.Servlet.CSRF.Protection to false. However, that is not recommended.
If you use a custom error page (JSF) you need to add /faces prefix to the location in the web.xml.
<error-page> <error-code>404</error-code> <location>/custom-404-error-page.xhtml</location> </error-page>
Maven natured projects that contain test code could throw new compilation errors. This happens if the
pom.xml contains dependencies marked with
<scope>test</scope> such as JUnit4. You see these JARs now with a dark-grey background within the
Maven Dependencies classpath container. To fix the issue the source directory of the test classes must be marked as
The change value will be reflected within the
.classpath of your project.
All document generating functions from IvyAddOns are now available in the DocFactory project. This project can be imported over the Ivy Projects Importer. All other IvyAddOns functions are not supported anymore.
The fields in the authentication section on the web service inscription mask are automatically converted to properties. You were able to use macros in these fields, which will be converted to valid ivy script. There is one special case which won't be supported anymore: Macro expansion within macro expansion. For example: The macro
<%= ivy.co("/pathInCms") %> reads the content from the specified cms path. If there is also macro in the specified cms path, this macro will not be expanded anymore.
The support to import a Xpert.ivy 3.9 project into Axon.ivy Designer has been removed. If you need to convert a Xpert.ivy 3.9 project use Axon.ivy Designer 7.0 or earlier.
For a better development experience, we disabled JSF resource caching and enabled XML validation in the Designer.
javax.faces.view.facelets.TagExceptionwhen calling your Html Dialog. If you run into XML validation errors, first try to fix them. If this is not possible (e.g. because the problem is caused by a required component you don't have permission to change) you can disable XML validation (and enable resource caching) by setting the context parameter
Productionin the Designer's
The resources in the
webapps/ivy/shared directory are deprecated and will be removed in later releases.
Core Workflow API
Many APIs and database tables have changed through the introduction of the new Custom Fields features on Tasks and Cases.
Consequently, many APIs have been deprecated and should no longer be used. However, to keep your application operating no adjustments should be required. We kept the legacy APIs functional and running. As system administrator you should verify that the newly introduced database tables are included in your regular backups.
ICase API was deprecated The numbered custom fields on
ICase have been deprecated e.g.:
The same for the business fields on
And for the categorization fields on
Additional Properties have been deprecated:
ch.ivyteam.ivy.workflow.IWorkflowContext.findTask(String, String, ...)
ch.ivyteam.ivy.workflow.IWorkflowContext.findCase(String, String, ...)
Use the new Custom Fields instead.
To categorize your Tasks and Cases you should still use
Workflow Event Log API
The workflow Event Log API is now deprecated and will be removed in a future version.
Since this was never Public API, most projects should not be affected.
We deprecated this API because it is customer specific and of no value for generic customers.
The API consists of the following methods, interfaces and enums:
We included the Apache
poi-ooxml-4.1.0 libraries in the Axon.ivy Classpath. This enables you to use them in your projects to write, read and export office documents.
Projects that used POI already must remove them now and apply API migrations.
Users of the PrimeFaces dataExporter features (e.g. in Portal) no longer must copy POI libraries to the Engine web libs (
Migrate POI Projects
If you included Apache POI already in your projects, you must remove them. First remove instances of
xmlbeans libraries from your project classpath. To do so:
If you were using a POI version prior to
4.1.0 you might encounter errors in your projects that must be fixed. We faced the following changes frequently:
CellStyleEnum has been replaced by
HSSFCellStyleEnum has been replaced by
setBoldWeight()anymore. You can directly call
Adjust Engine libs
If you want to use the Excel export in the Portal or PrimeFace's dataExporter, you don't have to manually add the
poi libraries anymore.
Verify that your engine setup does not enforce a manual coping of POI libraries to
Some libraries have been removed from the project classpath and are no longer available to the Axon.ivy project.
annotations-2.0.3.jar; if you have used these two libraries in your projects, you will need to update and re-deploy the projects to avoid
NoClassDefFoundErrors at runtime.
We have deprecated all public APIs around the database access flags
ch.ivyteam.ivy.application.ExternalDatabaseConfigurationAccessFlag. These have not been used since version 3.9.
Re-synchronise your device with the engine after migrating.
After your device has been successfully synchronised with the engine you can start working on your tasks like always.