AWS Step Functions Progress Tracking
This project creates an AWS Step Functions, which mocks a mutli-step ordering process, and demonstrates how clients can monitor the progress via Amazon API Gateway Websocket.
This blog post explains the sample in depth.
Project structure
This project contains Backend, which you can deploy with AWS SAM template.yml
, located in the root of the repository. handlers
directory contains all AWS Lambda functions' source code. progress-tracker-frontend
directory contains React-based Frontend, which is optional for deployment.
Requirements
- Create AWS Account in case you do not have it yet or log in to an existing one
- An IAM user or a Role with sufficient permissions to deploy and manage AWS resources
- AWS CLI installed and configured
- Git Installed
- AWS Serverless Application Model (AWS SAM) installed
- Python for changing AWS Lambda functions' code
- NPM for changing the frontend code (React)
Deployment instructions
The project contains Backend and Frontend. You can deploy Backend only. The deployment of Frontend is optional. You can use a hosted Frontend for testing application here and refer to the code in progress-tracker-frontend
to understand how it works under the hood. Alternatively, you can deploy the React-based Frontend locally or to AWS.
Backend
-
Open a terminal and create a new directory, which you will use to clone the repository from GitHub.
-
Clone GitHub repository:
git clone https://github.com/aws-samples/aws-step-functions-progress-tracking.git
-
Change directory to the cloned repository:
cd aws-step-functions-progress-tracking
-
Make sure that your terminal can access AWS resources. Use AWS SAM to deploy the backend resources:
sam build && sam deploy --guided
-
When prompted:
- Specify a stack name
- Choose AWS Region
- Allow SAM CLI to create IAM roles with the required permissions.
Once you have finished the setup, SAM CLI will save the specified settings in configuration file samconfig.toml so you can use
sam deploy
for quicker deployments. -
Note the WebSocketURL value in the output of
sam deploy --guided
command. You will need this value for the Frontend later.
Frontend
Option 1: Use hosted Frontend
AWS provides you with hosted React-based Frontend. Simply open this link.
Option 2: Deploy frontend Frontend locally
To test Frontend on your local machine, you can deploy the React app locally. To do this, follow these steps:
- Make sure you have npm installed:
npm -v
- Navigate to
progress-tracker-frontend
directory:cd progress-tracker-frontend
- Start the Frontend:
The command will open React app in your default browser. If it does not happen automatically, navigate to http://localhost:3000/ manually.
npm start
How it works
- The Frontend asks you for Websocket endpoint URL. This is the value of WebSocketURL, that you've got from SAM template.yml deployment. Paste it into
Enter Websocket URL
field and clickConnect
button. The Frontend will connect to your previously deployed Backend. You can open developer tools in the browser and navigate to Networking tab, filter byWS
(Websocket). You should seeProd
Websocket connection open. - Click
Send Order
button to invoke the state machine in AWS Step Functions. You will see messages appear below theSend Order
button coming from different stages of the state machine. Alternatively, you can observe raw messages in developer tools Networking tab of your browser. The messages will appear underProd
Websocket. - You can also trigger the state machine execution and observe progress messages by using other Websocket clients, like Pie Socket. Simply enter your Websocket URL from WebSocketURL value and click connect. To start execution, specify the following message:
{ "action": "onOrder" }
and clickSend
button. The raw progress messages will appear below. - Additionally, you can navigate to developer tools in your browser, open
Network
tab and observe raw messages coming to the client.
Security
See CONTRIBUTING for more information.
License
This library is licensed under the MIT-0 License. See the LICENSE file.