Skip to content

Item Mutation Intent

Intent Definitions

LAX (The “Upsert & Trust” Mode)

  • Intent: Flexibility and Idempotency. It prioritizes completing the operation over strict data validation.
  • Validation:
    - Partial Consistency Check: It verifies that if explicit fields (like Supplier or SKU) are provided in the reference, they match the existing database record for that Supply ID to prevent data corruption.
    - Missing IDs: Allows creating items with missing supply references or partial data, often relying on later enrichment.
  • Behavior:
    - Creation/Linking: If a Supply ID is provided, it links to it blindly.
    - Sub-Entity Handling: In createItemSupply, it acts as an Upsert. If the supply exists, it updates it; if not, it creates it.
  • Use Case: Automated scripts, CSV imports, or “Add/Edit” forms where data might be partial or the ID is considered the absolute source of truth.

STRICT (The “Verify” Mode)

  • Intent: Data Integrity and Consistency. It ensures that the user’s view of the data matches the system’s state before allowing a link.
  • Validation:
    - Consistency Check: If a Supply ID is provided, it must exist in the database.
    - Field Matching: The provided Name and Supplier in the payload must exactly match the values currently stored in the database for that ID.
    - Failure: If there is any drift (e.g., the user thinks ID 100 is “Apple”, but the DB says “Banana”), the operation fails with AppError.ArgumentValidation.
  • Behavior:
    - No Side Effects: It will never implicitly update a sub-entity. It only links to existing, verified records.
  • Use Case: UI operations where a user selects a Supply from a list. Ensures the user isn’t linking to a record that has changed meaning/content since they loaded the page.

PROPAGATE (The “Cascade” Mode)

  • Intent: Deep Persistence and Automation. It treats the payload as the master definition of the object graph.
  • Validation:
    - Relaxed: Like LAX, it skips the strict consistency check because it assumes differences are intentional updates.
  • Behavior:
    - Cascading Creation: If a Supply is defined in the payload without an ID (or matches specific “creation” criteria in PersistencePreparer), the service creates the new ItemSupply
    entity and links it to the Item automatically.
    - Cascading Updates: If a Supply ID is provided but the fields (Name, Supplier) differ from the DB, the service updates the actual ItemSupply entity to match the payload.
  • Use Case: Complex editors where a user can edit an Item and its Supply details simultaneously, or imports where the goal is to synchronize the database with an external dataset completely.

Summary Table

Qualifier Supply Check Behavior on Mismatch Sub-Entity Creation Use Case
LAX Partial (Supplier/SKU) Fails on Mismatch if provided Upsert (Create or Update) Scripts, Imports
STRICT Exists + Matches Fields Fails Operation Atomic on Item Create, else Manual UI Linking, Safety
PROPAGATE None Updates Database to match Payload Automated (Deep Insert) Deep Editing, Sync

Operation Behaviors

Item Creation

From ItemService.create method

The user provides Item information and primarySupply, secondarySupply contents.

General Validations and Defaulting Behavior for primarySupply and secondarySupply
  • supplier is a required field if primarySupply or secondarySupply values are present.
  • No supplyEid can be provided
  • If name is not provided, it is defaulted to the value of supplier
  • name (after default if applicable) should be different between primarySupply and secondarySupply if both are provided.
  • supplyEId (after default if applicable) should be different between primarySupply and secondarySupply if both are provided.
  • The Item.defaultSupply, if provided, it must match the name of either the primarySupply or secondarySupply after defaults.
  • If Item.defaultSupply is not provided, it is defaulted to the name of the first non-null name value of primarySupply or secondarySupply or null if none is provided.
LAX Behavior
  • Item is created with one-off supplies. No ItemSupply entities are created.
  • Item.defaultSupplyEid, primarySupply.supplyEId and secondarySupply.supplyEId are set to null if applicable (object is present)
STRICT and PROPAGATE Behavior
  • ItemSupply entities are created with the values provided (after defaulting) for primarySupply and secondarySupply
  • Item is enriched with the newly created ItemSupply.eId values for primarySupply and secondarySupply respectively.
  • Item.defaultSupplyEid is set to the eId of the ItemSupply entity that matches the defaultSupply name.

Note

Why STRICT behaves like PROPAGATE during creation: ItemSupply entities exist in a composition
relationship with their parent Item. Since no ItemSupply can exist before its parent Item is created,
STRICT mode ensures data integrity by atomically creating the supplies alongside the Item. The
“verify existing” semantic of STRICT applies only to Item updates where supplies may already exist.

Item Update

From ItemService.update method

