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.

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

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

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

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

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.

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

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'

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

• 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

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.

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.