State Machines



A state machine allows you to design and automate business processes and data pipelines by composing compute resources (like functions and batch jobs) and other AWS services into a workflow. State machines manage failures, retries, parallelization, and observability, so you can focus on your business logic.

When to use them

  • ETL processes: State machines can ensure that long-running, multi-step ETL jobs execute in order and complete successfully.
  • Microservice orchestration: You can use state machines to combine multiple functions into a responsive, serverless application.

Defining states

You define state machines using the Amazon States Language. This example shows a simple order payment flow composed of Lambda functions:

resources:
  checkAndHoldProduct:
    type: function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: 'check-and-hold-product.ts'

  billCustomer:
    type: function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: 'bill-customer.ts'

  shipmentNotification:
    type: function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: 'shipment-notification.ts'

  eshopBuyingProcessStateMachine:
    type: 'state-machine'
    properties:
      definition:
        StartAt: 'checkAndHold'
        States:
          checkAndHold:
            Type: Task
            Resource: $ResourceParam('checkAndHoldProduct', 'arn')
            Next: bill
          bill:
            Type: Task
            Resource: $ResourceParam('billCustomer', 'arn')
            Next: notify
          notify:
            Type: Task
            Resource: $ResourceParam('shipmentNotification', 'arn')
            Next: succeed
          succeed:
            Type: Succeed

Retry example

This example shows a state machine that ties together a batch job and a function. The state machine is configured to retry only the upload step if it fails, since regenerating the report would be costly and unnecessary.

  • generateReport: A batch job that generates a report.
  • uploadReport: A function that uploads the report.
  • reportStateMachine: The state machine that orchestrates the workflow.
resources:
  uploadReport:
    type: function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: 'upload-report.ts'

  generateReport:
    type: 'batch-job'
    properties:
      container:
        packaging:
          type: stacktape-image-buildpack
          properties:
            entryfilePath: generate-report.ts
      resources:
        cpu: 2
        memory: 7800

  reportStateMachine:
    type: 'state-machine'
    properties:
      definition:
        StartAt: 'generate'
        States:
          generate:
            Type: Task
            Resource: 'arn:aws:states:::batch:submitJob.sync'
            Parameters:
              JobDefinition: $ResourceParam('generateReport', 'jobDefinitionArn')
              JobName: report-job
              JobQueue: $Param('SHARED_GLOBAL', 'BatchOnDemandJobQueue::Arn')
            Next: upload
          upload:
            Type: Task
            Resource: $Param('uploadReport', 'LambdaFunction::Arn')
            Next: succeed
            Retry:
              - ErrorEquals:
                  - 'State.ALL'
                IntervalSeconds: 10
          succeed:
            Type: Succeed

Referenceable parameters

The following parameters can be easily referenced using $ResourceParam directive directive.

To learn more about referencing parameters, refer to referencing parameters.

arn
  • Arn of the state machine.

  • Usage: $ResourceParam('<<resource-name>>', 'arn')
name
  • AWS (physical) name of the state machine.

  • Usage: $ResourceParam('<<resource-name>>', 'name')