CreateBaseVirtualPosition

Home
Essential Knowledge
By Type
Building Blocks
APIs
Releases

Rule

Changed on:

8 Apr 2025

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	Data Type	Description
eventName	String	The name of the 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 catalog	String	Required
virtualCatalogueInventoryCatalogueRef	The inventory catalog ref of the virtual catalog	String	Required
virtualCatalogueProductCatalogueRef	The product catalog ref of the virtual catalog	String	Required
virtualCatalogueControlGroupRef	The control group ref of the virtual catalog	String	Optional

Exceptions

If
```
`inventoryPositionRef`
```
is not provided, the rule retrieves the corresponding inventory position using the reference
```
`{productRef}:{locationRef}:DEFAULT`
```
and
```
`{virtualCatalogueInventoryCatalogueRef}`
```
as the inventory catalog ref. If the retrieved inventory position lacks a product ref or location ref, an IllegalArgumentException is thrown.
An IllegalArgumentException is also thrown if the incoming event does not contain
```
`{entityRef}`
```
.
If any required event attributes are missing, an EventAttributeNotFoundException is thrown.

Configuration example

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

Language: json

Detailed Technical Description

Virtual Position Creation and Quantity Calculation

Inventory Position Retrieval & Validation

The rule first retrieves the corresponding inventory position for the virtual position being created. It uses the
```
`{virtualCatalogueInventoryCatalogueRef}`
```
event attribute (as the inventory catalog reference) and constructs the inventory position reference based on the following convention:
- If
```
`inventoryPositionRef`
```
  is not provided, the reference follows the format:
```
`{productRef}:{locationRef}:DEFAULT`
```
Once the inventory position is retrieved, the rule validates its fields. If any issues are detected, an exception is thrown, as outlined in the Exceptions section.

Effective Quantity Calculation

To create a virtual position, the system calculates its effective quantity—the final quantity after applying relevant buffer values to the on-hand inventory quantity. (See Quantity Calculation section for details.)
After determining the effective quantity, the virtual position is created with:
- ```
`{targetVirtualPositionRef}`
```
  as the virtual position reference
- ```
`{virtualCatalogueRef}`
```
  as the virtual catalog reference
- ```
`BASE`
```
  as the virtual position type

Finally, the rule generates an inline event with the following attributes:

`{entityRef}`

`{targetVirtualPositionRef}`

```
`{entityType}`
```
=
```
`VIRTUAL_POSITION`
```
```
`{entitySubtype}`
```
=
```
`BASE`
```

Quantity Calculation

The effective quantity of a virtual position (type

`BASE`

) is determined by evaluating exclusion buffers and quantity buffers.

Exclusion Buffer Check
- The rule checks if an exclusion buffer applies to the virtual position.
- If an active exclusion buffer is found, the effective quantity is immediately set to 0, and the calculation stops. (See Exclusion Control Buffer Calculation for details.)
Quantity Buffer Check
- If no exclusion buffers are found, the rule calculates the quantity buffer.
- The buffer value is added to the on-hand inventory quantity to determine the effective quantity.
- If the resulting value is negative, the effective quantity is set to 0.
- The final quantity is assigned to the new virtual position. (See Quantity Buffer Calculation for details.)
No Controls Applied
- If no controls are present, the effective quantity is equal to the on-hand value of the inventory position.

Exclusion Control Buffer Calculation

The rule retrieves all product categories using
```
`{productRef}`
```
and
```
`{virtualCatalogueProductCatalogueRef}`
```
event attributes.

It generates potential exclusion control references based on

`{virtualCatalogueControlGroupRef}`

`{productRef}`

, and category references:

`{virtualCatalogueControlGroupRef}:EXCLUSION:{productRef}`

`{virtualCatalogueControlGroupRef}:EXCLUSION:{category_ref}`

(for each category)

The rule attempts to fetch ACTIVE controls using these references.
- If at least one active exclusion control is found, the effective quantity is set to 0, and the process stops.
- If no exclusion controls are found, the rule proceeds to Quantity Buffer Calculation.

Quantity Buffer Calculation

The rule retrieves product categories using
```
`{productRef}`
```
and
```
`{virtualCatalogueProductCatalogueRef}`
```
event attributes.

It generates quantity buffer control references using

`{virtualCatalogueControlGroupRef}`

`{locationRef}`

`{productRef}`

, and category references:

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

`{virtualCatalogueControlGroupRef}:QUANTITY_BUFFER:{productRef}`

`{virtualCatalogueControlGroupRef}:QUANTITY_BUFFER:{locationRef}`

`{virtualCatalogueControlGroupRef}:QUANTITY_BUFFER:{category_ref}`

(for each category)

The rule attempts to fetch ACTIVE controls using these references.
- If controls are found, they are sorted in ascending order by their
```
`executionOrder`
```
  .
- The rule selects the lowest executionOrder control with a valid buffer value.
- This value is added to the on-hand inventory quantity to determine the effective quantity.
- If no valid buffer controls exist, the effective quantity defaults to the on-hand inventory value.

Version History

2025-04-14

v2.2.1

Rule 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.

2023-07-28

v2.0.0

Refers to the plugin