In store devices

In-Store Devices and Master Data

In-store devices refers to any device requiring master data to function, such as electronic shelf labels (ESL), label printers, scales, handhelds, and more.

These devices have different requirements but all need master data. Hii Retail provides standard integrations for such devices.

Note: Integration with in-store, third-party devices is a premium service. Contact your account manager for pricing and access.

Requirements: You must configure Business Unit Groups and Business Units in the Business Unit Management Service. The "Complete Item" feature must be enabled.

Requirements

Business Unit Configuration

Configure which devices are used in each Business Unit:

• EslVendors: PRICER, EWQ
• ScaleVendors: BIZERBA, DIGI
• PrintVendors: LTG
• OtherDeviceVendors: Contact your account manager

Multiple vendors per device type are supported.

External Events Configuration

Data distribution relies on webhook integrations managed by the customer. See External Events service and API for details.

See relevant sections below for specific webhook requirements.

Labels

Labels include both electronic and paper labels. Both require master data such as Item, Price Specification, Item Identifiers, and sometimes Promotions.

Additional data may be needed depending on your setup. Contact your account manager for non-standard requirements.

Electronic Shelf Labels (ESL)

Currently supported: PRICER, EWQ.

Mandatory Master Data

To distribute the required data to the appropriate devices, the following properties on master data entities must be provided.

item.id
item.businessUnitId
item.name
item.description
item.brand
item.itemCategoryId
item/additionalProperties.id:"Label.Name"
item/additionalProperties.id:"Label.ItemCount"
item/additionalProperties.id:"Label.MainEan"
item/additionalProperties.id:"Label.ArticleNumber"
item/additionalProperties.id:"Label.Platetext"
item/additionalProperties.id:"Label.ComparisonFlag"
item/additionalProperties.id:"Label.IsEsl" ### must be true
itemIdentifiers.id
itemIdentifiers.type
priceSpecifications.id ### (where isCurrent:true and type:SALES OR type:LOWEST_HISTORIC_PRICE)
priceSpecifications.type ### (where isCurrent:true and type:SALES OR type:LOWEST_HISTORIC_PRICE)
priceSpecifications.value ### (where isCurrent:true and type:SALES OR type:LOWEST_HISTORIC_PRICE)
priceSpecifications.isCurrent ### (where isCurrent:true and type:SALES OR type:LOWEST_HISTORIC_PRICE)

Optional Master Data

For certain functionalities and layouts used on ESL labels, the following information might also be expected.

item.assortmentTags
item/images.intendedAudience:"DIGITALSIGNAGE"
item/images.url
item/images.modified
item/additionalProperties.id:"Label.AgeRestriction"
item/additionalProperties.id:"Label.AutoOrderType"
item/additionalProperties.id:"Label.ExpirationDate"
item/additionalProperties.id:"Label.CharacteristicCode"
item/additionalProperties.id:"Label.ChainSpecificLabelType"
item/additionalProperties.id:"Label.CareInstructions"
item/additionalProperties.id:"Label.DefaultOriginCountry"
item/additionalProperties.id:"Label.Freetext1"
item/additionalProperties.id:"Label.Freetext2"
item/additionalProperties.id:"Label.Supplier.ItemIdentifier"
item/additionalProperties.id:"Label.LabelType"
item/additionalProperties.id:"Label.InventoryLocation"
item/additionalProperties.id:"Label.ExpirationReason"
item/additionalProperties.id:"Label.Ingredients"
item/additionalProperties.id:"Label.ComparisonUnit"
item/additionalProperties.id:"Label.ItemType"
item/additionalProperties.id:"Print.FruitAndVegetableItemInfo"
item/additionalProperties.id:"Label.PlateAttribute1"
item/additionalProperties.id:"Label.PlateAttribute2"
item/additionalProperties.id:"Label.WeightVolume"
priceSpecifications/additionalProperties.id:"Label.ComparePrice"
priceSpecifications/additionalProperties.id:"Label.DepositPrice"
priceSpecifications/additionalProperties.id:"Label.B2B.Price"
priceSpecifications/additionalProperties.id:"Label.B2B.BoxPrice"
priceSpecifications/additionalProperties.id:"Label.B2B.DepositBoxPrice"
priceSpecifications/additionalProperties.id:"Label.B2B.PriceTaxed"
priceSpecifications/additionalProperties.id:"Label.B2B.ComparePriceTaxed"
priceSpecifications/additionalProperties.id:"Label.B2B.BoxPriceTaxed"
priceSpecifications/additionalProperties.id:"Label.B2B.DepositPriceTaxed"
priceSpecifications/additionalProperties.id:"Label.B2B.DepositBoxPriceTaxed"
promotion.id ### (where promotionType:"NORMAL" AND status:"ACTIVE" AND startDate<=current date<=endDate, same rule applies to all promotion* properties)
promotion.name
promotion.startDate
promotion.endDate
promotion.type
promotion.additionalProperties.id:"Label.Offer.DisplayLowestHistoricPrice"
promotion.additionalProperties.id:"Label.Offer.Displaytext"
promotion.additionalProperties.id:"Label.Offer.Type"
promotion.additionalProperties.id:"Label.Offer.Threshold"
promotion.additionalProperties.id:"Label.Offer.UsageLimit"
promotion.additionalProperties.id:"Label.Offer.Reward"
promotion.additionalProperties.id:"Label.Offer.RewardType"
promotion.additionalProperties.id:"Label.Offer.Conditions"
promotion.additionalProperties.id:"Label.Offer.Coupon"
promotion.additionalProperties.id:"Label.Offer.ReceiptText"
promotion.additionalProperties.id:"Label.Offer.LoyaltyText"
promotion.additionalPromotionItemProperties.id:"Label.PromotionPrice"
promotion.additionalPromotionItemProperties.id:"Label.PromotionComparePrice"
promotion.additionalPromotionItemProperties.id:"Label.Promotion.Activitycodeid"
promotion.additionalPromotionItemProperties.id:"Label.B2B.Promotion.BoxPrice"
promotion.additionalPromotionItemProperties.id:"Label.B2B.Promotion.PriceTaxed"
promotion.additionalPromotionItemProperties.id:"Label.B2B.Promotion.ComparePriceTaxed"

