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).

Tutorial 7: Configure input and output for Step Functions workflows

A Step Functions execution receives a JSON text as input and passes that input to the first state in the workflow. Individual states in a workflow receive JSON data as input and usually pass JSON data as output to the next state. By default, data passes from one state to the next state in the workflow unless you’ve configured the input and/or output for one or more states in the workflow. Understanding how the information flows from state to another, and learning how to filter and manipulate this data, is key to effectively designing and implementing workflows in Step Functions.

Step Functions provides multiple filters to control the input and output data flow between states. The following filters are available for use in your workflows:

For more information about configuring input and output in your workflows, see Processing input and output in Step Functions.

Select specific portions of the raw input using the InputPath filter

Use the InputPath filter to select a specific portion of the input payload.

If you don't specify InputPath, its value defaults to $, which causes the state's task to refer to the entire raw input instead of a specific portion.

Step 1: Create a state machine

Step 2: Run the state machine

Step 3: Use the InputPath filter to select specific parts of an execution input

Manipulate the selected input using the Parameters filter

While the InputPath filter helps you limit the raw JSON input you provide, using the Parameters filter, you can pass a collection of key-value pairs as input. These key-value pairs can either be static values that you define in your state machine definition, or values that are selected from the raw input using InputPath.

In your workflows, Parameters are applied after InputPath. Parameters help you specify how the underlying task accepts its input payload. For example, if the check-address Lambda function accepts a string parameter as input instead of the JSON data, you can use the Parameters filter to transform the input.

In the following example, the Parameters filter receives the input you selected using InputPath in Step 3: Use the InputPath filter to select specific parts of an execution input and applies the intrinsic function States.Format on the input items to create a string called addressString. Intrinsic functions help you perform basic data processing operations on a given input. For more information, see Intrinsic functions in Amazon States Language for Step Functions workflows.

"Parameters": {
    "addressString.$": "States.Format('{}. {}, {} - {}', $.street, $.city, $.state, $.zip)"
  }

Consequently, the following string gets created and is provided to the check-address Lambda function as input.

{
    "addressString": "123 Main St. Columbus, OH - 43219"
}

Configure output using the ResultSelector, ResultPath, and OutputPath filters

When the check-address Lambda function is invoked in the WorkflowInputOutput state machine, the function returns an output payload after performing the address verification. On the Execution Details page, choose the Verify address step and view the output payload inside Task result on the Step details pane.

{
    "ExecutedVersion": "$LATEST",
    "Payload": {
      "statusCode": 200,
      "body": "{\"approved\":true,\"message\":\"identity validation passed\"}"
    },
    "SdkHttpMetadata": {
      "AllHttpHeaders": {
        "X-Amz-Executed-Version": [
          "$LATEST"
        ],
        ...
        ...
    "StatusCode": 200
  }

Using ResultSelector

Now if you need to provide the result of the identity and address verification checks to the following states in your workflow, you can select the Payload.body node in the output JSON and use the StringToJson intrinsic function in the ResultSelector filter to format the data as required.

ResultSelector selects what is needed from the task output. In the following example, ResultSelector takes the string in $.Payload.body and applies the States.StringToJson intrinsic function to convert the string to JSON and puts the resulting JSON inside the identity node.

"ResultSelector": {
    "identity.$": "States.StringToJson($.Payload.body)"
  }

Consequently, the following JSON data is created.

{
    "identity": {
      "approved": true,
      "message": "Identity validation passed"
    }
  }

As you work with these input and output filters, you can also encounter runtime errors arising because of specifying invalid JSON path expressions. For more information, see.

Using ResultPath

You can specify a location in the initial input payload to save a state’s task processing result using the ResultPath field. If you don't specify ResultPath, its value defaults to $, which causes the initial input payload to be replaced with the raw task result. If you specify ResultPath as null, the raw result is discarded and the initial input payload becomes the effective output.

If you apply the ResultPath field on the JSON data created using the ResultSelector field, the task result is added inside the results node in the input payload as shown in the following example:

{
  "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"
    },
  "results": {
    "identity": {
      "approved": true
    }
  }
}

Using OutputPath

You can select a portion of the state output after the application of ResultPath to pass to the next state. This enables you to filter out unwanted information, and pass only the portion of JSON that you care about.

In the following example, the OutputPath field saves the state output inside the results node: "OutputPath": "$.results". Consequently, the final output of the state, which you can pass to the next state is as follows:

{
    "addressResult": {
      "approved": true,
      "message": "address validation passed"
    },
    "identityResult": {
      "approved": true,
      "message": "identity validation passed"
    }
}

Using console features to visualize the input and output data flows

You can visualize the input and output data flow between the states in your workflows using the Step Functions console’s Data flow simulator or Advanced view option in the Execution Details page.