Skip to main content

Store Data Service

Hii Retail Store Data Service

Overview​

Store Data is the hub between the Master Data APIs, Checkout Config APIs, IAM, Business Unit Management and the ERPOS in the stores or Checkout Engine. The ERPOS and Checkout Engine are expecting messages in a certain order and that all referenced entites exists. Store Data handles these dependency checks and ordering so that the customer can send messages in any order.

Incoming APIs​

Store Data subscribes to the topics of the

Coming

Provides entity status to

Application Support​

Store Data currently supports ERPOS and Checkout Engine and in some API endpoints you need to select between them using the application parameter since a store can be using both Checkout Engine and ERPOS (and possibly others in the future), for example in a transition period.

Initial State​

When a store is setup for the first time, an Initial state is done from the Store Data API. A store will not get any messages until that is done. In this case the non-items subset is the preferred way to run the initial state. That subset will have all data except items, prices, promotions and PLU-lists. These messages will be send in the normal flow of data when the initial state is finished anyway.

The Initial state sends all currently known messages to the store and starts sending updates after the initial state is done.

Initial state can also be used as a crash recovery function for the store and in this case you would use the subset that matches the faulty data or a complete initial state to completely refresh the store's data.

The subsets are

  • items
  • non-items
  • item-categories
  • promotions
  • plulists
  • currencies
  • tax-groups
  • cashier-messages
  • tenders
  • reason-codes

Message Dependency Issues​

If an entity is missing any dependencies, for example a PLUList that is missing one of the Items, it will be held in Store Data and reported to External Events. The customer can subscribe to these events in their HiiRetail Customer Portal and be alerted of the issues on their selected web hook endpoint.

There is a window of ten minutes before a missing dependency is reported to External Events.

The message that is sent on the External Events is

{
  "entityId": "string",
  "businessUnitGroupId": "string",
  "messageType": "string",
  "correlationId": "string",
  "correlationSequence": "string",
  "createdDate": "string",
  waitingFor: {
    "entityId": "string",
    "businessUnitGroupId": "string",
    "messageType": "string"
  }
}

The messageType and waitingFor.messageType can be one of the following:

messageTypeDescription
currencies-changedCurrencies. Dependency of exchange rates and tender
rates-changedExchange rates. Depending on currency
tax-rules-updatesTax groups. Dependency of Item (and later price)
tendersTenders depending on currency
item-categoriesItem categories. Dependency of Item
itemsItems. Depending on price, item categories and tax groups
price-specificationsPrice, sales price. Depending on item and currency. The entityId will be the item id
other-pricePrice, purchase price. Depending on item. The entityId will be the item id
plulistsPLU list. Depending on item (item.identifier)

You can read the message as the messageType and entityId on the root level is waiting for the messageType and entityId on the waitingFor level.

Example:

{
  "entityId": "4711",
  "businessUnitGroupId": "store-1",
  "messageType": "items",
  "correlationId": "0dfae5b5-31b8-4235-9a00-a0427c397ac8",
  "correlationSequence": "82f959b8-2a8a-4e21-a2ae-10dc00f7efb5",
  "createdDate": "2023-01-01T12:34:19.012Z",
  waitingFor: {
    "entityId": "4711",
    "businessUnitGroupId": "store-1",
    "messageType": "price-specifications"
  }
}

For this message, there is an item with 4711 waiting for its sales price. Note that the entity Id for sales price and purchase price is the item Id (in this case 4711) regardless of what the price-specification's Id is. For other messages types, the actual entity Id is used.

Self Served Store Opening​

When opening a store, it is essential to configure it with the correct data. This configuration is done by the customer by defining the store in the Business Units Management system (taxRegionId property is mandatory) and specifying the appropriate application.

Applications are tailored for each specific client, allowing a single client to have multiple applications.

Possible values:

"ERPOS"
"CHECKOUT_ENGINE"
"EDGE_CHECKOUT_ENGINE"

Checkout Engine group is configured with a country code. This country code is used to map the Checkout Engine group to the Checkout Engine ID. The store is configured with a taxRegionId, which includes the country code, allowing it to be mapped to the Checkout Engine ID. When running the Checkout Engine for a specific country, all stores within that country with the "CHECKOUT_ENGINE" application will be served.

How to configure the application​

To configure the application, send a PUT request to: https://ccc-api.retailsvc.com/api/v1/config/che.store-application.v1/values/business-units/storeId. In the request body, specify the required application(s).

Example:

{
  "value": {
    "applications": [
      "CHECKOUT_ENGINE",
      "ERPOS"
    ]
  }
}

E2E steps:​

To enable the store to open automatically, follow these steps:

  1. The feature flag for Handle Store Application messages (Hierarchy) is enabled for the tenant(enable.hierarchy.store-application set to ENABLED)
  2. Ensure the store is registered(with valid taxRegionId) in Business Unit Management. This can be done by sending a PUT request to the following endpoint: https://business-unit.retailsvc.com/api/v1/business-units/storeId.

Example:

{
  "name": "storeId",
  "status": "Active",
  "taxRegionId": "SE"
}
  1. Configure an application for the store. This can be done by sending a PUT request to the following endpoint: https://ccc-api.retailsvc.com/api/v1/config/che.store-application.v1/values/business-units/storeId

Example:

{
  "value": {
    "applications": [
      "CHECKOUT_ENGINE"
    ]
  }
}