Migration Notes


This document informs you in detail about incompatibilities that were introduced between different Axon.ivy versions and tells you what needs to be done to get your existing projects working with the newest version. Go through the migration notes from version to version, also check our further migration hints:

How to upgrade an Engine properly is described in the Installation chapter of the Engine Guide.


Migration 7.0 to 8.0


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.

Axon.ivy Engine


Licence

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.

More

Learn more about public URLs and how to install the new licence in the Engine Guide.

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 removed

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.

Java 11

Axon.ivy now runs with a Java 11 runtime environment:

More

Verify libraries

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 @PowerMockIgnore({"com.sun.myissue.*}) annotation. More

Fix sun and com.sun imports

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.

Linux Designers

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.

Maven

A Java 11 JDK is required to execute Maven builds with the latest project-build-plugin. To prevent problems with multiple installed Java versions, the environment variable JAVA_HOME must be set.

PrimeFaces 7.0 upgrade

The User Dialog widget library PrimeFaces has been upgraded from 6.1 to 7.0.

PrimeFaces 7.0 comes with a few breaking changes. Therefore, please follow the official PrimeFaces migration guide to identify User Dialogs of your project that need manual adjustments.

More

Here is a list of the most common problems we encountered or changes we had to make:

  • Mobile has been removed. If you used any of the mobile (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.
    For example replace:
    • <pm:header> with <div class="container">
    • <pm:content id="content"> with <div class="ui-content">
  • facetFontStyle and cellFontStyle don't support setBoldWeight() anymore. You can directly call setBold().
  • Select one menu arrow alignment changed. Use !important for relative positioning.
  • autoUpdate attribute was removed from outputPanel, fragment, messages and growl. Use p:autoUpdate instead.
  • Change appendToBody="true" to appendTo="@(body)" in p:overlayPanel.
  • jQuery has been updated from version 1.11 to 3.3. Check your jQuery code if it is still valid.
  • Some of the styling has changed. Check your styling if it is still as expected.
  • The class org.primefaces.context.RequestContext is now deprecated.

Portal 8.0

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.

Portal Migration Notes

Portal Application

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.

More

To migrate the Portal application, you need to do the following steps:

  1. Migrate the projects you have deployed to the Portal application and that depend on the Portal to the new Portal 8.0.
  2. Reconfigure the file directory of the Portal application. This can be done by writing an app-Portal.yaml file to the [[EngineDir]/configuration directory and set the Data.FileDirectory property. See below.
  3. Redeploy your projects and the new Portal 8 to the Portal application by using the Engine Cockpit.

Example app_Portal.yaml file:

Data:
    FileDirectory: applications/Portal

EngineConfig binaries

The Axon.ivy Engine Configuration binaries have been removed. Namely bin/AxonIvyEngineConfig.exe, bin/AxonIvyEngineConfigC.exe and its Linux equivalent bin/AxonIvyEnginConfig.

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.

Engine configuration ported from database to .yaml files

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 ivy.yaml file.

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.

More

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.yaml or 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.

Removed serverconfig.xml

We removed the serverconfig.xml file in the configuration folder. The system database settings are now stored in the ivy.yaml file.

More

If you have a serverconfig.xml you should copy it into the new engine along with your other configuration files. The settings in the serverconfig.xml file are automatically converted during the next boot of the engine.

Elasticsearch

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.

Engine launch configuration

The OS specific launch configuration files bin/AxonIvyEngine.conf (Linux) and bin/AxonIvyEngine.ilc (Windows) are now streamlined into the platform independent file configuration/jvm.options.

If you made any specific launch configuration in the old launcher files you need to manually migrate your settings to the new jvm.options file.

More

Due to platform-independent configuration setup we no longer consider the following launch configurations:

  • bin/Example.ilc
  • bin/AxonIvyEngine.conf
  • bin/control.conf
  • bin/*.conf
  • bin/*.ilc

We introduced the platform-independent configuration/jvm.options. You must migrate the settings in your *.ilc and *.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 jvm.options file.

Keystore and trustore

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 jks to pkcs12.

You are affected by this if you have installed custom certificates or private keys in truststore.jks or keystore.jks of the [engineDir]/configuration/ directory.

Import keys to the new pkcs12 store or configure Axon.ivy to use the legacy key- and truststore.

More

Migrate to pkcs12

Preferred solution is to use the new pkcs12 key- and trustore located in [engineDir]/configuration.

Export the existing certificates and private keys from keystore.jks / truststore.jks and import them into keystore.p12 / truststore.p12.

You can adapt this command to convert a store from jks format into pkcs12.

keytool -importkeystore -srckeystore truststore.jks -destkeystore truststore.p12 -srcstoretype JKS -deststoretype PKCS12 -deststorepass changeit

Enable legacy jks store

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:

  • SSL.Client.KeyStore.Type
  • SSL.Client.TrustStore.Type

Furthermore, keys that define a keystore path must be re-located to configuration/keystore.jks or configuration/truststore.jks The following keys must be adjusted:

  • SSL.Client.TrustStore.File
  • SSL.Client.KeyStore.File
  • Connector.HTTPS.KeystoreFile

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 [engineDir]/configuration from keystore to keystore.jks. Afterwards legacy JKS type must be enabled (see previous).

Axon.ivy Engine demo mode defaults

Default log file name

The name of the default log file has changed from logs/ch.ivyteam.ivy.log to logs/ivy.log

Changed stored file paths for files attached to cases and workflows

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.

More

This change requires us to convert the file paths in the database (table 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.

Application name is case insensitive

If you have several applications with the same name (case sensitive) installed, these duplicated applications must be removed before an update. Example: Applications MyAPP and MyApp are installed. Remove one of the two applications.

The engine operates with packed projects

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.

More

Already deployed projects keep their expanded directory format.

Read-only projects

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 java.nio.file.ReadOnlyFileSystemException.

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:

  • with the maven project-build-plugin, the configuration parameter deployTargetFileFormat must be set to EXPANDED.
  • with the deploy directory, it can be enforced by providing an options.yaml file with the following content
target
  fileFormat : EXPANDED
  • with the Engine Cockpit, use the EXPANDED File Format Option in the deployment dialog.

Renew / change the session ID after login

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 Session.RenewIdOnLogin to 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 Session.RenewIdOnLogin to true.

REST services: CSRF-protection now enabled by default

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

More

To call a modifying REST service via PUT, POST or DELETE the caller needs to provide a HTTP Header called X-Requested-By with 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 GET, HEAD or OPTIONS should 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.

Location prefix for custom error pages

If you use a custom error page (JSF) you need to add /faces prefix to the location in the web.xml.

More

BEFORE:
<error-page>
  <error-code>404</error-code>
  <location>/custom-404-error-page.xhtml</location>
</error-page>
AFTER:
<error-page>
  <error-code>404</error-code>
  <location>/faces/custom-404-error-page.xhtml</location>
</error-page>

Axon.ivy Designer


Test scoped maven dependencies not on compile classpath

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 test directory.

More

You can achieve that as follows:

  1. switch to the Java perspective
  2. open the context menu of the source directory that contains test (e.g. src_test)
  3. select 'Build Path' > 'Configure Build Path...' in the context menu
  4. expand the test source directory within Java Build Path dialog
  5. select 'Contains tests sources: ...'
  6. hit the 'Toggle' button to change the value to 'yes'

BuildPath

The change value will be reflected within the .classpath of your project.

IvyAddOns not supported anymore

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.

Macros in Authentication section of Web Service Call Inscription

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.

Import a Xpert.ivy 3.9 project is no longer possible

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.

HTML Dialog caching

For a better development experience, we disabled JSF resource caching and enabled XML validation in the Designer.

More

Enabling XML validation for .xhtml files can potentially cause validation errors during dialog execution, e.g. you can get a javax.faces.view.facelets.TagException when 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 javax.faces.PROJECT_STAGE to Production in the Designer's webapps/ivy/WEB-INF/web.xml file.

Deprecated for removal: 'webapps/ivy/shared'

The resources in the webapps/ivy/shared directory are deprecated and will be removed in later releases.

More

They have been used in JSP layouts of older Axon.ivy projects (< 8.0). Copy all used CSS, JS-scripts and images from an old installation into your Axon.ivy projects.

Workflow APIs

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.

More

Some ITask and ICase API was deprecated The numbered custom fields on ITask and ICase have been deprecated e.g.:

  • ITask.setCustomVarCharField1(String)
  • ITask.getCustomVarCharField1()
  • ITask.setCustomDecimalField1(Number)
  • ...

The same for the business fields on ITask and ICase:

  • ICase.setBusinessCreatorUser(String)
  • ICase.getBusinessCreatorUser()
  • ...

And for the categorization fields on ITask and ICase:

  • ICase.setProcessCategory(String, String)
  • ICase.getProcessCategoryCode()
  • ICase.getProcessCategoryName()
  • ...

Additional Properties have been deprecated:

  • Interface ch.ivyteam.ivy.workflow.IAdditionalPropertyable implemented by ITask and ICase
  • ch.ivyteam.ivy.workflow.IWorkflowContext.findTask(String, String, ...)
  • ch.ivyteam.ivy.workflow.IWorkflowContext.findCase(String, String, ...)
  • ch.ivyteam.ivy.workflow.query.TaskQuery.create().where().additionalProperty(String)
  • ch.ivyteam.ivy.workflow.query.CaseQuery.create().where().additionalProperty(String)

Use the new Custom Fields instead.

To categorize your Tasks and Cases you should still use ICase.setCategoryPath(String) and ITask.setCategoryPath(String).

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.

More

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:

  • ch.ivyteam.ivy.workflow.IWorkflowContext.findEventLog(...)
  • ch.ivyteam.ivy.workflow.IWorkflowContext.createEventLog(...)
  • ch.ivyteam.ivy.workflow.IWorkflowContext.createEventLogPropertyFilter(...)
  • ch.ivyteam.ivy.workflow.eventlog.EventLogDescription
  • ch.ivyteam.ivy.workflow.eventlog.EventLogProperty
  • ch.ivyteam.ivy.workflow.eventlog.EventLogSeverity
  • ch.ivyteam.ivy.workflow.eventlog.EventLogStatus
  • ch.ivyteam.ivy.workflow.eventlog.IEventLog
  • ch.ivyteam.ivy.workflow.eventlog.IEventLogCase
  • ch.ivyteam.ivy.workflow.eventlog.IEventLogTask

Apache POI included

We included the Apache poi-4.1.0 and 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 (webapps/ivy/WEB-INF/lib).

More

Migrate POI Projects

If you included Apache POI already in your projects, you must remove them. First remove instances of poi, poi-ooxml, poi-ooxml-schemas and xmlbeans libraries from your project classpath. To do so:

  • switch to Java perspective
  • detect instances of POI JARs within the Referenced Libraries container.
  • remove POI related JARs from classpath via: Context Menu (right click) > Build Path > Remove form Build Path.
  • delete these JARs afterwards also from the file system.

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:

  • CellStyle Enum has been replaced by HorizontalAlignment or VerticalAlignment Enum.
  • HSSFCellStyle Enum has been replaced by FillPatternType Enum.
  • facetFontStyle and cellFontStyle don't support setBoldWeight() anymore. You can directly call setBold().

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 webapps/ivy/WEB-INF/lib.

Removed libraries from project classpath

Some libraries have been removed from the project classpath and are no longer available to the Axon.ivy project.

More

If you still need them, you can add them manually to the Axon.ivy project. There is one big advantage: You can now use them in the version you need. It concerns the following libraries:

  • Lucene: lucene-core-4.5.1.jar, lucene-analyzers-common-4.5.1.jar, lucene-queryparser-4.5.1.jar
  • JGroups: jgroups-3.3.4.Final.jar
  • Jetty: jetty-continuation-7.4.5.v20110725.jar, jetty-http-7.4.5.v20110725.jar, jetty-io-7.4.5.v20110725.jar, jetty-server-7.4.5.v20110725.jar, jetty-util-7.4.5.v20110725.jar
  • Freemarker: freemarker-2.3.23.jar
  • Spring Security Crypto: spring-security-crypto-4.2.3.RELEASE.jar
  • DB Libraries: ecs-1.4.2.jar, hsqldb-1.8.0.10.jar, jt400-7.3.0.3.jar, jtds-1.3.1.jar, mysql-connector-java-5.1.42.jar, ojdbc8-12.2.0.1.jar, postgresql-42.1.3.jar, mssql-jdbc-6.2.1.jre8.jar
  • XML Libraries: jaxen-1.1.6.jar, dom4j-1.6.1.jar
  • JSON Libraries: jettison-1.3.8.jar
  • Helper Libraries: reflections-0.9.8.jar, 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.

Deprecated AccessFlags

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.

Others


Axon.ivy iOS app

Re-synchronise your device with the engine after migrating.

More

Tasks that are not synchronised and are being worked on may throw ViewExpiredExceptions when synchronising with the engine. This only happens the first time and won't have any side effects except that you must re-submit your data for said tasks.

After your device has been successfully synchronised with the engine you can start working on your tasks like always.

Migration 7.4 to 8.0


Licence

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.

More

Learn more about public URLs and how to install the new licence in the Engine Guide.

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.

Portal

Portal versions 7 and earlier are no longer compatible with Axon.ivy 8.0. If you have used the Portal in your projects, you must migrate your projects to Portal version 8.0.

Portal Migration Notes

Debian Packge

The LTS debian package axonivy-engine-8 does not come with migration supports for its predecessor (the axonivy-engine-7x). These packages are designed to run independent engines on the same host at a time.

However, with a few simple manual copy tasks you can migrate leading edge engines to the LTS equivalent.

More

Our proposed migration strategy for leading edge debian package users:
  1. Install the latest axonivy-engine-8 package on the host running the 7x version. The new engine will not contain any configurations or data from the 7x train yet.
  2. Copy configuration files: sudo -u ivy -g ivy cp -rf /etc/axonivy-engine-7x /etc/axonivy-engine-8
  3. Copy application files: sudo -u ivy -g ivy cp -rf /var/lib/axonivy-engine-7x/applications /var/lib/axonivy-engine-8/applications
  4. Turn of the old engine: sudo systemctl stop axonivy-engine-7x && sudo systemctl disable axonivy-engine-7x
  5. Reboot the new engine: sudo systemctl stop axonivy-engine-8 && sudo systemctl start axonivy-engine-8
  6. Verify that Axon.ivy Engine 8 serves your workflow app as expected

Administrator Configuration

There were a hidden feature for container customers to define an administrator in a single definition way, mainly used with environment variables. This is no longer supported.

More

BEFORE:
  • IVY_ADMINISTRATOR_USERNAME=myAdmin
  • IVY_ADMINISTRATOR_PASSWORD=1234
  • IVY_ADMINISTRATOR_EMAIL=abc@domain.com
AFTER:
  • IVY_ADMINISTRATORS_myAdmin_PASSWORD=1234
  • IVY_ADMINISTRATORS_myAdmin_EMAIL=abc@domain.com

HTML Dialog Caching

For a better development experience, we disabled JSF resource caching and enabled XML validation in the Designer.

More

Enabling XML validation for .xhtml files can potentially cause validation errors during dialog execution, e.g. you can get a javax.faces.view.facelets.TagException when 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 javax.faces.PROJECT_STAGE to Production in the Designer's webapps/ivy/WEB-INF/web.xml file.

Location prefix for custom error pages

If you use a custom error page (JSF) you need to add /faces prefix to the location in the web.xml.

More

BEFORE:
<error-page>
  <error-code>404</error-code>
  <location>/custom-404-error-page.xhtml</location>
</error-page>
AFTER:
<error-page>
  <error-code>404</error-code>
  <location>/faces/custom-404-error-page.xhtml</location>
</error-page>

Deprecated for removal: 'webapps/ivy/shared'

The resources in the webapps/ivy/shared directory are deprecated and will be removed in later releases.

More

They have been used in JSP layouts of older Axon.ivy projects (< 8.0). Copy all used CSS, JS-scripts and images from an old installation into your Axon.ivy projects.

Axon.ivy iOS App

Re-synchronise your device with the engine after migrating.

More

Tasks that are not synchronised and are being worked on may throw ViewExpiredExceptions when synchronising with the engine. This only happens the first time and won't have any side effects except that you must re-submit your data for said tasks.

After your device has been successfully synchronised with the engine you can start working on your tasks like always.

Migration 7.3.1 to 7.4


Java 11

Axon.ivy now runs with a Java 11 runtime environment:

More

Verify libraries

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 @PowerMockIgnore({"com.sun.myissue.*}) annotation. More

Fix sun and com.sun imports

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.

Linux Designers

Openjdk-11-jre's are pre-installed on many recent Linux distributions. Unfortunately as of today, with OpenJDK 11.0.4, 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.

Maven

A Java 11 JDK is required to execute Maven builds with the latest project-build-plugin. To prevent problems with multiple installed Java versions, the environment variable JAVA_HOME must be set.

PrimeFaces 7.0 upgrade

The User Dialog widget library PrimeFaces has been upgraded from 6.1 to 7.0.

PrimeFaces 7.0 comes with a few breaking changes. Therefore, please follow the official PrimeFaces migration guide to identify User Dialogs of your project that need manual adjustments.

More

Here is a list of the most common problems we encountered or changes we had to make:

  • Mobile has been removed. If you used any of the mobile (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.
    For example replace:
    • <pm:header> with <div class="container">
    • <pm:content id="content"> with <div class="ui-content">
  • facetFontStyle and cellFontStyle don't support setBoldWeight() anymore. You can directly call setBold().
  • Select one menu arrow alignment changed. Use !important for relative positioning.
  • autoUpdate attribute was removed from outputPanel, fragment, messages and growl. Use p:autoUpdate instead.
  • Change appendToBody="true" to appendTo="@(body)" in p:overlayPanel.
  • jQuery has been updated from version 1.11 to 3.3. Check your jQuery code if it is still valid.
  • Some of the styling has changed. Check your styling if it is still as expected.
  • The class org.primefaces.context.RequestContext is now deprecated.

Apache POI included

We included the Apache poi-4.1.0 and 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 (webapps/ivy/WEB-INF/lib).

More

Migrate POI Projects

If you included Apache POI already in your projects, you must remove them. First remove instances of poi, poi-ooxml, poi-ooxml-schemas and xmlbeans libraries from your project classpath. To do so:

  • switch to Java perspective
  • detect instances of POI JARs within the Referenced Libraries container.
  • remove POI related JARs from classpath via: Context Menu (right click) > Build Path > Remove form Build Path.
  • delete these JARs afterwards also from the file system.

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:

  • CellStyle Enum has been replaced by HorizontalAlignment or VerticalAlignment Enum.
  • HSSFCellStyle Enum has been replaced by FillPatternType Enum.
  • facetFontStyle and cellFontStyle don't support setBoldWeight() anymore. You can directly call setBold().

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 webapps/ivy/WEB-INF/lib.

Configuration files

Global app.yaml revoked

You are affected by this if you have used the global application configuration [engineDir]/configuration/app.yaml which has been introduced in 7.2.0.

More

The global application configuration was removed again in 7.4.0, because we think this is more confusing than helpful. Now, you must manually configure each application in its own app-<APPNAME>.yaml. For each application there is an app-<APPNAME>.yaml in the configuration directory. e.g. for application MyApp there is the file [engineDir]/configuration/app-MyApp.yaml.

Migration Steps:

  1. open [engineDir]/configuration/app.yaml
  2. copy the configuration for each application in every [engineDir]/configuration/app-<APPNAME>.yaml.
  3. you can now safely delete [engineDir]/configuration/app.yaml (or move it to another location for backup)

Example Migration:

BEFORE:
[engineDir]/configuration/app.yaml

ActiveEnvironment: production
AFTER:
[engineDir]/configuration/app-MyApp.yaml

ActiveEnvironment: production


[engineDir]/configuration/app-AnotherApp.yaml

 ActiveEnvironment: production

Removed Applications from ivy.yaml

Configurations in ivy.yaml which starts with the prefix Applications were specific to applications and are no longer supported.

You are automatically affected by this change if our [engineDir]/configuration/ivy.yaml contains any application specific configurations. This is automatically the case if you have migrated from 7.2.0 to 7.3.0.

Application configurations now have to be transfered to specific app-<APPNAME>.yaml files.

More

You must manually move all application specific configurations from [engineDir]/configuration/ivy.yaml file to the corresponding app-<APPNAME>.yaml in the configuration directory without the application prefix. e.g. for application MyApp there is the file [engineDir]/configuration/app-MyApp.yaml.

Migration Steps:

  1. open [engineDir]/configuration/ivy.yaml
  2. identifiy all application specific configurations, which are prefixed by Applications
  3. copy the configuration for each application to the corresponding [engineDir]/configuration/app-<APPNAME>.yaml.
  4. remove the application specific configuration from [engineDir]/configuration/ivy.yaml

Example Migration:

BEFORE:
[engineDir]/configuration/ivy.yaml

Applications:
  AnotherApp:
    EMailNotification:
      OnNewTasks: false
      DailySummaryOn: never
      Language: en
  MyApp:
    SecuritySystem: ADOfMyCompany
AFTER:
[engineDir]/configuration/app-AnotherApp.yaml

EMailNotification:
  OnNewTasks: false
  DailySummaryOn: never
  Language: en


[engineDir]/configuration/app-MyApp.yaml

 SecuritySystem: ADOfMyCompany

Renamed key Administrator.Name

This key can be used to declare an administrator with an environment variable. We renamed it to Administrator.UserName.

More

You might have used this environment variable to declare an administrator in your docker-compose.yaml to create an administrator user while creating a container. If you containerized your engine and used the IVY_ADMINISTRATOR_NAME variable, you must rename it to IVY_ADMINISTRATOR_USERNAME in your docker-compose.yaml or your administrator user won't be created. For an example visit our docker-samples on GitHub: docker-samples

Business Calendar definitions moved to app-<APPNAME>.yaml We moved all business calendar configurations from the system database into each application's app-<APPNAME>.yaml file.

This is done automatically during the system database conversion. Please review the app-<APPNAME>.yaml files after the conversion.

Due to this migration some rarely used Public API's are now deprecated and may no longer work as expected.

More

The following Public API's are deprecated and may no longer work as expected:

  • ch.ivyteam.ivy.workflow.query.TaskQuery.IFilterableColumns.businessCalendarId()
  • ch.ivyteam.ivy.workflow.query.TaskQuery.IGroupByQueryColumns.businessCalendarId()
  • ch.ivyteam.ivy.workflow.query.TaskQuery.IOrderByQueryColumns.businessCalendarId()
  • ch.ivyteam.ivy.workflow.query.CaseQuery.IFilterableColumns.businessCalendarId()
  • ch.ivyteam.ivy.workflow.query.CaseQuery.IGroupByQueryColumns.businessCalendarId()
  • ch.ivyteam.ivy.workflow.query.CaseQuery.IOrderByQueryColumns.businessCalendarId()
  • ch.ivyteam.ivy.application.calendar.IBusinessCalendarSettings.getBusinessCalendarId(String)
  • ch.ivyteam.ivy.application.calendar.IBusinessCalendarSettings.getBusinessCalendarId(IBusinessCalendar)
  • ch.ivyteam.ivy.application.calendar.IBusinessCalendarSettings.findBusinessCalendarConfiguration(Long)

See the Public API documentation of these methods to find out what methods you should use instead.

In case your projects use any of the methods above we suggest you refactor those before migrating your engine.

Please note that business calendar names in the app-<APPNAME>.yaml are case insensitive. Never use the same (case insensitive) business calendar name within the same yaml file.

Portal

The CaseTemplate has been deprecated.

User Dialogs that refer it should be migrated to use TaskTemplate.

Portal Migration Notes

Elasticsearch

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.

Engine launch configuration

The OS specific launch configuration files bin/AxonIvyEngine.conf (Linux) and bin/AxonIvyEngine.ilc (Windows) are now streamlined into the platform independent file configuration/jvm.options.

If you made any specific launch configuration in the old launcher files you need to manually migrate your settings to the new jvm.options file.

More

Due to platform-independent configuration setup we no longer consider the following launch configurations:

  • bin/Example.ilc
  • bin/AxonIvyEngine.conf
  • bin/control.conf
  • bin/*.conf
  • bin/*.ilc

We introduced the platform-independent configuration/jvm.options. You must migrate the settings in your *.ilc and *.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 jvm.options file.

EngineConfig binaries

The Axon.ivy Engine Configuration binaries have been removed. Namely bin/AxonIvyEngineConfig.exe, bin/AxonIvyEngineConfigC.exe and its Linux equivalent bin/AxonIvyEnginConfig.

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.

Keystore and Trustore

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 jks to pkcs12.

You are affected by this if you have installed custom certificates or private keys in truststore.jks or keystore.jks of the [engineDir]/configuration/ directory.

Import keys to the new pkcs12 store or configure Axon.ivy to use the legacy key- and truststore.

More

Migrate to pkcs12

Preferred solution is to use the new pkcs12 key- and trustore located in [engineDir]/configuration.

Export the existing certificates and private keys from keystore.jks / truststore.jks and import them into keystore.p12 / truststore.p12.

You can adapt this command to convert a store from jks format into pkcs12.

keytool -importkeystore -srckeystore truststore.jks -destkeystore truststore.p12 -srcstoretype JKS -deststoretype PKCS12 -deststorepass changeit

Enable legacy jks store

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:

  • SSL.Client.KeyStore.Type
  • SSL.Client.TrustStore.Type

Furthermore, keys that define a keystore path must be re-located to configuration/keystore.jks or configuration/truststore.jks The following keys must be adjusted:

  • SSL.Client.TrustStore.File
  • SSL.Client.KeyStore.File
  • Connector.HTTPS.KeystoreFile

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 [engineDir]/configuration from keystore to keystore.jks. Afterwards legacy JKS type must be enabled (see previous).

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.

More

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:

  • ch.ivyteam.ivy.workflow.IWorkflowContext.findEventLog(...)
  • ch.ivyteam.ivy.workflow.IWorkflowContext.createEventLog(...)
  • ch.ivyteam.ivy.workflow.IWorkflowContext.createEventLogPropertyFilter(...)
  • ch.ivyteam.ivy.workflow.eventlog.EventLogDescription
  • ch.ivyteam.ivy.workflow.eventlog.EventLogProperty
  • ch.ivyteam.ivy.workflow.eventlog.EventLogSeverity
  • ch.ivyteam.ivy.workflow.eventlog.EventLogStatus
  • ch.ivyteam.ivy.workflow.eventlog.IEventLog
  • ch.ivyteam.ivy.workflow.eventlog.IEventLogCase
  • ch.ivyteam.ivy.workflow.eventlog.IEventLogTask

Migration 7.3 to 7.3.1


Performance Improvements for Case and Task Queries

Exceptionally a system database migration is needed with this Update Release to improve the performance of Case and Task queries.

Migration 7.2 to 7.3


Rich Dialog (ULC) Technology removed

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.

Portal Application

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.

More

To migrate the Portal application, you need to do the following steps:

  1. Reconfigure the file directory of the Portal application. This can be done by writing an app-Portal.yaml file to the [[newEngineDir]/configuration directory and set the Data.FileDirectory property. See below.
  2. Copy all files of the Portal application from directory [[oldEngineDir]]/system/applications/Portal to the new file directory of the application [[newEngineDir]]/applications/Portal.
  3. Copy the PortalConnector from directory [[oldEngineDir]]/system/applications/System/PortalConnector to the new location at [[newEngineDir]]/system/application/PortalConnector.

Example app_Portal.yaml file:

Data:
    FileDirectory: applications/Portal

Removed Libraries from Project Classpath

We removed libraries from Axon.ivy Classpath container and therefore they can no longer be used in Axon.ivy projects. Removed were the classpath scanning library reflections-0.9.8.jar and the findbugs library annotations-2.0.3.jar.

If you have used these libraries in your project, you must add them to your projects manually. Afterwards a re-deployment of the updated projects is required to avoid NoClassDefFoundErrors at runtime.

Admin UI features

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 ivy.yaml file.

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.

More

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.yaml or 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.

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.

More

Some ITask and ICase API was deprecated The numbered custom fields on ITask and ICase have been deprecated e.g.:

  • ITask.setCustomVarCharField1(String)
  • ITask.getCustomVarCharField1()
  • ITask.setCustomDecimalField1(Number)
  • ...

The same for the business fields on ITask and ICase:

  • ICase.setBusinessCreatorUser(String)
  • ICase.getBusinessCreatorUser()
  • ...

And for the categorization fields on ITask and ICase:

  • ICase.setProcessCategory(String, String)
  • ICase.getProcessCategoryCode()
  • ICase.getProcessCategoryName()
  • ...

Use the new Custom Fields instead.

To categorize your Tasks and Cases you should still use ICase.setCategoryPath(String) and ITask.setCategoryPath(String).

Database Tables

The corresponding columns have been removed from the system database tables (IWA_Task, IWA_Case). The data stored in those columns gets migrated to the new Custom Field tables (IWA_TaskCustom*Field, IWA_CaseCustom*Field). The deprecated setter and getter methods on ITask and ICase still work but now read and write data to the new Custom Field tables.

Query

Note that the CaseQuery and TaskQuery API are backwards compatible. If you have used the recordset API ch.ivyteam.ivy.persistence.query.IFluentQueryExecutor.recordset() to read Cases and Tasks then be aware of that these columns will not be part of the recordset anymore.

The inscription mask tab for the numbered custom fields, business information fields and categorization fields were removed. You can find your old inscriptions now in the new custom field inscription mask table.

Categorization

Until now, you could use macros for the categorization fields; they are now converted to ivy scripts. There is one special case that 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 a macro in the specified cms path, this macro will not be expanded anymore.

Additional Property API deprecated

Additional Properties have been deprecated:

  • Interface ch.ivyteam.ivy.workflow.IAdditionalPropertyable implemented by ITask and ICase
  • ch.ivyteam.ivy.workflow.IWorkflowContext.findTask(String, String, ...)
  • ch.ivyteam.ivy.workflow.IWorkflowContext.findCase(String, String, ...)
  • ch.ivyteam.ivy.workflow.query.TaskQuery.create().where().additionalProperty(String)
  • ch.ivyteam.ivy.workflow.query.CaseQuery.create().where().additionalProperty(String)

Use the new Custom Fields instead.

Database Tables

The tables used to store Additional Properties for Tasks and Cases (IWA_AdditionalProperty, IWA_TaskAdditionalProperty, IWA_CaseAdditionalProperty) have been removed from the system database. The data stored in those tables is migrated to IWA_TaskCustomTextField and IWA_CaseCustomTextField during the system database conversion. The deprecated Additional Properties API still works but now reads and writes data to the new Custom Field tables.

Note that search performance for Text Custom Fields is worse than those of the other Custom Field types. Consider using String, Number or Timestamp Custom Fields instead of Text Custom Fields.

Business Calendar Name

All inscribed business calendar names on case and task tab will be automatically converted to the newly introduced script fields. ivy.cal in task inscription is not mapped anymore to the business calendar name that has been inscribed in this tab.

Migration 7.1 to 7.2


Remove of Rich Dialog (ULC) Technology

Rich Dialog (ULC) technology will be removed. Axon.ivy 7.0 LTS is the latest version where Rich Dialogs (ULC) are fully supported. You must convert Rich Dialogs (ULC) to HTML Dialogs (JSF) in all your projects or stick on version 7.0 LTS.

More

  • With 7.1 we dropped the support for Rich Dialog Visual Editor. You can still open and edit Rich Dialog Panels with the Java class editor.
  • With 7.2 you can not built projects with Rich Dialogs (ULC) in the Designer. However, projects that use Rich Dialogs (and built with 7.1 or earlier) still works on the Engine.
  • For 7.3 we plan to remove the Rich Dialogs (ULC) technology completely.

Removed Libraries from Project Classpath

The following libraries are no longer part of the project classpath. If you require them in your project you need to add them to your project manually:

Test scoped maven dependencies not on compile Classpath

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 test directory.

More

You can achieve that as follows:

  1. switch to the Java perspective
  2. open the context menu of the source directory that contains test (e.g. src_test)
  3. select 'Build Path' > 'Configure Build Path...' in the context menu
  4. expand the test source directory within Java Build Path dialog
  5. select 'Contains tests sources: ...'
  6. hit the 'Toggle' button to change the value to 'yes'

BuildPath

The change value will be reflected within the .classpath of your project.

Deprecated AccessFlags

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.

Application name is case insensitive

If you have several applications with the same name (case sensitive) installed, these duplicated applications must be removed before an update. Example: Applications MyAPP and MyApp are installed. Remove one of the two applications.

Axon.ivy Engine Demo Mode Defaults

Default Log Filename

The name of the default log file has changed from logs/ch.ivyteam.ivy.log to logs/ivy.log

Removed serverconfig.xml

We removed the serverconfig.xml file in the configuration folder. The system database settings are now stored in the ivy.yaml file.

More

If you have a serverconfig.xml you should copy it into the new engine along with your other configuration files. The settings in the serverconfig.xml file are automatically converted during the next boot of the engine.

Changed stored file paths for files attached to cases and workflows

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.

More

This change requires us to convert the file paths in the database (table 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.

Migration 7.0 to 7.1


Removed Libraries from Project Classpath

Some libraries have been removed from the project classpath and are no longer available to the Axon.ivy project.

More

If you still need them, you can add them manually to the Axon.ivy project. There is one big advantage: You can now use it in the version you need. It concerns the following libraries:

  • Lucene: lucene-core-4.5.1.jar, lucene-analyzers-common-4.5.1.jar, lucene-queryparser-4.5.1.jar
  • JGroups: jgroups-3.3.4.Final.jar
  • Jetty: jetty-continuation-7.4.5.v20110725.jar, jetty-http-7.4.5.v20110725.jar, jetty-io-7.4.5.v20110725.jar, jetty-server-7.4.5.v20110725.jar, jetty-util-7.4.5.v20110725.jar
  • Freemarker: freemarker-2.3.23.jar
  • Spring Security Crypto: spring-security-crypto-4.2.3.RELEASE.jar
  • DB Libraries: ecs-1.4.2.jar, hsqldb-1.8.0.10.jar, jt400-7.3.0.3.jar, jtds-1.3.1.jar, mysql-connector-java-5.1.42.jar, ojdbc8-12.2.0.1.jar, postgresql-42.1.3.jar, mssql-jdbc-6.2.1.jre8.jar

Library upgrades

REST services: CSRF-protection now enabled by default

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

More

To call a modifying REST service via PUT, POST or DELETE the caller needs to provide a HTTP Header called X-Requested-By with 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 GET, HEAD or OPTIONS should 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.

The engine operates with packed projects

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.

More

Already deployed projects keep their expanded directory format.

Read-only projects

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 java.nio.file.ReadOnlyFileSystemException.

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:

  • with the maven project-build-plugin, the configuration parameter deployTargetFileFormat must be set to EXPANDED.
  • with the deploy directory, it can be enforced by providing an options.yaml file with the following content
target
  fileFormat : EXPANDED
  • with the Engine Cockpit, use the EXPANDED File Format Option in the deployment dialog.

IvyAddOns not supported anymore

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.

Macros in Authentication Section of Web Service Call Inscription

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.

Import a Xpert.ivy 3.9 project is no longer possible

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.

Renew / Change the session ID after login

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 Session.RenewIdOnLogin to 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 Session.RenewIdOnLogin to true.




Further Migration Hints


Project Conversion

When a new project version is introduced, a project conversion should be made. In the Axon.ivy Designer the project is marked with an error, there you can right-click on the project and use Convert to convert the project. We distinguish between optional and necessary project conversion. Optional project conversions lead to the fact that already deployed projects continue to run without a conversion. If a project migration is necessary, the projects must first be converted in the Axon.ivy Designer and then newly deployed.

System Database Conversion

Migrating an Engine usually implies a conversion of the system database. This can be resolved automatically by invoking the System Database Conversion.

Upgrade Apache Tomcat Connector

If the Engine is integrated with a reverse proxy (e.g. IIS or Apache), it is best practice to check if the most recent Apache Tomcat Connector is installed. For further information look at Upgrade Apache Tomcat Connector.

Previous Migration Notes