Migrating from 9.2 to 9.3

New project version

Due to the migration of the External Databases, Rest Clients, Web Service Clients, Environments, Formats, and Projects to Eclipse Maven projects, we introduced a new project version 93900. If you have an existing project in version:code:80000, it will still run on the Axon Ivy Engine, but we recommend migrating your projects to the new version and re-deploy them.

Defining Databases

Configurations of Databases are stored in new locations. During development, the project’s Databases are now stored in the databases.yaml file. On the Axon Ivy Engine, the configurations of Databases have been moved from the System Database to the application’s app.yaml file. Furthermore, the System Database and project migration converts from the old to the new format automatically.

Details

We have dropped the System Database tables IWA_ExternalDatabase and IWA_ExternalDatabaseProperty and migrated its data to the app.yaml. We recommend that you migrate your projects and redeploy them to your engine.

All APIs to load databases configuration from IApplication and IEnvironment has been removed. They were introduced to show the configuration in the legacy AdminUI. They were never intended to be used in your Axon Ivy Projects.

Defining REST Clients

Configurations of REST Clients are stored in new locations. During development, the project’s Rest Clients are now stored in the rest-clients.yaml file. On the Axon Ivy Engine, configurations of REST Clients have been moved from the System Database to the application’s app.yaml file. Furthermore, System Database and project migrations do converts from the old to the new format automatically.

Details

We have dropped the System Database tables IWA_RestClient, IWA_RestClientFeature and IWA_RestClientProperty and migrated its data to the app.yaml. We recommend that you migrate your projects and redeploy them to your engine.

Defining Web Service Clients

Configurations of Web Service Clients are stored in new locations. During development, the project’s Web Service Clients are now stored in the webservice-clients.yaml file. On the Axon Ivy Engine, configurations of Web Service Clients have been moved from the System Database to the application’s app.yaml file. Furthermore, System Database and project migrations converts from the old to the new format automatically.

Details

We have dropped the System Database tables IWA_WebService, IWA_WebServiceEndpoints, IWA_WebServiceEnvironments, IWA_WebServiceFeature, IWA_WebServicePortType and IWA_WebServiceProperty and migrated its data to the app.yaml. We recommend that you migrate your projects and redeploy them to your engine.

Environments

The environment editor and all environment aware editors like the Web Service Client Editor, the REST Client Editor, and the Database Editor are not environment aware anymore. Learn how you can define environment aware configurations.

Read more here about the future of environments: https://community.axonivy.com/d/142-environments-will-disappear-in-the-long-term

Formats

Formats are migrated from the so-called config CMS to the config/formats.yaml in your project. There is no more UI Editor to edit those formats. If you migrate a running Axon Ivy Engine you need to convert your projects and redeploy them again to make formats work.

Configuration deployment options removed

Now that most of the app configuration is defined in YAML files, the configuration deployment options are disregarded and can be removed from your deploy.options.yaml file.

Details

The following options are deprecated and can be removed:

configuration:
  overwrite: false               # [false], true
  cleanup: DISABLED              # [DISABLED], REMOVE_UNUSED, REMOVE_ALL

Removed support for CMS Page

We no longer support CMS pages. Both in Axon Ivy Designer and on Axon Ivy Engine. You will need to manually re-implement them to an alternative. For example as HTML Dialog (JSF) or as static JSF page. We still support plain JSP pages which would be a non-future alternative.

Removed support for Macro expansion in RTF documents

RTF is not a common format anymore. We have supported macro expansion in RTF documents from CMS. This is no longer working. To generate documents with placeholders, use other well-maintained components like the DocFactory.

Moved JSP pages from CMS to webContent

We now only support plain JSP pages in the webContent folder. The project conversion copies the JSP pages from the CMS automatically to the webContent folder.

Non-public API Email

If you have used some non-public email classes like EmailSetupConfiguration, EmailSetupProviderUtil or SimpleMailSender then you need to touch your project because they no longer exist. We are currently building a public API for mail. It is already available but not officially public yet:

import ch.ivyteam.ivy.mail.MailClient:
import ch.ivyteam.ivy.mail.MailMessage;

try (var client = MailClient.newMailClient()) {
  var message = MailMessage.create()
    .to("my.good.old.friend@neighborhood.com")
    .subject("Beer!")
    .textContent("Do you feel like having a beer on Friday?")
    .toMailMessage();
  client.send(message);
}

Drop AXIS Technology for Web Service Client

With Axon Ivy 7.1 we have introduced the CXF Web Service Client as a super-fast, secure, and future-proof technology to call SOAP Web Services. AXIS has been making more and more trouble. To keep the quality of Axon Ivy on a high level we need to remove AXIS. You have to convert all Web Service Clients based on AXIS (1+2) to CXF in the Axon Ivy Designer.

Details

The Designer comes with a project converter to convert your Axis2 clients automatically to CXF. Additionally, a quick fix is available on the Axis error marker.

The detailed steps to migrate from AXIS clients to CXF are outlined here: https://community.axonivy.com/d/199-migrate-from-axis2-webservice-to-cxf

Overriding

We deprecated the Case Scope (deprecated) project overrides in favor of Strict Overriding.

Details

If your application uses Overrides. You should migrate to Strict Overriding. Define the customization project in your app.yaml.

OverrideProject: com.acme.solution:MyCustomerAdaption

Default REST Client entity processing changed to buffered

Since we are using the ApacheConnectorProvider as the default provider for Rest Clients, the default entity processing has changed from BUFFERED to CHUNKED. This means that the HTTP header Content-length is not set which makes trouble with a lot of services. You can fix this by switching to chunked processing again. Change your REST Client config and set the property jersey.config.client.request.entity.processing to CHUNKED.

System Database Cache Configuration and MBean (JMX)

We have changed the System Database cache configuration. Instead of configuring a UsageLimit you can now configure a TimeToIdle (TTI) value. As an alternative, you can also configure a TimeToLive (TTL) value.

Details

The TimeToIdle value specifies how long the cache keeps an object after the last usage. Whereas the TimeToLive value specifies how long the cache keeps an object after the first usage. Have a look at configuration\ivy.cache.properties and replace all configured UsageLimit values with appropriate TimeToIdle and/or TimeToLive values. By default, the TimeToIdle value is 600 (10 minutes) and the TimeToLive is 0 (disabled).

The usageLimit attribute on MBeans with name pattern ivy Engine:type=CacheClassPersistencyService,name=*,strategy=CacheAllRemoveUnused has been removed. Instead, we introduced the timeToIdle and timeToLive attributes.

Cluster Name

The name of a cluster (Axon Ivy Engine Enterprise Edition) can now be configured in the ivy.yaml file. Before, it was pre-configured in the license file as server.cluster.name property.

JGroups Configuration

JGroups is the library we use to communicate between cluster nodes (Axon Ivy Engine Enterprise Edition). By default, you do not need to provide the jgroups.xml file in the configuration folder anymore. Please remove your existing jgroups.xml file from the configuration folder, if you have not made any changes to it; otherwise replace it with a standard JGroups 5.0 jgroups.xml file and re-apply your changes to this file. jgroups.xml files used in earlier versions of the Axon Ivy Engine are not compatible with JGroups 5.0.

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 highlights behaviors or features that are deprecated. That functionality will be removed soon. If you 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 has been available for the engine operation. If you 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 certain 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. That functionality will be removed soon. If you are a project developer, check if this change affects you.

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