Breadcrumbs

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.

Why this upgrade is large. Camel 4.19 dropped support for Spring Boot 3. Moving to Camel 4.22
therefore forces Spring Boot 4, which forces Spring Framework 7, Spring Security 7, Jakarta EE 11
and Tomcat 11. Camel's own alignment then brings Groovy 5. These cannot be taken separately.

Quick Navigation

Topic

Audience

Document

Customer-facing breaking changes (§3.1 – §3.24)

Customer integrators

customer-breaking-changes.md

Groovy 4 → 5 migration

Customer integrators

groovy-4-to-5-migration.md

Jackson 2 → 3 migration

Customer integrators

jackson-2-to-3-migration.md

Apache Camel 4.18 → 4.22 migration

Customer integrators

camel-4-22-migration.md

Library upgrade details (full classpath inventory)

IM team + integrators

library-upgrade-details.md

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.

Keep the pre-upgrade script backup until you are confident. Unlike the 7.3.0 upgrade, several of
the required rewrites here are not backward compatible — a tools.jackson import is invalid on
IM 8.0.x.

Migration tooling

A migration script for the IM upgrade service is planned for this upgrade, following the pattern of
the upgrade assistant 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.