New-client launch offer: talk to sales about a focused integration pilot using MuleSoft or n8n. See what's included →
Home / Insights / MuleSoft For Each: understanding payload behaviour
MuleSoft

MuleSoft For Each: understanding payload behaviour

Understand what For Each returns and how to collect results when processing multiple items.

For Each iterates a collection and runs the same set of processors against every element, one at a time. That part behaves as everybody expects. What catches people out is what happens when the scope finishes.

The payload after the scope is the payload before it

For Each is a scope, not a transformer. It does not collect what each iteration produced. Whatever payload entered the scope is the payload that leaves it. If you called an API inside the loop and expected an array of responses on the other side, you get your original array of inputs instead.

// payload in: [ {id:1}, {id:2}, {id:3} ]
<foreach doc:name="For Each">
  <http:request path="/enrich" method="POST"/>
</foreach>

// payload out: [ {id:1}, {id:2}, {id:3} ] <- unchanged

To keep the results, accumulate them yourself into a variable. It is three extra lines and it is the difference between a flow that works and one that silently returns stale data.

<set-variable variableName="results" value="#[[]]"/>

<foreach doc:name="For Each">
  <http:request path="/enrich" method="POST"/>
  <set-variable variableName="results"
    value="#[vars.results + payload]"/>
</foreach>

// now use vars.results, not payload
Variables set inside For Each survive the scope. The payload does not. Knowing which is which saves an afternoon.

The counter, and the batch size

Two attributes earn their keep. counterVariableName gives you the current index, which you want in every log line so a failure at item 400 of 500 is findable. batchSize makes the payload inside the scope a list of N items rather than one — useful when the downstream system accepts bulk requests and you would rather make 50 calls than 5,000.

One failure stops everything

By default an error inside the scope aborts the whole loop. Items already processed stay processed; the rest never run. That is occasionally what you want and usually not.

If the loop should carry on, wrap the body in a Try scope with an On Error Continue, and record the failure into your results variable so the caller can see which items did not make it. A run that reports "487 succeeded, 13 failed, here are the ids" is worth far more than one that reports a single exception from somewhere in the middle.

When to reach for it

  • Order matters. Sequential is the point, not a limitation.
  • Each iteration depends on the last. Running totals, cursors, tokens.
  • The downstream system will not take concurrency. Plenty of legacy endpoints will not, and finding out in production is expensive.
  • The collection is small. Below roughly a hundred items the thread overhead of going parallel usually costs more than it saves.

Building something where this matters?

Discuss a focused integration pilot covering the agreed workflow, error handling, testing and handover. Talk to our team about available new-client launch benefits.

See the scope

More on this

Let’s Talk

Your request has been accepted

Thank you for contacting BraidArc. We typically respond within one business day.

Reference: