Mapping Complex Arrays

Complex arrays are arrays of objects that can optionally contain nested arrays. You can map these arrays using the 3 available options - Configure with Items, Configure with Source and Configure with JSON.

For examples, refer to arrayforEach sample.

When you use the Configure with Items option, you define an implicit scope consisting of everything available in the Available data. It is equivalent to creating an implicit array with a single object element consisting of everything in the Available data. Hence, the resulting length of the array is always one element.

To create a confined scope within the Available data, use the Configure with Source option. When using this option, you must map 3 fields - Source, Loop name and the Filter by. Here, the Loop name gets auto populated. When mapping identical arrays, the source name gets inserted in the Select Source field by default.

The Source defines the scope within the Available data. Simply put, the input object or array can only be mapped to elements in the Available data that fall within the boundary indicated by its scope.

The Loop name is a scoping variable given to the scope that you have defined in the first argument. By default, the scoping variable name is the same as the input element name for which you are defining the scope. By doing so, the mapper associates the input object to its scope by the scoping variable. Once there is a scoping variable for the scope, the mapper uses that scoping variable to refer to the scope in future mappings. You can edit the scoping variable to any string that might be more meaningful to you. The scoping variable is particularly useful when mapping the child elements in nested arrays.

The Filter by field is optional. When iterating through an upstream output array, you can enter a filter to specify a particular condition for mapping as the Filter by field. When using this field, you must enter the scoping variable in the loop name field. Only array elements that match the filter get mapped. For instance, if you are iterating through an array, array1, in the upstream output with a filter $loop.name=="Jane" mapped in the Filter by field, if array1 has 10 elements and only four out of them match the condition of the filter, only those four elements are mapped to the input array and the remaining six are skipped. This results in the size of the input array being only four elements, even though array1 has 10 elements. See the section, Filtering Array Elements to Map Based on a Condition for more details.