CreateBaseVirtualPosition

Rule

Changed on:

29 Aug 2024

Overview

Creates a base virtual position and sends the event

`{eventName}`

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

Creates a base virtual position and sends the event {eventName}

Accepts

VIRTUAL_CATALOGUE

Actions

This rule produces a MutationAction to create a new virtual position and a SendEventAction that forwards the incoming event as an inline event with the given name
```
`{eventName}`
```
to the virtual position which has been created. The
```
`{entityType}`
```
of the generated event is VIRTUAL_POSITION and the
```
`{entitySubtype}`
```
is BASE.

Rule parameters

Parameter	Description
eventName	The name of event to be triggered

Event attributes

Parameter	Description	Data Type	Required?
productRef	The product ref to load inventory positions	String	Required
locationRef	The location ref of this virtual position	String	Required
inventoryPositionRef	Inventory position ref	String	Optional
targetVirtualPositionRef	The virtual position ref to be created	String	Required
virtualCatalogueRef	The ref of virtual catalogue	String	Required
virtualCatalogueInventoryCatalogueRef	The inventory catalogue ref of the virtual catalogue	String	Required
virtualCatalogueProductCatalogueRef	The product catalogue ref of the virtual catalogue	String	Required
virtualCatalogueControlGroupRef	The control group ref of the virtual catalogue	String	Required

Exceptions

If
```
`inventoryPositionRef`
```
is not provided, this rule retrieves the corresponding inventory position with ref (by concatenating
```
`{productRef}:{locationRef}:DEFAULT`
```
) and
```
`{virtualCatalogueInventoryCatalogueRef}`
```
as the inventory catalogue ref. If the retrieved inventory position does not have a product ref or location ref an IllegalArgumentException will be thrown
An IllegalArgumentException will also be thrown if the incoming event does not have
```
`{entityRef}`
```

Configuration example

1{
2  "name": "[[account.id]].globalinventory.CreateBaseVirtualPosition",
3  "props": {
4    "eventName": "CREATE"
5  }
6}

Language: json

Detailed Technical Description

The rule first fetches the corresponding inventory position of this virtual position that is to be created. It uses
```
`{virtualCatalogueInventoryCatalogueRef}`
```
event attribute (as the inventory catalogue ref) and the inventory position ref generated using the following convention to fetch the inventory position.
if
```
`inventoryPositionRef`
```
attribute is not provided, inventory position ref convention =>
```
`{productRef}:{locationRef}:DEFAULT`
```
It then performs a validation on the retrieved inventory position and throws the exception outlined in Exceptions if the inventory position fields have any issues.
In order to create the virtual position, the quantity of the virtual position has to be calculated. This quantity is called effective quantity because this quantity is the value after adding relevant buffer values to the on-hand quantity of the corresponding inventory position. See the Quantity Calculation section for details.
Once the effective quantity for this virtual position is calculated, it creates the virtual position where the virtual position ref has the value of
```
`{targetVirtualPositionRef}`
```
event attribute and the virtual catalogue ref has the value of
```
`{virtualCatalogueRef}`
```
event attribute. The generated virtual position type will be BASE.
Finally, the rule generates a new inline event where
```
`{entityRef}`
```
of the event is the value of
```
`{targetVirtualPositionRef}`
```
event attribute of the incoming event,
```
`{entityType}`
```
is VIRTUAL_POSITION and
```
`{entitySubtype}`
```
is BASE.

Quantity Calculation

The calculation of the effective quantity of the virtual position (of type BASE) involves querying the product's categories and controls. There are two types of controls.
Exclusion buffer controls
Quantity buffer controls
The rule first checks if an exclusion buffer is applicable to this virtual position. If so it will immediately stop the calculation by setting the effective quantity to 0. Therefore, the effective quantity of the new virtual position is set to 0. See the Exclusion Control Buffer Calculation for details.
If the rule cannot find any exclusion control buffer/s, it then proceeds to calculate the quantity buffer. Once the quantity buffer value is calculated, it is added to the on-hand value of the inventory position to calculate the effective quantity of the virtual position. If the effective quantity becomes negative after adding the quantity buffer value to the on-hand value of the inventory position, the effective quantity of the virtual position will be set to 0. The resulting value is used as the quantity of the new virtual position. See the Quantity Buffer Calculation for details.

Exclusion Control Buffer Calculation

The rule fetches all the categories belonging to the product by using the
```
`{productRef}`
```
and the
```
`{virtualCatalogueProductCatalogueRef}`
```
incoming event attributes. Then it uses
```
`{virtualCatalogueControlGroupRef}`
```
and
```
`{productRef}`
```
event attributes and the list of category references to generate all the possible exclusion control references:

`{virtualCatalogueControlGroupRef}:EXCLUSION:{productRef}`

for category_ref in each category →

`{virtualCatalogueControlGroupRef}:EXCLUSION:{category_ref}`

The above step will result in one or more exclusion control references. The rule then tries to fetch controls in ACTIVE status with the above exclusion control references. If it can find at least one exclusion control the effective quantity is set to 0. Otherwise, the rule proceeds with the quantity buffer calculation

Quantity Buffer Calculation

The rule fetches all the categories belonging to the product by using the
```
`{productRef}`
```
and the
```
`{virtualCatalogueProductCatalogueRef}`
```
incoming event attributes. Then it uses the
```
`{virtualCatalogueControlGroupRef}`
```
,
```
`{locationRef}`
```
and
```
`{productRef}`
```
event attributes, and the list of category references to generate all the possible quantity buffer control references:

`{virtualCatalogueControlGroupRef}:QUANTITY_BUFFER:{productRef}:{locationRef}`

`{virtualCatalogueControlGroupRef}:QUANTITY_BUFFER:{productRef}`

`{virtualCatalogueControlGroupRef}:QUANTITY_BUFFER:{locationRef}`

for category_ref in each category →

`{virtualCatalogueControlGroupRef}:QUANTITY_BUFFER:{category_ref}`

The above step will result in three or more quantity buffer control references. The rule then tries to fetch controls in ACTIVE status with the above quantity buffer control references. If there are controls found, the rule picks the control with the lowest
```
`executionOrder`
```
after sorting them in ascending order according to the
```
`executionOrder`
```
attribute of each control. If the lowest buffer control has a value, this value is used as the final buffer value and it is added to the on-hand value of the inventory position to calculate the effective quantity of the virtual position. If no quantity buffer controls are found or the lowest quantity buffer control does not have any value set, the effective quantity of the virtual position will be the same as the on-hand value of the inventory position.

Version History

2023-07-28

v2.0.0

Refers to the plugin