Configure workflow input and output in Step Functions

In the previous topic, Run your workflow , you learned how to run your workflow. In this topic, you'll learn how to select, filter, and manipulate data as it passes between states.

A Step Functions execution receives 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. 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 the following filters to control the input and output data flow between states:

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 for JSONPath states in Step Functions .

"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

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 might see runtime errors from invalid JSONpath expressions.

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. With this approach, you can filter out unwanted information and pass along only the portion of JSON that you need.

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.

Manipulate the selected input using the Parameters field

While the InputPath field helps you limit the raw JSON input you provide, using the Parameters field, 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, imagine if the check-address Lambda function accepts a string parameter as input instead of the JSON data, you can use the Parameters field to transform the input.

In the following example, the Parameters field receives the input you selected using InputPath in the Select specific portions of the raw input using the InputPath filter section 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.

"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"
}

Next steps

In the final topic, Debug errors, you’ll learn how to debug errors in your Step Functions workflows.