StepFunctions

The StepFunctions component lets you add state machines to your app. using AWS Step Functions.

Minimal example

const foo = sst.aws.StepFunctions.pass({ name: "Foo" });
const bar = sst.aws.StepFunctions.succeed({ name: "Bar" });

new sst.aws.StepFunctions("MyStateMachine", {
  definition: foo.next(bar),
});

Invoking a Lambda function

Create a function and invoke it from a state machine.

const myFunction = new sst.aws.Function("MyFunction", {
  handler: "src/index.handler",
});

const invoke = sst.aws.StepFunctions.lambdaInvoke({
  name: "InvokeMyFunction",
  function: myFunction,
});
const done = sst.aws.StepFunctions.succeed({ name: "Done" });

new sst.aws.StepFunctions("MyStateMachine", {
  definition: invoke.next(done),
});

Use express workflow

const foo = sst.aws.StepFunctions.pass({ name: "Foo" });
const bar = sst.aws.StepFunctions.succeed({ name: "Bar" });

new sst.aws.StepFunctions("MyStateMachine", {
  type: "express",
  definition: foo.next(bar),
});

Constructor

new StepFunctions(name, args, opts?)

Parameters

name string
args StepFunctionsArgs
opts? ComponentResourceOptions

StepFunctionsArgs

definition

Type State

The definition of the state machine. It takes a chain of State objects.

const foo = sst.aws.StepFunctions.pass({ name: "Foo" });
const bar = sst.aws.StepFunctions.succeed({ name: "Bar" });

new sst.aws.StepFunctions("MyStateMachine", {
  definition: foo.next(bar),
});

logging?

Type Input<false | Object>

includeData?
level?
retention?

Default {retention: “1 month”, level: “error”, includeData: false}

Configure the execution logs in CloudWatch. Or pass in false to disable writing logs.

{
  logging: false
}

logging.includeData?

Type Input<boolean>

Default false

Specify whether execution data is included in the logs.

{
  logging: {
    includeData: true
  }
}

logging.level?

Type Input<“all” | “error” | “fatal”>

Default “error”

Specify the category of execution events that are logged.

Read more about the Step Functions log level

{
  logging: {
    level: "all"
  }
}

Default 1 month

The duration the logs are kept in CloudWatch.

{
  logging: {
    retention: "forever"
  }
}

transform?

Type Object

logGroup?
stateMachine?

Transform how this component creates its underlying resources.

transform.logGroup?

Type LogGroupArgs | (args: LogGroupArgs, opts: ComponentResourceOptions, name: string) => void

Transform the Step Functions LogGroup resource.

transform.stateMachine?

Type StateMachineArgs | (args: StateMachineArgs, opts: ComponentResourceOptions, name: string) => void

Transform the Step Functions StateMachine resource.

type?

Type Input<“standard” | “express”>

Default “standard”

The type of state machine to create.

{
  type: "express"
}

Properties

arn

Type Output<string>

The State Machine ARN.

nodes

Type Object

stateMachine

The underlying resources this component creates.

nodes.stateMachine

Type StateMachine

The Step Function State Machine resource.

SDK

Use the SDK in your runtime to interact with your infrastructure.

Methods

static choice

StepFunctions.choice(args)

Parameters

args ChoiceArgs
The arguments for creating a Choice state.

Returns Choice

Create a Choice state.

A Choice state is used to conditionally continue to different states based on the matched condition.

const processPayment = sst.aws.StepFunctions.choice({ name: "ProcessPayment" });
const makePayment = sst.aws.StepFunctions.lambdaInvoke({ name: "MakePayment" });
const sendReceipt = sst.aws.StepFunctions.lambdaInvoke({ name: "SendReceipt" });
const failure = sst.aws.StepFunctions.fail({ name: "Failure" });

processPayment.when("{% $states.input.status === 'unpaid' %}", makePayment);
processPayment.when("{% $states.input.status === 'paid' %}", sendReceipt);
processPayment.otherwise(failure);

static ecsRunTask

StepFunctions.ecsRunTask(args)

Parameters

args EcsRunTaskArgs
The arguments for creating an ECS Run Task task.

Returns Task

Create a Task state running an ECS task. Learn more about running an ECS task - https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html

const myCluster = new sst.aws.Cluster("MyCluster");
const myTask = new sst.aws.Task("MyTask", { cluster: myCluster });

sst.aws.StepFunctions.ecsRunTask({
  name: "RunTask",
  task: myTask,
});

static eventBridgePutEvents

StepFunctions.eventBridgePutEvents(args)

Parameters

args EventBridgePutEventsArgs
The arguments for creating an EventBridge Put Events task.

Returns Task

Create a Task state sending custom events to one or more EventBridge buses. Learn more about sending custom events to EventBridge - https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutEvents.html

const myBus = new sst.aws.EventBus("MyBus");

sst.aws.StepFunctions.eventBridgePutEvents({
  name: "EventBridgePutEvents",
  events: [
    {
      bus: myBus,
      source: "my-source",
    },
  ],
});

