The serverless-step-functions plugin is a nifty Serverless Framework extension that allows you to define step functions directly within the serverless.yml. However, the definitions for step functions tend to get messy fast and it's hard to visualize how a workflow actually looks and flows just from looking at the YAML. The Step Functions Workflow Studio helps you with exactly this by allowing you to interactively sketch out your state machine. In this post, I'll give you a brief walkthrough of how we can use the Workflow Studio together with the Step Functions plugin.
Creating a State Machine
To get started, navigate to the Step Functions page in the AWS Console and press "Create state machine".
Next, choose "Design your workflow visually", then go to Next.
From here, you can drag and drop Actions and Flows, tinker with the properties, flow, and error handling until you're happy with the design.
Set any resources that you want to eventually define in your serverless app to refer to a made-up value in the meantime - setting the Lambda Function name to just a string name for example. Once you're done, click "Next".
At last, we have our generated JSON schema for the state machine! But wait. Our Serverless template is in YAML, not JSON - how do we translate this into something that we can actually use?
As it turns out, YAML is just a superset of JSON, meaning all JSON is valid YAML. The JSON that was generated is in the form of Amazon State Languages spec, and that same spec is used by our serverless-step-functions plugin. This means that we can translate our JSON snippet to YAML using an online tool, such as Code Beatify, or a CLI tool such as yq.
Now that we've got the state machine defined in YAML, all we need to do is actually use it in the serverless.yml.
Putting it together
If you don't already have a serverless project set up, check out my guide to a simple esbuild setup or just run serverless in your terminal to choose from one of the boilerplates.
The serverless-step-functions plugin extends the serverless.yml format with a root stepFunctions property. We'll use that to define our step function by pasting in our YAML snippet as the definition of the state machine.
// serverless.yml
[...]
stepFunctions:
stateMachines:
myStateMachine:
name: MyStateMachine
[your generated state machine goes here]
Keep in mind that any references to Lambda functions or other services that we used placeholder references for needs to be updated to refer to the actual resources we want them to point to. As an example, a Lambda definition might look like this when generated:
FirstFunction:
Type: Task
Resource: arn:aws:states:::lambda:invoke
OutputPath: $.Payload
Parameters:
Payload.$: $
FunctionName: firstFunction
and we can change that to instead refer to a firstFunction Lambda defined in our stack by changing it to:
FirstFunction:
Type: Task
Resource: !GetAtt firstFunction.Arn
OutputPath: "$.Payload"
Parameters:
Payload.$: "$"
For the workflow from the examples above, this is what the full serverless.yml might look like.
service: step-functions-demo
plugins:
- serverless-step-functions
provider:
name: aws
runtime: nodejs14.x
stepFunctions:
stateMachines:
myStateMachine:
name: MyStateMachine
definition:
Comment: This is your state machine
StartAt: First function
States:
First function:
Type: Task
Resource: !GetAtt firstFunction.Arn
OutputPath: "$.Payload"
Parameters:
Payload.$: "$"
Retry:
- ErrorEquals:
- Lambda.ServiceException
- Lambda.AWSLambdaException
- Lambda.SdkClientException
IntervalSeconds: 2
MaxAttempts: 6
BackoffRate: 2
Next: Wait
Wait:
Type: Wait
Seconds: 5
Next: Second function
Second function:
Type: Task
Resource: !GetAtt secondFunction.Arn
OutputPath: "$.Payload"
Parameters:
Payload.$: "$"
Retry:
- ErrorEquals:
- Lambda.ServiceException
- Lambda.AWSLambdaException
- Lambda.SdkClientException
IntervalSeconds: 2
MaxAttempts: 6
BackoffRate: 2
End: true
functions:
firstFunction:
handler: src/functions/first.handler
secondFunction:
handler: src/functions/second.handler
If you enjoyed this post and want to see more, follow me on Twitter at @TastefulElk where I frequently write about serverless tech, AWS, and developer productivity! 👋
