Shelf Vision turns image attachments on configured visit activities into measured results: how much of the shelf your brands hold and whether detections satisfy a matched planogram. Automatic processing starts when a qualifying image attachment is committed, not when the activity status changes. Each analyzed attachment creates a new Shelf Audit Result linked to the activity; a below-threshold compliance result can raise or refresh a nudge.
How it works
For the rep, the normal visit flow can remain unchanged: open the configured merchandising or photo-capture activity, take the required image and let the device upload it. A photo captured offline cannot be evaluated until its attachment is committed during sync.
On attachment save, the platform queues an evaluation for that exact file asset. The explicit asset id wins even when the activity has several images. The configured preferred slot (default filename prefix after-) is only a fallback for a manual or legacy run that does not identify an asset; otherwise the newest eligible image is used. The worker calls the stamp inference endpoint, computes the configured share metric, selects the narrowest active planogram for the outlet and inserts a new result row. If compliance is below the configured threshold, it reconciles a nudge on the activity.
On the web, a manager opens the visit's merchandising activity to see the compliance badge, score, findings and share-of-shelf percentage, and the result fields are available to the report designer for per-outlet and per-route compliance and share-of-shelf trends.
Two configurations drive the scoring. The stamp-level reference gallery maps detections to product labels and is maintained by a platform operator in Admin MLOps. The tenant planogram declares target labels, minimum facings and optional shelf bands. Without a matching planogram, the run can still compute share of shelf when own-brand target labels are available, but it leaves compliance unscored.
Prerequisites
- Shelf Vision enabled for your deployment — it is platform-provisioned, so if the settings below don't exist for you, ask your operator.
- The Feature Hub settings capability, for Setup → Feature Hub → Sales → Settings → Shelf Vision.
- Field visits already using a merchandising audit or photo-capture activity, so there are photos to analyze.
- Reference labels and crops maintained in the stamp's Admin MLOps gallery. Tenant administrators should coordinate additions or packaging changes with their platform operator.
Procedure
- 1
Shelf Vision settings live under the Sales module and remain independent from ordinary photo upload.
- 2
Auto-analyze is the tenant gate for evaluation; turning it off stops new inference calls.
- 3
Own-brand labels are a CSV fallback after a matched planogram and the tenant's own-brand Shelf Product taxonomy.
- 4
These labels select the share numerator; they do not add recognition crops to the operator-managed gallery.
- 5
Annotated-photo storage is optional and helps reviewers see detections, but roughly doubles image storage.
The Shelf Vision card is the production control surface. Automatic analysis is independent from ordinary photo upload, own-brand labels are a fallback when no matching planogram supplies targets, and annotated result images are an optional audit aid with a material storage cost.
Step 1 — Turn on automatic analysis
On the Shelf Vision card under Setup → Feature Hub → Sales → Settings, switch on Auto-analyze shelf photos. This is the tenant gate for the configured entity list, whose default is VisitTaskActivity; the host also has a separate deployment-level master switch and inference endpoint. Turning the tenant switch off prevents new automatic queueing and makes already-queued code-triggered jobs exit without analysis. Operator-initiated manual jobs can bypass the tenant auto-analysis gate.
Step 2 — Tell it which brands are yours
Share of shelf needs to know "yours" from "everything else." A matched planogram's targetBrandLabels wins. Without one, the evaluator first uses tenant Shelf Product or Cluster rows marked as own brand; the card's comma-separated Own-brand labels value is the fallback for tenants that have not adopted that taxonomy.
Step 3 — Author a planogram
For compliance scoring, create a Planogram record with Status Active. Scope it to one account, to an account type (for example a supermarket class), or to neither for a tenant-wide default — the narrowest matching scope wins per outlet. Optionally set a validity window. The layout declares the expected shelf:
{ "targetBrandLabels": ["brand-a-330ml", "brand-a-1l"],
"expected": [
{ "label": "brand-a-330ml", "minFacings": 4, "shelfBand": 1 },
{ "label": "brand-a-1l", "minFacings": 2 } ] }Each expected entry names a gallery label, its minimum facings, and optionally the shelf band it should occupy. Skip this step entirely if you only want share of shelf: with no active planogram matched, runs record share of shelf and leave compliance unscored.
Step 4 — Coordinate reference-gallery maintenance
The reference gallery is an operator surface in AdminWeb → MLOps, not a tenant Setup screen. The operator can add reference crops under a detection label and reindex the gallery. A new or changed package therefore needs coordinated gallery maintenance; it is not created by changing the tenant's comma-separated own-brand labels. Track the persisted Unknown Rate and Gallery Version on Shelf Audit Results, and give those values plus representative images to the operator when recognition degrades.
Step 5 — Verify with a real visit
Upload a new test image to a qualifying VisitTaskActivity and open its related Shelf Audit Results after the worker completes. Expect a newly inserted result for that analysis, a share-of-shelf percentage when target labels are available, and a compliance score only when a planogram with expectations matched. Then confirm a deliberately below-threshold result reconciles the expected nudge.
Expected result
A committed qualifying image produces a new Shelf Audit Result rather than updating one mutable "current" row. The result records analysis time, model and gallery versions, detection totals, unknown rate, share output and planogram findings when applicable. Repeating an analysis can therefore create another result, and two results may legitimately differ after model, gallery or operating-point changes. If a result is absent, check attachment commit, host and tenant gates, job history and inference configuration before uploading the photo again.
Common problems
The photo is visible but no result appears. Confirm it is an image attachment on a configured entity, Auto-analyze shelf photos is on, and the attachment commit created a vision.shelf-analyze job. If the job is skipped or fails, check the host master switch, inference endpoint and worker configuration with the operator. Activity completion by itself is not the trigger.
Results appear but everything is "unknown product". Compare the result's model and gallery versions and provide representative crops to the MLOps operator. The operator must update and reindex the stamp-level gallery; changing a tenant target-label setting alone does not teach the detector a product.
Compliance shows "Unable to Assess". No active planogram matched this outlet — check scope and validity window — or the photo was flagged for quality. Assign a planogram that covers the outlet's account or account type, or have the rep retake the photo.
Common questions
Does the field rep have to do anything differently?
Usually not. The rep takes the image required by the configured visit activity and can do so offline. Evaluation begins only after the image attachment is committed during sync, and results arrive asynchronously. Do not tell reps they must complete the activity merely to trigger analysis unless a tenant-specific process imposes that rule.
What exactly does share of shelf measure here?
The exact metric is deployment configuration. The built-in default is detection width share, while facings and area are supported alternatives. Target labels come from the matched planogram, otherwise from own-brand Shelf Product/Cluster taxonomy, and finally from the Feature Hub CSV fallback. Read the result's stored metric before interpreting the percentage as a facing count.
Is a new product a data-science task?
Not necessarily a training run, but it is an operator task. Add representative crops under the correct label in Admin MLOps and reindex the stamp gallery. Confirm the new Gallery Version and recognition on a fresh analysis before telling field users the package is supported.