Migration Notes for Axon.ivy Engine 7.0 (Jakobshorn)

This document informs you in detail how to migrate the data and projects of an existing Axon.ivy Engine 6.0 (Säntis) installation to a new Axon.ivy Engine 7.0 (Jakobshorn) installation.

When migrating an Axon.ivy Engine it may also be necessary to convert the deployed projects. Specially, if your projects are using HTML Dialogs with Primefaces. Therefore, also read the Designer Migration Notes before migrating the engine.

Table of Content:

New engine license required

Migration needed for all versions

The Axon.ivy Engine 7.0 requires a new license. Please contact your sales agent to upgrade your license.

The section "Installing a Licence" in the Installation chapter of the Engine Guide describes how to install a new license.


OSGi engine

Migration needed for all versions

The Axon.ivy Engine now runs in OSGi mode by default. This means that the runtime environment of an OSGi based Engine and a Designer is now nearly the same, which should reduce the amount of class loading problems significantly.

Axon.ivy Extensions (*.extensions file deprecated)

Like Axon.ivy Designer the Engine now also supports the Eclipse extension point mechanism. Therefore, extensions can be registered in the plugin.xml that is located in your Axon.ivy extension bundle (*.jar file). It is no longer necessary to write a *.extensions file and put it into the configuration/extensions directory.

Old Axon.ivy extensions with a *.extensions file still work but are deprecated. We suggest to refactor Axon.ivy extensions to use the plugin.xml file instead. Support for *.extensions file will be removed in future versions.

Tomcat valve

A custom Tomcat valve, that is used to authenticate your users, must be made accessible to the Axon.ivy OSGi environment. Basically the JAR that provides this valve needs additional OSGi headers in its manifest. In the Axon.ivy Engine Guide there is a new chapter that explains how you can provide your valve extension so that it can be used by the Tomcat in Axon.ivy:

See Engine Guide > Configuration > Configure Tomcat > Custom Valve

Supported Databases

Migration not needed for 6.4..7.0

With this release some old and rarely used databases are no longer supported. We dropped the database support for Sybase SqlAnywhere and IBM DB2 LUW.

The list of supported System Databases can be found in the Engine Guide:
See Engine Guide > Configuration > Engine Configuration > System Database

We also removed the bundled JDBC driver for these products so they are no longer usable as external database out of the box. But it is still possible to add your own JDBC driver to the classpath by copying it to jre/lib/ext.

System Database creation, character set and collation

Migration not needed for 6.6..7.0

You have now the possibility to previously create an empty Axon.ivy system database. In this case the server configuration tool will only create the necessary tables into the given database.

Additionally, in the Axon.ivy Engine Guide (Configuration / System Database) you will find some basic notes about character set and collation and how you can change them. The character set and collation influence which languages (e.g. Chinese characters) are support and how the database queries work (case insensitive).

Linux service based on systemd

Migration not needed for 6.5..7.0

The scripts to run the Axon.ivy Engine as a service under Linux are now based on systemd (AxonIvyEngine.service).

Please install the new service by starting ./InstallService.sh as root in the bin/ directory of your Engine.

Remove the old init.d service found under /etc/init.d/AxonIvyEngineService.

See Engine Guide > Miscellaneous > Tool Reference > InstallService for more information.

Portal

Migration needed for all versions

The Portal application that is bundled with the Engine has been improved in many areas. If you have customized the Portal please refer to the chapter Migration Notes in the PortalKit Documentation.

Session attributes cleaned after user logs out

Migration not needed for 6.4..7.0

Session attributes are cleaned after the logout of a user. Projects should not depend on values stored in a session after a logout.

Workflow Permissions

Migration not needed for 6.5..7.0

To change the expiry date of a Task previously the permission TaskWriteExpiryActivator was needed, now the new permission TaskWriteExpiryTimestamp is needed.

Assign the permission TaskWriteExpiryTimestamp to users and roles that should have the ability to change the expiry date of a task.

JSP Taglibraries

Migration not needed for 6.2..7.0

Taglibraries for JSP are no longer loaded and used by the Tomcat webserver if they are on the classpath of an IvyProject. Instead only taglibraries within the webapps/ivy/WEB-INF/lib folder is used.
Since most JSP implementors only use the standard JSTL 1.2 taglibrary, it is now included in the WEB-INF/lib directory by default.

Primefaces Theme

Migration not needed for 6.1..7.0

If you have configured a Primefaces theme in the file webapps/ivy/WEB-INF/web.xml and want to use the new feature to set the Primeface theme per application then you have to change the web.xml file as follows:

Change the following entry in the old web.xml:

<context-param>
  <param-name>primefaces.THEME</param-name>
  <param-value>le-frog</param-value>
</context-param>

to

