Order KCI Flows
KCI updates will usually originate from the supplier API and be delivered by the gateway. However, to help ensure consistency between suppliers and to provide additional order state information, the gateway may also send some KCI updates. For example, a supplier may acknowledge the order synchronously as part of the create order API call - the gateway would then send the acknowledged KCI.
The gateway performs sequence ordering/buffering to ensure KCIs arrive in the correct numeric sequence irrespective of where they originate.
An overview of the order KCI flows is represented below.
Successful Orders
The order is acknowledged by the supplier once received and verified - this can happen before or at the same time as committing to fulfil the order (the gateway may send appropriate KCIs to ensure consistency). Once a supplier has committed to delivering the order, it will have a "committedDate" that will not change from this point and the order will be transitioned to in progress. Initially the "targetDate" will contain the same value but as this is the current expected delivery date this can change in future KCIs.
If the supplier needs any action from the tenant/customer (i.e. information needed or a new appointment is required), they will send an appropriate KCI and the order status will become "pending". The tenant must then reserve a new appointment and/or send an appropriate amendment request which the supplier will acknowledge via a KCI. If accepted and the action is resolved, the order will return to the previous state.
Once an order is successful and complete, the supplier will action the order to "completed".
Delayed Orders
The order may be delayed by the supplier when problems are encountered. At this point, the supplier will send a delayed KCI moving the order status to "held" and giving a "problemCode". The KCI may contain optional textual context, for example, additional context and/or an estimated date for resolution. Once resolved, if there is no change to the booked appointment or the order is unappointed, the supplier would send a resumed KCI moving the order status back to the previous state. For unappointed orders, a new "targetDate" may be provided - this must be sent as an amended KCI as it represents a change.
Where the delay means that a new appointment is now required, the supplier will send a reappoint KCI moving the order to "pending". The tenant would then need to reserve a new appointment and send an amendment request. Once accepted by the supplier, the order will be moved back to the previous state and a new "targetDate" will be provided in the amended KCI.
Some suppliers may send a new appointment automatically - this could be based on engineer availability to complete the order or following discussion with the end customer. The appropriate fields within the KCI will be populated with the new appointment timeslot and supplier reference (as appropriate).
Failed or Cancelled Orders
There are various terminal flows that can occur resulting in a failed or cancelled order;
If the gateway cannot connect to the supplier API or receives an error communicating with the supplier API, the gateway will emit an appropriate "failed to send" KCI to inform the tenant and the order will need to be resubmitted.
Once an order is sent to the supplier, the supplier API may respond synchronously to reject the order which the gateway will handle by sending the rejected KCI itself. Alternatively, the supplier could reject the order asynchronously by sending the rejected KCI which the gateway will forward.
Where the tenant requests to cancel the order, the order may transition to "pending cancellation" awaiting supplier confirmation. A further KCI will then be sent to accept or reject the cancellation. Where the cancellation is rejected, the order would transition back to the previous state.
A supplier may also send an unsolicited order cancellation providing a reason for the cancellation.
