Map state

A Map state iterates over an array of JSON objects. The state runs each item in the array through a state machine that's similar to a ZIS flow.

"IterateThroughOrders": {
  "Type": "Map",
  "ItemsPath": "$.orders",
  "Iterator": {
    "StartAt": "GetOrderDetails",
    "States": {
      "GetOrderDetails": {
        "Type": "Action",
        "ActionName": "zis:INTEGRATION:action:GetOrderDetails",
        "Parameters": {
          "order_num.$": "$.order_num"
        },
        "End": true
      }
    }
  },
  "ResultPath": "$.order_details",
  "Next": "NextState"
}

Supported properties

In addition to common state properties, a Map state supports the following properties.

Name	Type	Mandatory	Description
ItemsPath	string	true	Reference path to an input array of JSON objects
Iterator	object	true	State machine that's run for each item in the ItemsPath array. Supports the same properties and states as a ZIS flow definition. A state within the Iterator can't transition to a state outside the Iterator. If any iteration fails, the entire Map state fails and ends all remaining iterations
Catch	array of objects	false	Contains a fallback state to run if the Map state encounters a runtime error. See Flow states retry and error handling

Accessing data in a Map state

A Map state's Iterator iterates through each item in the ItemsPath array. Each iteration's input is a single array item. The iteration can't access other data, such as the root-level "$" object. Instead, you can use a Transform action to add data to items in the ItemsPath array before running the Map state.

For example, a ZIS flow contains a $.contacts array with the following data:

{
  "contacts": [
    {
      "id": 1234,
      "name": "John Citizen",
      "phone": "[phone]"
    },
    {
      "id": 5678,
      "name": "Jane Doe",
      "phone": "[phone]"
    }
  ]
}

The flow also contains an $.appointments array with the following data:

{
  "appointments": [
    {
      "id": 1234,
      "name": "John Citizen",
      "next_appt": "2099-05-06T09:00:00Z"
    },
    {
      "id": 5678,
      "name": "Jane Doe",
      "next_appt": "2099-05-08T10:00:00Z"
    }
  ]
}

To use data from both arrays in a Map state, you must first merge them into a single array of JSON objects. The following Action state uses a Transform action to join objects from each array by customer_id. The state outputs the results to the $.contacts array, which is overwritten.

"AddAppointmentsToContacts": {
  "Type": "Action",
  "ActionName": "zis:common:transform:Jq",
  "Parameters": {
    "expr": "[.contacts + .appointments | group_by(.id)[] | add]",
    "data.$": "$"
  },
  "ResultPath": "$.contacts",
  "Next": "NotifyAll"
}

Afterward, each item in the $.contacts array contains a next_appt property:

{
  "contacts": [
    {
      "id": 1234,
      "name": "John Citizen",
      "next_appt": "2099-05-06T09:00:00Z",
      "phone": "[phone]"
    },
    {
      "id": 5678,
      "name": "Jane Doe",
      "next_appt": "2099-05-08T10:00:00Z",
      "phone": "[phone]"
    }
  ]
}

The following Map state uses the $.contacts array as input. The state uses a custom action to make an API request for each item in the array. The request includes the next_appt value.

"NotifyAll": {
  "Type": "Map",
  "ItemsPath": "$.contacts",
  "Iterator": {
    "StartAt": "NotifyContacts",
    "States": {
      "NotifyContacts": {
        "Type": "Action",
        "ActionName": "zis:INTEGRATION:action:NotifyContacts",
        "Parameters": {
          "name.$": "$.name",
          "next_appt.$": "$.next_appt",
          "phone.$": "$.phone"
        },
        "End": true
      }
    }
  },
  "ResultPath": "$.notified",
  "Next": "NextState"
}

Authenticating API requests in a Map state

You can use connections to authenticate API requests made by custom actions in a Map state's Iterator. For more information about using connections with custom actions, see Using a connection to authenticate API requests in a ZIS flow.

Previously, to authenticate requests in a Map state, you had to add an OAuth connection's access token to items in the ItemsPath array. This method involved using the $.connections.{oauth_connection_name}.access_token reference path. This method and the related reference path are deprecated. The reference path may be removed in a future release.

Example

For an example of a Map state in a ZIS flow, see Iterating over a collection in a ZIS flow.

Limitations

• You can't use a Map state to exceed the transition limit for a ZIS flow. Keep this limit in mind if you nest a Map state within another Map state.

• ItemsPath must point to an array of JSON objects. ItemsPath doesn't support other data types.

• The ItemsPath array size is limited to 100 objects. The Map state checks the array size before running any iterations. If there are more than 100 objects in the array, the Map state aborts and the flow ends.

• A ZIS Map state doesn't support the MaxConcurrency property from the Amazon States Language. In a ZIS Map state, the Iterator states run sequentially for each element in the ItemsPath array. Concurrent execution isn't supported.

• A ZIS Map state doesn't support the Parameters property from the Amazon States Language. As a workaround, you can use a Transform action to add data to the ItemsPath items before the Map state. See Accessing data in a Map state.

• A ZIS Map state doesn't support the Retry property from the Amazon States Language. Instead, ZIS uses a built-in retry logic for failed flows. Alternatively, you can use a Catch block to handle runtime errors in a Map state. See Flow states retry and error handling.