CreateAggregateVirtualPosition

Home
Essential Knowledge
By Type
Building Blocks
APIs
Releases

Rule

Changed on:

8 May 2025

Overview

Create an , calculate its Available-to-Sell (ATS) quantity, and send an .

ATS calculation is based on the associated Positions (SOH) quantities and the applied .

The associated Positions are defined with:

The given Product Reference
The list of Locations for the given Network (the first Network assigned to the Virtual Catalog)
The specified Inventory Position Statuses

Plugin Name	Inventory Reference Module
Namespace	[[account.id]].globalinventory

The is the foundation for related implementations. It provides reference Workflows for inventory ingestion and processing. Extensible by design, use this Module as a base to build a solution to the needs of your customers.

The Module includes the following areas:

Product Catalogue workflow
Inventory Catalogue workflow
Control Group workflow
Virtual Catalogue workflow

Inventory Reference Module

The Module includes the following areas:

Product Catalog workflow
Inventory Catalog workflow
Control Group workflows
Virtual Catalog workflows

UI Description

Creates an aggregate virtual position including inventory positions in statuses {statuses}. Sends event {eventName}.

Accepts

VIRTUAL_CATALOGUE

Actions

This Rule produces a MutateAction that creates a new Aggregate Virtual Position.
This Rule produces a SendEventAction that sends an inline event to the created Aggregate Virtual Position.

Rule parameters

Name	Data Type	Description
eventName	String	The name of the to be triggered
statuses	List<String>	Statuses of the Positions to be used for ATS calculation

Event attributes

Parameter	Description	Data Type	Required?
productRef	Product Reference to load Positions	String	Required
targetVirtualPositionRef	Reference to be created	String	Required
virtualCatalogueRef	Reference of the	String	Required
virtualCatalogueInventoryCatalogueRef	Reference of the Catalog associated with the	String	Required
virtualCatalogueProductCatalogueRef	Reference of the associated with the	String	Required
virtualCatalogueControlGroupRef	Reference of the Control Group associated with the	String	Optional
virtualCatalogueNetworkIds	IDs of the	List<String>	Required

Exceptions

This Rule throws a `PropertyNotFoundException` when the Rule parameter(s) is not provided.

This Rule throws an `EventAttributeNotFoundException` when the required Event attribute(s) is not provided.

Configuration example

1{
2  "name": "[[account.id]].globalinventory.CreateAggregateVirtualPosition",
3  "props": {
4    "eventName": "CREATE",
5    "statuses": [
6        "ACTIVE",
7        "AT_RISK",
8        "OUT_OF_STOCK"
9    ]
10  }
11}

Detailed Technical Description

This performs the following steps during execution:

Determine Relevant Inventory Positions
- The Rule identifies Inventory Positions that contribute to the creation of an Aggregate Virtual Position.
- It loads a list of Location References from the Network assigned to the specified Virtual Catalog. Only the first Network from the `virtualCatalogueNetworkIds` Event Attribute is considered.
- It queries Inventory Positions using these criteria:
  - The given Inventory Catalog Reference ( `virtualCatalogueInventoryCatalogueRef` Event Attribute);
  - The specified Product Reference ( `productRef` Event Attribute);
  - The list of Location References loaded in the previous step;
  - The set of Inventory Position Statuses defined by the Rule’s `statuses` parameter.
Calculate ATS Quantity
- The Rule calculates the Aggregate Virtual Position’s Available to Sell (ATS) quantity.
- This is based on the sum of SOH (Stock on Hand) quantities from the determined Inventory Positions, after applying any relevant Controls.
- If no Controls are defined, the ATS is simply the total on-hand quantity.
- The specific calculation logic is described in the next section.
Create the Aggregate Virtual Position
- The Rule generates a MutateAction to create the Aggregate Virtual Position, assigning it the ATS quantity calculated in the previous step.
Send a Custom Event
- Finally, the Rule generates a SendEventAction to send an inline event (with the name provided by the `eventName` Rule parameter) to the newly created Aggregate Virtual Position.

