Skip to content
Art2link ESB HomeDocumentationBlogContact
Updated May 5, 2026
Best practices/Promote only what you route on

Promote only what you route on

Promote a field on its message type when, and only when, a subscription filters on it, a router branches on it, an adapter parameter binds it, or an operator needs it for tracking. Everything else stays in the message body. A wide promoted context is cost without benefit.

Promotions are the routing and visibility surface of a message: named expressions defined on the message type, surfaced as {{Promoted.MessageType.Name}}, the small set of values the bus and the operator reason about. It is tempting to promote “just in case,” but every promotion is another expression to evaluate, maintain and reason about. Dozens of speculative promotions make filters harder to read and bury the two or three fields that actually drive routing.

Promote with a reason. If you cannot name the subscription, router, adapter binding or tracking view that consumes a value, leave it in the body where it already lives, it is still there if a real need appears later. Adapter bindings count because adapter parameters are plain strings: they substitute {{…}} tokens but never evaluate a body path, so a payload value an adapter needs must arrive promoted or in a Variable. This keeps the context lean and the routing logic legible, for operators and for the AI assistant alike.

message body (all fields) orderIdcustomerlines[]notescurrencytermsweightorigin type region promoted surfaceonly what routes filter / router
One question per promotion: “What routes, filters, binds or reports on this?” No concrete answer means no promotion. Promotions are part of the message type’s contract: promote only what routing, adapters and operators need; everything else stays readable on demand in subscriptions through {{Message.Body}}.XPath.