static fail

StepFunctions.fail(args)

Parameters

args FailArgs
The arguments for creating a Fail state.

Returns Fail

Create a Fail state.

A Fail state is used to fail the execution of a state machine.

sst.aws.StepFunctions.fail({ name: "Failure" });

static lambdaInvoke

StepFunctions.lambdaInvoke(args)

Parameters

args LambdaInvokeArgs
The arguments for creating a Lambda Invoke task.

Returns Task

Create a Task state invoking a Lambda function. Learn more about invoking a Lambda function - https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html

const myLambda = new sst.aws.Function("MyLambda", {
  handler: "src/index.handler",
});

sst.aws.StepFunctions.lambdaInvoke({
  name: "LambdaInvoke",
  function: myLambda,
});

static map

StepFunctions.map(args)

Parameters

args MapArgs
The arguments for creating a Map state.

Returns Map

Create a Map state.

A Map state is used to iterate over a list of items and execute a task for each item.

const processor = sst.aws.StepFunctions.lambdaInvoke({
  name: "Processor",
  function: "src/processor.handler",
});

sst.aws.StepFunctions.map({
  name: "Map",
  items: "{% $states.input.items %}",
  processor: processor,
});

static parallel

StepFunctions.parallel(args)

Parameters

args ParallelArgs
The arguments for creating a Parallel state.

Returns Parallel

Create a Parallel state.

A Parallel state is used to execute multiple branches of states in parallel.

const processorA = sst.aws.StepFunctions.lambdaInvoke({
  name: "ProcessorA",
  function: "src/processorA.handler",
});

const processorB = sst.aws.StepFunctions.lambdaInvoke({
  name: "ProcessorB",
  function: "src/processorB.handler",
});

const parallel = sst.aws.StepFunctions.parallel({ name: "Parallel" });
parallel.brance(processorA);
parallel.brance(processorB);

static pass

StepFunctions.pass(args)

Parameters

args PassArgs
The arguments for creating a Pass state.

Returns Pass

Create a Pass state.

A Pass state is used to pass the input to the next state. It’s useful for transforming the input before passing it to the next state.

sst.aws.StepFunctions.pass({
  name: "Pass",
  output: "{% $states.input.message %}",
});

static snsPublish

StepFunctions.snsPublish(args)

Parameters

args SnsPublishArgs
The arguments for creating an SNS Publish task.

Returns Task

Create a Task state publishing a message to an SNS topic. Learn more about publishing a message to an SNS topic - https://docs.aws.amazon.com/sns/latest/api/API_Publish.html

const myTopic = new sst.aws.SnsTopic("MyTopic");

sst.aws.StepFunctions.snsPublish({
  name: "SnsPublish",
  topic: myTopic,
  message: "Hello, world!",
});

static sqsSendMessage

StepFunctions.sqsSendMessage(args)

Parameters

args SqsSendMessageArgs
The arguments for creating an SQS Send Message task.

Returns Task

Create a Task state sending a message to an SQS queue. Learn more about sending messages to an SQS queue - https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessage.html

const myQueue = new sst.aws.Queue("MyQueue");

sst.aws.StepFunctions.sqsSendMessage({
  name: "SqsSendMessage",
  queue: myQueue,
  messageBody: "Hello, world!",
});

static succeed

StepFunctions.succeed(args)

Parameters

args SucceedArgs
The arguments for creating a Succeed state.

Returns Succeed

Create a Succeed state.

A Succeed state is used to indicate that the execution of a state machine has succeeded.

sst.aws.StepFunctions.succeed({ name: "Succeed" });

static task

StepFunctions.task(args)

Parameters

args TaskArgs
The arguments for creating a Task state.

Returns Task

Create a Task state.

A Task state is used to make calls to AWS resources.

For common tasks, you should use the convenience methods. For example,

use sst.aws.StepFunctions.lambdaInvoke to invoke a Lambda function
use sst.aws.StepFunctions.ecsRunTask to run an ECS task
use sst.aws.StepFunctions.eventBridgePutEvents to send custom events to EventBridge

Create a Task state that starts an AWS CodeBuild build.

sst.aws.StepFunctions.task({
  name: "Task",
  resource: "arn:aws:states:::codebuild:startBuild",
  arguments: {
    projectName: "my-codebuild-project",
  },
  permissions: [
    {
      actions: ["codebuild:StartBuild"],
      resources: ["*"],
    },
  ],
});

static wait

StepFunctions.wait(args)

Parameters

args WaitArgs
The arguments for creating a Wait state.

Returns Wait

Create a Wait state.

A Wait state is used to wait for a specific amount of time before continuing to the next state.

Wait for 10 seconds before continuing to the next state.

sst.aws.StepFunctions.wait({
  name: "Wait",
  time: 10,
});

Alternatively, you can wait until a specific timestamp.

sst.aws.StepFunctions.wait({
  name: "Wait",
  timestamp: "2026-01-01T00:00:00Z",
});