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.

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.

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.

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:

ActiveEnvironment: production

ActiveEnvironment: production

 ActiveEnvironment: production

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:

Applications:
  AnotherApp:
    EMailNotification:
      OnNewTasks: false
      DailySummaryOn: never
      Language: en
  MyApp:
    SecuritySystem: ADOfMyCompany

EMailNotification:
  OnNewTasks: false
  DailySummaryOn: never
  Language: en

 SecuritySystem: ADOfMyCompany

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

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

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.

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

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