Item Supply Behaviors

View Interactive Prototype →

The Item Supply (REF::SPL) sub-domain manages the vendor-specific sourcing records attached to an Item. An ItemSupply entity captures everything needed to re-order an item from a specific supplier: supplier name, SKU, order method, unit cost, lead time, and order quantity. An Item can have multiple supplies, and each supply can be designated as Primary, Secondary, or Default, giving the purchasing workflow a clear priority when it is time to reorder. Item Supply records link to Business Affiliate records (REF::BA), enabling bidirectional navigation between items and their suppliers.

Item Supplies implement the GEN::ENTSUB subordinate entity contract. They extend the generic pattern with:

• Designation management (Primary/Secondary/Default) — a supply-specific concept with no GEN counterpart.
• Inline creation during parent editing — supplies can be created within the Item form, not only from the Item Details Panel.
• Legacy compatibility — free-form supplier names from before the Business Affiliate system are supported as unlinked entries.

---

REF::SPL::0001 — View Item Supplies

The Inventory Manager or Purchasing Manager inspects all supply sources for a given Item from within the Item Details Panel.

Persona	Irene Itemsworth (Inventory Manager), David Dealsworth (Purchasing Manager)
Implements	GEN::ENTSUB::0001
Depends	REF::ITM::0002
Status	Covered

REF::SPL::0001::0001.BA — View Supplies in Item Details Panel

Specializes GEN::ENTSUB::0001::0001. The ItemSupplySection renders supply cards below the item’s standard fields in the Details tab. Each card shows: supplier name, SKU, unit cost, lead time, and order method. Designation badges appear on applicable cards:

• A blue “Primary” badge if the supply matches the item’s primarySupply.supplyEId.
• A gray “Secondary” badge if the supply matches secondarySupply.supplyEId.
• A gold star icon if the supplier matches defaultSupply.

If the item has free-form supply data from before the Business Affiliate system (legacy data) but no formal ItemSupply entities, that data is displayed in a simplified card with an italic label: “Legacy supply — not linked to a supplier record”.

Postcondition: The user sees all supply sources for the item, including designation status and legacy fallback data.

REF::SPL::0001::0002.BA — View Supply Details (Navigate to Supplier)

Specializes GEN::ENTSUB::0001::0003. Clicking the supplier name on a supply card navigates to /supplier/{supplierEId} if the supply has a supplierEId. Legacy free-form entries render the name as plain text with no link.

Postcondition: The user navigates from a supply card to the corresponding Business Affiliate record. See also: Business Affiliate Behaviors.

---

REF::SPL::0002 — Add and Edit Item Supplies

The Purchasing Manager adds a new supply source to an Item or updates the details of an existing supply, using a modal dialog accessible from the Item Details Panel.

Persona	David Dealsworth (Purchasing Manager)
Implements	GEN::ENTSUB::0002, GEN::ENTSUB::0003
Depends	REF::SPL::0001
Status	Covered

REF::SPL::0002::0001.BA — Add Supply from Item Details Panel

Specializes GEN::ENTSUB::0002::0001. The user clicks ”+ Add” in the ItemSupplySection header. The ItemSupplyFormDialog modal opens. The Supplier field uses an AffiliateTypeahead that searches Business Affiliates with the VENDOR role. Additional fields: Supply Name, SKU, Order Method, Order Quantity, Unit Cost, and Lead Time. Save calls POST /api/arda/items/{itemEId}/supply.

Postcondition: A new ItemSupply entity is created for the Item, linked to the selected Business Affiliate.

REF::SPL::0002::0002.BA — Add Supply with New Supplier (Create-on-the-Fly)

Specializes GEN::ENTSUB::0002::0002. The typeahead shows ”[+] New supplier: [name]” when no matches exist. A secondary inline form expands with the name pre-filled and the Role pre-selected as VENDOR. The system calls POST /api/arda/suppliers to create the Business Affiliate, then POST .../roles to add the VENDOR role. The Supplier field is populated with the new affiliate’s eId. The user completes the remaining supply fields and saves.

Postcondition: Both a new Business Affiliate and a new ItemSupply are created in a single workflow.

REF::SPL::0002::0003.BA — Edit Supply from Item Details Panel

Specializes GEN::ENTSUB::0003::0001. The user clicks Edit on a supply card. The ItemSupplyFormDialog opens pre-filled with current values. Save calls PUT /api/arda/items/{itemEId}/supply/{supplyEId}.

Postcondition: The ItemSupply entity is updated with the new values.

---

REF::SPL::0003 — Remove Item Supplies

The Purchasing Manager removes a supply source that is no longer valid. When the supply being removed has an active designation, the system provides an additional warning.

Persona	David Dealsworth (Purchasing Manager)
Implements	GEN::ENTSUB::0004
Depends	REF::SPL::0001
Status	Covered

REF::SPL::0003::0001.BA — Remove a Non-Designated Supply

Specializes GEN::ENTSUB::0004::0001. The user clicks Remove on a supply card that holds no designation. Confirmation dialog: “Remove supply from [supplier name] for this item? This cannot be undone.” On confirm, DELETE /api/arda/items/{itemEId}/supply/{supplyEId}.

Postcondition: The ItemSupply entity is deleted.

REF::SPL::0003::0002.BA — Remove a Designated Supply (Warning)

