Iterate Mediator¶

Note

From WSO2 MI 4.4.0 onwards, you can use the ForEach mediator instead of the Iterate mediator. The ForEach mediator includes all the functionality of the Iterate mediator and eliminates the need to use the Aggregate mediator to merge flows. It provides a more streamlined and efficient way to process individual elements in a message payload. It is recommended to use the ForEach mediator for new implementations.

The Iterate Mediator implements the Splitter enterprise integration pattern and splits the message into several different messages derived from the parent message.

Info

The Iterate mediator is similar to the Clone mediator. The difference between the two mediators is, that the Iterate mediator splits a message into different parts, whereas the Clone mediator makes multiple identical copies of the message.

Info

You can use complex expressions to conditionally select elements to iterate over in the Iterate mediator.
You need to always accompany an Iterate mediator with an Aggregate mediator to aggregate responses. For out-only (fire-and-forget) invocations, Aggregate mediator is not needed, as there is no response to aggregate.
In Iterate mediator, you need to send the split messages to an endpoint to continue the message flow.

Info

When using the Iterate Mediator, the message is cloned for each iteration, including properties with the default scope. If a property contains a large amount of data, this duplication can cause performance overhead.

Syntax¶

<iterate [sequential=(true|false)] [continueParent=(true|false)] [preservePayload=(true|false)] [(attachPath="expression")? expression="expression"]>
   <target [to="uri"] [soapAction="qname"] [sequence="sequenceKey"] [endpoint="endpointKey"]>
     <sequence>
       (mediator)+
     </sequence>?
     <endpoint>
       endpoint
     </endpoint>?
   </target>+
</iterate>

Configuration¶

The parameters available to configure the Iterate mediator are as follows.

Parameter Name	Description
Iterate ID	The iterate ID can be used to identify messages created by the iterate mediator. This is particularly useful when aggregating responses of messages that are created using nested iterate mediators.
Sequential Mediation	This parameter is used to specify whether the split messages should be processed sequentially or not. The processing is carried out based on the information relating to the sequence and endpoint specified in the target configuration. The possible values are as follows. True: If this is selected, the split messages will be processed sequentially. Note that selecting True might cause delays due to high resource consumption. False: If this is selected, the split messages will not be processed sequentially. This is the default value and it results in better performance. The responses will not necessarily be aggregated in the same order that the requests were sent, even if the `sequential Mediation` parameter is set to `true` .
Continue Parent	This parameter is used to specify whether the mediation flow continues on the mediators defined after the iterate mediator. Possible values are as follows. True: If this is selected, the mediation flow continues at the point where the iteration started, once all iterations are finished. False: If this is selected, the mediation flow will not return to the parent sequence after the iterations are complete.
Preserve Payload	This parameter is used to specify whether the original message payload should be used as a template when creating split messages. Possible values are as follows. True: If this is selected, the original message payload will be used as a template. The split elements are attached to the specified attach path. False: If this is selected, the original message payload will not be used as a template. After the iteration, the payload is replaced by the split elements. This is the default value.
Iterate Expression	The expression is used to split the message. This expression selects the set of sub messages from the request payload that are applied to the mediation defined within the iterate target. Each iteration of the iterate mediator will be executed on each sub message. New messages are created for each and every matching element and processed in parallel or in sequence based on the value specified for the Sequential Mediation parameter. In the Expression Editor you can click + Add Namespace to add namespaces.
Attach Path	When preserve payload is true, to form new messages, you can specify an expression to identify the parent element to which the split elements are attached. In the Expression Editor you can click + Add Namespace to add namespaces.

Target configuration¶

Each Iterate mediator has its own target by default. It appears in the mediation tree once you configure the above parameters and save them.

The parameters available to configure the target configuration are as follows:

Parameter Name	Description
SOAP Action	The SOAP action of the message.
To Address	The target endpoint address.
Sequence	This parameter is used to specify whether split messages should be mediated via a sequence or not, and to specify the sequence if they are to be further mediated. Possible options are as follows. Anonymous: If this is selected, you can define an anonymous sequence for the split messages by adding the required mediators as children to Target in the mediator tree. Key: If this is selected, you can refer to a predefined sequence.
Endpoint	The endpoint to which the split messages should be sent. Possible options are as follows. None: If this is selected, the split messages are not sent to an endpoint. Anonymous: If this is selected, you can define an anonymous endpoint within the iterate target configuration to which the split messages should be sent. Key: If this is selected, you can refer to a predefined endpoint.

Examples¶

In these examples, the Iterate mediator splits the messages into parts and processes them asynchronously. Also see the Splitting Messages and Aggregating Responses documentation.

Using an XPath expressionUsing a JSONpath expression

    <iterate expression="//m0:getQuote/m0:request" preservePayload="true"
             attachPath="//m0:getQuote"
             xmlns:m0="http://services.samples">
        <target>
            <sequence>
                <call>
                    <endpoint>
                        <address
                            uri="http://localhost:9000/services/SimpleStockQuoteService"/>
                    </endpoint>
                </call>
            </sequence>
        </target>
    </iterate>

    <iterate id="jsonIterator" preservePayload="true" 
             attachPath="json-eval($.placeHolder)" 
             expression="json-eval($.students.studentlist)">
       <target>
          <sequence>
             <call>
                 <endpoint>
                       <http method="POST" uri-template="http://localhost:8280/iteratesample/echojson"/>
                 </endpoint>
             </call>
          </sequence>
       </target>
    </iterate>