Stock Management¶

MatStream's stock management layer tracks on-hand inventory quantities for items across locations. Stock data is linked to entity records, so inventory quantities live alongside the full part lifecycle, BOM, and document context.

Concepts¶

Items and locations¶

In MatStream, both inventory items (parts, materials, products) and locations (warehouses, shelves, bins) are regular entities in the workspace. Any entity in the correct category can be an item or a location. Your administrator defines which categories serve as item types and which serve as location types.

Stock position¶

A stock position is the current quantity of a specific item at a specific location. It tracks four quantities:

Automatic stock replenishment¶

On a definition's Stock tab, enable Is Stock Item and enter Minimum Stock Qty and Maximum Stock Qty. Both limits must be filled in, the minimum must be nonnegative, and maximum must exceed minimum. Saving the settings makes the item eligible for the next check; it does not immediately create a requirement.

The API's StockReplenishment background job (type 16) defaults to every minute in Development for testing, and every five minutes otherwise. It calculates:

• Projected stock = On Hand minus Reserved + On Order.
• If projected stock is strictly below Minimum, required quantity = Maximum minus projected stock.
• At or above Minimum, an existing unfulfilled replenishment requirement is deleted.

Example: Minimum 10, Maximum 30, Available 6, On Order 3, no pending replenishment → create a requirement for 21. The next check keeps that same requirement at 21. Changes to stock or Min/Max update the existing unfulfilled line instead of creating another line. Older duplicate unfulfilled lines are consolidated into the oldest one. Ordered lines and lines with stock ledger history are preserved. Creating a requirement does not write a stock movement or place a purchase order.

Requirements are regular Material Requirement Lines and appear in Purchasing → Pending Material Requirements (MR), whose filter searches the whole workspace. They have no source project occurrence and no project number. The buyer orders them through normal procurement; the resulting on-order quantity counts as supply in the calculation. Replenishment requirements cannot be reserved from existing stock: that would consume the stock they are intended to refill.

Setup and operation: re-run the Engineering Project template to create the dedicated Purchasing → Stock Replenishment storage folder. Restart the updated API to register the job. The scheduler has a five-minute startup delay. Existing enabled/interval settings on the job are preserved. The job requires exactly one enabled Material Requirement category and exactly one replenishment folder under a Purchasing-category folder per workspace. It uses the folder creator as its workspace actor, who must still be enabled. Missing or ambiguous setup is skipped. Stock properties are resolved by their seeded names; preserve those names. Custom project requirements are not counted as replenishment. Unchecking Is Stock Item stops future checks for that definition and preserves existing requirements.

Stock ledger¶

Every change to a stock position is recorded as an immutable ledger entry. The ledger provides full traceability: who made the change, when, why (via a note), and what the delta was.

Viewing stock on an entity¶

Open any item entity and navigate to the Stock display tab (if configured for that category). The tab shows:

• Current on-hand, reserved, on-order, and available quantities per location
• A movement ledger showing all historical adjustments and transactions

Open a location entity and navigate to its Stock tab to see all items held at that location.

Adjusting stock manually¶

Manual adjustments are used for inventory counts, write-offs, receipts without a purchase order, and corrections.

1. On the item entity's Stock tab, click Adjust Stock (or use the tray icon from the ribbon).
2. Select the location.
3. Enter the adjustment quantity — positive to add stock, negative to remove.
4. Optionally enter a note explaining the reason.
5. Click Apply.

The adjustment is recorded in the ledger immediately. The on-hand quantity updates.

Movement types¶

The ledger distinguishes the following movement types:

Demand and supply lines¶

Two different kinds of line feed the stock picture, and the distinction matters.

Material Requirement lines — demand¶

A Material Requirement records that something is needed: four of this part, by this date, for this project. Nothing has moved in stock, so no ledger entry is written when a requirement is raised.

A requirement carries:

Open Qty is the buyer's working number. A requirement is finished when it reaches zero, regardless of how it got there — partly from the shelf, partly bought.

Purchase and sales order lines — supply and commitment¶

These categories carry the Stock Line behaviour, meaning the line is a stock movement. Their quantities are computed live from the ledger:

• A purchase-order line writes OnOrderAdd when it enters Ordered, and OnOrderRelease when it leaves.
• A sales-order line reserves and then ships.

How a requirement gets satisfied¶

1. An engineer moves a part in the Explorer to Ready for Procurement. If the Create Material Requirement automation is configured, a requirement line is raised automatically against the owning project.
2. A buyer reviews open requirements and decides per line:
   • Reserve from stock — writes an MR Reservation movement, raising Reserved Qty.
   • Order it — creates a purchase-order line, which writes OnOrderAdd and raises Ordered Qty.
3. Both routes can be used on the same requirement, so partial coverage works: 4 needed, 2 reserved, 2 ordered, 0 open.
4. Receipt of the purchase order posts PO Receipt, moving the quantity from On Order to On Hand.

API reference¶

Permissions¶

Receiving a purchase order also needs procurement.receive; creating or cancelling one needs procurement.order. These grants are enforced by the API. Entity and lifecycle permissions still apply to the item, location, requirement, or order being acted on.

Setting up stock management¶

1. Define categories for items and locations in Configuration → Categories.
2. Add a Stock display tab to the item and location categories (Configuration → Categories → Display Tabs). Set the tab type to Stock / Ledger.
3. Create location entities — create entities in a location category for each warehouse, shelf, or bin.
4. Start adjusting — open an item entity and use the Stock tab to post initial on-hand quantities.

Related¶

• Display Tabs — configure the Stock and Ledger tabs on categories
• Entities overview — entity concepts
• Explorer — navigate to item and location entities
• Procurement — requirements, purchase orders, receiving and vendor documents
• Barcode scanning - scanning items onto orders and pick lists