Exercise: Hello World API
This example describes development of a simple locally executed saga flow for train_rpc runner, which returns "Hello World" message in a detailed, step-by-step manner.
Last updated
Core Platform
This example describes development of a simple locally executed saga flow for train_rpc runner, which returns "Hello World" message in a detailed, step-by-step manner.
Last updated
Open the Saga screen from your Devops app. Unless you've modified your implementation, this screen is located at https://[YOUR_ADMIN_UI_DOMAIN]/app/devops/common/saga.
Click on "CREATE NEW" button on top of the menu lister of Saga screen. This will clear the contents of Saga design page, and allow you to create a new Saga from scratch.
Provide a unique identifier to your new saga flow from top left corner marked with "ID: " tag and a pencil icon. For this example, we are using "hello_world-0001" as the id.
It is optional to enter an ID for assets created. If no ID is given, backend services can automatically assign an ID if an ID generator is configured for the related state manager. However, giving a recognizable ID for core assets such as sagas, queries, models simply facilitates easier communication and auditing.
If you will be giving your own IDs, it is recommended to use alphanumerical characters, hyphen and underscore followed by a 4 digit partition identifier (i.e. 0001 for assigning assets to partition 1). For assets which do not require partitioning (i.e. will not be created in very high volumes), the partition identifier can be ignored.
Click on the circled edit icon for displaying Saga definition screen.
Enter the following details on displayed screen for describing your new Saga flow:
Saga Name: Hello World
Saga Domain (optional): util
Status: ACTIVE
Saga Description (optional): Returns "Hello World"
Saga Path: /HelloWorld
Version: 0
Allowed On: request_train
Auto Fail: true
These settings will mean that requests received on /HelloWorld URL path for train_rpc runner will trigger execution of this Saga flow as the first version of its kind.
"Allowed On" setting enables this Saga flow on a specific stream only, making sure unintended runners that are not receiving requests on that stream do not respond to this request. When left empty, all runners are allowed to execute the saga.
For this example, you do not need to set Resilience parameters. Click on the close icon on top right corner to apply changes.
From the stencil, drag and drop a Start step to saga flow.
Similarly, drag and drop a Transform and Success step from the stencil. Your graph should look like the following after these actions:
Click on the Start step and you will see a link icon displayed on its right bottom corner, click on the link icon and then the Transform step to connect these two steps together.
Similarly, link Transform step to the Success step. Your graph should look like the following after these connections:
Now that our steps are connected, it is possible to receive events, execute an action on them and return them with success code. However, we still need to change the event payload for returning "Hello World" message. To do this, click on the Transform step and open its editor by clicking on the edit icon displayed on its top left corner.
Enter the following details on displayed screen for configuring your data transformation:
Step Name: Say Hello World
Step Description(optional): This step adds a static "Hello World" message.
Transform Class: Add Value to Payload
Transform Parameters:
Key: value, Value: {message: "Hello World"}
Click on "Apply" button on top right corner to apply changes close this dialog.
Why is there a Transform "Class"?
As a design principle, instead of crowding the stencil for possible activities (such as different transformation types), we chose to provide different options using "Class" or "Action" selection in our Saga steps.
This allows users to change process type for any given step simply selecting/entering a new value, instead of replacing it with a different one which could break ongoing runs and create discontinuity in tracing performance of steps.
Your Transform step should now have the name you entered as follows:
Click on the "SAVE" button displayed on top right corner of the Saga screen.
You should receive a notification saying Saga was successfully saved.
Use your favorite API client or an internet browser to test your new API endpoint. Unless you've modified your implementation, this endpoint is available at https://[YOUR_ADMIN_API_DOMAIN]/api/request/train_rpc/HelloWorld.
You should receive a response with "200 OK" status and {message: "Hello World"} in its body for your GET requests.
