Skip to content

Items Information Model R1

Reference Data for materials, finished products, etc. and inventory pieces that need to be uniquely identified

This document applies to the R1 Version of the product that covers MVP1 through MVP4.

Note

The terms vendor and supplier can be used interchangeably, with a slight preference for vendor. In existing code the term supplier may be more prevalent but should not be updated at this time to avoid compatibility issues.

Class Diagram

uml diagram

Item Module Classes

Entities are understood to be journalled Entities as described in Bitemporal Entity with the default fields defined in journalled Entities Specification.

Item Entity

Property Type multi Description
name String [1..1] Primary name of the item.
description String [0..1] Detailed description of the item.
imageUrl URL [0..1] Link to an image representing the item.
classification ItemClassification [0..1] Category or type classification.
useCase String [0..1] Recommended or intended usage.
locator PhysicalLocator [0..1] Default storage or usage location.
internalSKU String [0..1] Company-specific identification code.
minQuantity Quantity [0..1] Minimum stock level or reorder point.
taxable Boolean [0..1] Whether the item is subject to taxes.
primarySupply ItemSupplyReference [0..1] Cached reference to the primary source.
secondarySupply ItemSupplyReference [0..1] Cached reference to the secondary source.
defaultSupply String [0..1] Name of the default supply source.
defaultSupplyEId UUID [0..1] Reference to the default supply source.
cardSize CardSize [0..1] Formatting for visual cards.

Invariants

  • name is required.
  • When either primarySupply or secondarySupply is not null, defaultSupply and defaultSupplyEId must match the name and supplyEId of the non-null value. If both primarySupply and secondarySupply are non-null, the values must match one of them.
  • When both primarySupply and secondarySupply are null, defaultSupply and defaultSupplyEId must also be null.

Interpretation

  • name is the business identifier for the item. It is not necessarily unique across items in the same tenant. Currently, the burden of differentiating items with the same name is on the user and business processes using the available Item entity instances.

Mutation Behaviors

Item Mutations through the ItemService must take an additional operation qualifier that determines how the information about its supply sources is to be interpreted and used. The qualifier values can be:

Value Description
lax Allow for unidentified supply sources.
strict Require supply sources to be fully identified, fail otherwise
update Create or update supply sources as needed to bring the Item to strict compliance. If this is not possible, the operation should fail.

When an Item is created or updated, the behavior of the operation, depending on its previous contents and the operation qualifier follows the following tables:

Create
Case primarySupply Input secondarySupply Input
No Supplies null null
Primary Supply Only not-null null
Secondary Supply Only null not-null
Both Supplies not-null not-null

Note

All behaviors assume that the input values are validated against the invariants specified for the Item Entity and ItemSupplyReference value objects.

Case Qualifier Behavior Propagation
No Supplies any creation proceeds, defaultSupply and defaultSupplyEId are set to null. (Input validated for invariants) No propagation needed.
XXX Supply Only strict Find an ItemSupply entity that matches all non-null properties provided strictly. If found proceed, otherwise fail No propagation needed.
XXX Supply Only lax Find an ItemSupply entity that matches all the non-null properties provided strictly. If found, fill in the rest of information from the Supply and proceed, otherwise, Fail if supplyEid is not null, as it hard links to an ItemSupply that should not be updated. Otherwise update the values and proceed. No propagation needed. (e.g., this allows to match an ItemSupply entity only by its eId)
XXX Supply Only update Find an ItemSupply entity that matches the supplyEId if not null. If found update it with the rest of the information (overwrite all fields that are not null in the input), then proceed. Otherwise, (ItemSupply entity not found) fail. If supplyEId is null, and an ItemSupply is not found with the name or the combination of parentItem, vendorEId and vendor information, create one and proceed. Propagate the changes to the ItemSupply entity, checking for validity. If the propagation fails, the whole operation fails.
Both Supplies any Behavior is as XXX Supply Only repeated for both ItemSupplyReferences, then the defaultSupply and defaultSupplyEId are set following the rules below. Propagation of both ItemSupplyReferences as per above. Any of them fails, the whole operation fails.

For the case of Primary Supply Only or Secondary Supply Only the behavior is the same except that the defaultSupply and defaultSupplyEId, if not provided are set to the non-null supply provided in the input.

