AWS Step Functions: State Machine Design & ASL Guide

Step Functions orchestrates complex workflows across AWS services with built-in error handling, retries, and visual debugging — no coordination code in Lambda. This guide covers ASL syntax, all state types, error handling patterns, and workflow design best practices.

ASL State Machine: Complete Example

{
  "Comment": "Order processing workflow",
  "StartAt": "ValidateOrder",
  "States": {
    "ValidateOrder": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:us-east-1:123456789:function:ValidateOrder",
      "Retry": [
        {
          "ErrorEquals": ["Lambda.ServiceException", "Lambda.AWSLambdaException"],
          "IntervalSeconds": 2,
          "MaxAttempts": 3,
          "BackoffRate": 2
        }
      ],
      "Catch": [
        {
          "ErrorEquals": ["ValidationError"],
          "Next": "SendRejectionEmail",
          "ResultPath": "$.error"
        }
      ],
      "Next": "ProcessPayment"
    },
    "ProcessPayment": {
      "Type": "Task",
      "Resource": "arn:aws:lambda:us-east-1:123456789:function:ProcessPayment",
      "TimeoutSeconds": 30,
      "Next": "CheckPaymentStatus"
    },
    "CheckPaymentStatus": {
      "Type": "Choice",
      "Choices": [
        { "Variable": "$.paymentStatus", "StringEquals": "SUCCESS", "Next": "FulfillOrder" },
        { "Variable": "$.paymentStatus", "StringEquals": "PENDING", "Next": "WaitForPayment" }
      ],
      "Default": "SendFailureNotification"
    },
    "WaitForPayment": {
      "Type": "Wait",
      "Seconds": 300,
      "Next": "CheckPaymentStatus"
    },
    "FulfillOrder": {
      "Type": "Parallel",
      "Branches": [
        {
          "StartAt": "UpdateInventory",
          "States": {
            "UpdateInventory": {
              "Type": "Task",
              "Resource": "arn:aws:states:::dynamodb:updateItem",
              "Parameters": {
                "TableName": "Inventory",
                "Key": { "productId": { "S.$": "$.productId" } },
                "UpdateExpression": "SET quantity = quantity - :qty",
                "ExpressionAttributeValues": { ":qty": { "N.$": "$.quantity" } }
              },
              "End": true
            }
          }
        },
        {
          "StartAt": "SendConfirmationEmail",
          "States": {
            "SendConfirmationEmail": {
              "Type": "Task",
              "Resource": "arn:aws:states:::sns:publish",
              "Parameters": {
                "TopicArn": "arn:aws:sns:us-east-1:123456789:OrderConfirmations",
                "Message.$": "States.Format('Order {} confirmed!', $.orderId)"
              },
              "End": true
            }
          }
        }
      ],
      "End": true
    },
    "SendRejectionEmail": { "Type": "Succeed" },
    "SendFailureNotification": { "Type": "Fail", "Error": "PaymentFailed" }
  }
}

Standard vs Express Workflow Comparison

Map State: Process Arrays in Parallel

// Map state processes each item in an array concurrently
{
  "ProcessOrders": {
    "Type": "Map",
    "ItemsPath": "$.orders",        // Array to iterate
    "MaxConcurrency": 10,           // Max parallel branches
    "Parameters": {
      "orderId.$": "$$.Map.Item.Value.id",
      "amount.$": "$$.Map.Item.Value.amount"
    },
    "Iterator": {
      "StartAt": "ProcessSingleOrder",
      "States": {
        "ProcessSingleOrder": {
          "Type": "Task",
          "Resource": "arn:aws:lambda:us-east-1:123456789:function:ProcessOrder",
          "End": true
        }
      }
    },
    "ResultPath": "$.processedOrders",
    "Next": "SendSummary"
  }
}

// Use case: process 100 orders in batches of 10 concurrently
// Much faster than sequential processing
// MaxConcurrency: 0 = unbounded parallelism