ItemsPath (Map, JSONPath only) - AWS Step Functions

ItemsPath (Map, JSONPath only)

Managing state and transforming data

This page refers to JSONPath. Step Functions recently added variables and JSONata to manage state and transform data.

Learn about Passing data with variables and Transforming data with JSONata.

In JSONPath-based states, use the ItemsPath field to select an array within a JSON input provided to a Map state. The Map state repeats a set of steps for each item in the array. By default, the Map state sets ItemsPath to $, which selects the entire input. If the input to the Map state is a JSON array, it runs an iteration for each item in the array, passing that item to the iteration as input.

Note

You can use ItemsPath in the Distributed Map state only if you use a JSON input passed from a previous state in the workflow.

You can use the ItemsPath field to specify a location in the input that points to JSON array used for iterations. The value of ItemsPath must be a Reference Path, and that path must point to JSON array. For instance, consider input to a Map state that includes two arrays, like the following example.

{
  "ThingsPiratesSay": [
    {
      "say": "Avast!"
    },
    {
      "say": "Yar!"
    },
    {
      "say": "Walk the Plank!"
    }
  ],
  "ThingsGiantsSay": [
    {
      "say": "Fee!"
    },
    {
      "say": "Fi!"
    },
    {
      "say": "Fo!"
    },
    {
      "say": "Fum!"
    }
  ]
}

In this case, you could specify which array to use for Map state iterations by selecting it with ItemsPath. The following state machine definition specifies the ThingsPiratesSay array in the input using ItemsPath.It then runs an iteration of the SayWord pass state for each item in the ThingsPiratesSay array.

{
  "StartAt": "PiratesSay",
  "States": {
    "PiratesSay": {
      "Type": "Map",
      "ItemsPath": "$.ThingsPiratesSay",
      "ItemProcessor": {
         "StartAt": "SayWord",
         "States": {
           "SayWord": {
             "Type": "Pass",
             "End": true
           }
         }
      },
      "End": true
    }
  }
}

When processing input, the Map state applies ItemsPath after InputPath. It operates on the effective input to the state after InputPath filters the input.

For more information on Map states, see the following: