AWS Step Functions
Developer Guide

Creating a Lambda State Machine

In this tutorial you'll create an AWS Step Functions state machine that uses a AWS Lambda function to implement a Task state. A Task state is a simple state that performs a single unit of work.

Lambda is well-suited for implementing Task states, because Lambda functions are stateless (they have a predicable input-output relationship), easy to write, and don't require deploying code to a server instance. You can write code in the AWS Management Console or your favorite editor, and AWS handles the details of providing a computing environment for your function and running it.

Step 1: Creating an IAM Role for Lambda

Both Lambda and Step Functions can execute code and access AWS resources (for example, data stored in Amazon S3 buckets). To maintain security, you must grant Lambda and Step Functions access to these resources.

In the Getting Started tutorial, this is done automatically for Step Functions: An IAM role is created when you create the state machine. However, Lambda requires you to assign an IAM role when you create a Lambda function in the same way Step Functions requires you to assign an IAM role when you create a state machine.

To create a role for Lambda

  1. Log in to the IAM console and choose Roles, Create role.

  2. On the Select type of trusted entity page, under AWS service, select Lambda from the list and then choose Next: Permissions.


    The role is automatically provided with a trust relationship that allows Lambda to use the role.

  3. On the Attach permissions policy page, choose Next: Review.

  4. On the Review page, type MyLambdaRole for Role Name and then choose Create role.

The IAM role appears in the list of roles.

Step 2: Creating a Lambda Function

Your Lambda function receives input (a name) and returns a greeting that includes the input value.

To create the Lambda function


Ensure that your Lambda function is under the same AWS account as your state machine.

  1. Log in to the Lambda console and choose Create a function.

  2. In the Blueprints section, choose Author from scratch.

  3. In the Basic information section, configure your Lambda function:

    1. For Name, type HelloFunction.

    2. For Role, select Choose an existing role.

    3. For Existing role, select the Lambda role that you created earlier.


      If the IAM role that you created doesn't appear in the list, the role might still need a few minutes to propagate to Lambda.

    4. Choose Create function.

      When your Lambda function is created, note its Amazon Resource Name (ARN) in the upper-right corner of the page. For example:

  4. Copy the following code for the Lambda function into the Configuration section of the HelloFunction page:

    exports.handler = (event, context, callback) => { callback(null, "Hello, " + event.who + "!"); };

    This code assembles a greeting using the who field of the input data, which is provided by the event object passed into your function. You will add input data for this function later, when you start a new execution. The callback method returns the assembled greeting from your function.

  5. Choose Save and Test.

Step 3: Testing the Lambda Function

Test your Lambda function to see it in operation.

To test your Lambda function

  1. On the Configure test event dialog box, type HelloFunction for Event name.

  2. Replace the example data with the following:

    { "who": "AWS Step Functions" }

    The "who" entry corresponds to the event.who field in your Lambda function, completing the greeting. You will use the same input data when running the function as a Step Functions task.

  3. Choose Create.

  4. On the HelloFunction page, Test your Lambda function using the new data.

    The results of the test are displayed at the top of the page.

Step 4: Creating a State Machine

Use the Step Functions console to create a state machine with a Task state. Add a reference to your Lambda function in the Task state. The Lambda function is invoked when an execution of the state machine reaches the Task state.

To create the state machine

  1. Log in to the Step Functions console and choose Get Started.

  2. On the Create a state machine page, Name your state machine, for example LambdaStateMachine.


    State machine names must be 1-80 characters in length, must be unique for your account and region, and must not contain any of the following:

    • Whitespace

    • Whitespace characters (? *)

    • Bracket characters (< > { } [ ])

    • Special characters (: ; , \ | ^ ~ $ # % & ` ")

    • Control characters (\\u0000 - \\u001f or \\u007f - \\u009f).

  3. Choose the Hello World blueprint.

  4. In the Code pane, add the following state machine definition using the ARN of the Lambda function that you created earlier, for example:

    { "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function", "StartAt": "HelloWorld", "States": { "HelloWorld": { "Type": "Task", "Resource": "arn:aws:lambda:us-east-1:123456789012:function:HelloFunction", "End": true } } }

    This is a description of your state machine using the Amazon States Language. It defines a single Task state named HelloWorld. For more information, see State Machine Structure.

  5. Use the graph in the Visual Workflow pane to check that your Amazon States Language code describes your state machine correctly.

    If you don't see the graph, choose 
    in the Visual Workflow pane.

  6. Choose Create State Machine.

    The IAM role for your state machine executions dialog box is displayed. Step Functions creates and selects an IAM role automatically.


    If you delete the IAM role that Step Functions creates, Step Functions can't recreate it later. Similarly, if you modify the role (for example, by removing Step Functions from the principals in the IAM policy), Step Functions can't restore its original settings later. For more information about creating an IAM role manually, see Creating IAM Roles for AWS Step Functions.

  7. Choose OK.

    The state machine is created and an acknowledgement page is displayed.

Step 5: Starting a New Execution

After you create your state machine, you can start an execution.

To start a new execution

  1. On the LambdaStateMachine page, choose New execution.

    The New execution page is displayed.

  2. (Optional) To help identify your execution, you can enter an ID for it. To specify the ID, use the Enter your execution id here text box. If you don't enter an ID, Step Functions generates a unique ID automatically.

  3. In the execution input area, replace the example data with the following:

    { "who" : "AWS Step Functions" }

    "who" is the key name that your Lambda function uses to get the name of the person to greet.

  4. Choose Start Execution.

    A new execution of your state machine starts, and a new page showing your running execution is displayed.

  5. (Optional) In the Execution Details section, choose the Info tab to view the Execution Status and the Started and Closed timestamps.

  6. To view the results of your execution, choose the Output tab.