Hey community,
I want to bring your attention to a configuration detail in the Axon Ivy project-build-plugin that you may have missed and that has become relevant for some customers since the release of Axon Ivy 12.0.12.
TL;DR: We recommend to set <ivyVersion> in your CI/CD pipeline to make it more reliable.
The <ivyVersion> property
The project-build-plugin uses an embedded Axon Ivy Engine under the hood to compile and test your projects in CI/CD pipelines. The engine version it downloads and uses is controlled by a property called <ivyVersion> (or the Maven property ivy.engine.version).
If you never set this property, the plugin falls back to a default: The version of the plugin itself. As of writing this, the latest released version of the project-build-plugin is 12.0.8. This means if you are using this version of the project-build-plugin and do not explicitly set <ivyVersion>, then your CI build will use an Axon Ivy Engine 12.0.8 even if you are developing your project with a newer version of the Axon Ivy Designer.
Most of the time, this is not an issue. Only, for example, if a new API is introduced within a major version release train and you use it in your project will the project no longer be able to compile with an older version of the Axon Ivy Engine.
How Axon Ivy versioning works
Axon Ivy follows a forward-compatibility guarantee within the same major version release train: A project created with, for example, designer 12.0.8 is guaranteed to work on any later 12.0.x engine. However, the reverse is not guaranteed: A project created or modified with a newer designer may not be compatible with an older engine.
This is a deliberate design decision that allows us to improve and introduce new features even on major release trains while we ensure forward-compatibility. However, older engines simply do not know about those changes.
The project-build-plugin is not released with every new Axon Ivy version. It is only released when the plugin itself changes and a new release is warranted. That is why the latest plugin version, as of writing this, is 12.0.8 while Axon Ivy itself is already at 12.0.13. The plugin is perfectly capable of downloading and using any newer engine version, but it needs to be told which one.
Why this matters now
With Axon Ivy 12.0.12, we introduced a change to how Data Class (.d.json) files are serialized on disk. The Data Class serializer was updated to omit default values when writing to disk, and add them back in-memory when reading. In practice, this means:
- Data Class files saved by designer 12.0.12 or newer might look different from files saved by older designers.
- An engine older than 12.0.12 does not know about this "omit defaults" format and will not correctly reconstruct the missing defaults when reading those files.
The result: if you are developing with designer 12.0.12 or newer and your CI build uses an older engine version, such as 12.0.8 (the latest plugin's default), your builds will fail as soon as any Data Class in your project has been saved by a newer designer.
This can affect a wide range of projects since Data Classes are fundamental to every Axon Ivy project.
How to fix
You need to explicitly tell the project-build-plugin which engine version to use. There are multiple ways to do this:
Option 1: Command-line (probably the best option for CI builds)
mvn clean install -Divy.engine.version=12.0.13
Option 2: Maven property in pom.xml (can be set for multiple projects with a multi-module project setup)
<properties>
<ivy.engine.version>12.0.13</ivy.engine.version>
</properties>
Option 3: Plugin configuration in pom.xml (needs to be done for every project)
<build>
<plugins>
<plugin>
<groupId>com.axonivy.ivy.ci</groupId>
<artifactId>project-build-plugin</artifactId>
<version>12.0.8</version>
<configuration>
<ivyVersion>12.0.13</ivyVersion>
</configuration>
</plugin>
</plugins>
</build>
In all cases, set the version to match the latest Axon Ivy release you are targeting or at minimum, the version of the designer you are developing with.
Note: This property is irrelevant during development as the engine running as the back end for the designer is also used for compilation. That's why it is enough to set it in the CI/CD pipeline.
General recommendation
Make it a habit to explicitly set <ivyVersion> in your CI/CD pipeline. Treat it the same way you would treat any other dependency version and update it when you upgrade your designer.
We are aware that this property and its documentation are a little hidden and are also working on improving that. Hence, this community post.
I hope this helps! If you are running into build failures after upgrading to Axon Ivy 12.0.12 or later, especially if you see errors related to Data Classes, this is very likely the root cause. Please don't hesitate to post your questions here.
Kind regards,
Lukas
PS: With the introduction of the ivy-project-parent POM coming with Axon Ivy 14 (and already part of LE 13.1) we hope to reduce the maintenance of such dependency versions even more.
