Step Functions and Orchestration

Topics Covered

State Machines and States

Amazon States Language

State types

Executions

Data flow between states

Payload limits

Why model a process this way

Many business processes are a sequence of steps that must happen in order, with decisions, waits, retries and parallel branches: an order is validated, payment is authorised, stock is reserved, shipping is booked, and the customer is notified, with each step able to fail in its own way. Writing that logic inside one Lambda function or a chain of functions that call each other works for simple cases, but it hides the process in code, loses track of where each order is, and handles failure inconsistently. AWS Step Functions models such processes as state machines that it executes, records and retries on the team's behalf.

Amazon States Language

A Step Functions state machine is defined in Amazon States Language, a JSON document listing states and the transitions between them. Each state has a type, and most have a Next field naming the following state or an End flag. The definition is versioned with the application, usually generated by infrastructure as code such as the CDK, and the console's Workflow Studio draws it as a graph. Because the definition is data rather than code, the process is visible: anyone can open the console and see the steps, the branches and which state each running execution is in.

Writing definitions by hand in JSON is error prone, so most teams generate them. The CDK offers typed constructs for each state and integration, which catch mistakes such as a misspelled state name at build time, and other tools such as the Serverless Framework and Terraform accept definitions as templates with substitutions for function ARNs and table names. Whatever the tool, the definition should be validated in continuous integration, for example with the ValidateStateMachineDefinition API, which reports syntax errors and common problems before deployment rather than when the first execution reaches a broken state.

State types

Task states do work, by invoking a Lambda function, calling an AWS service API directly, running an ECS task or waiting for an external system. Choice states branch on values in the input, such as routing orders over a threshold to manual review. Wait states pause for a fixed time or until a timestamp, without paying for compute while waiting. Parallel states run several branches at once and continue when all finish. Map states run the same steps for each item in an array. Pass states shape data, and Succeed and Fail states end an execution with a clear outcome.

Orders over $5,000 branched to manual review, and the rest ran payment and stock reservation in parallel before shipping.

Choice states deserve care because they encode business rules. Each rule compares a field with a value, and the first matching rule wins, so the order of rules matters, and a Default branch should always exist so that unexpected input does not fail the execution with a States.NoChoiceMatched error. When the rules grow complex, such as pricing tiers or eligibility checks with many conditions, moving the decision into a small Lambda function or a rules table, and having the Choice state branch on its single result, keeps the definition readable and the rules testable in isolation.

Executions

Each run of a state machine is an execution, started with an input JSON document and identified by a name that must be unique within the state machine for a period, which makes starting an execution idempotent when the name is derived from a business key such as the order ID. The execution history records every state entered and exited, with inputs, outputs, errors and timestamps, which is invaluable when investigating why one order failed. Standard workflows keep this history for 90 days, and it can be queried through the console or API and sent to CloudWatch Logs.

Execution names have their own rules. Names must be unique among executions of a state machine for the retention period of their history, which is 90 days for standard workflows, and are limited to 80 characters from a restricted set. A name such as order-81244 makes executions easy to find and gives free deduplication, since a second StartExecution with the same name and input returns the existing execution rather than creating another. With different input it fails, which signals a genuine conflict rather than a harmless retry.

Data flow between states

Each state receives a JSON input and produces a JSON output, which becomes the next state's input. Fields such as InputPath, Parameters, ResultSelector, ResultPath and OutputPath select and reshape data, and newer definitions can use JSONata expressions and variables, which make transformations simpler and let later states read values set earlier without threading them through every output. Getting data flow right is one of the main learning curves of Step Functions: a misplaced ResultPath can overwrite the original input, so the next state no longer sees the order ID it needs.

Testing data flow is easier with the TestState API, which runs a single state with a given input and shows how each path and selector transforms it, without deploying the whole machine. Teams can write unit tests for tricky states, such as those that merge results from a Parallel branch, and catch mistakes before they appear in production executions. For whole workflows, Step Functions Local and mocked service integrations let tests run the definition against canned responses for each task, including errors, to check retry and catch paths.

Payload limits

The data passed between states is limited to 256 KB. Workflows that handle documents, images or large result sets must not pass them through state; instead they store the data in S3 or DynamoDB and pass a reference, the same claim check pattern used with queues and streams. Exceeding the limit fails the execution with a States.DataLimitExceeded error, which often appears only in production when an unusually large order or report arrives, so tests should include the largest realistic inputs, and states that may produce large outputs should write them to storage by design.

The aggregate step returned 410 KB and the execution failed. Writing the result to S3 and passing its key kept every state under 2 KB.

Payload size also affects cost and speed indirectly. Large payloads take longer to serialise between states, appear in full in execution history and logs, and in express workflows increase CloudWatch Logs ingestion charges. Keeping state small, with identifiers and the few fields each step needs, makes workflows faster, cheaper and easier to read in the console. It also avoids storing personal or sensitive data in execution history, where it is retained for 90 days and visible to anyone with permission to view executions.

Why model a process this way

The benefits of a state machine show up in operations more than in the first build. Retries and error handling are declared consistently rather than reimplemented in each function. Long waits, from minutes to a year, cost nothing in compute. Each execution has a visible state, so support staff can answer where an order is. Changes to the process are reviewed as changes to a definition that maps directly to the business flow. And because each step is small and independent, it can be tested, deployed and scaled separately, while Step Functions takes care of coordination.

The visibility pays off beyond engineering. Support teams can be given read only access to executions, or a small internal page that looks up an execution by order ID, and answer customer questions without paging an engineer. Product managers can see how many orders wait in manual review, and finance can confirm which refunds were issued. The state machine becomes a shared, accurate picture of a process that previously lived only in code and in the heads of the engineers who wrote it.

The process becomes visible

Model multi step processes as state machines so every execution has a recorded path, a current state and declared error handling. Name executions with a business key to make starts idempotent, and pass references to large data in S3 instead of the data itself.