defaultSupply and defaultSupplyEId selection
When both primarySupply and secondarySupply are provided, and defaultSupply and defaultSupplyEId are not provided in the input set defaultSupply to the value of primarySupply.name and defaultSupplyEId to primarySupply.supplyEId.
Update
Case primarySupply Input secondarySupply Input primarySupply Previous secondarySupply Previous
No Supplies null null null null
Existing Supply Only not-null null null or not-null null
Alternate Supply Only null not-null null null or not-null
Both Supplies not-null not-null null or not-null null or not-null
Alternate Supply Only null not-null null null or not-null
Both Supplies not-null not-null null or not-null null or not-null
Case Qualifier Behavior Propagation
No Supplies any update proceeds No propagation
Existing Supply Only strict, lax If the existing supply identifies an ItemSupply entity (supplyEId not null) failure. If not, update without propagation as in Create
Existing Supply Only update Propagate the update to the existing ItemSupply entity as per the rules in {item-supply-update}. If propagation fails, the whole operation fails. If there is no linked ItemSupply, proceed as in Create Propagation of the existing ItemSupply as per above. when propagation fails, the whole operation fails.
Alternate Supply Only any Behavior as in Create Propagation as in Create
Both Supplies any Behavior for each supply as per Existing Supply Only but if one of them fails, the whole operation fails. Propagation as per above for both supplies. If one of them fails, the whole operation fails.

Updates to defaultSupply and defaultSupplyEId follow the same rules as in Create, ONLY if they are currently null, if they are not null, they are not updated unless the input provides new values.

ItemSupplyReference Value Object

A value object that captures a snapshot or a pointer to a ItemSupply. It is used within the Item entity to provide immediate access to supply details without navigating the full supply universe.

Property Type multi Description
supplyEId UUID [0..1] Unique ID of the referenced ItemSupply.
vendorEId UUID [0..1] ID of the Business Role.
name String [0..1] Specific name for this supply option. if vendorEId and vendor are null, this should not be null
vendor String [0..1] Name of the vendor.
sku String [0..1] Vendor SKU.
orderMethod OrderMethod [0..1] Communication method for placing orders.
url URL [0..1] Direct link to the item on the vendor’s site.
orderQuantity Quantity [0..1] Standard quantity for ordering.
unitCost Money [0..1] Cost per unit of measure.
averageLeadTime Duration [0..1] Expected time for fulfillment.

Invariants

  • If supplyEId is not null, All other properties must match their corresponding one in the ItemSupply entity, including matching null values.
  • Otherwise, (supplyEId is null):
    • If vendorEId is not null, vendor must not be null and must match the name of the BusinessAffiliate Entity associated to the BusinessRole identified by vendorEId.

Interpretation

  • If supplyEId is null, the ItemSupplyReference represents a one-off or ad-hoc supply option not linked to a persistent ItemSupply entity.
  • If vendorEId is null, but vendor is not null, the supply represents a one-off vendor without persistent representation in the system.
  • If unit cost is null, it is interpreted as 0.00 in the currency used in the contextual business transaction (e.g., Purchase Order) The system will not store or materialize this default as it may signal that the user has not provided a value yet.
  • If order quantity is null, it is interpreted as 0 eaches of the item.
  • If average lead time is null, it is interpreted as immediate availability (on-hand).

ItemSupply Entity

An entity representing a specific way an item can be acquired from a vendor. An ItemSupply behavew as a ChildRecord (documentation pending) of an Item entity, and as such it has a parentEId property that reference its parent Item entity instance. This property is not directly described in this document as it will be described in the ChildRecord general design documentation.

Property Type multi Description
vendorEId UUID [0..1] Reference to the Business Role. Null indicates an unknown vendor.
vendor String [0..1] Name of the vendor. Not Null if vendorEId is not null.
name String [0..1] Specific name for this supply option. if vendorEId and vendor are null, this should not be null
sku String [0..1] Vendor-specific SKU.
orderMethod OrderMethod [0..1] Communication method for placing orders.
url URL [0..1] Direct link to the item on the vendor’s site.
orderQuantity Quantity [0..1] Standard quantity for ordering.
unitCost Money [0..1] Cost per unit of measure.
averageLeadTime Duration [0..1] Expected time for fulfillment.

Invariants

  • name must be unique within the set of ItemSupply entities associated to both:
    • The same Item (identified by parentEId Need reference to ChildRecord design)
    • The same vendor (or null)
  • vendorEId is optional. If it is not null, it must refer to an existing BusinessRole entity at the
    time of creation or update. The BusinessRole entity must have its role property set to VENDOR.
  • If vendorEId is not null, vendor must not be null and its value must match the name of the BusinessAffiliate Entity associated to the BusinessRole identified by vendorEId.
  • If both vendorEId and vendor are null, name must not be null.

Interpretation

If vendorEId is null, the ItemSupply represents a source with an unknown or unspecified vendor. Users and/or business processes must handle such cases for order composition, receiving, etc.

The name property serves as a disambiguation label for ItemSupplies from the same vendor to be able to assign different unit costs depending on external factors (e.g., discount promotions, expedited pricing, etc.). When BusinessAffiliate instances are created automatically, the name can be used to named them is no other information is available.

