Orchestration examples with Step Functions

All work in your Step Functions state machine is done by Tasks. A Task performs work by using an activity, a Lambda function, or by passing parameters to the API actions of other Supported Amazon Service Integrations for Step Functions.

Configuring a Lambda function as a task

Step Functions can invoke Lambda functions directly from a Task state in an Amazon States Language definition.

...
        "MyStateName":{
          "Type":"Task",         
          "Resource":"arn:aws-cn:lambda:us-west-2:01234567890:function:my_lambda_function",         
          "End":true 
      ...
      

You can create a Task state that invokes your Lambda function with the input to the state machine or any JSON document.

{
  "max-depth": 10,
  "current-depth": 0,
  "error-rate": 0.05
}

Configuring a state machine as an event source

You can create a Step Functions state machine that invokes a Lambda function. The following example shows a Task state that invokes version 1 of a function named my-function with an event payload that has three keys. When the function returns a successful response, the state machine continues to the next task.

...
"Invoke": {
  "Type": "Task",
  "Resource": "arn:aws-cn:states:::lambda:invoke",
  "Parameters": {
    "FunctionName": "arn:aws-cn:lambda:us-east-2:123456789012:function:my-function:1",
    "Payload": {
      "max-depth": 10,
      "current-depth": 0,
      "error-rate": 0.05
    }
  },
  "Next": "NEXT_STATE",
  "TimeoutSeconds": 25
}

The FunctionName and Payload parameters map to parameters in the Invoke API operation. In addition to these, you can also specify the InvocationType and ClientContext parameters. For example, to invoke the function asynchronously and continue to the next state without waiting for a result, you can set InvocationType to Event:

"InvocationType": "Event"

Instead of hard-coding the event payload in the state machine definition, you can use the input from the state machine execution. The following example uses the input specified when you run the state machine as the event payload:

"Payload.$": "$"

You can also invoke a function asynchronously and wait for it to make a callback with the Amazon SDK. To do this, set the state's resource to arn:aws-cn:states:::lambda:invoke.waitForTaskToken.

For more information, see Invoke Lambda with Step Functions in the Amazon Step Functions Developer Guide.

Handling function and service errors

When your function or the Lambda service returns an error, you can retry the invocation or continue to a different state based on the error type.

The following example shows an invoke task that retries on 5XX series Lambda API exceptions (ServiceException), throttles (TooManyRequestsException), runtime errors (Lambda.Unknown), and a function-defined error named function.MaxDepthError. It also catches an error named function.DoublesRolledError and continues to a state named CaughtException when it occurs.

...
"Invoke": {
    "Type": "Task",
    "Resource": "arn:aws-cn:states:::lambda:invoke",
    "Retry": [
      {
        "ErrorEquals": [ 
            "function.MaxDepthError",
            "Lambda.TooManyRequestsException",
            "Lambda.ServiceException",
            "Lambda.Unknown"
          ],
        "MaxAttempts": 5
      }
    ],
    "Catch": [
      {
        "ErrorEquals": [ "function.DoublesRolledError" ],
        "Next": "CaughtException"
      }
    ],
    "Parameters": {
      "FunctionName": "arn:aws-cn:lambda:us-east-2:123456789012:function:my-function:1",
      ...

To catch or retry function errors, create a custom error type. The name of the error type must match the errorType in the formatted error response that Lambda returns when you throw an error.

For more information on error handling in Step Functions, see Handling Error Conditions Using a Step Functions State Machine in the Amazon Step Functions Developer Guide.

Amazon CloudFormation and Amazon SAM

You can define state machines using a Amazon CloudFormation template with Amazon Serverless Application Model (Amazon SAM). Using Amazon SAM, you can define the state machine inline in the template or in a separate file. The following example shows a state machine that invokes a Lambda function that handles errors. It refers to a function resource defined in the same template (not shown).

AWSTemplateFormatVersion: '2010-09-09'
Transform: 'AWS::Serverless-2016-10-31'
Description: An Amazon Lambda application that uses AWS Step Functions.
Resources:
  statemachine:
    Type: AWS::Serverless::StateMachine
    Properties:
      DefinitionSubstitutions:
        FunctionArn: !GetAtt function.Arn
        Payload: |
          {
            "max-depth": 5,
            "current-depth": 0,
            "error-rate": 0.2
          }
      Definition:
        StartAt: Invoke
        States:
          Invoke:
            Type: Task
            Resource: arn:aws-cn:states:::lambda:invoke
            Parameters:
              FunctionName: "${FunctionArn}"
              Payload: "${Payload}"
              InvocationType: Event
            Retry:
            - ErrorEquals:
              - function.MaxDepthError
              - function.MaxDepthError
              - Lambda.TooManyRequestsException
              - Lambda.ServiceException
              - Lambda.Unknown
              IntervalSeconds: 1
              MaxAttempts: 5
            Catch:
            - ErrorEquals:
              - function.DoublesRolledError
              Next: CaughtException
            - ErrorEquals:
              - States.ALL
              Next: UncaughtException
            Next: Success
          CaughtException:
            Type: Pass
            Result: The function returned an error.
            End: true
          UncaughtException:
            Type: Pass
            Result: Invocation failed.
            End: true
          Success:
            Type: Pass
            Result: Invocation succeeded!
            End: true
      Events:
        scheduled:
          Type: Schedule
          Properties:
            Description: Run every minute
            Schedule: rate(1 minute)
      Type: STANDARD
      Policies:
        - AWSLambdaRole
      ...

This creates a state machine with the following structure:

For more information, see AWS::Serverless::StateMachine in the Amazon Serverless Application Model Developer Guide.