IM 8.0.x → 8.1.0 — Migration Guide

Migrating from: IM 8.0.x (Spring Boot 3.5.15 / Camel 4.18.2 / Groovy 4.0.30 / Jackson 2 / Java 21) Migrating to: IM 8.1.0 (Spring Boot 4.1.0 / Camel 4.22.0 / Groovy 5.0.8 / Jackson 3 / Java 25)

This is the landing page for the IM 8.0.x → 8.1.0 upgrade. The full analysis is split across 4 detail docs — pick the one that matches what you need from the Quick Navigation table. The actionable Customer Migration Checklist lives on this page.

• Customer integrators — start with Customer-facing breaking changes, then the two deep dives for Groovy and Jackson, then walk the checklist.

• IM framework developers — Library upgrade details is the generated evidence for every classpath change.

Quick Navigation

Impact at a glance

• Customer integrations — 24 breaking changes: 6 HIGH · 11 MEDIUM · 7 LOW. HIGH items: Groovy 5 silent behaviour changes (§3.1), sandbox Jackson package change (§3.2), dead catch (IOException) around JSON parsing (§3.3), camel-cxf operationName header rename (§3.4), WS-Security libraries removed (§3.5), camel-mail header recipients now opt-in (§3.6).

• The dangerous category is SILENT. Eleven of the 24 items produce no error at all — the route deploys, runs, and behaves differently. Deploying your integrations is not a sufficient test for those; use the search patterns in each deep dive.

• Platform totals: 424 runtime dependencies changed version, 50 added, 49 removed, 68 major-version jumps. Generated inventory in library-upgrade-details.md.

• Much of the platform change is absorbed by IM — Spring Boot 4's module split, Spring Security 7's removed APIs, Jakarta EE 11, Tomcat 11 and the Jackson 3 migration of IM's own code and the Pricefx API client. See What IM handles for you at the end of the breaking-changes doc.

Customer Migration Checklist

Use this as a sequenced punch list when upgrading an instance from IM 8.0.x to 8.1.0.

Before the upgrade

• Raise a ticket first if you use WS-Security on any SOAP service (UsernameToken, signing, encryption, SAML) — the libraries are no longer on the classpath (§3.5). This needs an image change, not a configuration change.

• Search customer Groovy scripts for:

• com.fasterxml.jackson.databind / .core imports (§3.2) — switch to tools.jackson.*. Leave com.fasterxml.jackson.annotation alone — that package is unchanged.

• catch (IOException / catch (JsonProcessingException around JSON parsing (§3.3) — now dead code; catch tools.jackson.core.JacksonException.

• if (file) style truthiness checks on File/Path (§3.1) — now means "exists on disk".

• Classes that extends HashMap / implements Map and also declare fields (§3.1) — property access now prefers the field over the map entry.

• findIndexValues (returns Iterator now) and chop (no longer pads) (§3.1).

• Custom mod() methods used via % (§3.1).

• @CompileStatic scripts — overload selection and generics checking both changed (§3.1, §3.9).

• new ObjectMapper() followed by configure / registerModule / setDateFormat (§3.10) — rebuild with JsonMapper.builder(); drop JavaTimeModule.

• TextNode (§3.10) — renamed to StringNode.

• javax.annotation.* imports (§3.24) — move to jakarta.annotation.*.

• Duplicate import lines (§3.7) — now a compile error.

• Classes named Duration, Period, Instant, Clock in the default package (§3.8).

• Search customer routes for:

• header.operationName / literal "operationName" on CXF routes (§3.4) — rename to CamelCxfOperationName, and re-set it after any JMS/HTTP hop.

• <setHeader name="To"> (and From/Subject/Reply-To) feeding an smtp: endpoint (§3.6) — add useHeaderRecipients=true etc. to the endpoint URI.

• copyTo / moveTo / delete mail headers (§3.19) — now CamelMail* prefixed.

• <toD> / <enrich> whose URI can contain {{...}} at runtime (§3.15) — no longer resolved.

• xslt-saxon endpoints using Java extension functions or external DTDs (§3.16) — set secureProcessing=false.

• CamelFileName used after zip/tar unmarshal to rebuild directories (§3.17) — use zipFileName / CamelTarFileEntryName.

• pojoRequest=true on aws2-s3 listObjects (§3.20) — switch to the V2 request/response types.

• Removed components: serviceCall, stomp:, github:, camel-cloud (§3.18) — DEPLOY-FAIL.

• csimple expressions (§3.18) — deprecated, migrate to simple.

• Review JSON expectations — if a downstream system or your tests depend on JSON property order, note that the jackson dataformat now sorts alphabetically (§3.11). Pricefx API traffic is unaffected — IM preserves the old order there.

• Review deeply nested JSON — the default nesting limit dropped from 1000 to 500 (§3.14).

• Review Spring property overrides in your instance configuration against the Spring Boot 4 release notes — removed/renamed properties are the main way the internal upgrade can reach you.

• Take a backup: connection definitions, property files, custom routes and kamelets, Groovy scripts and deployed classes, and database state.

During the upgrade

• Deploy IM 8.1.0 to a non-production environment first.

• Apply the rewrites identified in the pre-upgrade scan.

• Deploy every customer route, mapper, filter and Groovy class — DEPLOY-FAIL items (duplicate imports, removed components, sandbox rejections, generics errors) all surface here.

After the upgrade — verification steps

• Application starts cleanly — no unresolved placeholders, no unknown-property warnings.

• Health endpoint returns UP.

• Exercise every connection end-to-end — at least one route per credential.

• Run a representative sample of Groovy scripts with real data and compare output, not just deploy them. The SILENT items (§3.1, §3.11, §3.12, §3.15) can only be caught this way. Pay particular attention to scripts using closures that capture external variables — the sandbox and the Groovy 5 compiler interact most tightly there.

• Send one mail through each mail route and confirm it reached the intended recipient (§3.6).

• Invoke each SOAP operation and confirm dispatch still routes correctly (§3.4).

• Compare a sample of produced JSON against IM 8.0.x output if a downstream system is order-sensitive (§3.11).

• Check monitoring dashboards — the routeId metric tag is now always present and JMX Throughput is smoothed (§3.22).

• Performance smoke test on the Java 25 runtime.

Rollback plan

If a critical issue surfaces post-upgrade and cannot be hotfixed:

1. Stop traffic to the IM 8.1.0 instance.

2. Redeploy the previous IM 8.0.x image / artifact.

3. Restore rewritten route/property/script files from the pre-upgrade backup — note that scripts rewritten for Jackson 3 (tools.jackson imports) and for the sandbox whitelist will not run on IM 8.0.x, so the originals are required.

4. Re-enable traffic and verify health.

5. File a defect with reproducer details before retrying.

Migration tooling

A migration script for the IM upgrade service is planned for this upgrade, following the pattern of the PFIMCORE-2957 script used for 7.3.0. It will run in two modes:

• Analysis (read-only) — scans customer routes, Groovy scripts and properties, and reports the detected items from the checklist above without modifying anything.

• Modification — applies the safe, regex- and XML-matchable rewrites: com.fasterxml.jackson → tools.jackson imports, TextNode → StringNode, header.operationName → header.CamelCxfOperationName, copyTo/moveTo/delete mail header renames, and javax.annotation → jakarta.annotation.

The SILENT items — File truthiness, Map property resolution, JSON property order, catch (IOException) dead blocks — cannot be safely automated because the correct rewrite depends on what the script intended. Those remain manual review items, and the analysis mode will flag them.