Step Functions for workflows in AWS - Commands & Configuration

Introduction

Sometimes you want to run tasks one after another or in a specific order automatically. AWS Step Functions help you create these task sequences so your app can do many things step-by-step without you doing it manually.

When you want to automate a process that has multiple steps, like processing an order and then sending a confirmation email.

When you need to run tasks in order and handle errors if something goes wrong.

When you want to connect different AWS services to work together smoothly.

When you want to see the progress of a multi-step job in one place.

When you want to retry a task automatically if it fails.

Config File - state_machine.json

state_machine.json

{
  "Comment": "A simple AWS Step Functions state machine example",
  "StartAt": "HelloWorld",
  "States": {
    "HelloWorld": {
      "Type": "Pass",
      "Result": "Hello, Step Functions!",
      "End": true
    }
  }
}

This JSON file defines a simple Step Functions workflow.

StartAt tells which step to start with.

States lists all steps. Here, there is one step called HelloWorld.

Type: Pass means this step just passes data through without doing work.

Result is the output of this step.

End: true means this is the last step.

Commands

This command creates a new Step Functions state machine named MyStateMachine using the JSON definition file. The role ARN gives permission to run the workflow.

Terminal

aws stepfunctions create-state-machine --name MyStateMachine --role-arn arn:aws:iam::123456789012:role/service-role/StepFunctions-MyRole --definition file://state_machine.json --region us-east-1

Expected Output

{

    "stateMachineArn": "arn:aws:states:us-east-1:123456789012:stateMachine:MyStateMachine"

}

→

--name - Sets the name of the state machine.

→

--role-arn - Specifies the IAM role that Step Functions uses to run the workflow.

→

--definition - Points to the JSON file that defines the workflow steps.

This command starts running the workflow named MyStateMachine. The execution is given a unique name 'execution1' to track it.

Terminal

aws stepfunctions start-execution --state-machine-arn arn:aws:states:us-east-1:123456789012:stateMachine:MyStateMachine --name execution1 --region us-east-1

Expected Output

{

    "executionArn": "arn:aws:states:us-east-1:123456789012:execution:MyStateMachine:execution1",

    "startDate": 1686000000.0

}

→

--state-machine-arn - Specifies which state machine to run.

→

--name - Gives a unique name to this run of the workflow.

This command checks the status and details of the running or finished workflow execution named 'execution1'.

Terminal

aws stepfunctions describe-execution --execution-arn arn:aws:states:us-east-1:123456789012:execution:MyStateMachine:execution1 --region us-east-1

Expected Output

{

    "executionArn": "arn:aws:states:us-east-1:123456789012:execution:MyStateMachine:execution1",

    "stateMachineArn": "arn:aws:states:us-east-1:123456789012:stateMachine:MyStateMachine",

    "status": "SUCCEEDED",

    "startDate": 1686000000.0,

    "stopDate": 1686000001.0,

    "output": "\"Hello, Step Functions!\""

}

→

--execution-arn - Specifies which execution to describe.

Key Concept

If you remember nothing else from this pattern, remember: Step Functions let you automate and track multi-step tasks easily by defining each step and how they connect.

Common Mistakes

Using an IAM role ARN that does not have permission for Step Functions.

The state machine creation or execution will fail due to lack of permissions.

Create or use an IAM role with the AWS managed policy 'AWSStepFunctionsFullAccess' or a custom role with needed permissions.

Forgetting to use 'file://' prefix when specifying the JSON definition file.

The CLI will treat the argument as a string instead of a file path and fail to load the workflow definition.

Always use 'file://state_machine.json' to tell AWS CLI to read the file content.

Starting an execution with a name that already exists.

Step Functions requires unique execution names; duplicate names cause errors.

Use a unique name for each execution or omit the --name flag to let AWS generate one.

Summary

Create a state machine with a JSON file that defines the workflow steps.

Start an execution of the state machine to run the workflow.

Check the execution status and output to see the results.