Ordering
Ordering a Product
To order a product through the remote API, you need to know the ID of the product you want to order. Every product that is configured on the coffee machine has an identifier that uniquely identifies that specific product. These identifiers are visible in a backup of the “Products”. Thus restoring these Products on a different machine will give you the same unique identifiers for the same products. Similarly adding and deleting products on a coffee machine will change the known identifiers on the machine. Changing parameter values of a product will however not change their identifiers.
The API offers a function to get a list of all configured products with their names as shown in the user interface together with this ID. The ID is required in subsequent API functions to refer to a product.
Various conditions on the coffee machine can prevent it from pouring some or all of the configured products. For example, when the milk container is empty, none of the milk products can be poured. To know which products can be poured at the moment, the API provides requests and events which inform about the currently available products.
![@startuml
participant "Remote Controller" as remote
participant "Coffee Machine" as cm
remote -> cm: Request GetProductList
cm -> remote: Response ProductList(map<string, string>)
note right
This response will contain a mapping of product
names as shown on the coffee machine screen to
the IDs used in the remote API.
end note
remote -> cm: Request GetAvailableProductIds
cm -> remote: Response AvailableProductIds(string[])
note right
The response will contain a list of product ids
for products which can currently be poured. An
empty list indicates that no product can currently
be poured.
end note
remote -> cm: Request StartProduct(string)
cm -> remote: Response ProductStarted(response_code)
note right
In case the product could be started, it will
return a response code ""SUCCESS""".
In case of a failure the product is not poured
and a corresponding error code is returned.
This could be ""PRODUCT_NOT_AVAILABLE""
when you attempted to start a product that
is currently unavailable.
end note
... product is poured ...
cm -> remote: Event ProductFinished(string, bool)
note right
Once the product has finished pouring, a
""ProductFinished" event is sent. It contains
the id of the product that has finished and a
boolean flag that indicates whether the product
could be poured successfully.
In case of a failure during pouring, you will
get additional events of the type ""ErrorEvent""
which will give you the details of the failure.
end note
@enduml](../_images/plantuml-59f000d5437a36b7054a0e3217db396b18acba57.png)
Order processing
After a product has been ordered at the coffee machine, the status of the order is reported each time
the data changes. The order_changed message returns the Order data set.
Cleaning and rinsing are also considered products.
This data set contains a unique identifier for the order and an identifier for the associated product.
As long as an Order exists on the machine, the status can be queried using the identifier.
When the machine cleans up one or more outdated orders, an orders_removed message is sent. This
message contains a list of the identifiers of the removed orders.
Cup placement handling - cup not placed
Note
This scenario is only applicable if the machine has a cup sensor and the sensor is activated.
If there is no cup placed below the outlet, the product cannot be poured. A CupPlacementAction::WaitForCup
is sent to inform about the missing cup.
Additional information is provided if the sensor detects a cup that is too small.
Cup placement handling - cup already placed
Note
This scenario is only applicable if the machine has a cup sensor and the sensor is activated.
If a cup of the required size is already placed below the outlet, no CupPlacementAction is sent.
Instead, the product dispensing starts immediately.