General Validation and Defaulting Behavior for primarySupply and secondarySupply
  • supplier is a required field if primarySupply or secondarySupply values are present.
  • IF name and supplyEId are provided, an ItemSupply with those values must exist.
  • If name is not provided, it is defaulted to:
    • If supplyEId is provided, the name value of the identified ItemSupply entity
    • If supplyEId is not provided, the value of supplier
  • name (after defaulting if applicable) should be different between primarySupply and secondarySupply if both are provided.
  • supplyEId if not provided and an ItemSupply for the item exists with the same name, it is populated with the eId of the matching ItemSupply entity.
  • All other non-null provided properties must match the values of a name matching ItemSupply if it exists after an update.
  • The Item.defaultSupply value, if provided, it must match the name of either the primarySupply or secondarySupply after defaults.
  • If Item.defaultSupply is not provided, it is defaulted to the name of the first non-null name value of primarySupply or secondarySupply or null if none is provided.
  • Item.defaultSupplyEid value, if provided, must match the eId of the ItemSupply entity that matches the defaultSupply name.
  • Swapping primarySupply and secondarySupply is allowed and should not cause an update of the defaultSupply or defaultSupplyEid values in the parent Item entity.
LAX Behavior
Condition Effect
ItemSupply matching name or supplyEid exists Validation Error if any non-null provided value does not match the values of the matching ItemSupply entity
ItemSupply matching name or supplyEid does not exist Item is Updated
primarySupply or secondarySupply is cleared defaultSupply and defaultSupplyEid are set to the remaining value if not null, otherwise they are set to null
STRICT Behavior
Condition Effect
matching ItemSupply exists with matching non-null values Item is Updated
matching ItemSupply does not exist or exists with different non-null values Validation Error
primarySupply or secondarySupply is cleared defaultSupply and defaultSupplyEid are set to the remaining value if not null, otherwise they are set to null
PROPAGATE Behavior
Condition Effect
matching ItemSupply exists with matching non-null values Item is Updated
matching ItemSupply does not exist Item is Updated, ItemSupply is created subject to uniqueness and other validations
matching ItemSupply exists with different non-null values Item is Updated, ItemSupply is updated with the new values, including nullifying values and name (subject to uniqueness validation)
primarySupply or secondarySupply is cleared defaultSupply and defaultSupplyEid are set to the remaining value if not null, otherwise they are set to null

Note that ItemSupply entities are never deleted as a consequence of an Item Update, they need to be explicitly deleted by the user.

Item Deletion

From ItemService.delete method

In all cases, all ItemSupply entities associated with the Item are deleted.

ItemSupply Creation

From ItemService.createItemSupply method

General Validation and Defaulting.
  • supplier is a required field.
  • If name is not provided, it is defaulted to supplier
  • No pre-existing ItemSupply with the same name for a given Item (identified by parentEId) is allowed. (name is optional in input but it is provided/defaulted by the system before persisting the entities)
  • supplierEId is optional. If not provided, it is resolved from supplier by matching BusinessAffiliate entities with vendor role if it exists.
LAX, STRICT behavior
Condition Effect
No ItemSupply exists with same name or eId ItemSupply is created
ItemSupply matching by eId exists ItemSupply is updated (Upsert behavior in LAX)
Parent Item has one-off reference (no supplyEId), matching the new ItemSupply by name or supplier ItemSupply is created, and the parent Item reference is updated to link to it
Parent Item has reference with matching name but different non-null fields (e.g. supplier) Validation Error
PROPAGATE
Condition Effect
No ItemSupply exists with same name or eId ItemSupply is created
Parent Item reference matches new ItemSupply by name or supplier ItemSupply is created, parent Item is updated to link to it

ItemSupply Update

From ItemService.updateItemSupply method

Validation and Defaulting
  • supplier is a required field
  • eId needs to be provided.
  • if no ItemSupply with the given eId is found, result is a NotFound error
LAX, STRICT, PROPAGATE

Note that all intents result in the same behavior for update operations. The intent is that as information is added to the system, its behavior becomes more predictable. Update operations on ItemSupply entities already have enough information to determine a unique consistent behavior across intents.

Furthermore, when a parent Item primary or secondary supply is already linked to an ItemSupply entity, the values should be the same due to previous create or update operations and propagation becomes the default behavior in the absence of validation errors.

Condition Effect
Parent Item with primarySupply.name or secondarySupply.name or corresponding supplyEId does not exist Update succeeds
Parent Item with matching supplyEid for primary or secondary supply, other values, including name do not match previous values Validation Error
Parent Item with matching supplyEid for primary or secondary supply, other values, including name match previous values Update succeeds, update propagates to parent Item entity

ItemSupply Delete

From ItemService.removeItemSupply method

Validation and Defaulting
  • eId needs to be provided.
  • if no ItemSupply with the given eId is found, result is a NotFound error
LAX, STRICT, PROPAGATE
Condition Effect
Supply is referenced by parent’s primarySupply Fails with AppError.IncompatibleState
Supply is referenced by parent’s secondarySupply Fails with AppError.IncompatibleState
Supply is not referenced by parent’s primary/secondary Deletes ItemSupply entity

Comments