Specializes GEN::ENTSUB::0004::0002. When the supply is designated as Primary, the dialog includes: “This supply is currently designated as Primary. Removing it will leave the Item with no primary supply. You should designate another supply as Primary.” On “Remove Anyway,” the system deletes the supply and clears the item’s primarySupply field.

Postcondition: The supply is removed and the item’s Primary designation is cleared, leaving it unset until the user reassigns it.

---

REF::SPL::0004 — Supply Designation Management

The Purchasing Manager controls which supply is the authoritative source (Primary), which is the backup (Secondary), and which is the system default for purchasing workflows (Default). This use case has no GEN counterpart — designation management is specific to the Item-ItemSupply relationship.

Persona	David Dealsworth (Purchasing Manager)
Depends	REF::SPL::0001
Status	Covered

REF::SPL::0004::0001.BA — Change the Primary Supply

With the ItemDetailsPanel open showing two or more supply cards, the user clicks the ”…” menu on a supply card that is currently Secondary. The dropdown shows “Set as Primary.” The user clicks it. The system calls PUT /api/arda/items/{itemEId} to update the Item’s primarySupply field. The previously Primary supply card loses its badge; the selected card gains it. Primary and Secondary must not be the same supply.

Postcondition: The item’s primarySupply is updated to the selected supply.

REF::SPL::0004::0002.BA — Set the Default Supply

With two or more supply cards visible, the user clicks the star icon (shown as an outline) next to a supply card. The star fills to gold. The previously default supply’s star reverts to an outline. The system calls PUT /api/arda/items/{itemEId} with defaultSupply set to this supply’s supplier name. A toast confirms: “Default supply updated.”

Postcondition: The item’s defaultSupply is updated, which the purchasing workflow will use as the default reorder source.

---

REF::SPL::0005 — Inline Supply Creation During Item Edit

While editing or creating an Item through the ItemFormPanel, the Inventory Manager can associate a supply with an existing Business Affiliate using a typeahead, or create a new Business Affiliate on-the-fly without leaving the item form. This extends the GEN::ENTSUB::0002 add pattern from the detail panel context to the parent entity’s own creation/edit form.

Persona	Irene Itemsworth (Inventory Manager)
Depends	REF::ITM::0003, REF::ITM::0004
Status	Covered

REF::SPL::0005::0001.BA — Select Existing Affiliate in Item Form

The user is in the ItemFormPanel and scrolls to the Primary Supply section. They type a partial name in the Supplier field. The AffiliateTypeahead queries GET /api/arda/suppliers/lookup?name={query}&role=VENDOR and shows matching results. The user selects a match; the supplierEId is stored in form state. The user fills in remaining supply fields and clicks Publish or Save Draft. The backend atomically creates or updates the ItemSupply entity with mutation-mode=PROPAGATE.

Postcondition: The item is saved with a structured supply linked to an existing Business Affiliate.

REF::SPL::0005::0002.BA — Create New Affiliate Inline in Item Form

In the Primary Supply section, the user types a supplier name with no existing matches. The typeahead shows ”[+] New supplier: [name]”. The user clicks it and a compact inline form appears. The system creates the Business Affiliate and VENDOR role in the background. The user completes the item form and saves. The backend creates or updates the ItemSupply with the new supplierEId.

Postcondition: A new Business Affiliate is created and the item’s supply is linked to it without leaving the item form.

REF::SPL::0005::0003.BA — Legacy Compatibility (Free-Form Entry)

In the ItemFormPanel, the user types a supplier name but presses Tab or clicks outside without selecting an existing affiliate or the “New supplier” option. The field accepts the raw text with no supplierEId. The system stores the supply with supplier: "[typed name]" and no Business Affiliate linkage. This preserves backward compatibility with item records created before the Business Affiliate system.

Postcondition: The item is saved with a free-form supplier name and no Business Affiliate linkage. The data displays as a legacy supply card.

---

REF::SPL::0006 — View Items by Supplier

The Purchasing Manager views all items that are sourced from a given supplier, accessed through the Supplier Details Panel.

Persona	David Dealsworth (Purchasing Manager)
Implements	GEN::ENTSUB::0005
Depends	REF::BA::0001
Status	Covered

REF::SPL::0006::0001.BA — View Items Tab in Supplier Details

Specializes GEN::ENTSUB::0005::0001. The Items tab in the SupplierDetailsPanel shows a grid of Items whose ItemSupply.supplierEId matches this affiliate. Columns: Item Name (link to /item/{itemId}), SKU, Unit Cost, and Designation badges. Clicking an item row navigates to /item/{itemId} with the ItemDetailsPanel open.

Postcondition: The user can navigate from a supplier to all items it supplies, completing the bidirectional cross-reference.

REF::SPL::0006::0002.BA — Supplier with No Items

Follows GEN::ENTSUB::0005::0002. Empty state: “No items are linked to this supplier.”

Postcondition: The user receives a clear empty-state message rather than a blank or errored view.

---

Summary

Use Case	Scenarios	BA
REF::SPL::0001 View Item Supplies	2	2
REF::SPL::0002 Add and Edit Item Supplies	3	3
REF::SPL::0003 Remove Item Supplies	2	2
REF::SPL::0004 Supply Designation Management	2	2
REF::SPL::0005 Inline Supply Creation During Item Edit	3	3
REF::SPL::0006 View Items by Supplier	2	2
Total	14	14

---