This documentation describes the old version of our handlebars powered mapper which is not available by default. We will stop supporting it by the end of Q1 2018. Please read the Migration guide to the new mapping language to get started with the new JSONata powered mapper.

Here is a very common scenario which requires the incoming array to be mapped into single Object fields. The procedure is better known as array splitting or many to one mapping.

Very often the incoming data comes in one single array containing multiple records, but it is required to process each record separately. To do so the array must be split into single records for further processing. Let us present two cases for the clarity.

Simple array splitting

Here is an example of simple incoming data which is encapsulated in the JSON array ([..]):

{
  "Customers" : [
    {
      "firstname" : "John",
      "lastname" : "Doe",
      "address" : "Street1",
      "phone" : "1234",
      "email" : "john.doe@example.com",
      "animal" : "cat",
      "lastcheck" : "12/12/2014"
    },
    {
      "firstname" : "Jane",
      "lastname" : "Eyre",
      "address" : "Street1",
      "phone" : "4321",
      "email" : "jane.eyre@example.com",
      "animal" : "dog",
      "lastcheck" : "15/12/2014"
    }
  ]
}

During the mapping, each field is being mapped in the following way. First, the drop-down shown on each field is opened. If the incoming data is an array ("Customers" : [..]) then it will be represented in the following way:

Then by selecting the  > [..] Customers it will extend further showing the sub-structure like this:

Here we select the property Phone (the numbers 123 indicate that the expected data is number) since we want to map this into an outgoing field called phone and by selecting it we will have the following mapped structure:

{{Customers[*].phone}} structure means that the record is the part of the array Customers[*].

After doing the same procedure for all the outgoing fields the final mapping would look like this:

Now if we test this mapping with the above presented JSON example then it will be split into two records and added into the spreadsheet:

Everything looks good, now we can activate the flow and start sending some data using the Postman like this:

Let's check the dashboard to see the integration in action:

As it can be seen from the picture, one incoming data was split into 3 different records and processed. Let's check the final result in the spreadsheet:

Complex array splitting

In the above example we explained how the splitting is occurring if the incoming data contains just multiple records encapsulated into an array. However, what would happen if the incoming JSON has not only an array structure but also a header part? How are those headers processed?

Let us take a different example of a typical array from one of our projects:

{
  "id": "546c9d78d8ad901b57d540a0",
  "type": "invoice",
  "currency": "EUR",
  "date": "2014-11-19",
  "dueDate": "2014-12-03",
  "lines": [
    {
      "taxRate": "20",
      "quantity": "1",
      "productName": "Awesome Product",
      "netAmount": "10",
      "grossAmount": "12",
      "taxAmount": "2"
    },
    {
      "taxRate": "20",
      "quantity": "1",
      "productName": "Another Product",
      "netAmount": "50",
      "grossAmount": "60",
      "taxAmount": "10"
    }
  ]
}

This array, when mapped into the object fields like above: meaning when a property of an array is mapped into a non-array property, such as the mapper, Stringwill start splitting it into:

{
  "id": "546c9d78d8ad901b57d540a0",
  "type": "invoice",
  "currency": "EUR",
  "date": "2014-11-19",
  "dueDate": "2014-12-03",
  "taxRate": "20",
  "quantity": "1",
  "productName": "Awesome Product",
  "netAmount": "10",
  "grossAmount": "12",
  "taxAmount": "2"
}

and

{
  "id": "546c9d78d8ad901b57d540a0",
  "type": "invoice",
  "currency": "EUR",
  "date": "2014-11-19",
  "dueDate": "2014-12-03",
  "taxRate": "20",
  "quantity": "1",
  "productName": "Another Product",
  "netAmount": "50",
  "grossAmount": "60",
  "taxAmount": "10"
}

Notice that the subsequent splitting created 2 objects in which array properties are merged together with properties on the level above. So each split record inherits the common properties of the incoming JSON.