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.

"RedactAttachment": {  "Type": "Map",  "ItemsPath": "$.orders",  "Iterator": {    "StartAt": "GetOrderDetails",    "GetOrderDetails": {      "Redact": {        "Type": "Action",        "ActionName": "zis:INTEGRATION:action:GetOrderDetails",        "Parameters": {          "order_num.$": "$.order_num",          "access_token.$": "$.access_token"        },        "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
Retry array of objects false Defines a retry policy for the state. See Flow states retry and error handling
Catch array of objects false Contains a fallback state to run if the Map state encounters a runtime error and can't retry. 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 ZIS connections or 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 an array with the following data:

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

You want to use a Map state to make an authenticated API call for each item in the array. To make the API calls, you'll use a ZIS custom action in the Map state's Iterator.

A ZIS connection named "sms_service" contains an OAuth access token for the API. You want to use the token to authenticate the API calls. The token is available at the $.connections.sms_service.access_token path. However, an action in a Map state can't access the path directly.

Instead, you add the following Action state before the Map state in your ZIS flow. The Action state uses a Transform action to add the connection's access token to each item in the array.

"IncludeAccessToken": {  "Type": "Action",  "ActionName": "zis:common:transform:Jq",  "Parameters": {    "expr.$": "[.contacts[] | (.access_token=\"{{$.connections.sms_service.access_token}}\")]",    "data.$": "$"  },  "ResultPath": "$.contacts",  "Next": "NotifyAll"}

Afterward, each item in the array contains the access token:

{  "contacts": [    {      "name": "John Citizen",      "next_appt": "2099-05-06T09:00:00Z",      "phone": "+16175551212",      "access_token": "***OAuth access token***"    },    {      "name": "Jane Doe",      "next_appt": "2099-05-08T10:00:00Z",      "phone": "+14155551212",      "access_token": "***OAuth access token***"    }  ]}

The following Map state uses the array as input. The state uses a custom action to make API calls for each item in the array. The action uses the access token in each item to authenticate the calls.

"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",          "access_token.$": "$.access_token"        },        "End": true      }    }  },  "ResultPath": "$.notified",  "Next": "NextState"}

For another example of this setup, 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.