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:
```
npm start
```
The command will open React app in your default browser. If it does not happen automatically, navigate to http://localhost:3000/ manually.

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 click Connect button. The Frontend will connect to your previously deployed Backend. You can open developer tools in the browser and navigate to Networking tab, filter by WS (Websocket). You should see Prod Websocket connection open.
Click Send Order button to invoke the state machine in AWS Step Functions. You will see messages appear below the Send 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 under Prod 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 click Send 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.

mhsnalm/aws-step-functions-progress-tracking