Mapping Complex Arrays - Using the array.forEach() Function

Complex arrays are arrays of objects that can optionally contain nested arrays. Complex arrays are mapped using the array.forEach() function. The array.forEach() function can be used with or without arguments.

Refer to https://github.com/TIBCOSoftware/tci-flogo/tree/master/samples/app-dev/array.forEach.sample for examples.

When you use array.forEach() without any arguments, you define an implicit scope comprising of everything available in the Upstream Output. It is equivalent to creating an implicit array with a single object element comprising of everything in the Upstream Output. Hence, the resulting length of the array is always one element.

To create a confined scope within the Upstream Output, use array.forEach() with arguments. You can do so by entering the mapping manually or by selecting the forEach() function under the array category under Functions. The forEach() function can accept three arguments. When mapping identical arrays, the array.forEach() function gets inserted with the first two arguments by default.

The first argument defines the scope within the Upstream Output. Simply put, the input object or array can only be mapped to elements in the Upstream Output that fall within the boundary indicated by its scope .

The second argument is a scoping variable given to the scope that you have defined in the first argument. The scoping variable name by default, 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 third argument is optional. When iterating through an upstream output array, you can enter a filter to specify a particular condition for mapping as the third argument. When using the filter as the third argument, you must mandatorily enter the scoping variable as the second argument. 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 that says $loop.name=="Jane" as the third argument, if array1 has ten elements and only four out of them match the condition of the filter, only those four elements will be mapped to the input array and the remaining six will be skipped. This results in the size of the input array to be only four elements, even though array1 has ten elements. See the section, Filtering Array Elements to Map Based on a Condition for more details.

Important: If you have used the array.forEach() in a legacy app, to update your app with the current changes in the array.forEach() function, delete the old mapping and remap the elements. A scoping variable is now included in the mapping. For example, if the old mapping is: array.forEach($flow.body.Book), after the remap, the mapping should be: array.forEach($flow.body.Book, "Book") where "Book" is the scoping variable.

This section contains the following topics:

  • Understanding array.ForEach() Function with an Example
    The example in this section illustrates an array, cakes.
  • Mapping Identical Arrays of Objects
    When mapping an array of objects in the input to an identical array of objects (matching property names and data types) in the Upstream Output, keep the following in mind:
  • Mapping Array Child Elements to Non-Array Elements or to an Element in a Non-Matching Array
    There may be situations when you want to map an element within an array of objects to an output element that is not in an array or belongs to an non-matching array in the Upstream Output. In such a situation, you must create an array with a single element. You do this by using the array.forEach() function without any arguments. When you use array.forEach() function without arguments, it creates an array with a single object element. The single object element treats everything in the Upstream Output as the children of the newly created array object element. This allows you to map to any of the Upstream Output elements as they are now treated as if they were within an array.
  • Mapping Nested Arrays
    Before you map a nested array, you must map its parent root. Scoping variable is particularly useful when mapping the child elements in nested arrays.
  • Filtering Array Elements to Map Based on a Condition
    When mapping arrays of objects, you can filter the objects that gets mapped by specifying a filter in the mapper.
Related tasks