Breadcrumbs

IM 7.2.0 → 7.3.0 — Migration Guide

IM 7.2.0 → 7.3.0 — Migration Guide

Migrating from: IM 7.2.0 (Spring Boot 3.1.5 / Camel 4.1.0 / Java 17)
Migrating to: IM 7.3.0 (Spring Boot 3.5.12 / Camel 4.18.1 LTS / Java 21)

This is the landing page for the IM 7.2.0 → 7.3.0 upgrade. The full analysis is split across 5 detail docs — pick the one that matches your role from the Quick Navigation table below. The actionable Customer Migration Checklist lives on this page.

  • Customer integrators — start with the Customer-facing breaking changes doc, then walk through the checklist below.

  • IM framework developers — start with the Internal / framework details docs to validate the upgrade.

Quick Navigation

Topic

Audience

Confluence

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

Customer integrators

Open ↗

Apache Camel 4.18 migration (§6)

Customer integrators

Open ↗

Library upgrade details (§1, §2, §4, §5, §7 – §12)

Customer integrators + IM team

Open ↗

Internal / framework details — part 1 (§13 – §19D: Spring Boot, libraries)

IM team

Open ↗

Internal / framework details — part 2 (§20+: Vavr, JSqlParser, AWS SDK, …)

IM team

Open ↗

Impact at a glance

  • Customer integrations — 27 breaking changes: 7 HIGH · 14 MEDIUM · 6 LOW. Full list in customer-breaking-changes.md. HIGH items: bootstrap.yml deletion (§3.5), camel.springboot.* properties (§3.12), pfx-api: businessKeysMaxLengths removed (§3.23), Apache HttpClient 4→5 (§3.24), removed Camel components (§3.26), template/script allowTemplateFromHeader silent breaker (§3.27), Apache POI 4→5 (§3.28).

  • Some §3 items affect IM framework internals too (e.g., §3.3 HTTPS enforcement, §3.4 BouncyCastle, §3.17 K8s client transport, §3.18 Jolokia) — listed in §3 because customers may notice the behaviour, but the underlying change is in IM-managed code.

Customer Migration Checklist

Use this as a sequenced punch list when upgrading a customer instance from IM 7.2.0 to 7.3.0. For full context on any item, see customer-breaking-changes.md.

