Serverless AWS Ruby Step Functions Express

This is an example of using AWS Step Functions Express Workflow Type. It uses AWS Lambda, DynamoDB, Amazon SES, API Gateway and flows from Step Functions.

Diagram

It's a simple workflow, it adds the user to the database (DynamoDB) and if the save is successful, we send an email notification (AWS Lambda + Amazon SES). We also have error handling.

Setup

npm install to install all needed packages.

Deployment

In order to deploy the service run:

sls deploy

for deploying with a specific profile (located in ~/.aws/credentials) you can simply use the command:

AWS_PROFILE=YOUR_PROFILE_NAME sls deploy

for deploying to the specific stage, let's say staging do:

sls deploy --stage staging

The expected result should be similar to:

Packaging service...
Excluding development dependencies...
Clearing previous build ruby layer build
[ '4.0' ]
Installing gem using local bundler
Zipping the gemfiles to aws-ruby-step-functions-express/.serverless/ruby_layer/gemLayer.zip
Configuring Layer and GEM_PATH to the functions
✓ State machine "myStateMachine" definition is valid
Uploading CloudFormation file to S3...
Uploading artifacts...
Uploading service aws-ruby-step-functions-express.zip file to S3 (971.85 KB)...
Uploading service gemLayer.zip file to S3 (553.86 KB)...
Validating template...
Updating Stack...
Checking Stack update progress...
................................
Stack update finished...
Service Information
service: aws-ruby-step-functions-express
stage: dev
region: eu-west-1
stack: aws-ruby-step-functions-express-dev
resources: 16
api keys:
  None
endpoints:
functions:
  send-email: aws-ruby-step-functions-express-dev-send-email
layers:
  gem: arn:aws:lambda:your-region:XXXXXXXXXXX:layer:aws-ruby-step-functions-express-dev-ruby-bundle:2
Serverless StepFunctions OutPuts
endpoints:
  POST - https://XXXXXXXXXXX.execute-api.your-region.amazonaws.com/dev/employees/add

Prerequistes

Make sure to validate sender and recipient emails within the Amazon SES (most likely for testing it, it will be one email):

Later on within serverless.yml edit in custom section, both sender and recipient.

Usage

There are two possible ways of invoking the example:

Via Api Gateway

After the deployment, grab the POST endpoint for this service. You can make a API call either by cURL or some tools like Postman.

Use payload like:

{ 
  "id": "The name of the employee",
  "jobTitle": "the name of the employee's position"
}

As a response you will get:

{
    "executionArn": "arn:aws:states:your-region:XXXXXXXXXXX:express:add-employee-and-send-email-state-machine-dev:e9fcce40-0642-48cb-bd9a-4d3d9cea7bcc:da5ee796-5944-4426-9ca2-410a5003ceee",
    "startDate": 1.62885382751E9
}

After it, you can then check the Dynamo database to see if a record has been created, and check the email.

Via AWS Dashboard

After the deployment, go to the AWS Dashboard, and enter Step Functions page. You will see a newly created state machine.

Open the state machine and click on Start Execution. You need to provide the input in the JSON schema.

Example:

{
 "id": "The name of the employee",
 "jobTitle": "the name of the employee's position"
}

Later on, simply start the excecution.

After it, you can then check the Dynamo database to see if a record has been created, and check the email.

Please keep in mind, that the Express workflow is different from the Standard workflow. Check the differences here. The main point here is the fact that you can't see all transitions between states. However, you can still use Workflow Studio.

Logs

By default, the logging is disabled. You can easily enabled it. The description is here.

Log retention

The log retention is setup for 30 days. To change it simply change the value of this attribute in serverless.yml file:

logRetentionInDays: 30

Advanced configuration

More options could be found in the plugin repository.

Structure

Serverless plugins

For this example, there are two serverless plugins used:

Ruby gems

Remove service

To remove the service do:

sls remove

And the stack will be removed from the AWS.