Alerts — rules & perimeter

Rules

An alert’s rules decide which entities trigger it, by tag.

"rules": {
  "operator": "AND",
  "tagRules": [
    { "tagId": "<uuid>", "mode": "INCLUDE" },
    { "tagId": "<uuid>", "mode": "EXCLUDE" }
  ],
  "checkLevel": "PRODUCT"
}

Field	Meaning
`operator`	`AND` (all tag rules must hold) or `OR` (any).
`tagRules`	One or more `{ tagId, mode }` entries; at least one required.
`mode`	`INCLUDE` (tag must be present) or `EXCLUDE` (must be absent).
`checkLevel`	(optional) The level the rules are evaluated at: `SHOP`, `BRAND`, `PRODUCT`, `VARIANT`, `INVENTORY_ITEM`. Omit it for no level restriction.

To alert on a metric threshold, first create a tagging rule that tags the matching entities, then reference that tag here with mode: "INCLUDE".

Perimeter (scope)

scope narrows which part of the catalog the alert covers. Every dimension is optional; an empty/absent one means “no restriction”.

"scope": {
  "storesIds": ["<uuid>"],
  "brandIds": ["<uuid>"],
  "productIds": [],
  "taxonomies": [ { "type": "SIZE", "values": ["S", "M"] } ],
  "collections": ["<uuid>"]
}

Field	Restricts to
`storesIds`	Specific shops.
`brandIds`	Specific brands.
`productIds`	Specific products.
`taxonomies`	Dimension values — each `{ type, values }` (e.g. SIZE, COLOR, CATEGORY).
`collections`	Specific collections.

Trigger types

When an instance is raised, it carries a trigger type describing why:

Trigger type	Meaning
`THRESHOLD_REACHED`	The condition is met now.
`THRESHOLD_APPROACHING`	The condition is being approached (an `approach_percentage` is recorded on the instance).
`FORECASTED_THRESHOLD`	A forecast predicts the condition will be met.

Condition operators (reference)

The metric comparison operators — used by the tagging-rule metric conditions that feed alert tags — are: LOWER_THAN, LOWER_OR_EQUAL, GREATER_THAN, GREATER_OR_EQUAL, EQUAL, NOT_EQUAL, plus the percentiles TOP_PERCENT / BOTTOM_PERCENT. Percentile operators are evaluated by the data platform (a percent_rank() window over the scoped population).

The scalar operators apply at row level; the two percentile operators only make sense across a population, so they’re resolved on the data platform.

API integration

API recipes

Platform & data model

Decision layer (reference)

Operations & infrastructure

Ingestion specs (reference)

Workflows (reference)

Tagging rules (reference)

Alerts (reference)

Alerts — rules & perimeter

Rules

Perimeter (scope)

Trigger types

Condition operators (reference)

​Rules

​Perimeter (scope)

​Trigger types

​Condition operators (reference)

Rules

Perimeter (scope)

Trigger types

Condition operators (reference)