The entrance point for every Axon Ivy Engine Migration since 10.0 is the migration wizard. Multiple migration tasks will be done:
Migration Tasks
- Base Url Migration The fronted properties
Frontend.Protocol, Frontend.HostName, and Frontend.Port will be read from ivy.yaml, combined into the property BaseUrl and will be written to ivy.yaml. The old frontend properties will be removed in ivy.yaml.
- Copy Configuration Files The configuration files from the old engine will be copied to the new engine
[engineDir]/configuration. The ivy.cache.properties will be copied to ivy.cache.lts8.properties and are not in charge anymore, because the file has been completely revised. You need to re-configure the ivy.cache.properties manually after migration if needed. Same for jgroups.xml which will be copied to jgroups3.xml and is only used for clustering. You need to configure manually log4j2.xml if you made any special configurations in log4jconfig.xml, because we updated log4j from version 1 to version 2.
- Copy Elasticsearch Configuration Files from the old engine to the new engine
[engineDir]/elasticsearch/config. If you made any changes in the old engine you need to double check the configuration in the new engine.
- Copy Elasticsearch Data Directory from the old engine to the new engine
[engineDir]/elasticsearch/data depending on if you have configured the data directory to another place in ivy.yaml. The copy operation for this directory is not needed, because if the data directory is missing the indices will be created on Axon Ivy Engine startup.
- Configure cluster name in
ivy.yaml If you have used a cluster in Axon Ivy Engine 8.0 with a proper Enterprise License, the name of the cluster was licensed. This is no longer true and can be configured in ivy.yaml. The migration wizard will read the cluster name from the old license file and write it to ivy.yaml.
- Move web configuration files
web.xml and context.xml which were placed in [engineDir]/webapps/ivy/WEB-INF/web.xml and [engineDir]/webapps/ivy/META-INF/context.xml. Both will be copied in [engineDir]/configuration. Revise the changes you made in those files.
- Preserve Web Server Context which was the prefix of all your URLs of the Axon Ivy Engine. You may remember you always had
ivy as the default prefix. Since Axon Ivy Engine 10.0 we don't have a prefix by default, but to have less migration pain it is still good to configure this prefix. The migration wizard will write this to ivy.yaml as WebServer.IvyContextName.
- Remove JTDS Driver because it is no longer maintained for SQL Server. This driver has been removed and if you have used this driver for the connection of the system database we will automatically migrate this to the official MS SQL Server JDBC Driver developed by Microsoft in
ivy.yaml.
- System Database Migration will connect to the System Database and migrate it to the new Axon Ivy Engine Schema. During this migration, almost all configurations in the System Database will be read from the database and written to
ivy.yaml or app.yaml. For more details, read below.
System Database Migration
There are a lot of changes in the database schema, notable are the following ones:
- Introducing UUIDs for users and roles
- Dropping all the views which has dramatically improved the query performance
- Scope data by the security system and not only by the application
- Removing all the configurations out of the system database
It's important to understand how the configuration has worked in Axon Ivy 8.0 and in Axon Ivy 10.0.
Axon Ivy 8.0: The projects are the carrier of the configuration (e.g. rest clients) for multiple environments. While deploying the will be written to the system database. At runtime you were able to overwrite these settings in the app-[YOUR-APP].yaml in the configuration directory. Also, the engine cockpit was writing the changes to these files. Side-Note: It was also possible to deploy an app.yaml as part of your application zip. This was placed in the application directory. The resulting runtime configuration was a merge out of different sources, by specific priority. 1. app.yaml in the configuration directory, 2. app.yaml in the application directory, 3. system database. Notable: The app.yaml had overwritten the configuration for all environments.
Axon Ivy 10.0: The projects are still the carrier of the default configuration. But we no longer deploy it at deploy time to the system database. At runtime, the default configuration will be read from the project itself. You can still overwrite the configuration in the app.yaml, but there is now also an app.yaml for each environment. And you can provide an app.yaml in your application zip. The priority is as follows: 1. app.yaml in the configuration directory (env), 2.app.yaml in the configuration directory (root), 3. app.yaml from the application directory, 4. configuration from the projects. Read more here: https://community.axonivy.com/d/403-how-the-axon-ivy-engine-becomes-highly-configurable
Keep in mind: It is not the case that only one app.yaml is in charge. It is always a merge from multiple app.yamls if they exist.
Axon Ivy 11.1: Short outlook. The environments are no longer available. Which will make the runtime much easier. Read more: https://community.axonivy.com/d/142-environments-will-disappear-in-the-long-term
Here are some more details about what happens with system database conversion:
- Security System to ivy.yaml: Connection settings of the identity provider will be written to
ivy.yaml.
- Application Properties to app.yaml: Drop
IWA_ApplicationProperty and migrate them to app.yaml.
- System Properties to ivy.yaml: Some last system properties will be read from IWA_SystemProperty and be written to
ivy.yaml.
- Business Calendar to app.yaml: Drop
IWA_BusinessCalendar and migrate it to app.yaml
- Administrators to ivy.yaml: Users of the security context
system are administrators and will be written to ivy.yaml as Administrators.
- Moving app.yaml: The app.yamls are no longer placed directly in the
configuration folder as app-MYAPP.yaml. They will be moved inconfiguration/applications/MYAPP/app.yaml`.
- Global Variables to app.yaml: Dropping
IWA_GlobalVariables and migrate them to app.yaml as Variables.
- External Databases to app.yaml: Drop tables
IWA_ExternalDatabase and IWA_ExternalDatabaseProperty and migrate them to app.yaml (environment aware).
- Rest Clients to app.yaml: Drop tables
IWA_RestServiceClient, IWA_RestServiceClientProperty and IWA_RestServiceClientFeature and migrate them to app.yaml (environment aware).
- Web Service Clients to app.yaml: Drop tables
IWA_WebService, IWA_WebServiceEndpoint, IWA_WebServiceEnvironment, IWA_WebServiceFeature, IWA_WebServicePortType and IWA_WebServiceProperty and migrate them to app.yaml (environment aware).
- Language Converter: The user languages in
IWA_User has no longer a reference to IWA_Language. Instead of that there is a standard locale as string saved.
- Creating a default security system: Creating a
default security system in the system database.
- External role name to ivy.yaml: Roles can be synchronized with the identity provider. This configuration was stored in
IWA_Role.ExternalSecurityName and will be written to ivy.yaml in the SecuritySystems.mySecuritySystem.Roles of a security system.
- Per application one security system in ivy.yaml: Users and roles are scoped now to the security system. A security system can have multiple applications. In Axon Ivy 8.0 you only can have one application per security system. This is why we create a security system for each application during migration. This will create new security systems in
ivy.yaml and also configure the configuration found in app.yaml for Language.Content, EMailNotification.OnNewTasks, EMailNotification.DailySummaryOn and StandardProcess.MailNotification in ivy.yaml for the given security system. Read more here: https://community.axonivy.com/d/289-shifting-boundaries-applications-users-and-roles
- User Synch Properties in ivy.yaml: The user synch properties in
ivy.yaml are renamed and made more expressive.
First start after migration
After successful migration, your Axon Ivy Engine will be started in Maintenance Mode. This is because the old license (8.0) is in charge. You need to upload the license for 10.0 in the engine cockpit. Then you can restart your Axon Ivy Engine.
Second start after migration
Your Axon Ivy Engine is starting in production mode. If you have running applications with Axon Ivy Projects, all Axon Ivy Projects will be automatically converted to the newest version. This conversion can also be applied manually in the Axon Ivy Designer. This is a best-effort approach and there is the chance that the projects are working. For an LTS migration, the chance is small, but for an LE migration, the chance is higher. Especially, we can not compile Java Code on an Axon Ivy Engine or properly convert the Axis Web Service Clients to CXF Web Service Clients. All projects that need to be run, must be converted in the Axon Ivy Designer first and deployed on the Axon Ivy Engine.
If you have running cases in an Axon Ivy Project and want those cases to proceed you need to overwrite the projects while deploying and not introducing a new process model version. Keep the amount of the process model versions as small as possible to lower the maintenance overhead!
Tip: Before starting the Axon Ivy Engine migration, we recommend stopping all applications in the Engine Cockpit. So that the applications don't automatically start after migration and may produce a lot of errors in the ivy.log.
Potential Pitfalls
Dropins
If you have installed custom extensions in the dropins directory. Then you need to copy this manually. There is a high chance that you need to first migrate them beforehand.
Patches
Patches won't be copied and you should not install them on the new Axon Ivy Engine.
Applications Directory
Applications won't be copied anywhere. It is best practice to configure the applications directory path to a specific path in the ivy.yaml. So the applications will be read from the same place after migration. If you work with the default settings, the applications are placed relative to the engine directory. Then you need to copy them manually.
Go ahead
If you plan to migrate to Axon Ivy 10.0, please use at least Axon Ivy 10.0.18. We made huge improvements in the Migration Wizard and all Migration Tasks. Especially noteworthy is that we write a very detailed log in ivy.log during the migration, with all actions that happen. Always make a backup of your installation and system database before you migrate. More info about migration can be found here: https://dev.axonivy.com/doc/10.0/axonivy/migration/index.html
