Example: Manipulating state data in Step Functions workflows - Amazon Step Functions
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Example: Manipulating state data in Step Functions workflows

This topic contains examples of how to manipulate state input and output JSON using the InputPath, ResultPath, and OutputPath fields.

Any state other than a Fail workflow state state or a Succeed workflow state state can include the input and output processing fields, such as InputPath, ResultPath, or OutputPath. Additionally, the Wait workflow state and Choice workflow state states don't support the ResultPath field. With these fields, you can use a JsonPath to filter the JSON data as it moves through your workflow.

You can also use the Parameters field to manipulate the JSON data as it moves through your workflow. For information about using Parameters, see Manipulate state data using parameters in Step Functions workflows.

For example, start with the Amazon Lambda function and state machine described in the Creating a Step Functions state machine that uses Lambda tutorial. Modify the state machine so that it includes the following InputPath, ResultPath, and OutputPath.

{
  "Comment": "A Hello World example of the Amazon States Language using an Amazon Lambda function",
  "StartAt": "HelloWorld",
  "States": {
    "HelloWorld": {
      "Type": "Task",
      "Resource": "arn:aws-cn:lambda:us-east-1:123456789012:function:HelloFunction",
      "InputPath": "$.lambda",
      "ResultPath": "$.data.lambdaresult",
      "OutputPath": "$.data",
      "End": true
    }
  }
}

Start an execution using the following input.

{
  "comment": "An input comment.",
  "data": {
    "val1": 23,
    "val2": 17
  },
  "extra": "foo",
  "lambda": {
    "who": "AWS Step Functions"
  }
}

Assume that the comment and extra nodes can be discarded, but that you want to include the output of the Lambda function, and preserve the information in the data node.

In the updated state machine, the Task state is altered to process the input to the task.

"InputPath": "$.lambda",

This line in the state machine definition limits the task input to only the lambda node from the state input. The Lambda function receives only the JSON object {"who": "AWS Step Functions"} as input. 

"ResultPath": "$.data.lambdaresult",

This ResultPath tells the state machine to insert the result of the Lambda function into a node named lambdaresult, as a child of the data node in the original state machine input. Because you are not performing any other manipulation on the original input and the result using OutputPath, the output of the state now includes the result of the Lambda function with the original input.

{
  "comment": "An input comment.",
  "data": {
    "val1": 23,
    "val2": 17,
    "lambdaresult": "Hello, AWS Step Functions!"
  },
  "extra": "foo",
  "lambda": {
    "who": "AWS Step Functions"
  }
}

But, our goal was to preserve only the data node, and include the result of the Lambda function. OutputPath filters this combined JSON before passing it to the state output.

"OutputPath": "$.data",

This selects only the data node from the original input (including the lambdaresult child inserted by ResultPath) to be passed to the output. The state output is filtered to the following.

{
  "val1": 23,
  "val2": 17,
  "lambdaresult": "Hello, AWS Step Functions!"
}

In this Task state:

  1. InputPath sends only the lambda node from the input to the Lambda function.

  2. ResultPath inserts the result as a child of the data node in the original input.

  3. OutputPath filters the state input (which now includes the result of the Lambda function) so that it passes only the data node to the state output.

Example to manipulate original state machine input, result, and final output using JsonPath

Consider the following state machine that verifies an insurance applicant's identity and address.

Note

To view the complete example, see How to use JSON Path in Step Functions.

{
  "Comment": "Sample state machine to verify an applicant's ID and address",
  "StartAt": "Verify info",
  "States": {
    "Verify info": {
      "Type": "Parallel",
      "End": true,
      "Branches": [
        {
          "StartAt": "Verify identity",
          "States": {
            "Verify identity": {
              "Type": "Task",
              "Resource": "arn:aws-cn:states:::lambda:invoke",
              "Parameters": {
                "Payload.$": "$",
                "FunctionName": "arn:aws-cn:lambda:us-west-2:111122223333:function:check-identity:$LATEST"
              },
              "End": true
            }
          }
        },
        {
          "StartAt": "Verify address",
          "States": {
            "Verify address": {
              "Type": "Task",
              "Resource": "arn:aws-cn:states:::lambda:invoke",
              "Parameters": {
                "Payload.$": "$",
                "FunctionName": "arn:aws-cn:lambda:us-west-2:111122223333:function:check-address:$LATEST"
              },
              "End": true
            }
          }
        }
      ]
    }
  }
}

If you run this state machine using the following input, the execution fails because the Lambda functions that perform verification only expect the data that needs to be verified as input. Therefore, you must specify the nodes that contain the information to be verified using an appropriate JsonPath.

{
  "data": {
    "firstname": "Jane",
    "lastname": "Doe",
    "identity": {
      "email": "jdoe@example.com",
      "ssn": "123-45-6789"
    },
    "address": {
      "street": "123 Main St",
      "city": "Columbus",
      "state": "OH",
      "zip": "43219"
    },
    "interests": [
      {
        "category": "home",
        "type": "own",
        "yearBuilt": 2004
      },
      {
        "category": "boat",
        "type": "snowmobile",
        "yearBuilt": 2020
      },
      {
        "category": "auto",
        "type": "RV",
        "yearBuilt": 2015
      },
    ]
  }
}

To specify the node that the check-identity Lambda function must use, use the InputPath field as follows:

"InputPath": "$.data.identity"

And to specify the node that the check-address Lambda function must use, use the InputPath field as follows:

"InputPath": "$.data.address"

Now if you want to store the verification result within the original state machine input, use the ResultPath field as follows:

"ResultPath": "$.results"

However, if you only need the identity and verification results and discard the original input, use the OutputPath field as follows:

"OutputPath": "$.results"

For more information, see Processing input and output in Step Functions.