MuleSoft Mule events and flow types explained for integration orchestration

MuleSoft fundamentals: the Mule event and why everything is a flow

A developer who had just moved from Spring Boot onto one of our banking integration teams pulled me aside in his first week. He was staring at a flow called customer-lookup and pointing at three expressions that looked, to him, like noise: #[payload], #[attributes.headers.authorization], and #[vars.customerId]. "Why are these written three different ways?" he asked. "In Spring I just had @RequestBody and @RequestHeader. What is all of this?" That question is the real entry point to MuleSoft. Not connectors, not DataWeave, not the deployment story — those all come later and they all sit on top of one idea. Everything that moves through a Mule application is a single object called the Mule event, and everything that does work is a flow. Once those two concepts click, the rest of the platform stops feeling like a pile of unfamiliar XML and starts feeling like a pipeline you can reason about. The context for everything below was a wealth-management integration at a bank: a relationship-manager front end on Salesforce Financial Services Cloud, sitting in front of a legacy core-banking system that only spoke SOAP and database links, plus a separate wealth platform holding investment portfolios. MuleSoft was the layer in the middle that turned all of that into clean REST. The examples are real in shape, anonymized in name. The Mule event is one object, not a request and a response In a typical web framework you hold the request and the response as two separate things. You read parameters off one and write your result to the other. MuleSoft collapses that into a single object that travels the entire length of the flow, getting transformed, routed, and logged as it goes. When an HTTP listener, a scheduler, or a JMS listener fires, the runtime constructs one Mule event and pushes it through every component in sequence. That event has four parts, and the whole game is knowing how each one behaves. The payload is the body — the actual data — and it is mutable; nearly every component replaces it. The attributes are the metadata the source produced: the HTTP method, the URI parameters, the query string, the headers, or for a file listener the filename and size. Attributes are immutable for the life of the flow, set once at the source and never legitimately written again. Variables are your own flow-scoped scratch space, the place you stash values you want to keep. And error only exists when something has thrown, inside an error handler; on the happy path it is null. Internalizing the mutability column of that table is what separates someone who can debug a Mule flow from someone who can't. The senior on that team put it bluntly to the new guy: understand the Mule event and you understand seventy percent of MuleSoft. Why you set a variable for everything you'll need later The single most common rookie mistake we saw was relying on the payload to still hold a value it no longer held. Picture a flow that takes GET /customer/{id}, reads the customer from the core-banking database, maps the record into a Salesforce account shape, creates that account, and returns a confirmation. The customer ID arrives in attributes.uriParams.id. The very first database select replaces the payload with the customer record. The transform after it replaces the payload again with the Salesforce-format object — and that object uses Name and BranchCode__c, not the original lowercase id. By the time you reach the final logger and want to write "synced customer 8888," the ID is simply gone from the payload. The fix is a one-line discipline: drop a Set Variable immediately after the source, copying #[attributes.uriParams.id] into vars.customerId. From that point on, every component can read #[vars.customerId] no matter how many times the payload has been rewritten underneath it. We applied the same pattern to correlation headers — the X-Correlation-Id we needed to forward to the downstream wealth platform — and to a startTime captured with now() for latency logging. Attributes are immutable and the payload is volatile, so variables are the only stable home for anything you intend to use downstream. A close cousin of this bug is trying to write into attributes directly, something like attributes.headers.'x-flag' = "processed" inside a transform. It fails quietly. Mule does not throw a loud error; the value simply never changes, and the next component that reads that header gets null. Whenever you feel the urge to stamp something onto attributes, that is your signal to use a variable instead. A flow is a pipeline; subflows and private flows are the reusable pieces A flow is a named sequence of processors with exactly one source — an HTTP listener, a scheduler, a queue listener — that creates the event and, at the end, hands back whatever the final payload is. That is your entry point. But you rarely want one giant flow, so MuleSoft gives you two sourceless, callable units you invoke with a flow reference. A subflow has no source and no error handler of its own; it runs in the caller's context, shares the caller's variables, and inherits the caller's error handling. It is the right tool for short, reusable logic where you have nothing special to say about failure. A private flow is also sourceless and callable, but it owns its own error handler. That distinction is not academic. On the banking work, any logic that touched money or moved a record into an irreversible state went into private flows precisely so that failure was handled deliberately and propagated, rather than being silently swallowed by whatever the parent happened to do. If a transfer step fails, you want it to fail loudly and let the caller decide — not vanish into an inherited On Error Continue somewhere up the stack. The everyday refactor, then, is simple: lift repeated logic into a subflow; reach for a private flow the moment that logic needs to own how it fails. And remember that variables flow into subflows and private flows because they share the event context, but the moment you cross an asynchronous boundary — publishing to VM or JMS — a fresh event is born and your variables do not come with it. Anything that needs to survive that hop has to ride in the payload. The components are just ways to touch the event Once the event model is clear, the palette stops being intimidating. The six core components you reach for constantly all describe themselves purely in terms of what they do to the event. Logger reads it and changes nothing. Set Payload replaces the body. Set Variable adds or updates one variable. Transform Message runs DataWeave and, by default, rewrites the payload — and can optionally target attributes or variables too. Choice branches on an expression, first match wins, and you should always include an otherwise so an unexpected value doesn't slide through untouched and leave you debugging a flow that quietly did nothing. For Each loops a collection, and the trap there is that inside the loop the payload is the current item, not the whole collection; after the loop the payload resets back to the original collection while any variables you set inside survive. DataWeave is where the real transformation work lives, and a tiny script shows how naturally it reads the event: %dw 2.0 output application/json --- { customerId: vars.customerId, fullName: payload.firstName ++ " " ++ payload.lastName, branch: payload.branch_code default "UNKNOWN", syncedAt: now() } There it is in one place — vars for the value you stashed, payload for the current body, now() for a timestamp. One last gotcha that bit us repeatedly: after a transform, the payload's type may have changed, not just its contents. If you output application/json you now hold a JSON string, and a downstream database insert that expected a Java map will not be able to read payload.id. When a later component needs structured data, output application/java. The same idea, scaled up to architecture What surprised the new developer most was realizing that API-led connectivity — the System, Process, and Experience layering that organizes a serious MuleSoft estate — is the exact same model wearing a bigger hat. A System API that maps one-to-one onto the core-banking system is just a set of flows receiving events and forwarding them, deliberately holding no business logic so it can be reused by many callers. A Process API that aggregates a customer's accounts and portfolio is flows orchestrating other flows. An Experience API that trims the payload down for a mobile channel is flows tailoring events. It is events passing through flows, all the way up. That is the whole foundation. If you ever feel lost in a Mule application, come back to two questions: what is in the event right now — payload, attributes, variables — and which flow owns this step and its failures. Almost every bug I have chased on this platform dissolved the moment I answered those two honestly. Building or operating MuleSoft integrations? Our Salesforce team designs API-led architectures, builds Mule flows, and runs them in production. Get in touch -> See our full platform services for the stack we cover.

