Saturday, April 23, 2022

AWS Step Functions - Integration, Logs & Docs - Part #03

 [AWS SF : Image Showing AWS Step Functions Logo]

Refer to Part-01 (AWS Step Functions - Features & Usage) of this Article 
Refer to Part-02 (AWS Step Functions - Features & Usage) of this Article

This series of articles will cover the Features and Usage of Step Functions. These are from the point of view of Integration with AWS API Gateway and REST Endpoints (Spring Boot) hosted on Elastic Beanstalk/EC2. Also, The discussion is from a purview of Data Management in Microservices, Transaction Management, Service Orchestration and Saga Design Pattern. 
[Important Information: The article is based on the experience of the author working on the PoC/Prototype/Pilot of AWS Step Functions, Elastic Beanstalk* (EC2), AWS API Gateway* for a Neo Bank Startup of Philippines/Singapore. It contains knowledge collated, referenced from various manuals, blogs and tutorials on the internet. The transaction shown below is a mock use-case or a mock business transaction. Any Images are copyright of their respective owners and only used for non-commercial purposes. I have verified and certify that it contains no copyright or confidential business information.]

 The topics covered in this specific article are :

    • API Gateway Integration   
    • Postman Invocation - SF API   
    • AWS Step Functions:Vast API*   
    • Invoking Step Functions from SF   
    • ‘Known’ Integration Issues   
    • Cloudwatch Logs
    • X-Ray Tracing   
    • EC2/Beanstalk (Optional)

[API Gateway Integration]
To understand how to perform API Gateway Integration with Step Functions, please refer to the following link: It is a pretty straightforward and requires a simple understanding of REST to create the API Gateway façade over the Step Functions. It allows to invoke the Step Functions from the outside world.
Fig.12 : Creating AWS API Gateway Facade Over Step Functions 
(For Purposes of External Invocation via a REST API)
[Postman Invocation - SF API]
In the above explanation, once we have completed creating the API Gateway over the Step Function, we will be able to invoke the Step Function via REST API (AWS API Gateway) using SOAPUI, Postman or even the Browser. Typical Endpoint (POST) for Invocation will be as Follows:
[Typical Step Functions URL - REST Endpoint on AWS API Gateway]
 Request Body (POST)  
 "input": "{}",  
 "name": "DemoExecution-99",  
 "stateMachineArn": "arn:aws:states:us-east-1:683993062563:stateMachine:uno-state-machine-poc"  
Typical Response { "executionArn": "arn:aws:states:us-east-1:683993062563:execution:uno-state-machine- poc:DemoExecution-99", "startDate": 1.649873197406E9 }
Typical Request and Response (Mock Use-Case using Step Function)

If you go the ‘Executions’ UI/Screen in AWS Console for Step Functions, you can find the visual execution results and details of the given Step Function instance that was started using Postman/SOAPUI.
AWS Step Functions:Vast API*
AWS has a very vast and deep API for the purposes of integration using any of our own services. This allows us to design our UI or Monitoring or Façade API services on the basis of the Step Functions API. The documentation for the usage of AWS Step Functions API is provided at:
Invoking Another Step Function from a SF
Another interesting aspect is that we can chain Step Functions and invoke one Step Function from another Step Function. Even though it falls under the category of calling any AWS Service from AWS Step Functions – It can allow us to differentiate concerns of business use-case flows and allows for a cleaner integration. There is an option to either just invoke the step function and return back or to wait for it synchronously to complete its execution.
Fig.13 : Invoking Another Step Function from a Step Function
‘Known’ Integration Issues
  • One of the Most Common Issue when IAM Rights are Correctly Not Provided, You may get No Message with a Red Cross when Saving the Workflow – Contact DevOps for Rights
  • Another Issue is that you may not be able to Invoke/Execute the Step Function from API Gateway – In this case also, you have to contact DevOps for Rights.
  • Your Workflow will not be Saved with Blank Error or Error with a Message. It usually means that your ASL or Workflow ‘Syntax’ is not correct. Please check online manual or reference to understand the correct usage of constructs.
  • EC2/Beanstalk fails to respond to the request citing Server Error. Make sure that you add the configuration parameter SERVER_PORT=5000
Cloudwatch Logs
You may use cloudwatch logs to get the details on all steps including input, output. Also, you may get finer details when an exception occurs. If you have given any console print or log statements (via cloudwatch appender in log4j) in your Java/Java EE code then you will find them in this console.
Fig.14 : Access Logs on Cloudwatch 
(Enable Logs while Creating Step Functions)
X-Ray Tracing
X-Ray Tracing is used to track the performance of each step as well as of the the entire step function and then compare it with their historical execution. You may enable X-Ray Tracing at the time of creating the Step Function.
Fig.15 : X-Ray Tracing (Performance & Statistics)
EC2/Beanstalk (Optional)
You may use the EC2 or Elastic Beanstalk to host your service. Especially, while trying to Deploy for the purposes of Learning or Prototyping anything on Step Functions – Elastic Beanstalk is very easy and elegant in case of Spring Boot/REST Deployments. For a step by step example to understand on Elastic Beanstalk, please refer to: Also, You will find a very basic step by step example for AWS Step Functions over here:  

Thanks and Hope you learnt the Features, Usage, Integration and Invocation of AWS Step Functions in the context of AWS API Gateway and Elastic Beanstalk/EC2. Wishing Happy and Productive Times on the Amazon Web Services Ecosystem!