Map state

A Map state enables you to execute a sequence of steps for each element of an input array.

To learn about using the Map state in a ZIS Flow, see Extending your first integration: Iterating over a collection.

In addition to the common state properties, the Map state also contains the following properties:

Name	Mandatory	Description
ItemsPath	Yes	The reference path to the input array of objects
Iterator	Yes	Contains the state machine that is executed for each item in the ItemsPath. States within an Iterator field can only transition to each other, and cannot transition to a state outside the Iterator. If any iteration fails, the entire Map state fails, and all remaining iterations are terminated
ResultPath	Yes	The reference path to store the output of the Map state

Example

Consider the following input data for a Map state:

{
  "notify": [
    {
      "name": "John Citizen",
      "next_appt": "19-AUG-2021 09:00",
      "phone": "123-456-789"
    },
    {
      "name": "Jane Doe",
      "next_appt": "20-AUG-2021 10:00",
      "phone": "456-123-789"
    }
  ]
}

Given the input, the following Map state involves calling an external action to send an SMS notification for each contact found in the notify array.

"NotifyAll": {
  "Type": "Map",
  "ItemsPath": "$.notify",
  "Iterator": {
    "StartAt": "Notify",
    "States": {
      "Notify": {
        "Type": "Action",
        "ActionName": "zis:<integration>:action:<name>",
        "Parameters": {
          "name.$": "$.name",
          "phone.$": "$.phone",
          "next_appt.$": "$.next_appt"
        },
        "End": true
      }
    }
  },
  "ResultPath": "$.notified",
  "End": true
}

Limitations

A Map state has the following limitations:

• The ItemsPath array size is limited to 100 objects. The size of the array is computed before attempting to execute any iterations. If there are more than 100 objects in the array the Map state aborts and the flow terminates
• The input to each iteration is a single element of the array field. For example, in Amazon Step Functions, the support for accessing other items from the input is provided by Parameters which is currently unsupported in ZIS. As a workaround, you could use the JQ state to add required input items to the object for processing inside the Map state. See Extending your first integration: Iterating over a collection
• The Iterator is executed sequentially for each element in the ItemsPath array. No concurrent execution is supported