List Map Operations - Usage and Examples

 

Updated: November 27, 2015

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

Map Operation

Description

Parameters

Output

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.

System_CAPS_noteNote

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

Using the Age Member:

Parameter

Output List

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

Using the Name Member and specifying a Condition:

Parameter

Output List

Member: Name

Condition: item.Age>25

Name

C

Using the Designation Member:

Parameter

Output List

Member: Designation

Developer

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

Parameter

Output List

Member: Emp_ID

Member: Name

Member: Age

Condition: item.Age>25

Emp_ID

Name

Age

3

C

26

4

D

32

6

F

36

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.

Using the Age Member:

Parameter

Output List

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:

Parameter

Output List

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

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.

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:

  1. Open a BizTalk Service project or the BizTalk Service Artifacts project in Visual Studio.

  2. Double-click a Transform (.trfm) to open the Transform Designer.

  3. 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.

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:

  1. Add a Create List to the design area.

  2. Add an Add Item To list inside the Create List.

  3. Add an input link to the Add Item To list.

  4. 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.

Show: