Migrating from 9.1 to 9.2

New project version

Due to the migration of the Global Variables, we introducing a new project version 92000. If you want to deploy a project to a Axon Ivy Engine 9.2, your project must be in this version. If you have a running project, it will still be able to run, but we recommend migrating your projects to the new version and redeploying them to your engine.

Business Case Lifecycle

The lifecycle of the Business Case has been simplified. The first case is the business case and will stay the business case forever. Additional cases will be sub cases of the business case.

Details

Previously the first case (formerly initial case) was copied as soon as new cases were attached. The copy was then the business case.

This change also means that the business case can now have tasks as direct children and not only sub cases as children.

Changes in app.yaml

New file locations

Shifting towards highly configurable ivy projects we needed to move the app.yaml to a new location in the Axon Ivy Engine.

Details

If the new engine is aware of the existing applications, the app.yaml files should be migrated automatically. The new locations look like the following:

Old Location	New Location
/[engineDir]/applications/myApplication/app.yaml	/[engineDir]/applications/myApplication/config/app.yaml
/[engineDir]/configuration/app-myApplication.yaml	/[engineDir]/configuration/applications/myApplication/app.yaml

If you deploy an app.yaml in an application zip file, it must be placed now in the sub-folder config. For compatibility reasons the old legacy place in the root of the full application deployment zip is still supported for the time being.

Renaming Global Variables

The GlobalVariables in the app.yaml are renamed to Variables. This is done automatically by the system database migration.

Details

Old app.yaml:

GlobalVariables:
  myVariable: value

New app.yaml:

Variables:
  myVariable: value

Defining Global Variables

Global Variables are stored in new locations. During development, the project’s Global Variables are now stored in the variables.yaml file. On the Axon Ivy Engine, Global Variables have been moved from the System Database to the application’s app.yaml file. Furthermore, database and project migrations do the conversion from the old to the new format for you automatically.

Details

Project:

Global Variables are no longer defined using the configuration editor but in the variables.yaml file within your project.

By running the latest Project-Migration in your Designer, your existing Global Variables are automatically migrated into the variable.yaml files.

Operation:

We have dropped the system database table IWA_GlobalVariables and migrated its data to the app.yaml. We recommend that you migrate your projects and redeploy them to your engine. If you used your app.yaml to override Global Variables, please take note of this change as well: Supporting Environments.

Supporting Environments

As we now support Environments for our app.yaml, the app.yaml will no longer override all environment values. If you want to override a value for a specific Environment, define this value in the _<environment>/app.yaml file, besides in the normal app.yaml file.

Custom Application Properties API deprecated

The Public-API’s ICustomProperties, ICustomProperty and ICustomPropertyProvider are deprecated and will be removed in the near future. Please use the Ivy.var() API to create application variables.

Upgrade Log4j 1 to Log4j 2

Logs are written now with Log4j 2, which has a new configuration format. If you made any custom logging configuration entries, you need to adapt these changes to the new logging configuration.

Details

The legacy logging configuration file [engineDir]/configuration/log4jconfig.xml is no longer in charge. You need to make all your custom logging configuration in [engineDir]/configuration/log4j2.xml. Read more about customizing in the Logging chapter.

HTTPS port disabled by default

HTTPS port is now disabled by default on the Axon Ivy Engine, because you should always terminate SSL on the reverse proxy (frontend webserver). If you need HTTPS directly on the Axon Ivy Engine then you need to set the property WebServer.HTTPS.Enabled to true in ivy.webserver.yaml.

Frontend config combined into BaseUrl

The configuration of the frontend url in ivy.yaml has been simplified. You need to define now the BaseUrl in your ivy.yaml. This property is a combination of the old frontend properties Frontend.Host, Frontend.Protocol and Frontend.Port.

AJP support is deprecated

AJP is used to integrate the Axon Ivy Engine with Microsoft IIS or Apache http as reverse proxy. We still support AJP but you should migrate to a more modern URL rewrite approach based on HTTP/HTTPS.

Details

AJP’s days are numbered. It is not getting developed any further and prevents the use of new web features such as websockets. We highly recommend to migrate to a modern URL rewrite approach based on HTTP/HTTPS, in future versions of Axon Ivy Engine you won’t be able to use AJP.

If you are using Microsoft IIS as your reverse proxy proceed as follows:

1. Open the IIS administration interface.

2. Delete the virtual directory named ivy which you can find under Default Website.

3. Follow the instructions here on how to integrate Microsoft IIS with a modern URL rewrite.

If you are using Apache http as your reverse proxy you need to reconfigure Apache http.

SSL Client Configuration

We made the life of Axon Ivy Engine administrators easier with some simplifications in the SSL configuration.

