Loops from the input message must be mapped to the output if you want to map one of its enclosed fields. Otherwise the mapper cannot resolve the reference to the field since there can be more than one occurrence. The "loop mappings" tell the mapper how to deal with this multiplicity of values.
You can make loop mappings to loop or value fields.
Loop to loop
In this case, every occurence of the source loop will by default lead to the creation of an occurence of the target loop.
It is possible to change the source loop (sort, filter, ...) by just adding a formula on it. The most used functions in this context are :
sortLoop : This function will sort the source loop according to a given criteria. Example : sortLoop([Loop], 'Code') will sort the loop elements following the value of their field Code.
sortLoopNumeric : This function will sort the source loop according to a given numeric criteria
filterLoop : This function will filter the source loop, and only keep elements that match the given condition. Example filterLoop([Loop], 'Area30000') will only keep the elements for which the field Area contains a value greater than 300000
You can find here a complete example, with sort and filter. The loop mapping only keeps countries with an Area300000, and sort the loop items according to the Code field. Example file and how it is mapped is also shown.
Loop to loop mapping with filter and sort.
Note: The filter loop function can be used multiple times in the same formula to enable the system to filter out the incoming loop based on first filter, the second filter,... and so on.
Loop to value
In this case, only one occurence of the loop will be used, as the target field doesn't allow repetition of value.
By default, the first occurence of the loop is used, but you can again change the default by using a formula. If your formula still returns a list of elements, only the first one will be used.
Note that if the source loop is empty, an empty element will be created in the out message.
Below, please find a complete example that chooses the Country with the biggest Area value. The sortLoop call will sort the list in decreasing order of Area. As this result still contains multiple entries, the first one will be automatically selected.
Loop to node mapping with sort.
Identify loop mappings in the interface
Loop mappings are identified with an additional icon in the formula bar.
Identifying loop mappings
Loop instructions without this icon will not work !
You can initiate a loop mapping by dragging a (input) loop to a target node. Directly selecting a target node and typing a formula in the formula bar will only lead to the creation of value mappings, not loop mappings.
Note: If you copy the loop expression from one node and paste it to a new node then the generated formula is a value mapping and not a loop mapping, So to make sure you will have a loop mapping then you must drag and drop the input loop to the target node.
Writing xpath expressions in loop functions
All the loop functions (filterLoop, sortLoop, ...) take as second parameter a String, that will be interpreted as an xpath. This xpath will be evaluated for every element of the list, to calculate the value that will be used to sort or filter.
The current node for the evaluation of this xpath will be the node of the list itself, and you can refer it with '.'. As an example, an expression like 'Code' is completely equivalent to './Code', and refers to the xml element Code, that is a direct child of the element on which the loop applies. On the previous examples, references like 'Code' or 'Area' in the xpath work, because these names are the names of the xml elements that are direct children of the element on which the loop applies (Country).
You must also be careful of always using the names of the fields to reference them in xpath, and not the labels. Labels are just present in the interface to be clearer, but do not correspond to anything in xpath or xml. This case happens more often when using csv messages, where all the fields will have the same name ('field'), even if they can have different labels ('Name', 'Code', 'Area', ...). In this case, an xpath like 'Code' will not correspond to anything, but you may for example use a reference like 'field[2]' .
As the second parameter (the xpath) is a String, and that Strings are delimited by single quotes, writing a xpath expression that also uses single quotes can also be a little tedious: you have to double your single quotes. As an example, the expression to filter Countries to only keep the one with Code='BE' will be
filterLoop([Loop], 'Code=''BE''')
Writing a filterLoop with a quote in the condition.
If you type your expression in the EasyFunctionEditor instead of the formula bar, you can type your expression normally, and the editor will make the necessary quotings for you.
Writing same filterLoop using the EasyFunctionEditor.