UpdateAggregateVirtualPosition

Rule

Changed on:

24 Oct 2024

Overview

Update an Aggregate Virtual Position and calculate its Available-to-Sell (ATS) quantity.

Aggregate Virtual Position ATS calculation is based on the associated Inventory Positions Stock on Hand (SOH) quantities and the applied Controls.

The associated Inventory 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 Inventory Reference Module is the foundation for inventory 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 Inventory Module includes the following areas:

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

Inventory Reference Module

The Inventory Module includes the following areas:

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

UI Description

Updates an aggregate virtual position including inventory positions in the given {statuses}.

Accepts

VIRTUAL_POSITION

Actions

This Rule produces a MutateAction that updates the target Aggregate Virtual Position ATS quantity.

Rule parameters

Name

Type

Description

`statuses`

`List<String>`

Statuses of the Inventory Positions to be used for Aggregate Virtual Position ATS calculation

Event attributes

Name	Type	Description	Required
`virtualPositionRef`	`String`	Virtual Position Reference	Required
`virtualPositionProductRef`	`String`	Product Reference of the Virtual Position	Required
`virtualPositionGroupRef`	`String`	Group Reference of the Virtual Position	Required
`virtualCatalogueRef`	`String`	Reference of the Virtual Catalog	Required
`virtualCatalogueInventoryCatalogueRef`	`String`	Reference of the Inventory Catalog associated with the Virtual Catalog	Required
`virtualCatalogueProductCatalogueRef`	`String`	Reference of the Product Catalog associated with the Virtual Catalog	Required
`virtualCatalogueControlGroupRef`	`String`	Reference of the Control Group associated with the Virtual Catalog	Required
`virtualCatalogueNetworkIds`	`List<String>`	Network IDs of the Virtual Catalog	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.UpdateAggregateVirtualPosition",
3  "props": {
4    "statuses": [
5        "ACTIVE",
6        "AT_RISK",
7        "OUT_OF_STOCK"
8    ]
9  }
10}

Language: json

Detailed Technical Description

This Rule execution includes the following steps:

The Rule retrieves the Aggregate Virtual Position and Catalog data from the Event attributes.
The Rule determines the Inventory Positions associated with the Aggregate Virtual Position (to be updated):
- Load the list of Location References from the Network assigned to the given Virtual Catalog.
  Only the first Network from the
```
`virtualCatalogueNetworkIds`
```
  Event attribute is considered.
- Query Inventory Positions by:
  - The given Inventory Catalog Reference (
```
`virtualCatalogueInventoryCatalogueRef`
```
    Event attribute)
  - The given Product Reference (
```
`virtualPositionProductRef`
```
    Event attribute)
  - The loaded (in the previous step) list of Location References
  - The specified Inventory Position Statuses (
```
`statuses`
```
    Rule parameter)
The Rule calculates the updated Aggregate Virtual Position ATS quantity based on the determined Inventory Positions SOH quantities and the relevant Controls to be applied.
The ATS calculation algorithm equals the one used in the
```
`CreateAggregateVirtualPosition`
```
Rule
and is described below.
The Rule produces a MutateAction that updates the Aggregate Virtual Position with the calculated (point 3) ATS quantity.

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

2024-10-28

v.24.10.28

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

The Rule Version refers to the Product Release Version.

2023-08-03

v2.0.0

refers to the plguin