2 hours ago

Flows, subflows, and private flows: orchestration in Mule 4

A while back I was building a Customer 360 Process API for a financial-services client. The mobile app team wanted one clean endpoint — GET /customers/{cif}/360 — that would return a customer's profile, their accounts from the core-banking system, their investment holdings from a wealth platform, their mortgage from the loan-origination system, and quietly drop an audit record into the logging pipeline on every call. One request in, one assembled view out. Simple from the app's perspective, four backend systems behind the curtain. The naive way to build that is to cram everything into a single flow. I've inherited those flows from other people and they are miserable: a 600-line XML file nobody dares touch, the same customer-ID validation copy-pasted across four endpoints, and an audit-format change that means editing eight places. Worse, you can't test one branch without deploying the whole application. Mule 4 hands you three building blocks to avoid exactly this, and confusingly they all read like "flows": the public <flow>, the <sub-flow>, and the private flow (which is just a <flow> with no source). They are not interchangeable. The differences come down to two questions — does it share my context, and does it own its own error handling — and once you internalize those two axes, the right choice is usually obvious. The two axes that actually matter A public flow is what most people picture: it starts with a source (an HTTP listener, a scheduler, a JMS listener), runs its processors, and has its own <error-handler> block. It owns an independent context — its variables, payload, and attributes belong to that instance. This is your endpoint, your scheduled job, your real entry point. You can also call it from another flow via a Flow Reference, in which case the source is simply ignored. A subflow has no source and, crucially, no error handler of its own. It inherits the caller's context completely — the parent's vars, payload, and attributes are all visible and mutable. Set a variable inside a subflow and the parent sees it the moment control returns. It runs inline, like a macro expansion, with no new transaction boundary. Any error it raises bubbles straight up to the parent's handler. Reach for a subflow when you want stateless reuse: shared validation, a common transform, the kind of logic you'd otherwise copy-paste and then forget to maintain in one of the copies. A private flow looks like a subflow — no source — but behaves like a public flow on the inside. It has its own error handler and its own isolated context. Variables you mutate inside it do not leak back to the parent after it returns. That isolation is the whole point: it's a self-contained unit whose failures it can decide to swallow or propagate on its own terms. Audit logging, notifications, fire-and-forget side effects, and per-system API callers all belong here. So the mental model I use: subflow means "inline me and share everything"; private flow means "I'm my own little boundary, hand me what I need and I'll return a result"; public flow is a private flow that also happens to have a front door. Wiring them together with Flow Reference All three get glued together with <flow-ref name="..."/>, which pauses the current flow, runs the target, and resumes. The behavior difference between calling a subflow versus a private flow is where people get tripped up. When my endpoint calls the validation subflow, it's a literal inline expansion. The subflow reads vars.cif even though it never declared it, because it's the parent's context. If validation fails and the subflow does <raise-error type="APP:INVALID_CIF">, that error lands directly in the endpoint's error handler. There is no intermediate catch — the subflow has no handler of its own. When that same endpoint calls the audit private flow, the audit logic can read context that was passed in, but anything it mutates stays local. And if the logging backend is down and the audit flow's on-error-continue swallows the connectivity error, the parent never finds out and the customer still gets their 200. That is exactly what you want for a non-critical side effect — a flaky log sink must never take down the main request. The other piece worth knowing early is target and targetValue. When I want to capture a flow's output without clobbering the main payload, I write <flow-ref name="get-accounts-flow" target="accounts" targetValue="#[payload]"/>. The original payload is untouched and vars.accounts now holds the result. This becomes essential the moment you orchestrate several calls. Orchestrating the downstream calls The Customer 360 endpoint has to hit three independent system APIs keyed on the same customer ID. Done sequentially, three roughly 300ms calls cost you about 900ms. Since none of them depends on another's output, running them in parallel with <scatter-gather> brings that down to roughly the slowest single call. Each route just invokes a private flow that does one HTTP request to one backend. <scatter-gather> <route><flow-ref name="get-accounts-flow" target="accounts" targetValue="#[payload]"/></route> <route><flow-ref name="get-holdings-flow" target="holdings" targetValue="#[payload]"/></route> <route><flow-ref name="get-mortgage-flow" target="mortgages" targetValue="#[payload]"/></route> </scatter-gather> Keeping each system caller in its own private flow pays off in two ways: every backend gets a clean, independently testable unit you can mock in MUnit, and you get a natural place to attach a per-system error policy later. Sequential orchestration — where one call genuinely needs another's output, like fetching an account ID before querying its transactions — is just flow-ref processors stacked vertically instead. The trap with scatter-gather is that it fails fast by default. If the wealth platform has its once-a-day hiccup, the whole scatter-gather throws MULE:COMPOSITE_ROUTING — even though the other two routes succeeded — and your entire 360 view collapses. You have to make a deliberate decision here. Fail-fast (return a 503 if anything is missing) is sometimes the correct business choice. More often, graceful degradation is better: give the customer their accounts and mortgage with holdings shown as empty rather than an error page. You get that either by adding an on-error-continue to the per-route flow so a failing route returns [], or by catching COMPOSITE_ROUTING at the parent and parsing the partial results out of the error object to assemble a 206-style partial response. Whichever you pick, write it down in a comment — the next engineer will not guess your intent from the absence of an error handler. The gotchas that actually bite The single most common confusion is "my variable disappeared after the private flow." Someone sets vars.x inside a private flow, returns, and finds it null in the parent. That's not a bug, that's the isolation contract — the parent's vars went in as a copy. If you genuinely need the result back, use flow-ref with target; if you need shared mutable state, you wanted a subflow, not a private flow. The mirror image bites too: a subflow that quietly rewrites payload to { valid: true } leaves the parent continuing with that instead of the original message. Because subflows share context, payload mutations are visible outside. My rule is that validation subflows only ever set vars — never touch the payload unless transforming the payload is the explicit, named purpose of that flow. A couple of structural ones round it out. Recursive flow references — flow A calls B, B accidentally calls A — deploy cleanly and then blow the JVM stack at runtime, because flow-ref is a call stack, not an asynchronous message. Sketch your dependency graph before deploying, and if you truly need recursion, push it through the VM connector so it doesn't sit on the stack. And resist the urge to wrap your audit private flow in <async> purely to shave latency: an async block spawns its own thread and its errors never bubble back, so a failing audit becomes a silent gap with no log at all. If you do go async, give the block its own error handler that at least writes to a local file. The principle underneath all of this is small: pick the flow type by the contract you want, not by what compiles. Decide up front whether a piece of logic should share your context or stand alone, and whether its failures are yours to handle or someone else's to ignore — answer those two questions honestly and the orchestration almost designs itself. Building or operating MuleSoft integrations? Our Salesforce team designs API-led architectures, builds Mule flows, and runs them in production. Get in touch -> See our full platform services for the stack we cover.

2 hours ago