Details

We removed SSL.Client.UseSystemTruststore and SSL.Client.UseCustomTruststore in the ivy.yaml. It’s not possible to configure them anymore. The system truststore of the JVM and the custom truststore of Ivy are always active now. If you don’t trust a certificate, simply remove it from the truststore.

Workflow Event Log API removed

The Workflow Event Log API has been deprecated in Axon Ivy 8.0 and has been removed now. As it was never Public API, most projects will not be affected.

Details

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

Legacy jTDS driver for MS SQL Server dropped

The legacy jTDS driver have been dropped. You need to switch to the official Microsoft JDBC Driver for the System Database and external databases if you still have used the jTDS driver.

Details

System Database

1. Go to Engine Cockpit / System Database

2. Choose Driver Microsoft SQL Server

3. Click Check Connection

4. Click Save

5. Restart Axon Ivy Engine

External Databases

1. Go to Engine Cockpit / External Databases

2. Edit all External Databases with Driver net.sourceforge.jtds.jdbc.Driver

3. Choose com.microsoft.sqlserver.jdbc.SQLServerDriver as Driver

4. Save configuration

Remove support for MySQL 5.5 as system database

MySQL 5.5 has been released in 2010 and is end of life. We do no longer support MySQL 5.5. We recommend to upgrade to MySQL 8.

Details

If you use MySQL as your system database or as an external database then you may have configured com.mysql.jdbc.Driver as the driver. MySQL has deprecated this driver and you should change it to com.mysql.cj.jdbc.Driver. The old driver still works.

Enabled JavaTime module for Rest Clients by default

The standard JSON serialization feature for Rest Clients is now aware of JavaTime objects, such as ZonedDateTime, and will therefore optimize their JSON representation.

Details

E.g. java.time.ZonedDateTime will be serialized as a simple timestamp number, rather than a complex object structure.

This change should not have any side-effects on existing clients since java.time objects, which did not have any special serializer features enabled, could not be serialized in a way that provides any value outside of the java world.

However, if you face any issues with the changed java.time object serialization, you may disable the JavaTime module by setting the RestClient property JSON.Module.JavaTime=false

Removed StartSignalEventElementQuery

There used to be an API to create a query for StartSignalEventElements (StartSignalEventElementQuery). As the StartElements are no longer part of the System Database, we removed this API. If you had this API in usage, please change to the simpler methods all(), matches(pattern) or contains(part).

Details

Replace usages of:

• Ivy.wf().signals().receivers().createStartSignalQuery()

With one of:

• Ivy.wf().signals().receivers().all()

• Ivy.wf().signals().receivers().matches(pattern)

• Ivy.wf().signals().receivers().contains(part)

Maven dependencies automatically packed into Ivy archives

With 9.2, it is no longer necessary to copy maven dependencies to a specific folder manually or with the Maven dependency plugin. However, the old way still works.

Details

There is a new project-build-plugin version 9.2.1 with new execution goals, which are active per default:

• maven-dependency: Copy maven dependencies to lib/mvn-deps

• maven-dependency-cleanup: Remove lib/mvn-deps folder.

When you use the functions to pack or export projects in the Axon Ivy Designer, the same happens as with the Maven plugin:

• Your Maven dependencies are copied to the lib/mvn-deps folder.

If you used the Maven dependency plugin to copy your dependencies and you have made manual entries to the .classpath file, you can remove those now and use the normal Maven dependencies descriptor. To remove those entries you can edit the .classpath file directly or use the Axon Ivy Designer.

Before:

After:

Warning

Make sure that your project is converted to a Maven project!

Only dependencies with the scope compile, system and runtime are copied. To reduce the size of your ivy archive, make sure that your dependencies are configured correctly:

• Mark test dependencies with the scope test

• Exclude transient dependencies that are already delivered by the Ivy core

Tag Legend:

This migration is handled either by the Migration Wizard or by the System Database conversion. The wizard will interact with you if you are affected by this change.

This migration will change something in the engine operation. If you are responsible for the operation of an engine, check if this change affects you.

This migration will highlight that a behavior or feature is deprecated in the engine operation. It means that this functionality will maybe removed in the near future. If your are responsible for the operation of an engine, you should check if this change affects you.

This migration will remove a behavior or feature that was available for the engine operation. If your are responsible for the operation of an engine, check if this change affects you.

This migration is handled by the Project Conversion automatically.

This migration will change a behavior in the projects. If you are a project developer, check if this change affects you.

This migration will mark features or APIs as deprecated in projects. It means that this functionality will maybe removed in the near future. If you are a project developer, check if this change affects you.

This migration will remove a behavior or feature for projects. If you are a project developer, check if this change affects you.