Introduction

This guide describes all steps required to migrate an IOM project from version 5.1.x to 6.0.1. The attached .md files contain all necessary reference information and are best used with Claude Code to automate the process.

Migration to IOM 6.0.0

Migration instruction files.

• iom6-project-migration-strategy.md

• iom6-project-migration-agent.md

• iom6-projectandcore_migration_ref.md

Database Migration

There is no database migration required for the upgrade to IOM 6.0. Consider nevertheless upgrading PostgreSQL to the latest supported version 18.

Step 1 - Basic Migration

The file iom6-project-migration-strategy.md describes the migration steps based on the iom-project-archetype. It uses iom6-project-migration-agent.md as its reference document.

Follow the instructions in those files to complete the basic migration of your project structure.

Step 2 - Project-Specific Code Migration

Project-specific code may require additional migrations beyond the basic migration. These can be identified by reviewing the full migration of the IOM core and related internal CI project.

All relevant changes are described in iom6-projectandcore_migration_ref.md.

Step 3 - Test Dependency Versions (Optional)

The following dependency versions were intentionally left unchanged during the core migration, as updating them could affect test code:

Updating these versions is optional and at your discretion. In the internal CI project, the upgrade was possible without any code changes.

Migration to IOM 6.0.1

No code changes are required for 6.0.1, but ensure your project pom.xml contains the following two blocks.

1. Jackson Annotations Dependency

Flyway 12.x (via iom-test-framework 8.0.0) uses Jackson 3.x internally. Jackson 3.x requires jackson-annotations 2.21, but the WildFly BOM pins an older version, which causes an ObjectMapper static init failure at runtime. Add this to your <dependencies> section:

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-annotations</artifactId>
    <version>2.21</version>
</dependency>

2. Maven Clean Plugin Configuration

Add this to your <plugins> section to keep the target/ directory intact so a devenv-4-iom bind-mount survives mvn clean:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-clean-plugin</artifactId>
    <configuration>
        <excludeDefaultDirectories>true</excludeDefaultDirectories>
        <filesets>
            <fileset>
                <directory>${project.build.directory}</directory>
                <includes>
                    <include>**/*</include>
                </includes>
                <followSymlinks>false</followSymlinks>
            </fileset>
        </filesets>
    </configuration>
</plugin>

Related Project Versions

All projects related to the IOM platform have also been upgraded to work with the new release: