List 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

List Map Operations

The following table lists the List Map Operations available in Microsoft Azure BizTalk Services:

Create List

Creates and initializes a List that can:

Hold intermediate data
Use List operations (like GroupBy)
Be used for complex structure transformations
Contain other container Map Operations, including ForEach Loop and MapEach Loop.

A List is like a table. A List has a set of Members (like columns in table) and a set of Items (like rows in a table). A List can be grouped.

Member Name: Add the members of the List.

Member Type: Click the type of the Member Name: String, Number, or Boolean.

Use the Add Item to List Map Operation to add an item to the List.

Every Map Operation within the Create List container should contribute on the path towards Add Item to List. Map Operations that create target tree nodes (like MapEach and Conditional Assignment) are not allowed within the Create List scope container.

Add Item to List

Adds an item to the list. Use only in the container of the Create List Map Operation.

Can have at least 0 input parameters:

Input	A Member in a Create List or a link.
Condition	An expression to conditionally add items to the List. Can also be a link from a Logical Expression Map Operation.

Results in an Item added to the Add Item To List Map Operation.

Select Unique Groups

Generates groups from a list. Each group is identified by a unique value of the selected members.

Requires exactly one input parameter:

Input	Required. A link to a Create List Map Operation.
Member	Required. Specify the Member to include in the output. If one Member is specified, the List is one Group for each unique Member value. If multiple Members are specified, the List-of-Groups will contain a Group for each unique combination of the Members value.

A List containing a single Group or List-Of-Groups based on the Member value.

Select Value

Selects the first item In a List. If a condition is specified, the first item in the list matching the condition is selected.

Requires at least one parameter:

Input	Required. A link to a Create List Map Operation.
Select List Member: Select the member in the list to return.	Optional. An expression to conditionally select items from the List.
Optional. An expression to conditionally select items from the List.

Accesses the value of the selected List Member and returns its value.

Select Entries

Filters a List.

Requires at least one parameter:

Input	Required. A link to a Create List Map Operation. A constant or link can also be added.
Member	Optional. Specify the member to include in the output. If no members are specified, the output is not filtered by member.
Condition	Optional. An expression to conditionally filter items from the List.

Returns the filtered output.

Get Items

Used in a ForEach or MapEach Loop. Gets the item in the list of the current iteration. When iterating over Unique Groups generated from a list, it returns the current group's items.

No input parameters.

Returns the current iteration.

Order By

Orders items in a List. Key notes:

Order By creates a new List. It does not modify the input List. The input List can still be used in other operations; these items are in a different order than the List returned by the Order By map operation.
Multiple members can be specified. In this scenario, Items in the List are sorted by the first specified Member. A tie between Items is resolved by comparing the second Member, and so on.

Note

Descending order is not supported.

Requires exactly one input parameter:

Input

A link

After the link is created, choose the Member to sort.

Returns a sorted list by the Member specified.

In the following examples, the All_Employees List contains four members: Emp_Id, Name, Designation, and Age. The All_Employees List has six Items:

Emp_ID	Name	Designation	Age
1	A	Developer	25
2	B	Tester	22
3	C	Developer	26
4	D	Program Manager	32
5	E	Tester	25
6	F	Manager	36

Select Unique Groups Example

Using the Age Member:

Member: Age

Group 1 (Age = 25)

Emp_ID	Name	Designation	Age
1	A	Developer	25
5	E	Tester	25

Group 2 (Age = 22)

Emp_ID	Name	Designation	Age
2	B	Tester	22

Group 3 (Age = 26)

Emp_ID	Name	Designation	Age
3	C	Developer	26

Group 4 (Age = 32)

Emp_ID	Name	Designation	Age
4	D	Program Manager	32

Group 5 (Age = 36)

Emp_ID	Name	Designation	Age
6	F	Manager	36

Select Value Example

Using the Name Member and specifying a Condition:

Member: Name

Condition: item.Age>25

Name

Using the Designation Member:

Member: Designation

Developer

Select Entries Example

Using the Emp_ID, Name and Age Members and specifying a Condition:

Member: Emp_ID

Member: Name

Member: Age

Condition: item.Age>25

Emp_ID	Name	Age
3	C	26
4	D	32
6	F	36

Get Items Example

Consider this scenario.

You connect the All_Employees List to a MapEach Loop. This results in six iterations of the MapEach’s body. To access each individual Item in the All_Employees List, use a Get Items Map Operation. In this scenario, Get Items returns a List containing a single Item. This single Item is the current iteration variable. You can then use a Select Value Map Operation (without a Condition) to select a specific Member of this Item.