<context-param>
  <param-name>primefaces.THEME</param-name>
  <param-value>#{ivyPrimefacesThemeResolver.getTheme('le-frog')}</param-value>
</context-param>

Project dependencies

Migration not needed for 6.1..7.0

In Axon.ivy 6.0 the project versions 1.0.0 and 1.0.0-SNAPSHOT were treated as equal. With the change to the new version format in Axon.ivy 6.1 the versions are treated as in maven. This means the version (e.g. 1.0.0) is greater than the SNAPSHOT version (e.g. 1.0.0-SNAPSHOT). A project deployed previously of Axon.ivy 6.1 with a version of 7 now shows up as 7-SNAPSHOT.

Process Model Version activity and release state

Migration not needed for 6.4..7.0

Earlier a process model version was put to the release state ARCHIVED if it had no running cases. Now, a process model version is only put to the release state ARCHIVED if it has no running cases and all process model versions that are using it over project dependencies are also in state ARCHIVED. This ensures that a process model version in state ARCHIVED is nowhere used and therefore resources can be saved because it's project files do not have to be loaded and started.

Earlier a process model version had an activity state ACTIVE if the process model version and it's process model and application had a configured ACTIVE activity state . Now, a process model version has only an activity state ACTIVE if additionally also the release state is RELEASED or DEPRECATED. A process model version in release state PREPARED, ARCHIVED or DELETED can therefore never be ACTIVE. This means the activity state now correspond to the state of the process engine and therefore better shows what is going on inside the engine.

Now, during engine startup, only process model versions that can be brought to state ACTIVE are started. In Axon.ivy 6.3 and earlier all process model version were started during engine startup independent of their activity and release states.

RIA client libraries

Migration not needed for 6.5..7.0

The engine does no longer contain the compressed pack200 webstart libraries for Rich Dialog applications. The normal client libraries packed as jar are still available. So any Rich Dialog application runs out of the box.

If your application contains mainly Rich Dialogs you can still enable pack200 client libraries in order to save network bandwidth. To do so you have to run a script in the commandline that will create the pack200 libararies in pack.gz format.

For more information see Engine Guide > Miscellaneous > Rich Dialogs > Compressed Client Libraries

Removal of deprecated Public API

Migration not needed for 6.1..7.0

The following Public API has been removed:

It was marked as deprecated for several years. The API was used for programmable process elements (Program Start Event, Program Intermediate Event, Program Interface Activity). Bean implementations using this class must be rewritten to use the new editor class ch.ivyteam.ivy.process.extension.impl.AbstractProcessExtensionConfigurationEditor.

Business Data

Migration only needed for 6.3..7.0

Format migration required

The stored JSON format of the Business Data values has been changed. Therefore, Business Data values, written with a previous version, are no longer accessible with the BusinessDataRepository until they are explicitly migrated.

To migrate your stored Business Data to the latest version you must add a new process in your ivy project that owns the root Business Data class. This process should call ch.ivyteam.ivy.business.data.store.migration.BusinessDataJsonFormatMigrator.migrate(com.workflow.MyBusinessData.class, false) in a script activity. Re-deploy the project and start an instance of this process to apply the migration. Ensure that you call the migration method for each root Business Data classes of your application.

See WorkflowDemos > Processes > BusinessData > MigrateData for an example

Elasticsearch server

Axon.ivy Engine now requires an Elasticsearch server 5.5.x. If you run an Axon.ivy Standard Edition the bundled Elasticsearch server is used and no additional setup steps are required. If you migrate an Axon.ivy Enterprise Edition you have to setup an external Elasticsearch server and configure the connection in Axon.ivy Engine. If you already have used an external Elasticsearch server migrate it to 5.5.x before migrating Axon.ivy to 6.7 or higher.

See Help > Engine Guide > Installation > Elasticsearch Installation

Prior to 6.7 the Java vm arguments used to start the bundled Elasticsearch server were stored in the system property Elasticsearch.BundledServer.JavaVmArguments. Since 6.7 they are now stored in the file elasticsearch/config/jvm.options and the system property was removed.

If you have configured other values than the default then reapply the changes in the jvm.options file.

Elasticsearch index migration

If an Elasticsearch index exists that has been created with a previous Axon.ivy Engine version (6.7 and later) the pre-existing index can be copied.

To reuse the pre-existing index simply copy elasticsearch/data/ directory from the currently installed engine to the same directory in the new Engine installation.

If no Elasticsearch index is copied or the index has an old version, the index is re-created on the first engine startup after the migration.

JVM Route Ids have changed

Only affects Engine Enterprise Edition installations

The JVM Route Ids of the cluster nodes have changed and need to be adjusted accordingly if they were specified in the workers.properties of the load balancer. See: Load Balancing with Tomcat connector