Before the upgrade

  • Search customer routes for the following patterns and queue them for rewrite:
    • bootstrap.yml files (Section 3.5) — delete; move properties to application.properties.
    • camel.springboot.* properties (Section 3.12) — rename to camel.main.*.
    • Camel Simple operators starts with, ends with, not contains, not regex, not range (Section 3.10) — rewrite to startsWith, endsWith, !contains, !regex, !range.
    • Vault secret references {{aws:foo/bar}} / {{hashicorp:secret:foo/bar}} (Section 3.16) — change / to #.
    • Camel <intercept> blocks using <when> (Section 3.13) — rename to <onWhen>.
    • Camel <loadBalance> with old element names (Section 3.14) — rename (e.g. <failOver> → <failoverLoadBalancer>).
    • Removed Camel components in URIs: facebook:, hdfs:, etcd3: (Section 3.26) — DEPLOY-FAIL impact; remove or migrate to supported components.
    • Template/script components without allowTemplateFromHeader=true (Section 3.27) — SILENT BREAKER; routes using velocity:, freemarker:, xslt:, groovy: etc. with header-driven content must opt in or output is wrong.
    • Camel REST DSL routes (Section 3.31) — review useXForwardHeaders (if behind proxy), Swagger 2.0 consumers must switch to OpenAPI v3.
    • Health endpoint paths /q/* → /observe/* (Section 3.29) — update monitoring tools / dashboards.
    • File endpoints using maxMessagesPerPoll with sortBy — set eagerMaxMessagesPerPoll=false to keep sort-then-limit semantics.
    • PFX-API &businessKeysMaxLengths=… URI parameter on pfx-api: URIs — strip the URI param; remove ${headers.businessKeysMaxLengthsClause} references and the now-dead <setHeader name="businessKeysMaxLengthsClause"> block.
    • Custom *.kamelet.yaml files using kebab-case (set-header, set-body, wire-tap, do-try …) — convert to camelCase. The PFIMCORE-2957 migration script does not rewrite YAML/kamelet files; convert manually.
  • Search customer Groovy scripts for:
    • Apache HttpClient imports org.apache.http.* (Section 3.24) — HIGH-impact: migrate to HttpClient 5 packages (org.apache.hc.client5.http.* / org.apache.hc.core5.http.*) per the §10 mapping. Method signatures also changed beyond imports — manual rewrite, the migration script reports an advisory only.
    • SnakeYAML new Yaml().load(...) (Section 3.25) — switch to typed loading yaml.loadAs(Class, input); remove !!java.lang.… tags from customer YAML files. SnakeYAML 2 defaults to SafeConstructor and rejects polymorphic instantiation.
    • Apache POI usage (Section 3.28) — Cell.CELL_TYPE_* constants removed (use CellType enum), Cell.setCellType() removed, alignment/fill constants replaced. Manual rewrite.
    • AWS SDK usage (Section 3.32) — multipart ContentStreamProvider::newStream() called twice (SDK 2.30+); presigned URL signature changed for endpointOverride+HTTP.
    • Camel Exchange API references (Section 3.30) — Exchange.ACTIVE_SPAN → Exchange.OTEL_ACTIVE_SPAN, Exchange.BEAN_METHOD_NAME no longer set, getCreated() deprecated, intercepted endpoint moved from header to property, HeaderFilterStrategy case-insensitive.
    • Custom ObjectMapper instances (Section 3.2) — add the coercion snippet.
    • Thread.stop(), Runtime.exec(String) (Section 3.20) — replace per Java 21.
    • org.apache.commons.codec.binary.Base64 (Section 3.19) — switch to java.util.Base64.
    • org.apache.commons.collections (v3) usages (Section 3.19) — migrate to commons.collections4 (v3 still works transitively today, but should be migrated proactively).
    • javax.ws.rs.* / javax.validation.* / javax.annotation.* imports (Section 3.19) — switch to jakarta.*.
  • Audit boolean properties — confirm every *.enabled value is exactly true or false (no yes, on, 1, 0, off).
  • Confirm HTTPS termination at the reverse proxy / load balancer / Ingress — IM no longer redirects HTTP→HTTPS.
  • Set explicit credentials (integration.user, integration.password) in production deployments — do not rely on the new admin/random-UUID fallback.
  • Review JSON payload sizes — if any single string field can exceed 20 MB, set integration.jackson.max-string-length=-1.
  • Take a backup: connection definitions, property files, custom routes/kamelets, Groovy scripts, and database state.

During the upgrade

  • Deploy IM 7.3.0 image / artifact to a non-production environment first.
  • Apply the rewrites identified in the pre-upgrade scan.
  • If using Kubernetes: review terminationGracePeriodSeconds against the new graceful shutdown default.

After the upgrade — verification steps

  • Application starts cleanly — no Could not resolve placeholder errors, no Unknown property warnings tied to renamed properties.
  • Health endpoint (/health) returns UP. Watch for FTP producer health regressions — if the route reports DOWN, set camel.health.producersEnabled=false.
  • Each connection is exercised end-to-end (one route per credential is sufficient) — encrypted passwords are expected to decrypt unchanged, so any EncryptionOperationNotPossibleException here would be a regression to escalate, not a planned migration step.
  • A sample of every kamelet / customer route is deployed and triggered — kebab-case, Simple operators, vault secrets, intercept, load balancer renames will fail at deploy time, not at runtime, so a deploy is the test.
  • Outgoing HTTP calls to external systems behave as expected with the new redirect-following default. If silent redirects are unwanted, set spring.http.client.redirects=dont-follow.
  • JMX / Jolokia consumers still parse responses correctly — Jolokia 2.x format may differ.
  • Kubernetes monitoring: pod termination time and rolling deployments behave acceptably under the new graceful shutdown default.
  • Performance smoke test: confirm throughput and memory are within expectations on the new Java 21 runtime.

Rollback plan

Connection passwords do not need to be backed up separately — the BouncyCastle 1.83 fix keeps IM 7.3.0 password decryption compatible with IM 7.2.0.

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

  1. Stop traffic to the IM 7.3.0 instance.

  2. Redeploy the previous IM 7.2.0 image / artifact.

  3. Restore any rewritten property/route files from the pre-upgrade backup (e.g. customer rewrites for camel.springboot.*, kebab-case kamelets, vault secret references).

  4. Re-enable traffic and verify health.

  5. File a defect with reproducer details before retrying the upgrade.

Migration tooling

The PFIMCORE-2957 migration script in im-upgrade-service automates many of the rewrites listed above. It runs in two modes:

  • Analysis (read-only): scans customer routes, properties, and pom.xml; reports detected breaking changes without modifying anything.

  • Modification: applies safe rewrites for regex-matchable patterns and structural XML transforms (load balancer renames, intercept <when> → <onWhen>, <bean> properties wrap, <onFallback> reorder, &businessKeysMaxLengths= strip, etc.). See the script's MR description for the complete list.

Run the script via the IM upgrade service against any customer instance on 7.2.x to bootstrap the migration.