Controls Utilities Overview
Essential knowledgeCore knowledge to understand Fluent Commerce
Intended Audience:
Technical User
Author:
Holger Lierse
Changed on:
26 Aug 2026
Overview
The Controls Utilities library (`util-controls`) applies controls to a catalog position in a consistent, reusable way. Rather than each rule reimplementing how to find and apply controls, a rule calls `ControlUtils.applyControls(...)`, which loads the required data from GraphQL, evaluates the applicable controls, and returns an updated position together with an audit of every change.Key points
- Prerequisites: Java, Maven, and JUnit; Rules SDK (Rules and the rule Context); Understanding of Fluent Inventory concepts and domain model
- Single entry point:
`ControlUtils.applyControls(...)`resolves and applies controls in one call - Standard control types:
`ControlUtils`includes inclusion, exclusion, buffer, limit, and threshold controls by default - Specificity-aware: position/product/variant-level controls take precedence over group-level (bulk) controls
- Auditable: the result includes a before/after snapshot for every control the utility applied
- Extensible: supply custom control functions to support control types specific to your implementation
Value Proposition
The core benefit is consistency: the utility resolves and applies controls the same way everywhere.- Reusable logic: one implementation of control resolution, shared across every rule that needs it.
- Self-contained: the utility loads the position and control data it needs directly from GraphQL; rules do not need to be chained to pass data.
- Configurable: you pass in the set of control types to apply, and can extend them per implementation.
Key Concepts
- Control: adjusts a position's
`status`and/or`quantity`when its context matches the position. - Control group: a collection of controls associated with a catalog. A catalog normally has a single control group; multiple groups are supported via the catalog's
`controlGroups`attribute. - Bulk (group-level) control: a control whose type is prefixed
`BULK_`, applying across a group. - Position-level control: a control targeting a specific product or position; takes precedence over bulk controls.
- Control function: the pairing of "does this control apply to this position?" and "how is it applied?". Build the standard set with
`ControlTypes.buildControlFunctions()`.
Explanation Through an Example
Resolve and apply the standard controls to a position, then persist the result:The call returns a`PositionUpdateResult` carrying the updated position and an audit of every control the utility applied.