Create loops to manage repetitive parts of your message definition.

Loops and grouping

A message is based on three node types as defined in the Message Definition chapter.

To specify that a value or a structural node can occur more than once, you need to enclose it in a Loop. A Loop is a virtual node representing the multiplicity of a node or a set of nodes. It is defined by its minOccurs and maxOccurs properties:

CSV Sample:

By definition a CSV message is composed of a header containing some header items followed by one or many lines containing line items. The number of line items correspond to the number of header items.

header1,header2,header3,header4
123,aaa,abc,000
456,bbb,def,111
789,ccc,ghi,222
...

Here is the message tree for this CSV:

Figure 2.14. Message tree

The headers and line nodes are structural nodes while header and line items are value nodes. To specify that the line can appear more than once, there is a virtual Loop node enclosing the line node.

Grouping

A Loop can define the multiplicity of a node sequence. To identify a node sequence in a Loop, you must manually group those relevant nodes using one of the following grouping type:

Loop parameters can be edited by right-clicking on the loop node in the message tree in the in or out message tab durint channel editing.

Figure 2.15. Loop parameters

The grouping value is an XPath expression identifying the grouping pattern.

By right clicking on any node, you can:

Regrouping a Loop

An existing loop can also be regrouped using one of the Grouping type. To do this you can use the Regroup this Loop in the loop contextual menu. This will create a new enclosing loop that requires specifying the Grouping type and the Grouping value.

Example with a DESADV message in a CSV format:

TruckId,PalletId,PacketId,Quantity,Item
 1,       1,       1,       5,Item 1
 1,       1,       1,      25,Item 2
 1,       1,       1,       1,Item 3
 1,       1,       2,       3,Item 4
 1,       1,       2,      15,Item 5
 1,       2,       1,     100,Item 6
 1,       2,       1,       2,Item 7
 1,       2,       3,      20,Item 8
 1,       2,       3,      11,Item 9
 1,       2,       3,       9,Item 10
 1,       2,       4,      72,Item 11
 2,       1,       1,      91,Item 12
 2,       2,       1,     423,Item 13
 2,       3,       1,      88,Item 14
 2,       4,       1,       3,Item 15
 3,       1,       1,      12,Item 16
 3,       1,       1,      21,Item 17
 3,       1,       1,     666,Item 18
 3,       1,       2,       3,Item 19
 3,       1,       2,      22,Item 20
 3,       1,       2,       2,Item 21
 3,       2,       1,     211,Item 22
 3,       2,       1,      64,Item 23
 4,       1,       1,      61,Item 24
 4,       1,       1,      17,Item 25
 4,       1,       2,       2,Item 26
 4,       1,       2,       9,Item 27
 4,       1,       2,      85,Item 28
 5,       1,       1,      57,Item 29

Figure 2.16. Default message tree

In this example, we have a loop of lines defining an item to dispatch, where each line has the truck id where the item is stored.

We could regroup this loop of lines by TruckId so we can loop on all trucks and then loop inside each truck on all items in that truck.

To do that we select the Regroup this Loop action on the loop, select the Group By value for Grouping type and set it to ' field[1] ' (as this is the XPath of the TruckId element).

Figure 2.17. Regroup this loop

We now have a loop on all trucks and a sub loop on all item in a truck.

Figure 2.18. Sub loop

We can even go further and decide to group by PalletId and PacketId, that would give us four nested loops, one for all trucks, the next one for all pallets in a truck, the next one for all packets in a pallet and the last one, for all items in a packet.

Figure 2.19. ...

Loops and Drag and Drop Mapping

Loops from the input message must be mapped to the output if you want to map one of its enclosed nodes. Otherwise the mapper cannot resolve the reference to the node since there can be more than one occurrence of the same node (as defined by the loop).

Figure 2.20. Loop to loop example

Figure 2.21. Loop to non loop example