A variable does not travel with the message. It lives at the application level, and every port and pipeline running inside that application sees the same variable. A receive port writing to CurrentBatchId and a send port reading {{Variable.CurrentBatchId}} a moment later are reading and writing the same slot.

This is the reverse of how promoted properties work. A promotion is a value lifted out of a specific message's payload; it is meaningful only while that message is being processed. A variable is a slot the application owns, and the runtime is what changes its value as messages move through ports.

Variables are scoped to an Application. From the application menu, the Variables list shows every variable defined in that application. Each entry has these fields:

The list view follows the platform's Selected Application behavior - with an Application selected, the list filters to it and the Application column is hidden; with no selection, the list spans every Application you have access to and the column is shown. Creating a new variable uses the same flow: with an Application selected, the form opens with that Application preemptively chosen; without one, the form exposes an Application picker.

A variable does not declare a data type at design time. The runtime type is whatever the most recent assignment produced - the same slot can hold a string in one stage, a node-set in another, and a whole XML document in a third.

This mirrors the way promotions resolve: an XPath that returns a single text node yields a scalar, one that returns a node-set yields a list, one that returns an inner element yields a sub-tree, and an XPath of / yields the whole message. A variable assignment using an XPath inherits the same shape spectrum.

Downstream consumers see the value as it currently is. A map that reads {{Variable.CapturedHeader}} will receive a sub-tree if that is what was last written; passing the same token to a string-only context (a header name, a literal in a subscription expression) coerces to text.

Anywhere a string can be typed in the platform - subscription expressions, map bindings, custom pipeline component property values, custom function arguments, port adapter settings - you can reference a variable with a double-curly-brace token. The exception is naming an object itself: the Name field on a variable, port, message type, schema, etc. is a literal, never an expression.

The token grammar is identical to {{Promoted.Name}} and {{Message.MessageType}} - the same expression engine evaluates all three. A subscription expression that filters a send port to only pick up messages while a feature flag is on, for example, looks like this:

{{Message.MessageType}} == "Invoice" && {{Variable.InvoiceForwardingEnabled}} == "true"

A custom pipeline component can also write to a variable directly - setting {{Variable.Name}} from C# code - which is the canonical way to surface a derived value out of a pipeline for the rest of the flow to consume. See Custom pipeline components.

Declaring a variable allocates the slot. Giving it a value is the job of port variable assignments - an optional stage that runs immediately after the port has been entered and immediately before it is left. Every port type exposes the same two assignment points:

On a receive port the On Entry stage is stage 2 and On Exit is stage 5 in the five-stage flow (Adapter is stage 1). On a send port the order is mirrored - On Entry is stage 1, On Exit is stage 4, and Adapter is the final stage 5. A two-way port runs both stages on the request and again on the response, mirrored. The numbered stage diagrams in the Receive, Send, Loopback, and Null port articles show exactly where the variable stage sits for each port type and direction.

Variables can also be written outside the port assignment stages: a custom pipeline component setting {{Variable.Name}} from code, or an XSLT map writing back through the platform's helper functions, will mutate the same slot. The port assignment stages are simply the configuration-only path that does not require code.

Three patterns account for most of how variables are used in practice. The platform does not enforce any of these - a variable is just a slot - but the patterns are worth recognizing because they show up across most non-trivial integrations.

Pattern 1 - Loop counter. A custom pipeline component that splits a multi-record file into individual messages can use a variable as the running index, incrementing it on each iteration so downstream stages know which record they are looking at.

{{Variable.RecordIndex}}

The component reads the current value, uses it, increments it, writes it back. Because variables are application-scoped, the index is visible to every stage that runs while the loop is in flight - no need to thread the value through component arguments.

Pattern 2 - XPath capture. A common need is to lift a value out of the inbound message and reference it later in the flow, without making it part of the message type as a promotion. An On Entry variable assignment using an XPath does exactly that:

Variable.CorrelationId  ←  /Order/Header/CorrelationId/text()

From that point on, every stage in the application can reach {{Variable.CorrelationId}} - a send port can use it in a subscription expression, a map can drop it into the response, a custom pipeline component can log it. The value is a scalar string, because that is what the XPath returned.

Pattern 3 - Holding a fragment or a whole message. The same XPath assignment works for sub-trees and whole messages. To capture an entire envelope inbound for later wrapping:

Variable.OriginalRequest  ←  /

The variable now holds the whole message as a sub-tree. A two-way send port further along can drop {{Variable.OriginalRequest}} into an outbound envelope produced by a map, embedding the original payload verbatim. The same technique with a more selective XPath - /Order/ShipTo, say - captures just that branch.

Variables are evaluated lazily. The runtime does not pre-resolve every variable reference at the start of a flow; it resolves each {{Variable.Name}} token at the moment the stage that contains it executes.

Because the slot is application-scoped, two messages flowing through the same application at the same time share it. Treat a variable as state owned by the integration, not state owned by the message - if per-message state is what you need, a promotion is the right tool.

Variables and promotions are two halves of the platform's expression model. Both are referenced with double-curly-brace tokens, both can resolve to scalar / list / sub-tree / whole-message shapes, and both are evaluated by the same expression engine.

The difference is whose state they describe. A promotion is a value derived from this message at the moment it enters the bus - bound to a message type, scoped to the lifetime of the message. A variable is a slot the application owns - bound to the application, written by ports and pipelines, visible to anything else running inside the application until something overwrites it.

When a routing or mapping expression needs both - a per-message value and an integration-state value - it can mix them freely. {{Message.MessageType}} == "Invoice" && {{Promoted.Currency}} == "USD" && {{Variable.RegionRoutingEnabled}} == "true" is a valid subscription expression that combines all three reference forms.