Skip to content

Item Create & Update with Item Supplies

Context

This feature is developed in the context of Business Affiliate Reference Data

This is preliminary work to introduce the full BusinessAffiliate entity, preparing the Item entity to reference BusinessAffiliate entities through ItemSupply entities that represent a specific Supply agreement for an Item by a Vendor.

Documents in this Section

Document Description
Item Mutation Intent Detailed behavior specifications for LAX, STRICT, PROPAGATE qualifiers
Requirements Complete incremental service requirements for ItemSupply
Unit Test Coverage Mapping of requirements to unit tests

Pre-Existing Implementation

In the current implementation (Q4-2025) the Item Entity has the following structure:

uml diagram

Not shown in the diagram for clarity, ItemSupplyReference has the following additional properties

Property Type Cardinality Description
supplier String 1 The name of the supplying company
sku String 0..1 The SKU in the supplier catalog
orderMethod OrderMethod 0..1 The method used to order the item from the supplier
url URL 0..1 A Url pointing to the online catalog of the supplier, required if OrderMethod is ONLINE
orderQuantity Quantity 0..1 The quantity of the item required to order from the supplier
unitCost Money 0..1 The cost of the item from the supplier per unit of orderQuantity
averageLeadTime Duration 0..1 The average time it takes to receive the item from the supplier

With the following validations and behavior:

  1. primarySupply, secondarySupply and defaultSupply can be null.
  2. if primarySupply or secondarySupply are not null, defaultSupply must match the value of the first non-null value of primarySupply?.supplier or secondarySupply?.supplier

Introduction of ItemSupply

In Q1-2026, as part of MVP2, the system must support:

  1. Multiple (more than 2) potential suppliers for an Item.
  2. Seamless backward compatibility with current implementation.
  3. Ability for users to create and update ItemSupply entities by simply creating items with information provided for their primary or secondary supply values.
  4. Ability to create and update Item entities without creating or updating an item supply entity (one-off supplies.

The updated domain model is:

uml diagram

An Item may have multiple ItemSupply entities associated with it (i.e. they are created by the user or client application). It additionally may have a primarySupply and a secondarySupply which may reference one of the existing ItemSupply entities or may be one-off definitions for the Item.

ItemSupply entities are bound to an Item entity by a parentEId property, constituting an implicit supplies collection that is managed by adding or removing ItemSupply entities with their parentEId set to the Item.eId value of the parent Item entity.

Note

Storage Location: The parentEId is stored in ItemSupplyMetadata, not in the ItemSupply payload itself. This follows the bitemporal entity pattern where relationship identifiers are stored in metadata to support temporal queries across parent-child relationships.

Item Supply Information Contents

The ItemSupply Entity has the following properties, which also update the ItemSupplyReference value.

Property Type Cardinality ItemSupplyReference Description
eId UUID 1 No Standard Entity Id
parentEId UUID 1 No Entity Id of the parent Item
supplierEId UUID 0..1 Yes Entity Id of the Supplier
supplier String 1 Yes Name of the Supplier
name String 0..1 Yes Name of the Supply
sku String 0..1 Yes Stock Keeping Unit
orderMethod OrderMethod 0..1 Yes Method of ordering
url URL 0..1 Yes URL of the Supply
orderQuantity Quantity 0..1 Yes Quantity to order
unitCost Money 0..1 Yes Cost per unit
averageLeadTime Duration 0..1 Yes Average time to receive the supply

The ItemSupplyReference also adds a property:

Property Type Cardinality Description
supplyEId UUID 0..1 The eId of an associated ItemSupply entity

The behavior of ItemSupplyReference in relation with an associated ItemSupply depends on the operation performed and the intent of the user with general validation and defaulting rules

  1. The name property of an ItemSupply acts as a unique natural key for all ItemSupply and ItemSupplyReference for an Item.

Capturing User Intent

When a user creates or updates an Item, it may provide information about up to two Supplies through the primarySupply and secondarySupply properties. This information can be used to:

  1. Keep it as one-off supplies (no ItemSupply entity is created)
  2. Create new ItemSupply entities associated with the Item or update pre-existing ones.
  3. Reject the update unless there is a matching ItemSupply entity.

The intent of the user is captured by additional create and update operations in the ItemService. These new oprations have a parameter ItemMutationQualifier that can take the following values:

  • LAX: Allows for flexibility in data input, trusting the user to provide the required information for the use cases it needs.
  • STRICT: Ensures data integrity is preserved. During creation, atomically creates supplies with the Item. During updates, rejects changes unless existing supplies match the provided values.
  • PROPAGATE: Updates the necessary ItemSupply and Item properties to create data integrity.

The detailed behavior for each operation is detailed in item-mutation-intent.md

Copyright: © Arda Systems 2025-2026, All rights reserved

Comments