Volume 5 • Article #15 Procurement & SRM Routes: vendor/index • add • viewVendor • settings
Suppliers, Price Book Contracts, SLA Scorecards & Procurement Governance Studio
A complete field-by-field and button-by-button reference to the 4-Mode Supplier & Procurement Command Center, Negotiated SKU Price Books, Delivery SLA & Quality Scorecards, EFT Banking & Tax Compliance, the 5-Tab 360° Supplier Cockpit, and the 3-Tab Supplier Governance Studio.
Plain-English Procurement & Accounting Primer: Suppliers, Price Books & Trade Credit
Just as Customers represent your Accounts Receivable (AR) on the sales side, Suppliers (Vendors) represent your supply chain partners and Accounts Payable (AP) on the purchasing side:
1. Catalog Cost vs. Price Book Contract
An Inventory SKU has a general Catalog Cost Price. However, you may buy that same SKU from three different suppliers at different negotiated rates, Minimum Order Quantities (MOQs), and lead times. The Supplier Price Book maps each Supplier's exact Part Number and negotiated cost to your internal SKU.
2. Open PO Commitment vs. Actual AP Spend
When you issue a Purchase Order (PO), it is an Open PO Commitment (an order in transit—not yet a financial debt). Only when the goods arrive via a Goods Received Note (GRN) or a Supplier Expense / AP Voucher is recorded does it become actual expenditure or an Accounts Payable liability.
3. EFT Banking & Tax/VAT Verification
To prevent payment fraud and rejected SARS Input VAT claims, Keystone X tracks whether a supplier's EFT Bank Account is Verified and whether they are Tax Compliant / VAT Registered, and can block unverified suppliers from receiving Purchase Orders.
1. Supplier & Procurement Command Center (vendor/index)
Navigate to Procurement → Suppliers in the left sidebar (`vendor/index`). This workspace unifies supplier relationship management (SRM), negotiated SKU price books, delivery SLA scorecards, and EFT banking readiness.
📸 [SCREENSHOT PLACEHOLDER: vendor-command-center-directory.png]
- Where to Navigate: Go to
vendor/index?mode=directory. - What to Capture: Capture the full Supplier Command Center showing the Header Banner, the 6 Executive Telemetry KPI Cards, the 8-Pill Supplier Lifecycle & Tier Pipeline Strip, the 4 Mode Navigation Pills, and the Master Supplier Directory table.
1.1 Header Banner Badges & Action Buttons
| Button / Badge | Route / Trigger | Exact System Behavior |
|---|---|---|
| Enterprise Supplier & Procurement ERP Badge | Header Status Pill | Identifies the active SRM & Procurement Command Center. |
| X Mapped Price Book SKUs Badge | Header Status Pill | Displays the total number of supplier-specific SKU price contracts (`$stats->catalog_skus_count`) mapped across all suppliers. |
| X Low-Stock Reorder Alerts Badge | Header Status Pill | Appears dynamically when mapped Price Book SKUs have fallen at or below their Reorder Point (`$stats->reorder_alerts_count`). |
| Purchase Orders & GRNs | PurchaseOrder/index |
Jumps directly to the Purchase Order & Goods Received Note Command Center. |
| Serial & RMA Center | inventory/serialTracking |
Jumps to the 360° Serial Number, Warranty & Supplier RMA Command Center. |
| + Map Price Book SKU | #addCatalogItemModal |
Opens the modal to link an internal Inventory SKU to a Supplier with a negotiated Ex-VAT unit cost, Supplier Part #, MOQ, Lead Time, and OEM Warranty duration. |
| + Log SLA Review | #logEvaluationModal |
Opens the modal to score a supplier's Delivery SLA (1–5), Product Quality (1–5), Pricing Competitiveness (1–5), Observed OTD %, and Quality Acceptance %. |
| Customize | vendor/settings |
Opens the 3-Tab Supplier, Price Book & Procurement Governance Studio. |
| + Onboard Supplier | vendor/add |
Opens the 6-card Enterprise Supplier Onboarding Workbench (requires `add_vendors` permission). |
1.2 The 6 Executive Procurement Telemetry KPI Cards
| KPI Card Title | Primary Metric & Sub-Metrics Displayed |
|---|---|
| 1. Registered Suppliers | Total supplier count (`$stats->total_vendors`), plus breakdown of Active vs. Preferred / Strategic partners. |
| 2. Cumulative PO Spend | Total lifetime Purchase Order value (`$stats->total_po_spend`), total PO count, and number of Fully Received POs. |
| 3. Open PO Commitment | Total rand value of open/in-transit Purchase Orders (`$stats->open_po_commitment`) and count of Open / In-Transit POs awaiting warehouse GRN receipt. |
| 4. Direct Expenses & AP | Total direct expenditure recorded against suppliers (`$stats->total_expense_spend`) and total number of linked Expense Vouchers. |
| 5. Price Book & Reorder | Total Mapped SKUs (`$stats->catalog_skus_count`) and live count of Low-Stock SKUs needing a restock PO. |
| 6. SLA & Banking Health | Fleet-wide average On-Time Delivery (OTD %) (`$stats->avg_otd_pct`), count of suppliers with Verified EFT Banking (`Bank OK`), and average Quality Acceptance (`QA %`). |
1.3 The 8-Pill Interactive Supplier Lifecycle & Tier Pipeline Strip
Clicking any pill filters the Command Center immediately:
- All Suppliers (`status=all`): Shows every supplier record in the database.
- Active Partners (`status=active`): Filters to operational suppliers (`is_active = 1`).
- Strategic & Preferred (`status=preferred`): Filters to top-tier suppliers (`supplier_tier = 'Strategic Partner'` or `'Preferred'`).
- Open POs In-Transit (`status=open_pos`): Filters to suppliers with active Purchase Orders currently awaiting warehouse delivery.
- Low-Stock Reorder Alert (`mode=catalog&status=reorder`): Switches directly to the Price Book mode and filters to SKUs at or below their Reorder Level.
- EFT Banking Verified (`status=verified_bank`): Filters to suppliers whose bank details have been verified (`banking_verified = 1`).
- Tax Compliant (`status=tax_compliant`): Filters to suppliers marked tax-compliant (`tax_compliant = 1`).
- On Hold / Inactive (`status=inactive`): Filters to suspended or on-hold suppliers (`is_active = 0`).
2. The 4 Workspace Modes on vendor/index
2.1 Mode 1: Master Supplier Directory & Procurement Matrix (?mode=directory)
Includes a live filter bar (**Search Box** for Supplier Name, `SUP-` Code, VAT #, Account #, Contact, Email, or Phone; **Category Dropdown**; **Strategic Tier Dropdown**; **Filter** & **Reset** buttons) and a 10-column matrix:
| Column Header | Data & Interactive Elements |
|---|---|
| Supplier & Code | Clickable Supplier Name (opens 360° Cockpit), Supplier Code badge (`SUP-1001`), Our Account # with Vendor, and VAT Number. |
| Category & Tier | Procurement Category badge (e.g., *Hardware & Electronics*) and color-coded Tier badge (`Strategic Partner`, `Preferred`, `Approved`, `Probationary`, or `On Hold`) plus B-BBEE Level. |
| Primary Contact | Account Manager name, clickable `mailto:` email link, and telephone number. |
| Terms & Lead Time | Payment Terms badge (`30 Days Net`, `COD`, etc.), average Lead Time in days, and Default OEM Warranty months. |
| Price Book SKUs | Clickable badge showing count of mapped SKUs for that supplier, plus a red **X Low Stock** alert badge if any mapped SKU is below its reorder point. |
| POs & Open Value | Total PO count, count of **Open POs** in transit, and open commitment value in Rand. |
| Cumulative Spend | Combined lifetime PO + Direct Expense spend, broken down into `PO: R X` and `Exp: R Y`. |
| SLA & OTD % | Star rating (`4.8 / 5.0`), On-Time Delivery % (`OTD`), and Quality Acceptance % (`QA`). |
| Governance | Active vs. On Hold badge, **Bank OK** vs. **Unverified Bank** badge, and **Tax OK** indicator. |
| Actions | 360° Supplier Cockpit ( `vendor/view/{id}`), Raise Purchase Order ( `PurchaseOrder/add?vendor_id={id}`), Edit Supplier ( `vendor/edit/{id}`), and Delete Supplier ( `vendor/delete/{id}`). |
2.2 Mode 2: Supplier Price Book, SKU Mapping & Replenishment Radar (?mode=catalog)
Cross-references every supplier-mapped SKU against live warehouse stock levels and current catalog cost prices. Rows where warehouse stock is at or below the Reorder Level are highlighted in amber.
📸 [SCREENSHOT PLACEHOLDER: vendor-price-book-replenishment-radar.png]
- Where to Navigate: Click the Supplier Price Book & Replenishment mode tab (`vendor/index?mode=catalog`).
- What to Capture: Capture the Price Book table showing Negotiated Cost vs. Catalog Cost savings badges, Stock vs. Reorder alerts, and the 1-Click Raise PO action button.
| Column Header | Details & Formula |
|---|---|
| Supplier & Tier | Links to the Supplier's 360° Cockpit along with their Supplier Code and Tier badge. |
| Internal SKU & Item | Clickable SKU Number (`inventory/view/{item_id}`) and Item Name. |
| Supplier Part # | The vendor's own catalog/part code (`supplier_sku`, e.g., `SNM-5KVA-HYB`) printed on Purchase Orders. |
| Negotiated Cost (Ex VAT) | Contracted unit price (`unit_cost_ex_vat`) and currency. |
| Current Catalog Cost | Compares the supplier's negotiated price against the SKU's master catalog cost (`current_catalog_cost`). Displays a green Save R X.XX badge if the Price Book contract is cheaper! |
| MOQ / Pack | Minimum Order Quantity (`moq`) and Pack Size (`pack_size`, e.g., `Box of 10`). |
| Lead Time & Warranty | Item-specific delivery lead time (`lead_time_days`) and OEM Warranty coverage (`warranty_months`). |
| Stock vs Reorder | Shows current on-hand quantity (`current_stock`) vs. `reorder_level`. Flags low stock in red (`Reorder <= X`). |
| Preferred | Displays a gold star **Preferred** badge (`is_preferred = 1`) or `Secondary`. |
| 1-Click Action | Raise PO (`PurchaseOrder/add?vendor_id={vid}&item_id={iid}`) pre-populates a new Purchase Order for that supplier and SKU; plus a red Delete (`vendor/deleteCatalogItem/{id}`) button. |
2.3 Mode 3: Delivery SLA, Quality & RMA Scorecard (?mode=performance)
Contains two side-by-side analytical tables:
- Top Table — Supplier Delivery SLA, Quality Acceptance & RMA Reliability Matrix: Ranks every supplier by Overall Rating (1.00–5.00 stars), On-Time Delivery % (`OTD %` progress bar), Quality Acceptance % (`QA %` progress bar), Total POs vs. Late POs, Supplied Serials & Active RMA Claims, and a quick button to score the supplier.
- Bottom Table — Recent Supplier Performance & SLA Reviews: Audit log of individual evaluations showing Date, Supplier, Reviewer Name, Delivery SLA score, Quality score, Pricing score, Observed OTD % & QA %, and Evaluator Remarks.
2.4 Mode 4: Spend, Credit Facility & EFT Banking Readiness (?mode=financials)
Provides Treasury and Accounts Payable controllers with a complete financial view of every supplier:
- Payment Terms & Credit Limit: Shows net terms (`30 Days Net`) and maximum negotiated trade credit limit (`credit_limit`).
- Open PO Commitment vs. Credit Utilization Bar: Calculates `Credit Utilization % = (Open PO Value / Credit Limit) × 100` with a color-coded progress bar (Green < 65%, Amber 65–85%, Red > 85%).
- Cumulative PO Spend, Direct Expenses & Total Lifetime Spend: Full expenditure breakdown per supplier.
- EFT Banking Details & Compliance Readiness: Displays Bank Name, masked Account Number (`****1234`), Branch Code, Account Type, and badges for **EFT Verified** vs. **Pending Verification** and **Tax Compliant** vs. **Tax Non-Compliant**.
3. Interactive Modals on vendor/index
3.1 Map Inventory SKU to Supplier Price Book Modal (#addCatalogItemModal)
Submits to vendor/saveCatalogItem:
| Field Label & Input Name | Description & Automation Behavior |
|---|---|
Supplier * (vendor_id) |
Selects which registered Supplier this price contract belongs to. |
Internal Inventory SKU * (item_id) |
Selects an internal Inventory item. Automatically populates the Negotiated Unit Cost (Ex VAT) field with the item's current catalog cost as a starting point (`onModalItemSelect()`). |
Supplier Part / Catalog Code (supplier_sku) |
The supplier's own part number (e.g., `SNM-5KVA-HYB`). |
Supplier Item Description (supplier_item_description) |
Optional supplier-specific description override. |
Negotiated Unit Cost (Ex VAT) * (unit_cost_ex_vat) |
Contracted Ex-VAT purchase price for this supplier. |
Currency (currency) |
Defaults to system currency (`ZAR`, `USD`, `EUR`, `GBP`, etc.). |
Minimum Order Qty (MOQ) (moq) |
Minimum units required per Purchase Order (defaults to `1`). |
Pack Size (pack_size) |
Packaging unit description (e.g., `Each`, `Box of 10`). |
Lead Time (Days) (lead_time_days) |
Expected delivery days from PO issue (defaults to `7`). |
OEM Warranty (Months) (warranty_months) |
Supplier-backed warranty period in months (defaults to `12`). |
Preferred Primary Supplier Switch (is_preferred) |
Marks this vendor as the default preferred supplier for this SKU on the Smart Replenishment Radar. |
Sync Cost Price to Master Inventory Catalog Switch (sync_item_cost) |
When checked, immediately updates the SKU's master `cost_price` and `preferred_vendor_id` in the Inventory Catalog upon saving. |
3.2 Log Supplier Delivery SLA & Quality Evaluation Modal (#logEvaluationModal)
Submits to vendor/addEvaluation. Captures **Supplier** (`vendor_id`), **Evaluation Date** (`review_date`), **Delivery SLA Score (1.0–5.0)** (`delivery_score`), **Product Quality Score (1.0–5.0)** (`quality_score`), **Pricing Competitiveness (1.0–5.0)** (`pricing_score`), **Observed On-Time Delivery %** (`on_time_pct`), **Observed Quality Acceptance %** (`quality_pass_pct`), and **Evaluation Notes / Audit Remarks** (`notes`). Submitting automatically recalculates the supplier's composite star rating and SLA percentages!
4. Onboarding & Editing a Supplier (vendor/add & vendor/edit/{id})
Clicking + Onboard Supplier opens a structured 6-Card Enterprise Onboarding Workbench.
📸 [SCREENSHOT PLACEHOLDER: vendor-onboard-workbench.png]
- Where to Navigate: Go to
vendor/add. - What to Capture: Capture the 6-card layout showing Card 1 (Supplier Identity & SRM Classification), Card 4 (Commercial Terms, Logistics & Warranty Defaults), and Card 5 (EFT Banking & Tax / B-BBEE Governance).
| Card Section | Fields & Input Names | Purpose & System Impact |
|---|---|---|
| Card 1: Supplier Identity & SRM Classification | vendor_code (Auto `SUP-1005`), category, supplier_tier (`Strategic Partner`, `Preferred`, `Approved`, `Probationary`, `On Hold`), is_company switch, company_name, account_number_with_vendor, website |
Establishes the supplier's unique ERP code, procurement category, strategic tier, and your customer account number on their books (printed on POs and EFT remittances). |
| Card 2: Primary Account Representative & Linked Contacts | contact_id (Optional link to Contacts directory), contact_first_name, contact_last_name, email, phone |
Selecting an existing Contact from `contact_id` automatically fills First Name, Last Name, Email, and Phone via `populateFromContact()`. |
| Card 3: Warehouse Dispatch & Physical Address | address (textarea) |
Printed on official Purchase Orders and used for courier collection routing. |
| Card 4: Commercial Terms, Logistics & Warranty Defaults | payment_terms, default_warehouse_id, credit_limit, minimum_order_value, currency, lead_time_days, warranty_months, rma_return_days |
Pre-populates new Purchase Orders with the supplier's default receiving warehouse hub, expected delivery date (`PO Date + lead_time_days`), and OEM warranty expiration (`Receipt Date + warranty_months`). |
| Card 5: EFT Banking & Tax / B-BBEE Governance | banking_verified switch, vat_number, registration_number, bbbee_level (`Level 1`–`Level 8`, `EME`, `QSE`, `Non-Compliant`), bank_name, bank_account_holder, bank_account_number, bank_branch_code, bank_account_type, swift_code |
Stores beneficiary banking details for EFT batch runs and validates SARS Input VAT claims. |
| Card 6: Internal Procurement Notes & Governance Switches | notes, is_active switch (Active Supplier), tax_compliant switch (SARS Tax Clearance / Compliant) |
Toggling is_active off places the supplier On Hold; when governance rules are enabled, On-Hold or unverified suppliers cannot receive new Purchase Orders. |
5. The 360° Supplier & Procurement Cockpit (vendor/viewVendor/{id})
Clicking any Supplier name or the action icon opens the 360° Supplier Cockpit.
- Header Action Bar: Quick buttons for + Map Price Book SKU, + Log SLA Evaluation, + Raise Purchase Order (`PurchaseOrder/add?vendor_id={id}`), + Record Expense (`expense/add?vendor_id={id}`), Edit Supplier, and Command Center.
- 6 Cockpit Telemetry Cards: Total PO Spend, Open PO Commitment (with Credit Limit % bar), Direct Expenses, Price Book SKUs (with Low-Stock count), SLA & OTD %, and Supplied Serials & Active RMAs.
- 5 Interactive Cockpit Tabs (`.command-nav-pills`):
?tab=overview(360° Profile, Banking & Contacts): Displays Commercial & Logistics Profile, EFT Banking & Tax/B-BBEE Governance card, Primary Account Rep & Dispatch Address, and Additional Supplier Contacts (`vendor/addVendorContact`).?tab=catalog(Supplied SKU Price Book): Lists every SKU contracted to this supplier with Negotiated Cost vs. Catalog Cost, MOQ, Lead Time, OEM Warranty, Stock vs. Reorder alerts, and 1-Click Raise PO buttons.?tab=pos(Purchase Orders & FIFO Batches): Displays all Purchase Orders issued to this supplier alongside a second table of all **Warehouse FIFO Batch Lots Received** (`batch_number`, SKU, Warehouse Hub, Remaining/Initial Qty, Unit Cost, Received Date, Expiry Date).?tab=serials(Supplied Serials & RMA Claims): Displays every individual serialized asset (`serial_number`) supplied by this vendor along with its OEM Warranty Expiry date, plus a dedicated table of **Supplier RMA & Defective Return Claims** (`rma_number`, Serial #, Issue Description, Status).?tab=financials(Direct Expenses & SLA Evaluations): Displays all Direct Expense Vouchers paid/payable to this supplier alongside the complete history of **Delivery SLA & Quality Evaluations**.
6. Supplier, Price Book & Procurement Governance Studio (vendor/settings)
Clicking Customize on the Supplier Command Center opens the 3-Tab Governance Studio (`vendor/settings`):
| Studio Tab | Configurable Settings & Switches |
|---|---|
Tab 1: Auto-Numbering, Categories & Defaults (?tab=numbering) |
|
Tab 2: Procurement Governance, Price Book & PO Controls (?tab=governance) |
5 enterprise governance switches:
|
Tab 3: Delivery SLA Targets, OEM Warranty & RMA Policy (?tab=sla) |
|