Skip to content

item-registry + item-registry-api

Cloud Run service names: item-registry, item-registry-api Tech stack: Quarkus (Java), Gradle; backed by Cloud Spanner (request tracking) and GCS (item payload staging)

item-registry and item-registry-api form a two-tier system for ingesting external item master data (from ERP, PIM, or any backoffice system) into the Pricer platform. item-registry-api is the HTTP entry point that accepts, validates, and queues item update requests. item-registry is the async worker that dequeues those requests, applies the business rules, and writes the resulting storeitemvalues.v1 DTOs into DtoFlow, where downstream services (most importantly ecc-image-render-service) pick them up.

DTO Ownership

DTO Version Why
storeitemvalues v1 Per-item key-value store; one record per t/{tenantId}/s/{storeId}/i/{itemId}/values; written by item-registry after processing each inbound update batch
itemproperties v1 Singleton per store (t/{tenantId}/s/{storeId}/itemproperties); exports the complete property catalogue (property name, numerical_id, type, max_length) including the dynamically generated protobuf descriptor for typed item payloads; written when the store's property schema changes
itemprocessingparameters v1 Singleton per store (t/{tenantId}/s/{storeId}/itemprocessingparameters); controls how item-registry handles incoming updates — specifically unknown_item_behavior (INSTALL/IGNORE/REJECT), sic_append, sic_allow_moving_sic, and reject_update_on_unlinked

CQS Subscriptions

item-registry does not subscribe to any DtoFlow DTOs. It is triggered by Pub/Sub messages published by item-registry-api.

Processing Logic

Ingestion (item-registry-api):

  1. External caller sends a PATCH /store/{storeId}/api/public/core/v1/items (single or bulk) or a multi-store variant to item-registry-api.
  2. item-registry-api validates the request (auth via OIDC tenant token, constraint validation).
  3. The item payload is serialised as JSON and written to a GCS staging bucket at {tenantId}/{requestId}.json.
  4. A Pub/Sub message is published to the item-registry topic with tenantId, storeId, requestId, and requestType (UPDATE / UPDATE_CSV / UPDATE_SIC / DELETE / DELETE_ALL).
  5. The API returns HTTP 202 Accepted with the requestId for async status polling.

Processing (item-registry):

  1. item-registry receives the Pub/Sub message at POST /process/item, validated by Google JWT validator.
  2. Reads the staged JSON file from GCS.
  3. For UPDATE / UPDATE_CSV:
  4. Streams items from the JSON payload in batches of 1 000.
  5. For each batch, reads current storeitemvalues from DtoFlow (batch gRPC read).
  6. Resolves SIC alias conflicts (scans any SIC identifiers to detect duplicates across items).
  7. Applies a patch: system-defined properties (itemId, department, itemName, itemGroup, price, presentation) are updated only when the incoming value is non-null; custom properties are upserted and can be cleared with an explicit null; SICs are appended or replaced depending on appendSics flag and sic_allow_moving_sic rule.
  8. Writes the merged storeitemvalues records back via DtoFlow streaming gRPC (putMany).
  9. For UPDATE_SIC: same as UPDATE but appendSics = false (replaces rather than appends).
  10. For DELETE: reads a JSON array of itemIds, deletes each in batches of 1 000 via DtoFlow deleteMany.
  11. For DELETE_ALL: issues a DtoFlow deleteChildren on the store ancestor ID, wiping all items.
  12. On completion (success or failure), calls back to item-registry-api (reportProcessingDone / reportProcessingFailed) so status can be returned to the original caller.

SIC handling: Secondary Item Codes (SICs) are stored as a sorted repeated string sics field on storeitemvalues. If a SIC is already owned by a different item, the incoming record is rejected for that SIC to prevent duplicate links. The sic_allow_moving_sic flag in itemprocessingparameters can override this to allow a SIC to migrate from one item to another.

itemprocessingparameters fields (PLT-2487):

Field Default Effect
unknown_item_behavior INSTALL How to handle an item update for an itemId not yet in the registry: INSTALL (create), IGNORE (skip silently), REJECT (return error)
sic_append true Whether SICs in the incoming payload are appended to or replace existing SICs
sic_allow_moving_sic false Whether a SIC already claimed by another item can be moved to the incoming item
reject_update_on_unlinked false Whether to reject an item update if that item has no active ESL link
  • ecc-image-render-service — subscribes to storeitemvalues.v1; re-renders ESL images when item data changes
  • ecclink-projector — the link between an item and its ESL; subscribed indirectly via ecclink.v1
  • item-registry-api — HTTP gateway; same logical system, separate deployment