Loop Map Operations - Usage and Examples

Article
06/12/2017

Important

Microsoft Azure BizTalk Services (MABS) is being retired, and replaced with Azure Logic Apps. If you currently use MABS, then Move from BizTalk Services to Logic Appsprovides some guidance on moving your integration solutions to Logic Apps.

If you're brand new to Logic Apps, then we suggest getting started here:

What are logic apps
Create your first logic app, or quickly get started using a pre-built template
View all the available connectors you can use in your logic apps

Loop Map Operations

There are two Loop Map Operations in Microsoft Azure BizTalk Services: ForEach Loop and MapEach Loop. Loop Map Operations provide the following benefits:

When an input message contains repeating elements, a Loop flattens the hierarchy in the output document.
To perform data manipulation, like concatenating fields or applying a mathematical formula, a Loop can use an expression and output the results.
A Loop filters an input document based on criteria and outputs the filtered data.

Loop Map Operations:

Map Operator	Description	Parameters	Output
ForEach Loop	Loops over a repeating record in the source document. Relationships defined within the ForEach Loop container are evaluated at each iteration of the loop. There is no record in the target document and there are no output links. ForEach is typically used to flatten a source loop hierarchy. It cannot output a record.	Requires one input parameter and one optional parameter: Source: Required. A repeating record in the source document or a List Map Operation. Condition: Optional. Acts as a filter for the records to iterate.	None
MapEach Loop	Loops over a repeating record in the source document. Relationships defined within the MapEach Loop container scope are evaluated at each iteration of the loop. Each iteration of the loop produces an instance of the repeating record in the target document.	Requires one input parameter and one optional parameter: Source: Required. A repeating record in the source document or a List Map Operation. Condition: Optional. Acts as a filter for the records to iterate.	A record is created in the target document.

ForEach Loop

Loops over a repeating record in the source document. Relationships defined within the ForEach Loop container are evaluated at each iteration of the loop. There is no record in the target document and there are no output links.

ForEach is typically used to flatten a source loop hierarchy. It cannot output a record.

Requires one input parameter and one optional parameter:

Source:

Required. A repeating record in the source document or a List Map Operation.

Condition:

Optional. Acts as a filter for the records to iterate.

None

MapEach Loop

Loops over a repeating record in the source document. Relationships defined within the MapEach Loop container scope are evaluated at each iteration of the loop. Each iteration of the loop produces an instance of the repeating record in the target document.

Requires one input parameter and one optional parameter:

Source:

Required. A repeating record in the source document or a List Map Operation.

Condition:

Optional. Acts as a filter for the records to iterate.

A record is created in the target document.

Set Scope with Direct Links

The ForEach Loop and MapEach Loop have a container. All Map Operations added to the container execute in the scope of that Loop container.

In addition to the Loop container, the MapEach Loop has the Set Scope icon: Pinned Scope . When a MapEach Loop is added to the Transform design area, Set Scope is automatic, as indicated by the arrow . To work in the Home container or any other container, select the arrow to unset the Set Scope icon: Unpinned Scope .

When linking a repeating record in the source document to a repeating record in the target document, a MapEach Loop is needed. Creating these links from each source node to the target node is often time consuming. As a result, BizTalk Services includes Direct Link functionality. Direct Linking includes the following features:

Automatically does a bulk direct link of a repeating record and its nodes on the source schema to the target schema.
A MapEach Loop (with Set Scope enabled) is automatically created when you link repeating records in the source schema to repeating records in the target schema.
Automatically does a bulk direct link of non-repeating records and its nodes on the source schema to the target schema.

To use the Direct Link functionality of a repeating record

Draw a link from a repeating record in the source document to the repeating record in the target document.

A dialog window displays the following options:

Option	Description
Simple Link	Creates a link between the repeating records. The node links under the repeating record are not created. A MapEach Loop is not created.
Map Each	Adds a MapEach Loop (with Set Scope enabled) and creates a link between the two repeating records. Node links under the repeating records are not created.
Link by Structure	Adds a MapEach Loop (with Set Scope enabled) and creates a bulk link between the repeating records and their node links. A MapEach Loop is created for every link between the source and target repeating records.
Link by Name	Adds a MapEach Loop (with Set Scope enabled) and creates a bulk link between the repeating records and their node links that have the same name. A MapEach Loop is created for every link between the source and target repeating records. If the names do not match, a link is created between the two repeating records in the MapEach Loop. Node links under the repeating records are not created.
Cancel	Cancels the link and returns to the Home container.

Warning

A MapEach Loop is only used when creating a link between repeating records in the source and target schemas. If the source or target record is non-repeating, a MapEach Loop is not automatically created. In this situation, create the links under the scope of an existing MapEach Loop.

To use the Direct Link functionality of a non-repeating record

Draw a link from a repeating record in the source document to a non-repeating record in the target document.

OR, draw a link from a non-repeating record in the source document to a repeating record in the target document.

A dialog window displays the following options:

Option	Description
Simple Link	Creates a link between the records. The node links under the records are not created.
Link by Structure	Creates a bulk link between the records and their node links.
Link by Name	Creates a bulk link between the records and their node links that have the same name. If the names do not match, a link is not created between the two records. Node links under a record are not created.
Cancel	Cancels the link and returns to the Home container.