How Controls Utilities work

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

Topic

Authors:

Holger Lierse, Kirill Gaiduk

Changed on:

24 Aug 2026

Overview

The articles walks you through the Controls Utilities bundle (`util-controls`): a library that applies controls to catalog positions from within a Rule, so that inclusion, exclusion, buffer, limit and threshold logic is resolved and applied the same way everywhere it is used.Prerequisites

Basic understanding of the Utility Bundles
Familiarity with writing Rules using the Rules SDK
Completion of the Getting Started with the Utility Bundles guide

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

Java Docs

The helper methods contained in the Utility Bundles libraries are many and varied, so the JavaDocs provided with the packages should be treated as the source of truth for documentation.

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()`.

Note

The utility loads only controls with `status = "ACTIVE"`, and caches results for 10 minutes.This bundle uses `context`-based controls with a `BULK_` type prefix (for example `BULK_BUFFER`), applied from a rule. These are distinct from the classic Inventory Reference Module controls (`QUANTITY_BUFFER` and `EXCLUSION`, targeted by ref such as `<controlGroupRef>:QUANTITY_BUFFER:<productRef>`), which are applied during Available to Sell calculation. The two mechanisms can coexist in the same control group; this bundle only reads its own `BULK_` controls. See the Control Groups and Controls article for the classic model.

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}

Note

The convenience overload `applyControls(context, inventoryCatalogueRef, inventoryPositionRef)` assumes the inventory position ref is the same as the virtual position ref, and uses the default position supplier and the default set of control functions.

The call returns a `PositionUpdateResult` carrying the updated position and an audit of every control the utility applied.

Overview

Key points

Specificity-aware: position/product/variant-level controls take precedence over group-level (bulk) controls
Auditable: `ControlUtils` records every applied control with a before/after snapshot
Extensible: the position source and the set of control functions are both parameters you can supply

Applying Controls to a Position

`applyControls(context, inventoryCatalogueRef, inventoryPositionRef)`

The convenience overload. Loads the position with the default position supplier and applies the default set of control functions. Use this when the position maps one-to-one to the triggering event.

1// applyControls (convenience)
2ControlUtils.PositionUpdateResult result =
3        ControlUtils.applyControls(context, inventoryCatalogueRef, inventoryPositionRef);

Note

This overload assumes the inventory position ref is the same as the virtual position ref. If that is not true for your model, use the `defaultPositionSupplier` (or your own supplier) with the overload below.See the Controls Utilities Overview for a complete example using this overload.

`applyControls(context, positionSupplier, controlFunctions)`

Applies the given control functions to the position produced by `positionSupplier`. Use this to control where the position comes from (for example, an aggregate across locations) and which control functions run.

1// applyControls (custom supplier and functions)
2ControlUtils.PositionUpdateResult result = ControlUtils.applyControls(
3    context,
4    ControlUtils.defaultPositionSupplier(context, inventoryCatalogueRef, inventoryPositionRef),
5    ControlTypes.buildControlFunctions()
6);

`applyControls(context, positionSupplier, controlFunctions, defaultControls)`

Like the previous overload, but the `ControlUtils` adds `defaultControls` to the loaded controls where a control of that type is not already present. Use this to guarantee a baseline of behavior when no matching control exists.

`applyControlsWithDefaultBehavior(context, positionSupplier, controlFunctions)`

A shorthand for the overload above that supplies `ControlTypes.DEFAULT_THRESHOLD_CONTROL_ACTIVE` as the default control, so a position with no matching threshold control defaults to `ACTIVE`.

1// applyControlsWithDefaultBehavior
2ControlUtils.PositionUpdateResult result = ControlUtils.applyControlsWithDefaultBehavior(context,
3        ControlUtils.defaultPositionSupplier(context, inventoryCatalogueRef, inventoryPositionRef),
4        ImmutableList.of(ControlTypes.CONTROL_FUNCTION_THRESHOLD));

Position Suppliers

A position supplier is a `Supplier<Position>` that tells `applyControls` which position to operate on. `ControlUtils` provides two.

`defaultPositionSupplier(context, inventoryCatalogueRef, inventoryPositionRef)`

Loads a single inventory position and enriches it with the standard related product and location information.

Note

The resulting position takes its identity (catalog ref and position ref) from the triggering event, while the util loads inventory data using the supplied `inventoryCatalogueRef` and `inventoryPositionRef`. This assumes the inventory position ref corresponds to the event's position.

`aggregatePositionSupplier(...)`

Produces a single position whose `quantity` is the sum of on-hand across multiple locations, for a product. `ControlUtils` provides three variants:

`aggregatePositionSupplier(context, inventoryCatalogueRef, productRef, activeStatuses)`
aggregates the positions passed to it, counting only those whose status is in `activeStatuses`.
`aggregatePositionSupplier(context, inventoryCatalogueRef, productRef, networkRef, activeStatuses)`
aggregates across every location in the given network.
`aggregatePositionSupplier(context, inventoryCatalogueRef, productRef, locationSupplier, activeStatuses)`
aggregates across the locations returned by a custom `locationSupplier`.

1// applyControls with an aggregate supplier
2ControlUtils.PositionUpdateResult result = ControlUtils.applyControls(context,
3    ControlUtils.aggregatePositionSupplier(
4        context, 
5        inventoryCatalogueRef, 
6        productRef, 
7        ImmutableList.of("ACTIVE")
8    ),
9    ControlTypes.buildControlFunctions()
10);

`locationsByNetworkSupplier(context, networkRef)`

Returns a `Supplier<List<LocationReference>>` of the locations in a network. Pass it to the `locationSupplier` variant of `aggregatePositionSupplier` when you want to aggregate over a network but supply the locations yourself.

Supplying Custom Control Functions

The control functions passed to `applyControls` determine which control types `ControlUtils` recognizes and how each applies. `ControlTypes.buildControlFunctions()` returns the standard set; pass your own list to add or override behavior. The example below assumes you have statically imported the relevant members of `ControlTypes` (`ControlFunction`, `CONTROL_FUNCTION_*`, `appliesToPosition`, `EXCLUSION_TYPE`):

1// applyControls with custom control functions
2ControlUtils.applyControls(context,
3    ControlUtils.defaultPositionSupplier(context, inventoryCatalogueRef, inventoryPositionRef),
4    ImmutableList.of(
5            CONTROL_FUNCTION_INCLUSION,
6            // Override the default EXCLUSION control function
7            new ControlFunction(20,
8                    (position, control) -> control.getType().endsWith(EXCLUSION_TYPE) && appliesToPosition(position, control),
9                    (position, control) -> position.update("INACTIVE").update(0)
10            ),
11            CONTROL_FUNCTION_BUFFER
12            // Optionally add more here
13    )
14);

Note

A `ControlFunction` takes an `index` (the order in which the system applies functions), an is-applicable predicate, and an apply function that returns the updated position. `ControlFunction` and the standard control functions and types live in `ControlTypes`.

The Result: `PositionUpdateResult`

Every overload returns a `PositionUpdateResult`:

`getPosition()` - the updated position (`status` and `quantity` after all controls were applied).
`getPositionBefore()` - the original position, before any control was applied.
`getAudit()` - an ordered list of `PositionUpdate` entries, one per applied control.
`getMessage()` - a human-readable summary, for example `"2 controls were applied"`.

Each `PositionUpdate` in the audit exposes `getBefore()`, `getAfter()` and `getControl()`, giving the position on either side of that single control and the control that applied the change.

Overview

Key points

Behavior is chosen by the `type` suffix: the suffix of `type` selects the control function of `type` (`...INCLUSION`, `...EXCLUSION`, `...BUFFER`, `...LIMIT`, `...THRESHOLD`).
Group-level controls use the `BULK_` prefix: Control Utils loads a control as group-level (bulk) only when its `type` begins with `BULK_`, for example `BULK_BUFFER`.
Every control needs a `context:` the `context` value decides which positions a control applies to. A control with no `context` never applies; a `CATALOGUE` context always matches.
Only `ACTIVE` controls apply: the utility only loads controls whose top-level status is `ACTIVE`.
Order is explicit: `executionOrder` orders controls within a group in ascending order; lower runs first.

Anatomy of a Control

Each control belongs to a control group. When the utility loads a control, it has the following structure:

1{
2  "ref": "Ctrl-001",
3  "type": "BULK_BUFFER",
4  "status": "ACTIVE",
5  "name": "Buffer for Category ABC",
6  "executionOrder": 0,
7  "values": [
8    { 
9        "name": "context", 
10        "type": "CONTEXT", 
11        "value": [ ... ] 
12    }
13  ]
14}

`type` - selects the control function by its suffix (`...INCLUSION`, `...EXCLUSION`, `...BUFFER`, `...LIMIT`, `...THRESHOLD`). Group-level (bulk) controls are loaded when `type` begins with `BULK_`; Position, Product and Variant level controls are matched by `ref`.
`status` - only controls with a `status` of `ACTIVE` are loaded.
`executionOrder` - orders controls within a group (ascending); the lowest value is applied first. When several controls of the same type can match one position only the first is applied, so give those controls distinct orders.
`values` - the configuration. Every control carries a `context` value that decides which positions it applies to, plus any type-specific values described below.

Targeting with `context`

The `context` value is an array of matcher objects. All objects in the array must match for the control to apply to a position; where an individual object's `value` is itself an array, any one of those values may match.

1{ 
2    "name": "context", 
3    "type": "CONTEXT", 
4    "value": [
5        { 
6            "type": "CATEGORY", 
7            "property": "ref", 
8            "value": "ABC" 
9        }
10    ]
11}

`type` - what to match against: `PRODUCT`, `VARIANT`, `LOCATION`, `CATEGORY`, `NETWORK` or `POSITION`. `CATALOGUE` is a special case that always matches (used for catalog-wide controls).
`property` - the path within that entity, for example `ref`, `status`, or an attribute via `attributes.byName.<attributeName>`.
`value` - the expected value at that path. A single value, or an array of values of which any one may match.

The structure of a `context` matcher:

A catalog-wide control (applies to every position in the catalog):

1{ 
2    "name": "context", 
3    "type": "CONTEXT", 
4    "value": [ 
5        { 
6            "type": "CATALOGUE" 
7        } 
8    ]
9}

Multiple matchers are combined with AND. The following applies only to product `AH8050` in network `F_NSW`:

1{ 
2    "name": "context", 
3    "type": "CONTEXT", 
4    "value": [
5        { 
6            "type": "NETWORK", 
7            "property": "ref", 
8            "value": "F_NSW" 
9        },
10        { 
11            "type": "PRODUCT", 
12            "property": "ref", 
13            "value": "AH8050" 
14        }
15    ]
16}

Control Types

Inclusion

Sets the matched position's `status` to `ACTIVE`. Carries only a `context`.

1{
2  "ref": "Ctrl-inc-1",
3  "type": "BULK_INCLUSION",
4  "status": "ACTIVE",
5  "name": "Include Category ABC",
6  "executionOrder": 0,
7  "values": [
8    { 
9        "name": "context", 
10        "type": "CONTEXT", 
11        "value": [ 
12            { 
13                "type": "CATEGORY", 
14                "property": "ref", 
15                "value": "ABC"
16            } 
17        ] 
18    }
19  ]
20}

Exclusion

1{
2  "ref": "Ctrl-ex-1",
3  "type": "BULK_EXCLUSION",
4  "status": "ACTIVE",
5  "name": "Exclude Category ABC",
6  "executionOrder": 0,
7  "values": [
8    { 
9        "name": "context", 
10        "type": "CONTEXT", 
11        "value": [ 
12            { 
13                "type": "CATEGORY", 
14                "property": "ref", 
15                "value": "ABC" 
16                
17            } 
18        ] 
19    }
20  ]
21}

Sets the matched position's `status` to `INACTIVE`. Carries only a `context`.

Buffer (Absolute)

Adjusts the position `quantity` by a fixed amount. A negative `quantity` reduces available stock; a positive one increases it.

1{
2  "ref": "Ctrl-buf-1",
3  "type": "BULK_BUFFER",
4  "status": "ACTIVE",
5  "name": "Reduce size 10 by 10",
6  "executionOrder": 0,
7  "values": [
8    { 
9        "name": "context", 
10        "type": "CONTEXT", 
11        "value": [ 
12            { 
13                "type": "VARIANT", 
14                "property": "attributes.byName.size", 
15                "value": "10" 
16            } 
17        ] 
18    },
19    { 
20        "name": "quantity", 
21        "type": "INTEGER", 
22        "value": -10 
23    }
24  ]
25}

Buffer (Percentage)

A buffer control uses one of two values: a `quantity` value (the absolute buffer shown above) or a `percentage` value. When the control has no `quantity` value, the utility calculates the buffer as the `percentage` of the position's current quantity. A positive percentage increases the quantity; a negative one reduces it.

1{
2  "ref": "Ctrl-buf-2",
3  "type": "BULK_BUFFER",
4  "status": "ACTIVE",
5  "name": "Buffer Category ABC by 50%",
6  "executionOrder": 0,
7  "values": [
8    { "name": "context", "type": "CONTEXT", "value": [ { "type": "CATEGORY", "property": "ref", "value": "ABC" } ] },
9    { "name": "percentage", "type": "INTEGER", "value": 50 }
10  ]
11}

Note

Add `min` and/or `max` values to bound the calculated buffer amount. They are signed bounds (as with Limit): the buffer is clamped to the range `[min, max]`. Because a buffer is usually a reduction, this typically reads as "reduce by the percentage, but hold back no more than `min` and no less than `max`". For example `percentage: -10, min: -100, max: -10` reduces by 10%, capped at 100 units and floored at 10 units: a position with 2000 on hand is reduced by 100 (to 1900), and one with 50 on hand is reduced by 10 (to 40).

Limit

Clamps the position `quantity` so it is never below `min` nor above `max`.

1{
2  "ref": "Ctrl-lim-1",
3  "type": "BULK_LIMIT",
4  "status": "ACTIVE",
5  "name": "Cap AH8050 in F_NSW at 80",
6  "executionOrder": 1,
7  "values": [
8    { 
9        "name": "context", 
10        "type": "CONTEXT", 
11        "value": [
12            { "type": "NETWORK", "property": "ref", "value": "F_NSW" },
13            { "type": "PRODUCT", "property": "ref", "value": "AH8050" }
14        ]
15    },
16    { 
17        "name": "min", 
18        "type": "INTEGER", 
19        "value": 80 
20    },
21    { 
22        "name": "max", 
23        "type": "INTEGER", 
24        "value": 80
25    }
26  ]
27}

Threshold

Sets the position `status` when the `quantity` is at or below `threshold`. It changes status only, never quantity.

1{
2  "ref": "Ctrl-thr-1",
3  "type": "BULK_THRESHOLD",
4  "status": "ACTIVE",
5  "name": "Mark UNISEX_SHOES at risk under 200",
6  "executionOrder": 0,
7  "values": [
8    { 
9        "name": "context", 
10        "type": "CONTEXT", 
11        "value": [ 
12            { "type": "CATEGORY", "property": "ref", "value": "UNISEX_SHOES" } 
13        ]
14    },
15    { 
16        "name": "threshold", 
17        "type": "NUMBER", 
18        "value": 200 
19    },
20    { 
21        "name": "status", 
22        "type": "STRING", 
23        "value": "AT_RISK" 
24    }
25  ]
26}

Note

`threshold` is optional; when omitted, the control applies whenever its `context` matches (regardless of quantity). `status` is optional and defaults to `ACTIVE`.

Combined Example

A control group typically holds several controls of different types. The util applies them in a fixed order - inclusion, then exclusion, then buffer, then limit, then threshold - and the effect is cumulative: each type sees the quantity and status left by the previous one. Within a single type, the utility applies the most specific matching control (position or product level before group level).The controls below belong to one group scoped to category `ABC`: an absolute buffer and a two-tier threshold.

1[
2  {
3    "ref": "Ctrl-buf",
4    "type": "BULK_BUFFER",
5    "status": "ACTIVE",
6    "name": "Hold back 10 for Category ABC",
7    "executionOrder": 0,
8    "values": [
9      {
10        "name": "context",
11        "type": "CONTEXT",
12        "value": [
13          {
14            "type": "CATEGORY",
15            "property": "ref",
16            "value": "ABC"
17          }
18        ]
19      },
20      {
21        "name": "quantity",
22        "type": "INTEGER",
23        "value": -10
24      }
25    ]
26  },
27  {
28    "ref": "Ctrl-thr-oos",
29    "type": "BULK_THRESHOLD",
30    "status": "ACTIVE",
31    "name": "Out of stock at 0",
32    "executionOrder": 0,
33    "values": [
34      {
35        "name": "context",
36        "type": "CONTEXT",
37        "value": [
38          {
39            "type": "CATEGORY",
40            "property": "ref",
41            "value": "ABC"
42          }
43        ]
44      },
45      {
46        "name": "threshold",
47        "type": "NUMBER",
48        "value": 0
49      },
50      {
51        "name": "status",
52        "type": "STRING",
53        "value": "OUT_OF_STOCK"
54      }
55    ]
56  },
57  {
58    "ref": "Ctrl-thr-risk",
59    "type": "BULK_THRESHOLD",
60    "status": "ACTIVE",
61    "name": "At risk at 10",
62    "executionOrder": 1,
63    "values": [
64      {
65        "name": "context",
66        "type": "CONTEXT",
67        "value": [
68          {
69            "type": "CATEGORY",
70            "property": "ref",
71            "value": "ABC"
72          }
73        ]
74      },
75      {
76        "name": "threshold",
77        "type": "NUMBER",
78        "value": 10
79      },
80      {
81        "name": "status",
82        "type": "STRING",
83        "value": "AT_RISK"
84      }
85    ]
86  }
87]

Language: json

Name: Combined Example

Description:

Applied to a position in category `ABC` with 15 units on hand:1. Buffer subtracts 10: the quantity of 15 becomes 5.
2. Threshold then runs against the buffered quantity of 5. The util considers the two threshold controls in `executionOrder`, and the first that applies wins: "Out of stock at 0" needs a quantity of 0 or lower (5 does not qualify), so "At risk at 10" applies and sets the status to `AT_RISK`.The resulting `PositionUpdateResult` therefore has a quantity of 5, a status of `AT_RISK`, and an audit of two entries (the buffer, then the threshold), each with its before and after snapshot. See the How Controls Utilities work for the result structure.

Note

Only one control is applied per type in a single run: for each control function the util applies the most specific matching control. Here that means one of the two threshold controls takes effect, not both.

How Controls Utilities work

Overview

Controls Utilities Overview

Overview

Key points

Value Proposition

Key Concepts

Explanation Through an Example

Related content

How Controls Utilities work

Control Utils

Controls Utilities

Control Types

Control Utils

Overview

Key points

Applying Controls to a Position

`applyControls(context, inventoryCatalogueRef, inventoryPositionRef)`

`applyControls(context, positionSupplier, controlFunctions)`

`applyControls(context, positionSupplier, controlFunctions, defaultControls)`

`applyControlsWithDefaultBehavior(context, positionSupplier, controlFunctions)`

Position Suppliers

`defaultPositionSupplier(context, inventoryCatalogueRef, inventoryPositionRef)`

`aggregatePositionSupplier(...)`

`locationsByNetworkSupplier(context, networkRef)`

Supplying Custom Control Functions

The Result: `PositionUpdateResult`

Related content

Controls Utilities Overview

How Controls Utilities work

Controls Utilities

Control Types

Control Types

Overview

Key points

Anatomy of a Control

Targeting with `context`

Control Types

Inclusion

Exclusion

Buffer (Absolute)

Buffer (Percentage)

Limit

Threshold

Combined Example

Related content

Controls Utilities Overview

How Controls Utilities work

Controls Utilities

Related content

Controls Utilities

Utility Bundles Overview

Holger Lierse

Contributors:

Building Blocks

By Type

Helpful Resources

Quick Links