Delete Operation Requirements

The following information must be present on an Item for Hii Retail to be able to send a delete message to ESL providers. This applies for both soft delete and permanent delete.

item.id
item.businessUnitId
itemIdentifiers.id
item/additionalProperties.id:"Label.MainEan"

Paper Labels for Manual Printing

Currently supported: LTG.

Mandatory Master Data

In addition to the mandatory properties for ESL the following property is required:

item/additionalProperties.id:"Label.LabelType"

The following mandatory property for ESL is not mandatory for Print

item/additionalProperties.id:"Label.IsEsl"

Hybrid ESL and Paper Labels

If an Item needs both ESL and paper labels, set:

item/additionalProperties.id:"Label.IsEsl" ### must be true
item/additionalProperties.id:"Label.RequiresAdditionalPrinting" ### must be true

Label.IsEsl: true means do not block label printing rules.
Label.RequiresAdditionalPrinting: true will block for printing even if Label.IsEsl: true.

Delete Operation Requirements

The following information must be present on an Item for Hii Retail to be able to send a delete message to print providers. This applies for both soft delete and permanent delete.

item.id
item.businessUnitId
itemIdentifiers.id
item/additionalProperties.id:"Label.MainEan"

Scales

Currently supported: BIZERBA, DIGI.

Mandatory Master Data

To distribute the required data to the appropriate devices, the following properties on master data entities must be provided.

item.id
item.businessUnitId
item/additionalProperties.id:"Scale.Code"
item/additionalProperties.id:"Scale.PriceType"
item/additionalProperties.id:"Scale.SellByDatePeriod"
item/additionalProperties.id:"Scale.SellByDatePeriodPrint"
item/additionalProperties.id:"Scale.UseByDatePeriod"
item/additionalProperties.id:"Scale.UseByDatePeriodPrint"
item/additionalProperties.id:"Scale.Tare"
item/additionalProperties.id:"Scale.DepartmentCode"
item/additionalProperties.id:"Scale.IsSelfService"
item/additionalProperties.id:"Scale.ScaleGroups"
item/additionalProperties.id:"Scale.StorageTemperature"
item/additionalProperties.id:"Scale.HasTraceability"
item/additionalProperties.id:"Scale.Title"
priceSpecifications.id ### (where isCurrent:true and type:SALES)
priceSpecifications.type ###  (where isCurrent:true and type:SALES)
priceSpecifications.value ###  (where isCurrent:true and type:SALES)
priceSpecifications.isCurrent ###  (where isCurrent:true and type:SALES)

Optional Master Data

item/images.intendedAudience:"SCALE"
item/images.url
item/images.modified
item/additionalProperties.id:"Scale.FixedWeight"
item/additionalProperties.id:"Scale.PackDatePrint"
item/additionalProperties.id:"Scale.TraceabilityType"
item/additionalProperties.id:"Scale.IsEco"
item/additionalProperties.id:"Scale.PackDatePrint"
item/additionalProperties.id:"Scale.PrintImage1Link"
item/additionalProperties.id:"Scale.PrintImage1Timestamp"
item/additionalProperties.id:"Scale.PrintImage2Link"
item/additionalProperties.id:"Scale.PrintImage2Timestamp"
item/additionalProperties.id:"Scale.LabelNo"
item/additionalProperties.id:"Scale.Description1"
item/additionalProperties.id:"Scale.Description2"
item/additionalProperties.id:"Scale.Description3"
item/additionalProperties.id:"Scale.CountryOfOriginISO"
item/additionalProperties.id:"Scale.Ingredients"
item/additionalProperties.id:"Scale.Allergens"
item/additionalProperties.id:"Scale.MightContain"
item/additionalProperties.id:"Scale.Nutrifacts"
item/additionalProperties.id:"Scale.Barcode"
item/additionalProperties.id:"Scale.BarcodeType"
item/additionalProperties.id:"Scale.MinWeight"
item/additionalProperties.id:"Scale.MaxWeight"
item/promotions/id ### (where promotionType:"NORMAL" AND status:"ACTIVE" AND startDate<=current date<=endDate, same rule applies to all promotion* properties)
item/promotions/additionalProperties.id:"ScalePromotionPrice"

Delete Operation Requirements

As the item.id is not the unique identifier in the scale systems, the following information must be present on an Item for Hii Retail to be able to send a delete message. This applies for both soft delete and permanent delete.

item.id
item.businessUnitId
item/additionalProperties.id:"Scale.Code"

The Scale.Code is the unique identifier to the scale system which is why it is mandatory as part of the delete message.

Scale consumers require a tenant reference, provided as a URL parameter or custom header.

• As a URL parameter (e.g. https://scale.se?domain=`tenantIdentifier`)
• Via custom headers in the setup of the cloud events. This has to be determined between the tenant and the scale vendor before setting up the webhook.

Both options are illustrated in the screen shot below. Both are not needed at the same time.

Handheld or Custom Devices

Currently supported: HDR. Contact your account manager for additional needs.

Mandatory Master Data

To distribute the required data to the appropriate devices, the following properties on master data entities must be provided.

item.id
item.businessUnitId
priceSpecifications.id
priceSpecifications.type ### (where isCurrent:true AND (type:SALES OR type:LOWEST_HISTORIC_PRICE OR type: PURCHASE))
priceSpecifications.value
priceSpecifications.isCurrent

Optional Master Data

priceSpecifications/additionalProperties.id:"Label.ComparePrice"
priceSpecifications/additionalProperties.id:"Label.DepositPrice"
priceSpecifications/additionalProperties.id:"Label.B2B.Price"
priceSpecifications/additionalProperties.id:"Label.B2B.BoxPrice"
priceSpecifications/additionalProperties.id:"Label.B2B.DepositBoxPrice"
priceSpecifications/additionalProperties.id:"Label.B2B.PriceTaxed"
priceSpecifications/additionalProperties.id:"Label.B2B.ComparePriceTaxed"
priceSpecifications/additionalProperties.id:"Label.B2B.BoxPriceTaxed"
priceSpecifications/additionalProperties.id:"Label.B2B.DepositPriceTaxed"
priceSpecifications/additionalProperties.id:"Label.B2B.DepositBoxPriceTaxed"
promotion.id ### (where promotionType:"NORMAL" AND status:"ACTIVE" AND startDate<=current date<=endDate, same rule applies to all promotion* properties)
promotion.additionalPromotionItemProperties.id:"Label.PromotionPrice"
promotion.additionalPromotionItemProperties.id:"Label.PromotionComparePrice"
promotion.additionalPromotionItemProperties.id:"Label.B2B.Promotion.BoxPrice"
promotion.additionalPromotionItemProperties.id:"Label.B2B.Promotion.PriceTaxed"
promotion.additionalPromotionItemProperties.id:"Label.B2B.Promotion.ComparePriceTaxed"

Delete Operation Requirements

As the item.id is not the unique identifier in the scale systems, the following information must be present on an Item for Hii Retail to be able to send a delete message. This applies for both soft delete and permanent delete.

item.id
item.businessUnitId
itemIdentifiers.id
item/additionalProperties.id:"Label.MainEan"

What Triggers an Update

Changes to Items, Price Specifications, or Promotions can trigger updates to external devices via External Events. The type of change (POST or DELETE) depends on the entity and the nature of the update.

Items

• Added with any item.status other than DELETED and assortmentType: IN_ASSORTMENT or EXPIRING_ASSORTMENT → httpMethod: POST
• Deleted (httpMethod: DELETE)
• Updated if any of the properties that are defined as included for the relevant device type.
  • Applies for all item.status enums values except DELETED → httpMethod: POST
• A change to item.status will not generate any updates unless the status changes to DELETED → httpMethod: DELETE
  • A change from DELETED to any other status → httpMethod: POST
• A change on item.assortmentType will only generate updates for:
  • to REMOVE_FROM_ASSORTMENT → httpMethod: DELETE
  • from REMOVE_FROM_ASSORTMENT → httpMethod: POST

Price Specifications

• Added with priceSpecification.status: ACTIVE and priceSpecification.type defined as included for the relevant external device type (some require only SALES, others SALES and LOWEST_HISTORIC_PRICE etc) → httpMethod: POST
• Updated if any of the properties that are defined as included for the relevant external device type → httpMethod: POST
  • Or if the current price has changed → httpMethod:POST

Promotions

Only applies where the itemId is in the promotionItems lists on the applicable Promotion

• Added with promotion.status: ACTIVE and the current date and time is within the interval of the from and to defined on the promotion → httpMethod: POST
• Deleted with promotion.status: DELETED → httpMethod: POST
  • If the Item is removed from the promotionItems list → httpMethod: POST
• Updated if any of the properties that are defined as included for the relevant external device type → httpMethod: POST