Skip to content

Flow: Item Update

Trigger: An ERP or PIM system pushes updated item data to item-registry-api (REST) Key services: item-registry, studio-link-evaluator, studio-renderer, eslimage-merger, pricer-server Key DTOs: storeitemvalues, studiolink, studioeslimage, eslimage

Item data changes are one of the most frequent events in the system — prices change daily, promotional flags toggle, names are corrected. When updated data arrives at item-registry-api, it writes a new storeitemvalues DTO. studio-link-evaluator subscribes to these changes and re-evaluates every link that references the affected item. The critical idempotency point is here: if the re-evaluation produces exactly the same studiolink as before (same resolved design, same item reference, same render context hash), no write is performed and the pipeline terminates immediately — no re-render, no re-transmit, no unnecessary churn on the ESL hardware. Only if the evaluation result genuinely differs (a different design has become the winner, or a property value used in the label has changed) does the pipeline continue through render and transmit. This behaviour keeps the system efficient at scale: a store with thousands of ESLs can process a bulk price update without re-rendering every label unnecessarily.

Steps

  1. ERP/PIM → item-registry-api: The external system calls the item-registry-api REST endpoint with the updated item payload. The API accepts the request, validates the item identifier against the tenant/store scope, and applies itemprocessingparameters rules: if the item is previously unknown and the accept_unknown_items parameter is false, the update is rejected; if SIC (Store Item Catalogue) behaviour is enabled, additional validation applies.

  2. item-registry → DTOflow (storeitemvalues): item-registry processes the validated update and writes a new storeitemvalues DTO (id: t/{tenantid}/s/{storeid}/items/{itemid}/values). The DTO is a flat key-value map of all item fields received from the ERP/PIM, plus metadata (source system, ingestion timestamp).

  3. DTOflow (CQS) → studio-link-evaluator: CQS emits a change notification on storeitemvalues. studio-link-evaluator subscribes to storeitemvalues changes. It fetches the updated values and looks up all link.v2 DTOs that reference this item (via the by_item alias on studiolink: t/{tenantid}/s/{storeid}/items/{itemid}/studiolink). This may be multiple links if the same item is displayed on several ESLs.

  4. studio-link-evaluator — evaluation: For each link referencing the item (looked up via the by_item alias on studiolink), studio-link-evaluator fetches the link.v2 and the relevant communicationpack, then re-evaluates the CEL scenario rules with the new storeitemvalues. It computes the new winning design ID and render context (a deterministic hash of the inputs that affect the rendered output).

Where does communicationpack come from? communicationpack is owned by studio-scenario-library. It is a tenant-level (or store-level) container of CEL scenario rules: each rule pairs a condition (a CEL expression over item properties, store context, etc.) with a target design. studio-link-evaluator does not write communicationpack itself — it only reads. When a scenario library author publishes new rules, the corresponding communicationpack.v1 write triggers studio-link-evaluator to re-evaluate all affected links the same way an item-value change does.

  1. Idempotency check — pipeline fork:
  2. If evaluation result is unchanged (same design ID, same render-context hash as the existing studiolink): studio-link-evaluator does not write a new studiolink. The pipeline stops here for this ESL. No re-render, no re-transmit.

  3. If evaluation result changed (different design selected, or render-context hash differs because a bound property value changed): studio-link-evaluator writes an updated studiolink DTO and the pipeline continues from step 6.

  4. DTOflow (CQS) → studio-renderer: CQS emits a change notification on studiolink. studio-renderer fetches the studiolink, the resolved design DTO, and the new storeitemvalues. It re-renders the PNG with the updated item data.

  5. studio-renderer → dtoflow-lfs + DTOflow (studioeslimage): The new PNG is uploaded to dtoflow-lfs and a new studioeslimage DTO is written with the updated file_path. The old PNG in LFS is superseded.

  6. DTOflow (CQS) → eslimage-merger: CQS notifies eslimage-merger. The merger re-runs its priority logic (Studio wins over ECC), writes an updated eslimage DTO pointing to the new PNG.

  7. DTOflow (CQS) → pricer-server: CQS notifies pricer-server of the updated eslimage. It fetches the storeesl (for hardware routing) and esldriver (for rotation), downloads the new PNG from dtoflow-lfs, and pushes it to the physical ESL over RF/IR.

  8. ESL hardware acknowledgment: The physical ESL renders the new image and acknowledges. pricer-server updates its internal state DB and PUTs storeeslstatus accordingly (remains OK for a label that was already linked; transitions back to OK if it was in ROAMING).

Sequence diagram

sequenceDiagram
    participant ERP as ERP/PIM System
    participant IR as item-registry
    participant DTOflow
    participant SLE as studio-link-evaluator
    participant SR as studio-renderer
    participant Merger as eslimage-merger
    participant PS as pricer-server
    participant ESL as Physical ESL

    ERP->>IR: POST /items/{id} (updated values)
    IR->>DTOflow: Write storeitemvalues DTO
    DTOflow-->>SLE: CQS: storeitemvalues changed
    SLE->>DTOflow: Fetch link.v2 DTOs by_item alias
    SLE->>DTOflow: Fetch communicationpack
    Note over SLE: Re-evaluate CEL with new item data

    alt Evaluation result unchanged (same design + render context)
        Note over SLE: No write — pipeline stops here
    else Evaluation result changed
        SLE->>DTOflow: Write updated studiolink DTO
        DTOflow-->>SR: CQS: studiolink changed
        SR->>DTOflow: Fetch studiolink, design, storeitemvalues
        SR->>DTOflow: Upload new PNG → dtoflow-lfs
        SR->>DTOflow: Write studioeslimage DTO
        DTOflow-->>Merger: CQS: studioeslimage changed
        Merger->>DTOflow: Fetch studioeslimage + ecceslimage
        Merger->>DTOflow: Write eslimage DTO
        DTOflow-->>PS: CQS: eslimage changed
        PS->>DTOflow: Fetch eslimage, storeesl, esldriver
        PS->>ESL: Push updated PNG over RF/IR
        ESL-->>PS: Acknowledge image received
        PS->>DTOflow: Write storeeslstatus → OK
    end

Key DTOs involved

DTO Role in this flow Page
storeitemvalues.v1 Updated item data that triggers re-evaluation; flat key-value map from ERP/PIM storeitemvalues.v1
link.v2 Fetched by studio-link-evaluator to find all ESLs affected by this item link.v2
communicationpack.v1 CEL scenario rules evaluated against the new item values to determine winning design communicationpack.v1
studiolink.v1 Updated only if evaluation produces a different result; the idempotency gate for the whole pipeline studiolink.v1
studioeslimage.v1 New rendered PNG produced only when studiolink changes studioeslimage.v1
eslimage.v1 Merged authoritative page image; updated only when studioeslimage changes eslimage.v1
  • Item–ESL Linking — steps 6–10 of this flow are identical to steps 6–10 of the linking flow; linking flow contains the full detail
  • Design Publication — a design change also triggers studio-link-evaluator re-evaluation; same idempotency logic applies