Example
Build an order lookup flow
A customer opens one of their orders. The web app asks the orders service for it by id; the service reads it from its database and answers with the order, or with 404 when there is no such order.
You will build
- 2 new systems: Orders Service and Orders DB
- The GET /api/v1/orders/{id} API with a path parameter, and an orders.findById query
- 2 pieces of logic: the order page and the lookup
- The Order lookup flow with test data, 2 test cases and 1 requirement, all passing
System map
- Web AppOrders ServiceGET /api/v1/orders/{id}
- Orders ServiceOrders DBorders.findById (query)
Web App, kind Web frontend.
Part 1: Create the systems
- 1.
Systems → New system, then Create system: - Name
- Orders Service
- Type
- Backend service
- 2.
And again: - Name
- Orders DB
- Type
- Database
Part 2: Declare the order API
- 1.
Open Orders Service. On APIs, click Add an API. - 2.
Under Basics: - This endpoint is…
- Provided
- Method
- GET
- Path
- /api/v1/orders/{id}
- Summary
- One order by its id
- Lifecycle
- To do
- 3.
Under Request, Path parameters shows {id}. Set its type tointeger. A GET has no request body. - 4.
Type the 200 response’s body: id: integer status: string total: number
- 5.
Click +404, type its body and click Create endpoint. error: string
Part 3: Connect the web app to the API
- 1.
Open Web App → … → Add a dependency…. Consumer Web App, providerOrders Service. - 2.
Tick GET /api/v1/orders/{id}and click Connect 1 API.
Check:
Part 4: Add the lookup
- 1.
Open Orders DB → Resources → Operation. Keep may return nothing ticked, then Save. - Name
- orders.findById
- Type
- query
- Query / description
- SELECT id, status, total FROM orders WHERE id = :id
- Input fields
- id: integer
- Output fields
- id: integer status: string total: number
Part 5: Build the lookup logic on the orders service
- 1.
Open Orders Service → APIs. On GET /api/v1/orders/{id}, click + Logic. On Request has anidconnection point: the path parameter. - 2.
Add Query Database (label Find order), OperationOrders DB · orders.findById (query). Connect the On Request arrow into it andidinto itsidconnection point. - 3.
From Found: Return Response 200, with the query’sresultconnected straight intobody(it has the same fields). - 4.
From Not found: Return Response 404. Body: Make Objecterror: string=Order not found. - 5.
Tick Key step on Find order.
Check:
Part 6: Build the order page logic on the web app
- 1.
Open Web App → Logic → + Logic. Choose Event / UI action. - Event name
- Open order page
- Name
- Open order page
- 2.
Inputs: - orderId
- Whole number
- 3.
Return values: - found
- Yes / No
- status
- Text
- message
- Text
- 4.
Click Create and open. In Details, make statusandmessagenullable (string | null). - 5.
Add Call Contract (label Load order) with APIGET /api/v1/orders/{id}. Connect the On Event arrow into it andorderIdinto itsidconnection point. - 6.
From 200: Return with found= true,message= null,statusfrom Get Propertystatuson the call’sbody. - 7.
From 404: Return with found= false,status= null,messagefrom Get Propertyerroronbody. - 8.
From Other: Return with found= false,status= null,message=Something went wrong.
Check:
Part 7: Create the flow
- 1.
Flows → New flow, then Create flow: - Name
- Order lookup
- Where does the flow start?
- Existing logic
- (the list)
- Web App · Open order page (event)
- Criticality
- Normal
Check:
Part 8: Add test data
- 1.
Test data → New test data → orders.findById. NamePlaced order, WHENid==1001, THEN RETURN:{ "id": 1001, "status": "placed", "total": 42.5 } - 2.
One more on orders.findById:No such order, WHENid= * (any), THEN RETURNnull. - 3.
Expected results → New expected result for Order lookup.Order shown:foundequalstrue,statusequals"placed". - 4.
Order missing:foundequalsfalse,messageequals"Order not found".
Part 9: Write the test cases
- 1.
Open Order lookup→ Test → Manage… → New, once per row. - 2.
Existing order: expectOrder shown.{ "orderId": 1001 } - 3.
Missing order: expectOrder missing. PickNo such orderfor orders.findById.{ "orderId": 9999 }
Part 10: Link the requirement
- 1.
Requirements → New requirement: An order that does not exist answers 404, not an error.FlowOrder lookup, test caseMissing order.
Part 11: Run it
- 1.
Open the flow → Test → Run all. - 2.
Open a run and step through it: the Step data panel shows the idthat went in and the order that came back.
Check:
