In store devices

In-Store devices and master data

In this context the term in-store devices refers to any type of device that requires master data to function. Common examples are electronic shelf labels (ESL), label printing services, scales, handheld computers and more.

These devices have different purposes and different requirements to function, but what they have in common is to be loaded with master data to do their job.

In Hii Retail we provide several standard integrations for such devices.

Important: The integration with in-store, third-party vendor devices is a premium service. Please contact your account manager for further details on pricing and how to get access to this service.

Requirements: To be able to use this feature it is required that you setup your Business Unit Groups and Business Units properly in the Business Unit Management Service. You also need to have the feature called "Complete Item" enabled.

Requirements

Required configuration of Business Units

In addition to the configuration of Business Unit Groups and Business Units in general, there is also a requirement to set up which devices are in use in each Business Unit.

The following additional properties must be configured for each Business Unit:

• EslVendors - Supported values: PRICER, EWQ
• ScaleVendors - Supported values: BIZERBA, DIGI
• PrintVendors - Supported values: LTG
• OtherDeviceVendors - Contact your account manager for details on other devices

It is possible to have more than one vendor configured for the same device type.

Required configuration of External Events

To distribute the data to the supported vendors, we rely on webhook integrations that you as a customer manage yourselves. Please have a look at the External Events service for details on how to use it. External Events API

Please read the details in the relevant sections below for specific details on additional webhook requirements.

Labels

Electronic labels and paper labels serve the same purpose, and we group them together under the term labels.

They have slightly different requirements so pay attention to the differences.

Should you need both capabilities in your organization, that is of course supported.

Labels of any kind and from any vendor usually requires information about the Item, Price Specification, Item Identifiers and sometimes also Promotions.

Depending on your setup and use case, there might be even more data needed. Please talk to your account manager if you have needs beyond the standard description provided here.

Electronic Shelf Labels (ESL)

In Hii Retail we currently support ESL devices from PRICER and EWQ.

Mandatory information on 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 properties on 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"

Mandatory properties to perform a delete operation

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

In Hii Retail we currently support manual printing services from LTG.

Contact your account manager in Extenda Retail if you have manual printing requirements with other vendors.

Mandatory information on 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 scenario with ESL and printed paper labels

If you have a mix of ESL and paper labels where one Item would need both label types, it is mandatory to instruct the Hii Retail service about this.

To be able to have ESL and paper label on the same Item the following properties are mandatory for the Item

item/additionalProperties.id:"Label.IsEsl" ### must be true
item/additionalProperties.id:"Label.RequiresAdditionalPrinting" ### must be true to also be able to print paper labels

Overall concept is: Label.IsEsl: true means do NOT block even if a label printing rule would trigger on the changes Label.RequiresAdditionalPrinting: true will BLOCK for printing even if Label.IsEsl: true

Optional properties on master data

item/referencePriceConversionFactor
item/additionalProperties.id:"Print.FruitAndVegetableItemInfo"

Mandatory properties to perform a delete operation

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

In Hii Retail we currently support scale devices from BIZERBA and DIGI.

Mandatory information on 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 information on 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"

Mandatory properties to perform a delete operation

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 also require a reference to the the tenant in their system (often referred to as the domain). This information can be conveyed in one of the following ways:

• 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 devices or other custom devices

In Hii Retail we currently support HDR. This type is customer specific in its origin, but can be used by anyone if the mandatory and optional definition covers your use case.

Please reach out to your account manager to discuss any additional needs you might have.

Mandatory information on 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 information on 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"

Mandatory properties to perform a delete operation

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 of external devices

There are a number of changes that will generate an update output to the external devices. The changes will either be denoted as a POST or a DELETE.

The following entities and changes to them would trigger an update through External Events:

The httpMethod below describes what type of output would be sent through External Events to the device vendor service.

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