---
schema_version: "1"
id: 3ba34b871ca5503e89a9d4bb92cc9b322356dc5415873b458a6b5f17385957d7
title: For Each Scope
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/mule-runtime/4.9/for-each-scope-concept.md
canonical_url: https://docs.mulesoft.com/mule-runtime/4.9/for-each-scope-concept
source_site: docs.mulesoft.com
content_type: documentation
content_hash: eb612834fd4b135fb7f25237236f19f93dcad6062aca456a12daec9758e75dda
description: MuleSoft Documentation Site
release: "4.9"
latest: false
---
---
product: Mule Runtime
version: 4.9
---

# For Each Scope

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

The For Each scope splits a payload into elements and processes them one by one through the
components that you place in the scope. It is similar to a `for-each`/`for` loop code block in most
programming languages and can process any collection, including lists and arrays. The collection can
be any supported content type, such as `application/json`, `application/java`, or `application/xml`.

General considerations about the For Each scope:

- By default, For Each tries to split the payload. If the payload is a simple Java collection, the
  For Each scope can split it without any configuration. The payload inside the For Each scope is
  each of the split elements. Attributes within the original message are ignored because they are
  related to the entire message.

- For Each does not modify the current payload. The output payload is the same as the input.

- For non-Java collections, such as XML or JSON, use a DataWeave expression to split data. Use the
  **Collection** field for this purpose.

  In the following example, the **Collection** field in For Each is set to iterate over an array
  stored in `payload.topics`:

  ![A For Each component showing a flow with settings](/mulesoft/current/en-us/mule-runtime/4.9/_images/component-foreach-example.png)

The For Each scope stores each item of the collection in `payload` during each iteration.

You can also split an array into batches to enable quicker processing. Each batch is treated as a
separate Mule message. For example, if a collection has 200 elements and you set **Batch Size** to
`50`, the For Each scope iteratively processes 4 batches of 50 elements, each as a separate Mule
message.

## Example XML

This is an example XML based on the For Each scope configuration detailed above:

```xml
...
  <foreach doc:name="For Each" collection="#[payload.topics]" batchSize="1" rootMessageVariableName="rootMessage" counterVariableName="counter">
      <file:write ... >
      <!--Any other module that you want to include in the For Each scope -->
  </foreach>
...
```

## Variable Propagation

Every execution of the For Each scope starts with the variables and values from the previous
execution of the block. New variables or modifications to existing variables that take place when
processing one element are visible during the processing of another element. These changes to
variables continue to be available outside the For Each scope.

```xml
<set-variable variableName="var1" value="var1"/>
<set-variable variableName="var2" value="var2"/>
<foreach collection="#[['apple', 'banana', 'orange']]">
    <choice>
        <when expression="#[payload == 'apple']">
            <set-variable variableName="var2" value="newValue"/>
            <set-variable variableName="var3" value="appleVal"/>
        </when>
        <when expression="#[payload == 'banana']">
            <set-variable variableName="var3" value="#[vars.var3 ++ ' bananaVal']"/>
            <!-- var3 will now have value 'appleVal bananaVal'-->
        </when>
        <otherwise>
            <set-variable variableName="var3" value="otherVal"/>
            <set-variable variableName="var4" value="val4"/>
        </otherwise>
    </choice>
</foreach>
```

After aggregation, the variables are:

```json
{ "var1": "var1", "var2": "newValue", "var3": "otherVal", "var4": "val4" }
```

## Error Handling

If one of the elements in a collection throws an exception, the For Each scope stops processing that
collection and invokes the error handler.

## Example Projects

There are several example projects in Anypoint Exchange that you can open in Anypoint Studio to
learn more about how to use the For Each scope:

- _Authenticating Salesforce using OAuth2_

- _Import contacts into Microsoft Dynamics CRM_

- _Importing a CSV file into mongoDB_

- _Importing an Email Attachment using the IMAP Connector_

- _Importing Email Attachments using the POP3 Connector_

- _Querying a Database and Attaching Results to an Email_

To download and open an example project while you are in Anypoint Studio, click the Exchange icon in
the upper-left corner. Then, in the window that opens, log into Anypoint Exchange and search on the
name of the project.

## XML Reference

For Each scopes open and close with a `<foreach>` tag. Components that are affected by this scope
are defined as child elements of the `<foreach>` tag.

### Configurable Variables

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Variable</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td><p><code>collection</code></p></td><td><p><code>payload</code></p></td><td><p>An expression that returns a Java collection, object array, map, or DOM nodes.</p></td></tr><tr><td><p><code>counterVariableName</code></p></td><td><p><code>counter</code></p></td><td><p>Name of the variable that stores the number of messages over which it iterates.</p></td></tr><tr><td><p><code>batchSize</code></p></td><td><p><code>1</code></p></td><td><p>Partitions the collection into sub-collections of the specified size. For example, if a collection has 200 elements and you set the batch size to 50, it processes 4 batches of 50 elements each.</p></td></tr><tr><td><p><code>rootMessageVariableName</code></p></td><td><p><code>rootMessage</code></p></td><td><p>Name of the variable that stores the parent message. The parent is the complete, non-split message.</p></td></tr></tbody></table>

## Differences between For Each and Parallel For Each Scopes

Both For Each and Parallel For Each split the defined collection, and the components within the
scope process each element in the collection. Also, in both cases, each route runs with the same
initial context. The difference between these two scopes are:

- For Each works sequentially, while the Parallel For Each processes in parallel. This difference
  affects _error handling_:

  Because of the processing differences, the execution of For Each execution is interrupted when an
  error is raised (and the Error Handler is invoked), while Parallel For Each processes every route
  before invoking the Error Handler with a `MULE:COMPOSITE_ROUTE` error type.

- For Each does not modify the payload, while the Parallel For Each outputs a collection of the
  output messages from each iteration.

See [Parallel For Each Scope](https://docs.mulesoft.com/mule-runtime/4.9/parallel-foreach-scope).

## See Also

- [Mule Events](https://docs.mulesoft.com/mule-runtime/4.9/about-mule-event)

- [Mule Message Structure](https://docs.mulesoft.com/mule-runtime/4.9/about-mule-message)