Shelf products and clusters

Shelf products and shelf product clusters tell Shelf Vision which of the products it recognises on a shelf photo are yours, so that share of shelf counts them. A shelf product stands for one detection label (the name the recognition model gives a pack, such as orchard-mango-500). A shelf product cluster is a group of shelf products, such as "Our juices" or "Competitor colas". Either one can be marked Is Own Brand. You set them up once, before or alongside your planograms, and every shelf photo analysed after that uses them.

Overview

When a shelf photo from a visit is analysed, Shelf Vision detects the packs on the shelf and labels each one. Share of shelf is the part of the shelf held by the labels that count as yours. xMatix takes that list of "your" labels from one of three places, in this order:

1. The target brand labels in the layout of the planogram that matched the outlet, when it lists any.
2. Otherwise, your shelf products: every shelf product marked Is Own Brand, plus every shelf product in a cluster marked Is Own Brand.
3. Otherwise, when no shelf product counts as own brand, the Own-brand labels (comma-separated) setting on the Shelf Vision card in Feature Hub.

Shelf products and clusters are the second source. They let you keep your own-brand list as records, one per pack, instead of a single comma-separated setting.

When to use it

• You use Shelf Vision for share of shelf and want to maintain the list of your products as records rather than as a typed list.
• You want to mark a whole family of packs as yours in one place: put them in a cluster and mark the cluster Is Own Brand.
• A new pack has been added to the recognition gallery and its share should start counting as yours.

You do not need shelf products for planogram compliance. Compliance is judged against the products the planogram expects.

How xMatix handles it

• Matching is by detection label. A shelf product counts only through its Detection Label. It must be the same label the recognition model uses. Letter case does not matter, but every other character does: orchard-mango-500 and orchard mango 500 are different labels.
• The two flags add up. A shelf product counts as your own brand when it is marked Is Own Brand, when its cluster is marked Is Own Brand, or both. Clearing the flag on a product does not stop it counting while its cluster is still marked.
• A cluster counts only through its products. Marking a cluster Is Own Brand adds the detection labels of the shelf products that point at it. A cluster with no shelf products adds nothing.
• Shelf products replace the setting completely. As soon as at least one shelf product counts as own brand, the Own-brand labels (comma-separated) setting is ignored for every analysis. It is not merged with your shelf products. If you remove or clear the last own-brand shelf product, the setting is used again.
• A matched planogram still wins. If the planogram chosen for the outlet lists target brand labels, those labels are used and your shelf products are not read for that photo.
• Changes apply to the next analysis. The list is read each time a photo is analysed. Results already saved keep the share of shelf they were calculated with. A new analysis adds a new result, it does not change an old one.
• Label, Description and Cluster are for your records. Shelf audit results show share per detection label (in Share Of Shelf Brand Json) and the overall Share Of Shelf %. They do not use a shelf product's Label as a display name, and they are not totalled by cluster. A cluster's only effect on the numbers is its Is Own Brand flag.

Prerequisites

• Shelf Vision is switched on for your organization. See Shelf Vision.
• Access to the Field Sales Setup app. Shelf products and clusters are under the Shelf Vision group.
• The exact detection labels of your packs. The recognition gallery is maintained for you by your platform operator. You can also read the labels from a recent shelf audit result: Share Of Shelf Brand Json lists the share of every label detected in that photo.
• A numbering setting or a Name field for both records. Every record needs a Name, and the delivered New forms for shelf products and clusters have no Name box. Until your administrator adds one of the two (see Configuration), saving a new record is refused with "Name is required".

Procedure

Step 1 — Open the shelf product clusters

Open the Field Sales Setup app and, under Shelf Vision, select Shelf Product Clusters. The list shows Name, Label, Description, Is Own Brand and Created Date.

You can skip the clusters if you only want to flag products one by one. Go to Step 3.

Step 2 — Create a cluster

1. Select New.
2. Fill in Label, for example Our juices, and a Description if it helps others understand the group.
3. Tick Is Own Brand if every pack in this group is yours. Leave it clear for a group of competitor packs.
4. Save.

The cluster opens on its own page with a Key Information panel (Label, Description, Is Own Brand) and Edit and Delete buttons. The page does not list the shelf products in the cluster. To see them, open the Shelf Products list and filter or sort on the Cluster column.

Step 3 — Create a shelf product for each pack

1. Under Shelf Vision, select Shelf Products, then New.
2. Fill in Detection Label exactly as the recognition model uses it, for example orchard-mango-500. This field is required.
3. Fill in Label, for example Orchard Mango 500 ml, so people recognise the pack.
4. Optionally pick a Cluster.
5. Tick Is Own Brand if this pack is yours. You do not need to tick it when the cluster you picked is already marked Is Own Brand.
6. Add a Description if needed and save.

The list shows Name, Detection Label, Cluster, Is Own Brand and Created Date. Each detection label can have only one shelf product. A second one with the same label is refused.

Step 4 — Check the result on the next audit

Ask a field executive to complete a shelf photo activity on a visit, or wait for the next one. Once the photo has synced and been analysed, open the merchandising activity on the visit. The new shelf audit result shows the Share Of Shelf % counting your own-brand labels. If the matched planogram lists its own target brand labels, those are used instead (see How xMatix handles it).

Step 5 — Change or remove products and clusters

• To change a record, open it and select Edit, or change a field directly on the record page.
• To move a pack to another group, change the shelf product's Cluster.
• To stop a pack counting as yours, clear Is Own Brand on the shelf product, and also on its cluster or move it out of the cluster.
• To remove a record, open it and select Delete, or use Delete in the list. Deleting a cluster does not delete its shelf products. Those products stop counting as own brand through the cluster, so tick Is Own Brand on any that should still count.