Mutation Behaviors

When an ItemSupply is directly created or updated through the ItemSupplyService the cases to consider are:

Create Operation
Case Qualifier Behavior
Fully Identified any ItemSupply is created if all invariants are met
Identify by Name strict if a pair BusinessAffiliate/BusinessRole exists matching the given name, the vendorEId is set from the BusinessRole, otherwise fail
Identify by Name lax if a pair BusinessAffiliate/BusinessRole exists matching the given name, the vendorEId is set from the BusinessRole, otherwise create a one-off supply with null vendorEId
Identify by Name update if a pair BusinessAffiliate/BusinessRole exists matching the given name, the vendorEId is set from the BusinessRole, otherwise create a new BusinessAffiliate with the given ItemSupply.vendor or ItemSupply.name if vendor is null, and associated BusinessRole as VENDOR and set vendorEId accordingly
Identify by eId any If a BusinessRole exists with that eId and type VENDOR, set the vendor the name of its associated BusinessAffiliate. Otherwise, fail.
Unknown Vendor strict Fail
Unknown Vendor lax Create a one-off supply with null vendorEId and vendor, name is required or operation fails.
Unknown Vendor update Create a BusinessAffiliate with the name of the supply and an associated BusinessRole with type VENDOR. Update the vendor and vendorEId with the corresponding values
Update Operation

The ItemSupply to be updated is determined by the input eId and bitemporal coordinates.

Case vendorEId Input vendor Input Previous vendorEId Previous vendor
Fully Identified Target not-null not-null not-null not-null (per invariant)
Link, fully identified not-null any null any
Link, Identify by name null not-null null any
Undefined Vendor in Input null null not-null not-null
Case Qualifier Behavior
Fully Identified Target strict, lax If the vendorEId and vendor match, proceed with update; otherwise fail (switching suppliers should be accomplished by creating a different ItemSupply).
Fully Identified Target update If the vendorEId matches but the vendor does not, update the name of the Business Affiliate, then proceed with update
Link, fully identified strict, lax If the vendorEId matches a BusinessRole with a BusinessAffiliate.name that matches the vendor, proceed, update the resulting vendorId and vendor (the ItemSupply becomes linked to the BusinessRole) otherwise fail. Note that vendor must match the value of the BusinessRole/BusinessAffiliate identified by vendorEId or be null, in which case the value from the reference entities is taken.
Link, fully identified update If the vendorEId matches a BusinessRole with a BusinessAffiliate.name that matches the vendor, proceed, update the resulting vendorId and vendor (the ItemSupply becomes linked to the BusinessRole). If the input vendor does not match the existing BusinessAffiliate.name update it and then proceed. Otherwise, Fail (including when BusinessRole not found)
Link, Identify by name strict, update Find a BusinessAffiliate with that name and a BusinessRole associated with it with type VENDOR. If found, link the ItemSupply to them and proceed with update, otherwise fail
Link, Identify by name lax Find a BusinessAffiliate with that name and a BusinessRole associated with it with type VENDOR. If found, link the ItemSupply to them and proceed with update, otherwise update without linking
Undefined Vendor in Input any Fail. Unlinking would degrade data integrity. The client must explicitly delete the ItemSupply and create a new one.

ItemClassification (Value Object)

Classification for an Item with two levels: type and subtype. In the future, these will be migrated to represent actual category entities.

Property Type multi Description
type String [1..1] Primary category type.
subType String [0..1] Secondary category subtype.

Note

ItemClassification will become an Entity with a Reference in future versions.

OrderMethod (Enumeration)

An enumeration of the predefined supply methods supported by the system for procurement and fulfillment.

Value Description
UNKNOWN Default value when the method is not specified.
PURCHASE_ORDER Formal procurement via a PO.
EMAIL Informal ordering via email.
PHONE Informal ordering via telephone.
IN_STORE Direct purchase at a physical location.
ONLINE Purchase via a vendor website.
RFQ Request for Quote process.
PRODUCTION Internal production or manufacturing.
TASK Fulfillment via a task or service.
THIRD_PARTY Sourced from a third-party provider.
OTHER Any other unspecified method.

Quantity (Value Object)

A value object representing an amount of an item with units specific to that item.

Property Type multi Description
amount Double [1..1] Numerical value of the quantity.
unit String [1..1] Unit of measure (e.g., \(kg\), \(each\), \(m\)).

Interpretation

  • Quantity frequently appears as a nullable property in Entities or other Value Objects. When a value is present, it requires to have a valid amount (defaulting to 0.0) and a valid unit to support proper addition of inventory amounts.

Other Referenced Modules

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

Comments