Non Stock and Trade In Applet

Overview

The Non Stock and Trade In applet (NSTI) is the register of items that sit outside the normal inventory ledger: trade-in units taken from customers (a used phone accepted against a new one at the POS) and non-stock items you still want to track one unit at a time. Each record in the listing is one unit — one serial number at one location — with its purchase and sale prices, category, GL code and a running quantity balance. The applet also maintains the NSTI categories and offers a CSV import.

It is opened by the store or inventory team that receives and resells trade-ins, and by finance for the GL side. Most NSTI records are not typed in here: they are created by the backend when a POS cash bill or sales document with a trade-in line is finalised, and they are reduced again when the unit is sold. This applet is where you look them up, correct them, finalise them and attach documents.

Where it fits

Modules: Inventory, Sales, Financial Accounting.

Screens and menus

Left menu (route applet/tnt/wavelet/erp/nsti-applet/…):

Gear (Settings) menu: System Configuration › Field Settings, Default Selection; the shared frame adds Server Side Permissions (Permission Wizard, Permission Set, User Permission, Role Permission), Integration › Triggers (webhooks) and Developer Tools. All of those have routes in this applet except the developer-tools links; Feature Visibility is routed but has no menu entry. Personalization lists Field Settings (no personalization route — the link does nothing) and Default Selection.

NSTI Stock listing

Columns: NSTI Code, NSTI Name, Type (TRADE_IN / NON_STOCK), Serial Number, Category, Branch, Location, Amount (purchase price incl. tax), Stock Balance (qty_base), Posting Status (DRAFT / FINAL), Status, Created Date (the purchase date), Updated Date. Keyword search plus column filters. + opens the create panel; clicking a row opens the edit panel.

Create panel

One Details tab (see Fields). Pressing + first posts a temporary header (status = TEMP, posting_status = DRAFT) so that the record already has a guid; SAVE then updates it to ACTIVE (nsti-listing.component.ts onAdd(), nsti-stock.effects.ts createTempNstiStock$ / createActiveNstiStock$). A SCAN button next to Serial Number opens the camera barcode reader.

Edit panel

Tabs Details, Txn Line, Attachment (or three stacked panels when Vertical Orientation is on). Header buttons SAVE and FINAL; a Delete button below the tabs (two clicks — the first arms it, the second sends the delete).

• Details — the create fields plus read-only Purchase Date, Purchase Price, Sales Date, Sales Price (filled by the document processors) and editable Current Value and Current For Sale Price.
• Txn Line — the unit’s transaction history (bl_fi_nsti_stock_txn_line): Txn Doc No, Txn Date, Doc Short Code, Txn Type (ACQUISITION / DISPOSAL / ADJUSTMENT), Qty, Unit Price, SST/VAT/GST, WHT, Txn Amount; filter by keyword and document type. Add Transaction creates a manual line; lines that came from a document are read-only.
• Attachment — files attached to the unit (bl_fi_nsti_stock_attachment): Attachment Name, Details, file.

NSTI Category

Listing: Category Code, Category Name, Creation Date, Updated Date, Status. Create: Code, Name, Description, Status. Edit adds Delete (two-click). There is no parent category — the list is flat.

Import NSTI

Listing: File Name, File Size, Format, Status, Process Status (PROCESSING / DONE / FAILED), User Error Message, Created Date, Updated Date, Created by. Create: drag-and-drop or Upload File, ADD, and a Sample Format link that downloads MasterData_Upload_Nsti_Stock.csv from the backend. Opening a row shows the parsed helper rows (Code, Name, Type, Category Code …) and a Delete.

Configuration

Before you can use it

