Menu
AWS Step Functions
Developer Guide

State Machine Data

State Machine data takes the following forms:

  • The initial input to a state machine

  • Data passed between states

  • The output from a state machine.

This topic describes how state machine data is formatted and used in AWS Step Functions.

Data Format

State machine data is represented by JSON text, so values can be provided using any data type supported by JSON: objects, arrays, numbers, strings, Boolean values, and null.

Note that:

  • Numbers in JSON text format conform to JavaScript semantics, typically corresponding to double-precision IEEE-854 values.

  • Stand-alone quote-delimited strings, Booleans, numbers, and null are valid JSON text.

  • The output of a state becomes the input to the next state. However, states can be restricted to working on a subset of the input data by using Input and Output Processing.

State Machine Input/Output

AWS Step Functions can be given initial input data when you start an execution, by passing it to StartExecution or by passing initial data using the Step Functions console. Initial data is passed to the state machine's StartAt state. If no input is provided, the default is an empty object {}.

The output of the execution is returned by the terminal (last) state that is reached, and is provided as JSON text in the execution's result. Execution results can be retrieved from the execution history by external callers (for example, in DescribeExecution) and can be viewed in the Step Functions console.

State Input/Output

Each state's input consists of JSON text received from the preceding state or, in the case of the StartAt state, the input to the execution.

A state's output must be given as JSON text. Certain flow-control states simply echo their input to their output.

For example, the following state machine adds two numbers together:

{
  "Comment": "An example that adds two numbers.",
  "StartAt": "Add",
  "Version": "1.0",
  "TimeoutSeconds": 10,
  "States":
    {
        "Add": {
          "Type": "Task",
          "Resource": "arn:aws:lambda:us-east-1:123456789012:function:Add",
          "End": true
        }
    }
}

The state machine uses the following Lambda function:

function Add(input) {
  var numbers = JSON.parse(input).numbers;
  var total = numbers.reduce(
    function(previousValue, currentValue, index, array) {
      return previousValue + currentValue; });
  return JSON.stringify({ result: total });
}

If an execution is started with the JSON text:

{ "numbers": [3, 4] }

The Add state receives the JSON text and passes it to the Lambda function, which returns the result of the calculation to the state. The state then returns this value in its output:

{ "result": 7 }

Since Add is also the final state in the state machine, this value is returned as the state machine's output. If the final state returns no output, then the state machine returns an empty object ({}).

Filters

Some states, such as Task, have InputPath, ResultPath, and OutputPath fields. The values of these fields are path.

The InputPath field selects a portion of the state's input to be passed to the state's processing logic (an activity, Lambda function, or so on). If the InputPath field is omitted, the entire state input is selected by default ($). If it is null, an empty object {} is passed.

The ResultPath field selects a portion of the state's input to be overwritten by, or added to, with result data from the state's processing logic. The ResultPath field is optional and, if omitted, defaults to $, which overwrites the entire input. However, before the input is sent as the state's output, a portion can be selected with the OutputPath field.

The OutputPath field is also optional and, if omitted, defaults to $, which selects the entire input (as modified by the ResultPath), sending it as the state's output.

The ResultPath field's value can be null, which causes any output from your state's processing logic to be discarded instead of being added to the state's input. In this scenario, the state's output is identical to the state's input, given the default value for the OutputPath field.

If the OutputPath field's value is null, and empty object {} is sent as the state's output.

Here is an example. Given the following ResultPath field in a state that outputs the sum of its input values:

"InputPath": "$.numbers",
"ResultPath": "$.sum"
"OutputPath": "$"

With the following state input data:

{
  "numbers": [3, 4]
}

The state output data will have the following structure and values:

{
  "numbers": [3, 4],
  "sum": 7
}

Let's change the OutputPath in our example slightly...

"InputPath": "$.numbers",
"ResultPath": "$.sum"
"OutputPath": "$.sum"

As before, with the following state input data:

{ "numbers": [3, 4] }

However, now the state output data is 7:

{ 7 }

By using the InputPath and ResultPath fields in this way, you can design separation between the names of data members in your state machine data, and the functions that process it.