Fields

Shelf product cluster

Shelf product

Business rules

• Required fields: Name on both records and Detection Label on shelf products.
• One shelf product per detection label. A second record with a label already in use is refused with "Detection Label '…' already exists". A deleted shelf product no longer blocks its label.
• Own-brand list: the detection labels of shelf products marked Is Own Brand, together with those whose cluster is marked Is Own Brand.
• Order of sources: the matched planogram's target brand labels first, then the own-brand shelf products, then the Own-brand labels (comma-separated) setting.
• No own-brand labels at all: if none of the three sources gives any label, share of shelf is recorded as 0.
• Deleting a cluster never deletes its shelf products.
• No numbering, statuses, approvals or automation are delivered for these records.

Example

A beverage company sells two juice packs and wants share of shelf to count them on every outlet that has no planogram.

1. The administrator adds a numbering setting for Shelf Product Cluster and Shelf Product, so new records get a Name automatically.
2. In Field Sales Setup → Shelf Product Clusters, they create Our juices and tick Is Own Brand. They also create Competitor colas without ticking it.
3. In Shelf Products, they create three records:
   • Detection Label orchard-mango-500, Label Orchard Mango 500 ml, Cluster Our juices.
   • Detection Label orchard-mango-1l, Label Orchard Mango 1 litre, Cluster Our juices.
   • Detection Label fizzup-cola-330, Label FizzUp Cola 330 ml, Cluster Competitor colas.
4. The next day a field executive photographs a shelf where the two mango packs fill 30 % of the shelf width and the cola fills the rest. The outlet has no planogram.
5. The shelf audit result shows Share Of Shelf % of 30. The cola label appears in the per-label breakdown but does not count toward the share.
6. Later the company adds a 200 ml pack. The administrator creates a shelf product for orchard-mango-200 in Our juices, and it counts from the next analysed photo.

Training

Practice exercise

In a sandbox where Shelf Vision is switched on and numbering is set up for both records:

1. Create a cluster Practice own packs with Is Own Brand ticked.
2. Create a shelf product for one detection label taken from a recent shelf audit result, in that cluster, with Is Own Brand left clear.
3. Create a second shelf product for another label from the same result, with no cluster and Is Own Brand ticked.
4. Try to create a third shelf product with the same detection label as the first.

Expected result: the first two records save. The third is refused because the detection label already exists. On the next analysed photo that shows both packs, their shares together make up the Share Of Shelf %.

Quick reference

• Shelf products and clusters are in Field Sales Setup → Shelf Vision.
• One shelf product per detection label. Copy the label exactly.
• A pack counts as yours if it, or its cluster, is marked Is Own Brand.
• A cluster on its own counts for nothing. Its shelf products carry the labels.
• One own-brand shelf product switches off the comma-separated Own-brand labels setting.
• A planogram that lists target brand labels overrides your shelf products.
• Changes count from the next analysed photo. Old results are not recalculated.
• The delivered New forms need a numbering setting or a Name field before they can save.

Permissions

Shelf products and clusters follow the record permissions of the security profile. In the delivered profiles, System Admin, Sales Manager, Sales Executive and Standard User all have full access (read, create, edit and delete) to both. Because one changed flag changes share of shelf for every later audit, remove create, edit and delete from the profiles your field executives hold if only merchandising should maintain these records. No server actions are involved, so there is nothing to grant on a profile's Actions tab. See security profiles.

Configuration

Common problems

Saving a new shelf product or cluster fails with "Name is required"

Cause: the delivered New forms have no Name field and no numbering setting is delivered for these records.

Fix: an administrator adds a document numbering setting for the record, or adds the Name field to its create layout. See Configuration.

"Detection Label '…' already exists"

Cause: another shelf product already uses that detection label.

Fix: open the existing shelf product from the Shelf Products list and change it instead, for example its Cluster or Is Own Brand.

Share of shelf did not change after I marked a product as own brand

Check, in this order:

1. The detection label. It must match the label the model gives that pack, character for character apart from letter case. Compare it with the result's Share Of Shelf Brand Json.
2. The planogram. If the planogram matched to the outlet lists target brand labels, those are used instead.
3. The timing. Only photos analysed after your change use it. Older results are not recalculated.

Packs I listed in the Own-brand labels setting stopped counting

Cause: at least one shelf product now counts as own brand, so the setting is no longer read.

Fix: create a shelf product, marked Is Own Brand, for each label in the setting.

A competitor pack counts as ours

Cause: the pack's shelf product is in a cluster marked Is Own Brand, or is marked itself.

Fix: move it to another cluster or clear the cluster's flag, and clear the product's own flag.

Common questions

Do I need clusters?

No. Clusters are a shortcut for marking many packs as your own brand at once. You can mark each shelf product Is Own Brand instead. Clusters do not group the share-of-shelf figures: results show the overall share and the share of each detection label. A cluster's Label and Description are for your own reference, and the only thing a cluster changes is whether its products count as yours.

Can I keep using the comma-separated Own-brand labels setting?

Yes, as long as no shelf product counts as own brand. Once one does, the setting is ignored completely, so move every label you need into shelf products at the same time. Clearing or deleting the last own-brand shelf product brings the setting back into use. Either way, a matched planogram that lists target brand labels takes precedence over both.

Where do I find the exact detection labels?

The labels come from the recognition gallery, which your platform operator maintains. The easiest place to read them is a recent shelf audit result: its Share Of Shelf Brand Json field lists every detected label with its share. For a new pack that the model does not recognise yet, ask your operator to add it to the gallery first and to tell you its label.

Related topics

• Planograms and shelf audits
• Shelf Vision
• Checklists and tasks
• Document numbering
• Shelf Product reference and Shelf Product Cluster reference