Fluent Commerce Logo
Docs

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.