• A doc item of transaction type NSTI in Doc Item Maintenance. The Financial Item picker on the NSTI record lists every ACTIVE doc item (item-details.component.ts getFiItems()), but the document processors only act on lines whose item has txn_type = NSTI (NonStockTradeInTxnLineService.isNSTIItem, L98-108). Pick a non-NSTI item and the unit will never be moved by documents.
• Company, branch and location in Organisation — all three are mandatory on the record; the backend rejects unknown guids (NON_STOCK_TRADE_IN_HDR_COMPANY_GUID_DOES_NOT_EXIST, …_BRANCH_GUID_…, …_LOCATION_GUID_…, NonStockTradeInHdrDataConsistencyObject).
• Company default GL code NSTI in Chart of Account › Companies › Default GL Codes — optional: if the company has no valid NSTI link when a document creates or updates a unit, the backend creates a GL code named “Non-Stock and Trade-In”, links it to the company and resolves a subledger (NonStockTradeInStockHdrService.createTradeInStock L108-160, ensureNSTIGLCode L298-425). Set it deliberately if you want the value on an account of your choosing. COGS_NSTI and STOCK_BALANCE_NSTI are needed only for the month-end closing-stock journal (FinancialReportService L504-508).
• Job-processor subscriptions. Documents create NSTI transaction lines only if the tenant’s job-template links subscribe NSTI_TXN_LINE_PROCESSOR to the generic-document primary queue (BLG_ERP_GENERIC_DOCUMENT_PRIMARY_PROCESSOR, GenericDocumentPrimaryProcessor L73-90) and NSTI_TXN_LINE_TO_CURRENT_STOCK_BALANCE_PROCESSOR to NSTI_TXN_LINE_PROCESSOR (NonStockTradeInTxnLineProcessor.findAndTrigger, L126-149). Neither is an applet setting; ask the platform team when FINAL documents leave no trace here.
• Server-side permissions — TNT_API_NON_STOCK_TRADE_IN_HDR_{CREATE,READ,UPDATE,DELETE} (or _OWNER / _ADMIN), the same set with _TXN_LINE_, _CATEGORY_, _ATTACHMENT_ and the import-file controllers (NonStockTradeInHdrController L62-128 and siblings).

Applet settings

Settings are applet-local: settings/field-settings renders this repo’s own FieldConfigurationComponent (four panels: Stock Settings, Category Settings, Import File Settings, Vertical UI Setting), saved by the shared session effect into the applet’s APPLET_SETTINGS extension. The shared document-applet Field Configuration screen is not used, so applet-scan.sh / gates.py do not apply. Every control starts unset, so all hides are off, records lock at FINAL and the layout is horizontal until someone saves the screen. Anyone with access to the Settings menu can change them; they apply tenant-wide.

Those 27 keys pass the declared / rendered / persisted / consumed test (checked at commit 209aafd). Also on the screen or in the model, but short of it:

• STOCK_HIDE_COMPANY — rendered and saved, but the listing has no Company column and nothing reads the key.
• SHOW_API_UPLOAD — declared and saved (the save handler even logs it) but has no toggle and no reader.
• Read without a control: STOCK_HIDE_TYPE, STOCK_HIDE_BRANCH, STOCK_HIDE_SN, STOCK_HIDE_AMOUNT, STOCK_HIDE_PURCHASE_DATE, STOCK_HIDE_UPDATED_DATE (listing columns Type, Branch, Serial Number, Amount, Created Date, Updated Date — nsti-listing.component.ts L128-143) and DEFAULT_TOGGLE_COLUMN / DEFAULT_ORIENTATION (the orientation formula). They can be set only by writing APPLET_SETTINGS directly.
• Default Selection (Default Branch, Default Location): the subscription that would load the container is commented out, so choosing a value throws on an undefined appletContainer; nothing reads DEFAULT_BRANCH / DEFAULT_LOCATION (default-settings.component.ts L30-66). Personalization › Default Selection is the same code (personal-default-settings.component.ts L31-75). PRINTABLE is model-only.

Document behaviour settings

Not applicable in the document sense — this is master data with its own posting_status. What FINAL does is described under Lifecycle and effects: it is a header field that the applet’s own buttons honour; the backend does not post anything on it.

Settings in other applets that control this applet

Feature visibility / permissions

