Step Functions Lab

AWS Step Functions makes it easy to coordinate the components of distributed applications and microservices using visual workflows.

In this lab, let's build a state machine to orchestrate a tax microservice.

Step 1 - Console

• Access the AWS Step Functions console at https://console.aws.amazon.com/states

  • Note the region you are in on the top right-hand corner.
  • For all additional services (CloudWatch, Lambda, etc.), ensure that you remain within this region

• If you're in the initial Splash Screen page, click on Get Started, if not just ignore this step

• Click on Create a state machine

• Under Step 1, for Name your state machine, enter ProductOrderPipeline-[YOUR_ORG_ID]

• Under Step 2, for Select a blueprint, choose Hello World

  • This is just to get some sample values and see it working immediately
  • We will modify this and create a more comprehensive state machine right after this

• You'll be prompted with a dialog box titled IAM role for your...

  • Choose the default execution role: StatesExecutionRole-us-east-2 (depending on which region you're in, this will be different)
  • Click OK
  • And you will have just created your first state machine

Let's now take this for a quick spin

• Click on New execution
• In the ensuing dialog box:
  • Under input add the following input JSON

{
  "Who": "Big Daddy!"
}

• Now click on Start Execution
• If all's good, you should see the execution succeed with a load of details
• Expand into each of the states and notice that our exact input is logged. Basically, this simple in-built Lambda function logs all of our input verbatim.

We have now successfully created and executed our very first (albeit, very simple) State Machine using AWS Step Functions and Lambda.

Step 2 - Create Lambda Functions

Let's take this a bit further and explore more complex state machines and how we'd go about building them. Before we go ahead though, we'll need a few Lambda functions to execute at various stages in the State machine. So let's create a few additional Lambda functions (these will serve as our rudimentary mico-services).

Once we're done creating our Lambda functions, we will create a state machine using Step Functions to orchestrate them.

Step 2.1 - Simple Tax Calculator

You can use the previously created SimpleTaxCalculator Lambda function here, no need to create a new one. But I'm adding the code here anyway.

Ensure that you pick the one that's yours: SimpleTaxCalculator-[YOUR_ORG_ID]

'use strict';

console.log('Loading tax calculator function...');

exports.handler = (event, context, callback) => {
    console.log('Received event: ', JSON.stringify(event, null, 2));
    
    try {
        console.log(`Product price: $${event.productPrice}`);
        console.log(`Tax rate: ${event.taxRate}%`);
        console.log(`Surcharge rate: ${event.surchargeRate}%`);
        
        let tax = event.productPrice * (event.taxRate / 100.00);
        let surcharge = event.productPrice * (event.surchargeRate / 100.00);
        let finalPrice = event.productPrice + tax + surcharge;

        console.log(`Final price with tax: $${finalPrice}`);
        
        let returnValue = {
            price: finalPrice
        }

        // On success, invoke the callback like so (2 arguments)
        // first one being null.
        callback(null, returnValue); // Return calculated tax
    }
    catch(e) {
        console.log(e);
        
        // On failure, invoke the callback like so (a single argument)
        // with a helpful error message.
        callback('ERROR: Something went wrong!');
    }
    
    console.log("Done calculating tax.");
};

Step 2.2 - California Tax Calculator

Follow the same steps as before to create a brand new Lambda function. Let's name this CaliforniaTaxCalculator-[YOUR_ORG_ID]. Just ensure that you add the following values to each of the fields in the Create Lambda screen.

Name: CaliforniaTaxCalculator
Runtime*: Node.js 6.10
Role*: Choose an existing role
Existing Role*: lambda_execution_role_YOUR_ORG_ID

Once created, edit the code inline and add this:

'use strict';

console.log('Loading California tax calculator function...');

const CA_STATE_TAX_RATE = 20;

exports.handler = (event, context, callback) => {
    console.log('Received event: ', JSON.stringify(event, null, 2));
    
    try {
        console.log(`Product price: $${event.price}`);
        console.log(`Calculating California state taxes at ${CA_STATE_TAX_RATE} rate`)

        let stateTax = event.price * (CA_STATE_TAX_RATE / 100.00);
        let finalPrice = event.price + stateTax;

        console.log(`Final price with tax: $${finalPrice}`);

        // On success, invoke the callback like so (2 arguments)
        // first one being null.
        callback(null, finalPrice); // Return calculated tax
    }
    catch(e) {
        console.log(e);
        
        // On failure, invoke the callback like so (a single argument)
        // with a helpful error message.
        callback('ERROR: Something went wrong!');
    }
    
    console.log("Done calculating California tax.");
};

• You can test this new Lambda function by clicking on Test and configuring a test event like so:

{
  "price": 20
}

• The result of this execution should be 24.0

Step 2.3 - Wisconsin Tax Calculator

Follow the same steps and add a WisconsinTaxCalculator-[YOUR_ORG_ID].

Use the same execution role as before. All of our Lambda functions will use the same execution role when running.

Edit the code inline and update it to the below:

'use strict';

console.log('Loading Wisconsin tax calculator function...');

const WI_STATE_TAX_RATE = 10; // cheaper than California

exports.handler = (event, context, callback) => {
    console.log('Received event: ', JSON.stringify(event, null, 2));
    
    try {
        console.log(`Product price: $${event.price}`);
        console.log(`Calculating Wisconsin state taxes at ${WI_STATE_TAX_RATE} rate`)

        let stateTax = event.price * (WI_STATE_TAX_RATE / 100.00);
        let finalPrice = event.price + stateTax;

        console.log(`Final price with tax: $${finalPrice}`);

        // On success, invoke the callback like so (2 arguments)
        // first one being null.
        callback(null, finalPrice); // Return calculated tax
    }
    catch(e) {
        console.log(e);
        
        // On failure, invoke the callback like so (a single argument)
        // with a helpful error message.
        callback('ERROR: Something went wrong!');
    }
    
    console.log("Done calculating Wisconsin tax.");
};

• Similarly, you can also test out this new function by creating and configuring an event like so (similar to previous step)

{
  "price": 20
}

Step 3 - Modify Step Function

Let's modify the new Step Function that we just created in Step 1 to use the Lambda functions that we just created.

• Go to the Step Functons console at https://us-east-2.console.aws.amazon.com/states/
• Click on the Step Function that you just created: ProductOrderPipeline-[YOUR_ORG_ID]
• Click on the State machine details tab
• Notice the two sections under Code and Visual Workflow
  • The Code here is JSON and describes the flow of the state machine
  • The Visual Workflow is a visual representation of this state machine
• From the top right-hand corner, click on Edit state machine
• Update the state machine Code to below:

{
  "Comment": "A more complicated tax calculator",
  "StartAt": "SimpleTaxCalculator",
  "States": {
    
    "SimpleTaxCalculator": {
      "Type": "Task",
      "Resource": "[MOVE CURSOR HERE TO SEE OPTIONS]",
      "Next": "ChooseState"
    },
    
    "ChooseState": {
      "Type" : "Choice",
      "Choices": [
        {
          "Variable": "$.state",
          "StringEquals": "CA",
          "Next": "CaliforniaTaxCalculator"
        },
        {
          "Variable": "$.state",
          "StringEquals": "WI",
          "Next": "WisconsinTaxCalculator"
        }
      ],
      "Default": "InvalidState"
    },

    "CaliforniaTaxCalculator": {
      "Type" : "Task",
      "Resource": "[MOVE CURSOR HERE TO SEE OPTIONS]",
      "End": true
    },

    "WisconsinTaxCalculator": {
      "Type" : "Task",
      "Resource": "[MOVE CURSOR HERE TO SEE OPTIONS]",
      "End": true
    },

    "InvalidState": {
      "Type": "Fail",
      "Error": "Cannot calculate state tax!",
      "Cause": "Invalid State!"
    }
  }
}

• Click Update
  • Notice how the Visual Workflow is automatically updated to reflect the changes in the state machine
• We now have 3 states that need to be backed by Lambda functions: SimpleTaxCalculator, CaliforniaTaxCalculator, and WisconsinTaxCalculator
• In the state machine's JSON, for each of the above lambda functions, find the Resource key
• Click so that your cursor is between the quotes and you'll see autocomplete options popup
• For each state, choose the appropriate Lambda resource ARN that you created
  • ARN - Amazon Resource Number. Everything you create in AWS, gets it's own unique ARN
• Now click on Update again
• Now click on Start Execution
• Configure the Input for the execution as

{
  "productPrice": 20,
  "taxRate": 10,
  "surchargeRate": 1
}

• And click on Start Execution to execute.

You will notice that the Step Function just failed. Can you figure out why?

Expand the result of each state and dig in...

Step 4 - Fix Step Function

Now that we've identified the issue, let's fix this by updating the original code for SimpleTaxCalculator.

• Go to the Lambda console
• Open the SimpleTaxCalculator-YOUR_ORG_ID function
• Update line 20 of the SimpleTaxCalculator code to

    state: "CA"

• The return value should now look like:

let returnValue = {
    price: finalPrice,
    state: "CA"
}

• Click Save
• Now click Test and test that the lambda function still works using the test event that we've already configured and used previously.

Step 5 - Execute State Machine Again

• Go back to the Step Functions console
• Choose the ProductOrderPipeline-YOUR_ORG_ID Step Function
• Click on New Execution
• Configure the Input for the execution as

{
  "productPrice": 20,
  "taxRate": 10,
  "surchargeRate": 1
}

• And click on Start Execution to execute

This time, notice that the state machine branched off to the correct states and finished executing successfully.

Extra Credits

For this, let's deliberately update the State Machine Code to something invalid and see what kind of errors we get.

To do this, go to the Step Functions console to edit the State Machine. Refer to the instructions in Step 3 for the full monty.

Update the Stat Machine Code to the below:

{
  "Comment": "A more complicated tax calculator",
  "StartAt": "SimpleTaxCalculator",
  "States": {
    
    "SimpleTaxCalculator": {
      "Type": "Task",
      "Resource": "[MOVE CURSOR HERE TO SEE OPTIONS]",
      "Next": "FirstState"
    },
    
    "ChooseState": {
      "Type" : "Choice",
      "Choices": [
        {
          "Variable": "$.state",
          "StringEquals": "CA",
          "Next": "CaliforniaTaxCalculator"
        },
        {
          "Variable": "$.state",
          "StringEquals": "WI",
          "Next": "WisconsinTaxCalculator"
        }
      ],
      "Default": "InvalidState"
    },

    "CaliforniaTaxCalculator": {
      "Type" : "Task",
      "Resource": "[MOVE CURSOR HERE TO SEE OPTIONS]",
      "End": "true"
    },

    "WisconsinTaxCalculator": {
      "Type" : "Task",
      "Resource": "[MOVE CURSOR HERE TO SEE OPTIONS]",
      "End": true
    },

    "InvalidState": {
      "Type": "Fail",
      "Error": "Cannot calculate state tax!",
      "Cause": "Invalid State!"
    }
  }
}

• Click on Update and notice the errors it spits out.

Can you figure out why?

States Language Reference

See here for more information on how to define StepFunctions using Amazon States Language