Order By Example

Using the Age Member:

Member: Age

Emp_ID	Name	Designation	Age
2	E	Tester	22
1	A	Developer	25
5	B	Tester	25
3	C	Developer	26
4	D	Program Manager	32
6	F	Manager	36

Using the Designation and Age Members:

Member: Designation

Member: Age

Emp_ID	Name	Designation	Age
1	A	Developer	25
3	C	Developer	26
6	F	Manager	36
4	D	Program Manager	32
2	E	Tester	22
5	B	Tester	25

Scope Container

When Create List is added to the Transform design area, a scope container is created. All Map Operations added to the container execute in the scope of that Loop container.

For details on working within the scope container, see Using Scope in a Loop - How To.

Error and Data Handling

BizTalk Services provides the ability to configure how an error is handled and how an empty or null node is handled. The error handling behavior of the following List Map Operations is configurable:

Add Item to List
Select Value
Select Entries

Steps:

Open a BizTalk Service project or the BizTalk Service Artifacts project in Visual Studio.
Double-click a Transform (.trfm) to open the Transform Designer.
In the Transform toolbar, select Settings.

Error Handling tab

In the Error Handling tab, the following List Map Operations have two Behavior options:

Add Item to List:
- Fail map: The entire Transform is aborted. Since Transforms are executed within a pipeline, an error occurs within the pipeline and the error is then sent back to the client that sent the message.
- Do not add item into the list: If the Map Operation fails, the item is not added to the list in the output.
Select Value:
- Fail map: The entire Transform is aborted. Since Transforms are executed within a pipeline, an error occurs within the pipeline and the error is then sent to the client that sent the message.
- Output Null/Zero/False based on type of output: If the Map Operation fails, Null/Zero/False is returned as the output based on type of output.
Select Entries:
- Fail map: The entire Transform is aborted. Since Transforms are executed within a pipeline, an error occurs within the pipeline and the error is then sent back to the client that sent the message.
- Output an empty list: If the Map Operation fails, an empty list is returned as the output.

Null/Empty Data Handling tab

In the Null/Empty Data Handling tab, there are three options:

Consider empty nodes in cumulative operations: By default, this is not checked. When not checked, no empty nodes are included in the iteration. When checked, all nodes, including empty nodes, are included in the iteration.

EXAMPLE: There is a document with 10 <record> nodes. Three of these <record> nodes are empty. When Consider empty nodes in iterations is not checked, the Map Operation returns a value of seven. When Consider empty nodes in iterations is checked, the Map Operation returns a value of 10.
Consider empty nodes in iterations: By default, this is not checked. When not checked, no empty nodes are included in the iteration. When checked, all nodes, including empty nodes, are included in the iteration.

EXAMPLE: there is a document with 10 <record> nodes. Three of these <record> nodes are empty. When Consider empty nodes in iterations is not checked, the Map Operation iterates seven times for the non-empty nodes. As a result, seven <record> nodes are generated in the Target. When Consider empty nodes in iterations is checked, the Map Operation iterates 10 times for all nodes, including the empty nodes. As a result, 10 <record> nodes are generated in the Target.
Target Node Generation: If empty nodes are configured to be considered, you choose to generate an empty node in the output or to not generate an empty node in the output. Specifically:
- Do not generate empty nodes: Default option.
- Generate empty nodes
EXAMPLE: There is a document with 10 <record> nodes. Three of these <record> nodes are empty. Consider empty nodes in cumulative operations or Consider empty nodes in iterations are not checked, the Map Operation iterates seven times for the non-empty nodes. As a result, seven <record> nodes are generated in the Target. When Consider empty nodes in iterations is checked, the Map Operation iterates 10 times for all nodes, including the empty nodes. As a result, 10 <record> nodes are generated in the Target.

Known Issue

The Add Item To list Map Operation returns an error if the Create List Map Operation is populated after assigning inputs to the Add Item To list operation. For example:

Add a Create List to the design area.
Add an Add Item To list inside the Create List.
Add an input link to the Add Item To list.
Add a member value in the Create List.

In this scenario, the input link is added to Add Item To list. Then, a member value is added to Create List. When you do this, the Add Item To list operation displays error:

Add Item to List operation labeled <Name> should add 1 member(s).

To work around this behavior, delete the input link to the Add Item To list and then redraw the link.