• Client-side permissions: bl_applet_client_side_perm_dfn holds no rows for nonStockAndTradeInApplet, and the applet checks no SHOW_* codes. Feature Visibility is the shared Manage Team Access screen only; the HIDE_* settings cannot be reopened per role.
• Server-side permissions: the Permission Set / User / Role routes are the shared containers; each NSTI controller checks its own TNT_API_NON_STOCK_TRADE_IN_* code (checkNormalPermissionWithBC) with the tenant owner / admin roles as fallback.

Fields

NSTI Stock — Details

Txn Line — Add Transaction

A manual line is stored with nsti_stock_hdr_guid = the unit and no document; the backend validates existence of any guids set (NonStockTradeInTxnLineDataConsistencyObject) and does not change the unit’s Stock Balance — only the balance processor does that, and it runs for document-generated lines only (see below).

Attachment

Attachment Name, Details, one file → bl_fi_nsti_stock_attachment (file_name, import_format, file_details, upload_date).

NSTI Category

Import NSTI — CSV columns

CODE, NAME, TYPE, FINANCIAL_ITEM_CODE, CATEGORY_CODE, COMPANY_CODE, BRANCH_CODE, LOCATION_CODE, EMPLOYEE_NAME, CURRENCY, GL_CODE, WARRANTY_EXPIRY, SERIAL_NUMBER, PURCHASE_DATE, PURCHASE_PRICE_INCL_TAX, SALES_DATE, SALES_PRICE_INCL_TAX, CURRENT_VALUE_INCL_TAX, CURRENT_FOR_SALES_PRICE_INCL_TAX (NonStockTradeInImportFileColumnNames). Header row required (case-insensitive), values trimmed, dates as ISO zoned date-times, UTF-8 with or without BOM (NonStockTradeInImportFileHdrService.readCSV, L136-168).

Lifecycle and effects

This is a master-data applet with its own tables — no server document type, no amount or quantity signum of its own, no journal from this applet, no open-queue rows. The posting_status on a unit is set by the applet’s FINAL / SAVE buttons through an ordinary PUT …/non-stock-trade-in/stock-hdrs/backoffice-ep; the backend validates the container and updates the row (NonStockTradeInStockHdrService.updateNonStockTradeInHdr) — it posts nothing and does not lock anything server-side. The lock is enforced only by the applet’s buttons and reopened by ALLOW_EDIT_TXN_LINE_AFTER_FINAL.

What the applet writes

How documents create and move units (the real lifecycle)

1. A generic document is finalised. BLG_ERP_GENERIC_DOCUMENT_PRIMARY_PROCESSOR fans out to the tenant’s subscribed processors; NSTI_TXN_LINE_PROCESSOR (NonStockTradeInTxnLineProcessor) calls createAndPostNstiTxnLines (NonStockTradeInTxnLineService L243-344). It returns nothing when the header’s posting_trade_in is already set (checkCanBePosted, L64-66) or when the document is in a foreign currency (doc_ccy ≠ base_doc_ccy, L255-265).
2. For every PNS line with a non-zero quantity whose item has txn_type = NSTI and which carries serial numbers, NonStockTradeInTxnLineFactory writes one transaction line per serial with quantity_base = 1, the document’s quantity signum (forced to +1 for INTERNAL_SALES_CREDIT_NOTE) and the line’s amounts, prices and taxes; txn_type = ACQUISITION for +1, DISPOSAL for −1, ADJUSTMENT for 0 (L20-48, L115-135, L160-170). Lines without serial numbers create nothing. Stock-in-transit counter-lines are added for transfer-type documents (createStockInTransitTxns, L383-420).
3. Each new line is handed to NSTI_TXN_LINE_TO_CURRENT_STOCK_BALANCE_PROCESSOR → processTxnLine (L111-198): the unit is looked up by item + serial number + location (getCurrentBalanceQtyContainer, L72-88 — all three mandatory). If it exists, qty_base += quantity_base × quantity_signum and an invalid GL link is repaired; if not, a unit is created with type = TRADE_IN, posting_status = FINAL, a code from the CODE running number, the line’s item name, currency, company / branch / location, purchase date and price (amount_txn / quantity_base), the serial, qty_base = the line quantity, and the company NSTI GL code (created if missing) plus subledger (createTradeInStock, L89-168).
4. POST …/non-stock-trade-in/txn-lines/posting/{docGuid} (NonStockTradeInTxnLineController L178-200) re-runs steps 1-3 for one document by hand — the repair path when the queue was not subscribed.

