ResultPath - AWS Step Functions
Replace Input with ResultDiscard Result and Keep InputInclude Result with InputUpdate a Node in Input with ResultInclude Error and Input in a Catch

ResultPath

The output of a state can be a copy of its input, the result it produces (for example, output from a Task state’s Lambda function), or a combination of its input and result. Use ResultPath to control which combination of these is passed to the state output.

The following state types can generate a result and can include ResultPath:

Use ResultPath to combine a task result with task input, or to select one of these. The path you provide to ResultPath controls what information passes to the output.

Note

ResultPath is limited to using reference paths, which limit scope so that it can identify only a single node in JSON. See Reference Paths in the Amazon States Language.

These examples are based on the state machine and Lambda function described in the Creating a Step Functions state machine that uses Lambda tutorial. Work through that tutorial and test different outputs by trying various paths in a ResultPath field.

Tip

Use the data flow simulator in the Step Functions console to test JSON path syntax, to better understand how data is manipulated within a state, and to see how data is passed between states.

Use ResultPath to Replace the Input with the Result

If you don't specify a ResultPath, the default behavior is as if you had specified "ResultPath": "$". Because this tells the state to replace the entire input with the result, the state input is completely replaced by the result coming from the task result.

The following diagram shows how ResultPath can completely replace the input with the result of the task.

Replace input with ResultPath.

Use the state machine and Lambda function described in Creating a Step Functions state machine that uses Lambda, and change the service integration type to AWS SDK integration for the Lambda function. To do this, specify the Lambda function Amazon Resource Name (ARN) in the Resource field of the Task state as shown in the following example. Using AWS SDK integration ensures that the Task state result only contains the Lambda function output without any metadata.

{  
   "StartAt":"CallFunction",
   "States":{  
      "CallFunction": {  
         "Type":"Task",
         "Resource":"arn:aws:lambda:us-east-2:123456789012:function:HelloFunction",
         "End": true
      }
   }
}

Then, pass the following input:

{
  "comment": "This is a test of the input and output of a Task state.",
  "details": "Default example",
  "who": "AWS Step Functions"
}

The Lambda function provides the following result.

"Hello, AWS Step Functions!"
Tip

You can view this result on the Step Functions console. To do this, on the Execution Details page of the console, choose the Lambda function in the Graph view. Then, choose the Output tab in the Step details pane to see this result.

If ResultPath isn't specified in the state, or if "ResultPath": "$" is set, the input of the state is replaced by the result of the Lambda function, and the output of the state is the following.

"Hello, AWS Step Functions!"
Note

ResultPath is used to include content from the result with the input, before passing it to the output. But, if ResultPath isn't specified, the default is to replace the entire input.

Discard the Result and Keep the Original Input

If you set ResultPath to null, it will pass the original input to the output. Using "ResultPath": null, the state's input payload will be copied directly to the output, with no regard for the result.

The following diagram shows how a null ResultPath will copy the input directly to the output.

Copy Input to Output with ResultPath.

Use ResultPath to Include the Result with the Input

The following diagram shows how ResultPath can include the result with the input.

Include input with ResultPath

Using the state machine and Lambda function described in the Creating a Step Functions state machine that uses Lambda tutorial, we could pass the following input.

{
  "comment": "This is a test of the input and output of a Task state.",
  "details": "Default example",
  "who": "AWS Step Functions"
}

The result of the Lambda function is the following.

"Hello, AWS Step Functions!"

To preserve the input, insert the result of the Lambda function, and then pass the combined JSON to the next state, we could set ResultPath to the following.

"ResultPath": "$.taskresult"

This includes the result of the Lambda function with the original input.

{
  "comment": "This is a test of input and output of a Task state.",
  "details": "Default behavior example",
  "who": "AWS Step Functions",
  "taskresult": "Hello, AWS Step Functions!"
}

The output of the Lambda function is appended to the original input as a value for taskresult. The input, including the newly inserted value, is passed to the next state.

You can also insert the result into a child node of the input. Set the ResultPath to the following.

"ResultPath": "$.strings.lambdaresult"

Start an execution using the following input.

{
  "comment": "An input comment.",
  "strings": {
    "string1": "foo",
    "string2": "bar",
    "string3": "baz"
  },
  "who": "AWS Step Functions"
}

The result of the Lambda function is inserted as a child of the strings node in the input.

{
  "comment": "An input comment.",
  "strings": {
    "string1": "foo",
    "string2": "bar",
    "string3": "baz",
    "lambdaresult": "Hello, AWS Step Functions!"
  },
  "who": "AWS Step Functions"
}

The state output now includes the original input JSON with the result as a child node.

Use ResultPath to Update a Node in the Input with the Result

The following diagram shows how ResultPath can update the value of existing JSON nodes in the input with values from the task result.

Replace input with ResultPath

Using the example of the state machine and Lambda function described in the Creating a Step Functions state machine that uses Lambda tutorial, we could pass the following input.

{
  "comment": "This is a test of the input and output of a Task state.",
  "details": "Default example",
  "who": "AWS Step Functions"
}

The result of the Lambda function is the following.

Hello, AWS Step Functions!

Instead of preserving the input and inserting the result as a new node in the JSON, we can overwrite an existing node.

For example, just as omitting or setting "ResultPath": "$" overwrites the entire node, you can specify an individual node to overwrite with the result.

"ResultPath": "$.comment"

Because the comment node already exists in the state input, setting ResultPath to "$.comment" replaces that node in the input with the result of the Lambda function. Without further filtering by OutputPath, the following is passed to the output.

{
  "comment": "Hello, AWS Step Functions!",
  "details": "Default behavior example",
  "who": "AWS Step Functions",
}

The value for the comment node, "This is a test of the input and output of a Task state.", is replaced by the result of the Lambda function: "Hello, AWS Step Functions!" in the state output.

Use ResultPath to Include Both Error and Input in a Catch

The Handling error conditions using a Step Functions state machine tutorial shows how to use a state machine to catch an error. In some cases, you might want to preserve the original input with the error. Use ResultPath in a Catch to include the error with the original input, instead of replacing it. 

"Catch": [{ 
  "ErrorEquals": ["States.ALL"], 
  "Next": "NextTask", 
  "ResultPath": "$.error" 
}]

If the previous Catch statement catches an error, it includes the result in an error node within the state input. For example, with the following input:

{"foo": "bar"}

The state output when catching an error is the following.

{
  "foo": "bar",
  "error": {
    "Error": "Error here"
  }
}

For more information about error handling, see the following: