Change detection and validation

Change Detection and Validation

Hii Retail provides advanced change detection and validation capabilities to ensure data integrity and compliance throughout the product and price lifecycle. The main services in this area are:

Change Detection
Validation Engine
Approval
Print Scheduling
Distribution

Together, these services enable you to:

Identify and output changes on an entity, including previous values
Validate changes against customer-specific rules
Hold back changes that violate any rules
Set aside changes requiring manual intervention before distribution, such as:
- Printing paper labels or posters
- Manual approval in a UI
Trigger custom actions and warnings
Distribute data to downstream services when all validations pass

Change Detection Service

The Change Detection service tracks the current state of any entity (e.g., Item, Price Specification, Item Identifier). When an update for the same id is received, it identifies what has changed and produces change events. These events are stored and can be used by UIs to display all changes for individual stores. They also serve as input for the Validation Engine.

Each change event contains a list of properties that have changed since the entity was last updated.

For more details, see the Changes Query API.

Validation Engine

The Validation Engine listens for all change events and determines if any field changes require validation. If validation is needed, it executes all applicable rules for the changed properties and produces a Validation Result.

The Validation Result is then used by the Distribution service to determine if the content is ready for downstream consumption.

How Validation Works

The Validation Engine requires defined rules to operate. If no rules exist for the changes in the event, or if none are violated, the Validation Result is valid and instructs the Distribution service to allow the change. If rules are violated, the Validation Result will include details for each violated rule.

Validation Rules can be of several types and apply different checks to the changed data. See more about Validation Rules in the API documentation.

Key properties of a Validation Rule include name, entityType, fieldName, ruleType, ruleValue, and severity.

Rule Types

The rule type defines the functional area for the rule. Possible values:

LABEL_RELEVANCE: Determines if the change should trigger label printing (relevant for stores using paper labels or posters).
VALIDATION: Used for content validation according to custom preferences. Can be coupled with an action to trigger alerts in your system or Hii Retail.
MANUAL_APPROVAL: Stops the change from being distributed, regardless of severity. Used to hold changes until manual approval is given. See Approval.
ACTION: Triggers actions without restricting the change. Recommended to set severity to ACTION as well.

Rule Values

Rule Values define the validation logic that is applied to a field change. Each rule instructs the system how to validate newValue (and in some cases previousValue) according to a specific logical condition.

Allowed values (enum):

HAS_CHANGED: This rule checks whether newValue is different from previousValue.

Violated when:

newValue ≠ previousValue
One value is null and the other is not
Arrays differ in any element or order

Examples

previousValue	newValue	Result
`"red"`	`"blue"`	❌ Violated
`10`	`10`	✔ Pass
`null`	`"x"`	❌ Violated
`[1,2]`	`[1,2,3]`	❌ Violated

MUST_HAVE_VALUE: This rule ensures that a specific field must contain a value.

Violated when:

Single: null
Array: null or empty ([])

Examples

newValue	Result
`"x"`	✔ Pass
`null`	❌ Violated
`[]`	❌ Violated

MUST_BE_INT: This rule ensures that the newValue field contains a value and that the value can be converted to an integer.

Violated when:

Value is null
Not integer-convertible
Any array item is invalid

Examples

newValue	Result
`"42"`	✔ Pass
`"12.5"`	❌ Violated
`"abc"`	❌ Violated
`["1","2","x"]`	❌ Violated

MUST_BE_BOOLEAN: This rule ensures that the newValue field contains a value (not null/empty) and that the value can be interpreted as a boolean.

Violated when:

Null
Not "true" or "false"
Any invalid array element

Examples

newValue	Result
`"true"`	✔ Pass
`"FALSE"`	✔ Pass
`"1"`	✔ Pass
`0`	✔ Pass
`"yes"`	❌ Violated
`["true","x"]`	❌ Violated

MUST_BE_NUMERIC: This rule ensures that the newValue field contains a value and that the value can be converted to a numeric (float) type. It behaves the same as MustBeFloat.

Violated when:

Null
Non-numeric string
Any array element invalid

Examples

newValue	Result
`"12.5"`	✔ Pass
`"3"`	✔ Pass
`"abc"`	❌ Violated
`["1.2","y"]`	❌ Violated

MUST_BE_FLOAT: This rule ensures that the newValue field contains a value and that the value can be converted to a float.

Violated when:

Null
Not float-convertible
Any array element invalid

Examples

newValue	Result
`"1.25"`	✔ Pass
`"true"`	❌ Violated
`"abc"`	❌ Violated

MUST_BE_ONE_OF: This rule ensures that the newValue field contains a value and that the value matches one of the allowed values provided in the rule parameters. Comparison is case-insensitive.

Parameters

    "arguments": [
        {
            "key": "mustBeOneOf.values",
            "value": ["Red", "Green", "Blue"]
        }
    ]

Violated when:

newValue not found in values
Null

Examples

newValue	Result
`"red"`	✔ Pass
`"GREEN"`	✔ Pass
`"yellow"`	❌ Violated
`null`	❌ Violated

MUST_BE_GREATER_THAN_PREVIOUS: The property must be numeric and greater than the previous value.

Violated when:

Either value missing
Any non-numeric
newValue < previousValue

Examples

previousValue	newValue	Result
`10`	`11`	✔ Pass
`11`	`10`	❌ Violated
`"10"`	`Reduced`	❌ Violated
`null`	`5`	❌ Violated

MUST_BE_SMALLER_THAN_PREVIOUS: The property must be numeric and smaller than the previous value.

Violated when:

Missing values
Non-numeric
newValue > previousValue

Examples

previousValue	newValue	Result
`10`	`9`	✔ Pass
`9`	`10`	❌ Violated
`8`	`text`	❌ Violated

MUST_BE_GREATER_THAN_THRESHOLD: The property must be numeric and greater than a defined threshold.

Parameters

"arguments": [
    {
      "key": "MustBeGreaterThanThreshold.threshold",
      "value": "40.5"
    }
  ]

Violated when:

Null
Non-numeric
newValue ≤ threshold

Examples

newValue	Result
`150`	✔ Pass
`100`	❌ Violated
`"abc"`	❌ Violated

MUST_BE_SMALLER_THAN_THRESHOLD: The property must be numeric and smaller than a defined threshold.

Parameters

"arguments": [
    {
      "key": "MustBeSmallerThanThreshold.threshold",
      "value": "1200"
    }
  ]

Violated when:

Null
Non-numeric
newValue ≥ threshold

Examples

newValue	Result
`10`	✔ Pass
`50`	❌ Violated
`"x"`	❌ Violated

MUST_MATCH_REGEX: Ensures newValue matches the full regex expression.

Parameters

"arguments": [
    {
      "key": "regex.regexExpression",
      "value": "^[A-Z]{3}[0-9]{2}$"
    }
  ]

Violated when:

Value does not fully match regex
Null

Examples

newValue	Result
`"ABC12"`	✔ Pass
`"abc12"`	❌ Violated
`"AB123"`	❌ Violated
`null`	❌ Violated

HAS_NOT_CHANGED: Triggered when newValue equals previousValue.

Violated when:

Values are identical
Arrays equal in content and order
Both values null

Examples

previousValue	newValue	Result
`"A"`	`"A"`	❌ Violated
`5`	`7`	✔ Pass
`[1,2]`	`[1,2]`	❌ Violated
`null`	`null`	❌ Violated

IS_EQUAL_TO: Triggers when newValue exactly equals the provided value. Comparison is case-sensitive.

Parameters

"arguments": [
    {
      "key": "isEqualTo.value",
      "value": "FORBIDDEN"
    }
  ]

Violated when:

newValue is exactly equal to the provided value (case-sensitive)
Both values null

Examples

newValue	Result
`"FORBIDDEN"`	❌ Violated
`"forbidden"`	✔ Pass
`"allowed"`	✔ Pass
`null` (and param null)	❌ Violated

Approval

The MANUAL_APPROVAL rule type is used to hold back changes that require manual approval before distribution.

A typical use case is price changes for franchise stores, which may require local approval before being applied.

Example:
A large retailer with four brands controls prices at the brand level. One brand consists of many franchise stores that want to control pricing locally. The manual approval process stops all price changes for these stores. Store managers use a Manual Approval UI to review, approve, or deny price changes daily. Approved changes are applied; denied changes are not.

Print Scheduling

The LABEL_RELEVANCE rule type is designed for manual label printing processes. Changes caught by this rule mark the entity for printing. Hii Retail identifies and schedules what needs to be printed but does not manage the print process itself; integration is required.

Once printing is confirmed via the input API, Hii Retail marks the print schedules as completed. The changes are then ready for distribution, unless manual approval is also required.

See the Label Query API for more information.

Distribution

The Distribution service holds all changes until a Validation Result is received from the Validation Engine. If the result is positive, the data is distributed. If negative, actions are performed according to the severity defined in the Validation Result.

Note: Some actions may be handled by external services, not natively by Hii Retail or the Distribution service.

Change Detection and Validation

Change Detection Service​

Validation Engine​

How Validation Works​

Rule Types​

Rule Values​

Approval​

Print Scheduling​

Distribution​

Change Detection Service

Validation Engine

How Validation Works

Rule Types

Rule Values

Approval

Print Scheduling

Distribution