Controls Utilities
Package
Changed on:
25 Aug 2026
| Publisher: | Fluent Commerce |
|---|---|
| Website: | Fluent Commerce |
Download Package
Version History
Overview
`util-controls` is a helper library called from a Rule. Given a position, it resolves the controls that apply to that position - both group-level (bulk) controls and position/product/variant-level controls - and applies them in a defined order to produce an updated position, along with an audit trail of every change.The library removes the need to hand-write control resolution logic in each rule: a single call to `ControlUtils.applyControls(...)` loads the required data from GraphQL, evaluates the controls, and returns the result.Detailed Technical Description
Usage
A control adjusts a position's`status` and/or `quantity` when the control's context matches the position. Controls are grouped under a control group, which is associated with a catalog.Resolution order- The applicable control group(s) for the catalog are resolved (from the catalog and, where present, its
`controlGroups`attribute). - Bulk (group-level) controls - those whose type is prefixed
`BULK_`- are loaded for those groups and sorted by`executionOrder`. - Position-level controls - those whose ref targets the position's product or position ref - are loaded and take precedence over bulk controls.
- Each configured control function is applied in turn. For each function, the most specific matching control wins: position-level controls are checked before bulk controls.
- Inclusion - sets the position
`status`to`ACTIVE`. - Exclusion - sets the position
`status`to`INACTIVE`. - Buffer - adjusts
`quantity`by an absolute amount (`quantity`) or by a`percentage`(optionally bounded by`min`/`max`). - Limit - clamps
`quantity`between`min`and`max`. - Threshold - sets
`status`(from the control's`status`, default`ACTIVE`) when`quantity`is at or below the configured`threshold`.
`context` describing which positions it applies to. A `CATALOGUE` context always matches; `PRODUCT`, `VARIANT`, `LOCATION`, `CATEGORY`, `NETWORK` and `POSITION` contexts are matched against the corresponding values on the position and its related product/location data.Behavioral notes
- Only controls with
`status="ACTIVE"`are loaded. - Resolved control groups and bulk controls are cached with a 10-minute expiry. Changes to control or catalog configuration may therefore take up to ~10 minutes to take effect.
1<dependency>
2 <groupId>com.fluentcommerce</groupId>
3 <artifactId>util-controls</artifactId>
4 <version>${util-controls.version}</version>
5</dependency>| Capability type: | Tool |
|---|
