serverless-step-functions

What is serverless-step-functions?

The serverless-step-functions npm package is a Serverless Framework plugin that allows you to define and deploy AWS Step Functions using the Serverless Framework. It simplifies the process of creating, managing, and deploying state machines, which are used to orchestrate complex workflows in AWS.

What are serverless-step-functions's main functionalities?

Define State Machines

This feature allows you to define state machines directly in your serverless.yml file. The code sample shows a simple state machine with a single Pass state that returns 'Hello, World!'.

{
  "service": "my-service",
  "frameworkVersion": "2",
  "plugins": ["serverless-step-functions"],
  "provider": {
    "name": "aws",
    "runtime": "nodejs14.x"
  },
  "stepFunctions": {
    "stateMachines": {
      "helloStateMachine": {
        "definition": {
          "Comment": "A Hello World example of the Amazon States Language using a Pass state",
          "StartAt": "HelloWorld",
          "States": {
            "HelloWorld": {
              "Type": "Pass",
              "Result": "Hello, World!",
              "End": true
            }
          }
        }
      }
    }
  }
}

Deploy State Machines

This feature allows you to deploy your state machines to AWS using the Serverless Framework. The code sample shows a script that can be added to your package.json to deploy your service and state machines.

{
  "scripts": {
    "deploy": "serverless deploy"
  }
}

Invoke State Machines

This feature allows you to invoke state machines from your Lambda functions. The code sample shows a Lambda function that can be triggered via an HTTP POST request to invoke a state machine.

{
  "functions": {
    "invokeStateMachine": {
      "handler": "handler.invokeStateMachine",
      "events": [
        {
          "http": {
            "path": "invoke",
            "method": "post"
          }
        }
      ]
    }
  }
}

Other packages similar to serverless-step-functions

aws-sdk

The aws-sdk package is the official AWS SDK for JavaScript. It provides a comprehensive set of tools for interacting with AWS services, including Step Functions. Unlike serverless-step-functions, which is a Serverless Framework plugin, aws-sdk is a general-purpose library that can be used in any Node.js application.

stepfunctions-local

The stepfunctions-local package allows you to run AWS Step Functions locally for development and testing purposes. It provides a local version of the Step Functions service, which can be useful for offline development. This package is more focused on local development, whereas serverless-step-functions is focused on deployment and management in AWS.

README

Serverless Step Functions

Serverless plugin for AWS Step Functions.

This plugin requires Serverless v1.4.0 or later.

Install

Run npm install in your Serverless project.

$ npm install --save serverless-step-functions

Add the plugin to your serverless.yml file

plugins:
  - serverless-step-functions

Setup

Specifies your statemachine definition using Amazon States Language in a definition statement in serverless.yml.

custom:
  accountId: xxxxxxxx

functions:
  hellofunc:
    handler: handler.hello

stepFunctions:
  stateMachines:
    hellostepfunc1:
      events:
        - http:
          path: gofunction
          method: GET
      definition:
        Comment: "A Hello World example of the Amazon States Language using an AWS Lambda Function"
        StartAt: HelloWorld1
        States:
          HelloWorld1:
            Type: Task
            Resource: arn:aws:lambda:${opt:region}:${self:custom.accountId}:function:${self:service}-${opt:stage}-hello
            End: true
    hellostepfunc2:
      definition:
        StartAt: HelloWorld2
        States:
          HelloWorld2:
            Type: Task
            Resource: arn:aws:states:${opt:region}:${self:custom.accountId}:activity:myTask
            End: true
  activities:
    - myTask
    - yourTask

Events

API Gateway

To create HTTP endpoints as Event sources for your StepFunctions statemachine

Simple HTTP Endpoint

This setup specifies that the hello statemachine should be run when someone accesses the API gateway at hello via a GET request.

Here's an example:

stepFunctions:
  stateMachines:
    hello:
      events:
        - http:
            path: hello
            method: GET
      definition:

HTTP Endpoint with Extended Options

Here You can define an POST endpoint for the path posts/create.

stepFunctions:
  stateMachines:
    hello:
      events:
        - http:
            path: posts/create
            method: POST
      definition:

Send request to an API

You can input an value as json in request body, the value is passed as the input value of your statemachine

$ curl -XPOST https://xxxxxxxxx.execute-api.us-east-1.amazonaws.com/dev/posts/create -d '{"foo":"bar"}'

Command

deploy

Runn sls deploy, the defined Stepfunctions are deployed.

invoke

$ sls invoke stepf --name <stepfunctionname> --data '{"foo":"bar"}'

options

• --name or -n The name of the step function in your service that you want to invoke. Required.
• --stage or -s The stage in your service you want to invoke your step function.
• --region or -r The region in your stage that you want to invoke your step function.
• --data or -d String data to be passed as an event to your step function.
• --path or -p The path to a json file with input data to be passed to the invoked step function.

IAM Role

The IAM roles required to run Statemachine are automatically generated. It is also possible to specify ARN directly.

Here's an example:

stepFunctions:
  stateMachines:
    hello:
      role: arn:aws:iam::xxxxxxxx:role/yourRole
      definition: