Controls Utilities Overview
Essential knowledge
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:1// ApplyControlsToPosition
2public void run(Context context) {
3 String virtualPositionRef = context.getEvent().getEntityRef();
4 String virtualCatalogueRef = context.getEvent().getRootEntityRef();
5 String inventoryCatalogueRef = context.getProp(PROP_INVENTORY_CATALOGUE_REF);
6 String inventoryPositionRef = virtualPositionRef; // assumes the inventory position ref matches the virtual position ref
7
8 ControlUtils.PositionUpdateResult result =
9 ControlUtils.applyControls(context, inventoryCatalogueRef, inventoryPositionRef);
10
11 context.action().mutation(UpdatePositionMutation.builder()
12 .catalogueRef(virtualCatalogueRef)
13 .ref(virtualPositionRef)
14 .quantity(result.getPosition().getQuantity())
15 .build(),
16 result.getPosition().getStatus()
17 );
18}The call returns a
`PositionUpdateResult` carrying the updated position and an audit of every control the utility applied.