Signums of the trade-in document types (GenericDocumentTypeHandler L824-839): INTERNAL_PURCHASE_TRADE_IN — quantity +1, amount −1 (the POS trade-in line: the unit comes in, the customer’s bill goes down); INTERNAL_SALES_TRADE_IN — quantity −1, amount +1. A normal sales line (INTERNAL_SALES_CASHBILL, INTERNAL_SALES_INVOICE, quantity −1) on an NSTI serial disposes of the unit; a sales credit note brings it back.

Journal. NSTI lines are posted by the document’s own posting, not by this applet: JournalPostingService maps a PNS line whose item is NSTI (or whose document type is either trade-in type) to transaction code NSTI (L154-157) and resolves the GL as line GL → header GL → item-company link with code NSTI → company default NSTI (L158-188). Month end: FinancialReportService posts the NSTI closing-stock value between COGS_NSTI and STOCK_BALANCE_NSTI (L504-508, L602-607).

Stock check on sale. When the backend validates stock for a document (GenericDocumentService.validateStockBalance, called at L1667), every NSTI serial on a line must have qty_base ≥ 1 at the line’s location (delivery location, else guid_store), otherwise the document is rejected with STOCK_BALANCE_OBJECT_NO_STOCK_AT_LOCATION — “There’s not enough stock for NSTI item code, serial number sn” (L2115-2152).

Backend validation that stops a save (the exact throws): unit — guid unique (NON_STOCK_TRADE_IN_HDR_GUID_ALREADY_EXISTS); company, branch, location, category, GL code, subledger, item, applet, module and linked purchase / sales document guids must exist if set (NON_STOCK_TRADE_IN_HDR_*_DOES_NOT_EXIST); status, revision, created / updated dates and subjects mandatory (NonStockTradeInHdrDataConsistencyObject). Transaction line — the same shape (NON_STOCK_TRADE_IN_TXN_LINE_OBJECT_*), including NSTI_STOCK_HDR_GUID_DOES_NOT_EXIST. Category — guid, applet, module, label header and audit fields (NON_STOCK_TRADE_IN_CATEGORY_*). There is no uniqueness check on unit code, serial number or category code.

What it only reads. Stock Availability unions bl_fi_nsti_stock_hdr (grouped by company, location, item; cost = purchase_price_incl_tax) with inventory balances for items of type NSTI (StockAvailabilityUow L261-307). The historical stock balance report does not include NSTI units (gh:bigledger/blg-int-general-task#1422, open).

Related applets

• Doc Item Maintenance — creates the NSTI-type items that the record’s Financial Item should point at; only those are recognised by the document processors.
• POS General — trade-in lines (INTERNAL_PURCHASE_TRADE_IN) on a cash bill are the main way TRADE_IN units are created; selling the unit later disposes of it.
• Sales Invoice, Sales Credit Note — dispose of and restore NSTI serials; the credit note’s quantity signum is forced to +1 for NSTI lines.
• Stock Availability — the only stock report that shows NSTI balances; Stock Balance and Stock Report show inventory only.
• Chart of Account — company default GL codes NSTI, COGS_NSTI, STOCK_BALANCE_NSTI and the closing-stock record’s NSTI value; Financial Report — where the month-end NSTI closing journal lands.
• Organisation — company, branch and location; the location is part of the unit’s identity.
• Tax Configuration — tax and WHT codes on manual transaction lines.
• Employee Maintenance — the optional person in charge on a unit.

Troubleshooting

Related documentation

• Inventory Workflow applets
• Doc Item Maintenance — where the NSTI item type is set
• POS General — trade-in lines at the till
• Inventory module