Aggregate Virtual Position Available-to-Sell (ATS) quantity Calculation Algorithm

Determine the relevant Controls for the Aggregate Virtual Position:
- Load the list of Categories for the Variant Product (returns only the first 10) by:
  - The given Product Catalog Reference (`virtualCatalogueProductCatalogueRef` Event attribute)
  - The given Product Reference (`productRef` / `virtualPositionProductRef` Event attribute)
- Query Controls by:
  - The given Product Reference (`productRef` / `virtualPositionProductRef` Event attribute)
  - The loaded (in the previous step) list of Categories
  - The loaded list of Location References (from the first Network assigned to the given Virtual Catalog)
Apply the `EXCLUSION` Control.
- Exclusion Control types available:
  - Category Exclusion
    Control Reference naming convention: `{controlGroupRef}:EXCLUSION:{categoryRef}`
  - SKU Exclusion
    Control Reference naming convention: `{controlGroupRef}:EXCLUSION:{productRef}`
- The Aggregate Virtual Position ATS quantity is set to zero if an Exclusion Control with `ACTIVE` Status matches the Aggregate Virtual Position by Product or Category References
If no compatible Exclusion Controls have been found, apply the `QUANTITY_BUFFER` Controls to the Inventory Positions' SOH quantities:
- Get the relevant Buffer Controls with `ACTIVE` Status
  The following types are available:
  - Category Buffer
    Control Reference naming convention: `{controlGroupRef}:QUANTITY_BUFFER:{categoryRef}`
  - SKU Buffer
    Control Reference naming convention: `{controlGroupRef}:QUANTITY_BUFFER:{productRef}`
  - Location Buffer
    control ref: naming convention: `{controlGroupRef}:QUANTITY_BUFFER:{locationRef}`
  - SKU - Location Buffer
    Control Reference naming convention: `{controlGroupRef}:QUANTITY_BUFFER:{productRef}:{locationRef}`
- Sort the retrieved Controls by `executionOrder` in ascending order
- Apply only the first Buffer Control (compatible with a particular Inventory Position) to the SOH quantity
  Buffered SOH = SOH + Buffer value
- Set the Buffered SOH quantity to zero if it results in less than zero value after the Buffer application
Calculate the Aggregated Buffered SOH quantity for the Aggregate Virtual Position.
Aggregated Buffered SOH = IP1 Buffered SOH + IP2 Buffered SOH + ... + IPN Buffered SOH (IP 1,2,...,N stands for the Inventory Positions associated with the target Aggregate Virtual Position)
Apply the `MASTER_BUFFER` Control:
- Get the relevant Master Buffer Control with `ACTIVE` Status
  - SKU Master Buffer
    Control Reference naming convention: `{controlGroupRef}:MASTER_BUFFER:{productRef}`
- Calculate the Aggregate Virtual Position ATS quantity
  ATS = Aggregated Buffered SOH + Master Buffer value
- Set the ATS quantity to zero if it results in less than zero value after the Master Buffer application

Version History

2025-04-14

v2.2.1

changes:

Now apply control-specific logic only if the event includes a Control Group reference.
Skip all control-related validation and logic if no such reference is present in the event payload.

2024-10-28

v.24.10.28

This has been optimized to load all the related (by Product, its Categories, and list of Locations) at once for efficient Available-to-Sell (ATS) calculations.

The Version refers to the Product Release Version.

2023-07-28

v2.0.0

refers to the

CreateAggregateVirtualPosition

Overview

Inventory Reference Module

UI Description

Accepts

Actions

Rule parameters

Event attributes

Exceptions

Configuration example

Detailed Technical Description

Version History

v2.2.1

v.24.10.28

v2.0.0

Related content

Control Groups and Controls Management

Master Buffer: Strategic Adjustment of Available-to-Sell (ATS) Quantity

Building Blocks

By Type

Helpful Resources

Quick Links