Consignment GRN Applet (Internal)

Overview

The Consignment GRN Applet (Internal) raises a goods received note for consignment stock — stock a supplier (the consignor) places at one of your locations while still owning it. Finalising a consignment GRN puts the quantity into the location named on the document and, where your company posts journals for it, records the value as consignment stock against a consignment liability — not as a purchase and not as an amount owed to a creditor. Ownership only changes later, when the stock is sold and billed through the consignment billing documents.

Server document type INTERNAL_PURCHASE_CONSIGNMENT_GRN, short code CSGGRN; quantity signum +1, amount signum −1. It is the inbound half of the pair whose outbound half is the Consignment GIN (quantity −1 / amount +1). Unlike the GIN, a consignment GRN can be knocked off from a Consignment Purchase Order and can be voided.

The applet is a single-document applet: one listing with bulk FINAL / VOID / print, a create/edit form, a cross-document line-item listing, and the standard settings pages plus a custom-status designer.

Where it fits

Modules: Purchasing, Inventory.

Screens and menus

Gear (Settings) menu, group System Configuration: Application Settings, Default Selection, Printable Format Settings, Custom Status. The shared settings shell adds the platform pages (Webhook, Feature Visibility, Client-Side Permission, Role Pricing Scheme Link, Permission Wizard / Set / User / Team / Role, Release Notes, Audit Trail). Personalisation: Default Selection and Sidebar.

Listing

Columns: Doc Short Code, Doc No (Tenant), Doc No (Company), Doc No (Branch), Posting Status, Status, Tracking ID, Branch Code, Currency, Supplier Name, Description, Doc Description, Purchaser, Doc Reference, Amount Txn, ARAP PNS, ARAP Settlement, ARAP Doc Open, ARAP Contra, ARAP Bal, Updated Date, Created Date, Transaction Date, Created by, Client Doc Type, Client Doc 1–5, and one column per enabled custom header status. By default the listing shows the last month of transactions for the branches you have permission targets on, sorted by updated_date descending (or by the SORT_ORDER column). FINAL posts every selected row that is DRAFT and ACTIVE; VOID voids every selected row that is FINAL and ACTIVE; the print button is disabled until a default printable format is chosen.

Create / edit form

Tabs on create: Main Details, Account, Lines, Delivery Details, Payment, KO For, Department Hdr (the last four each hideable by the matching HIDE_*_TAB setting), plus a Search tab (“Search By Intercompany Sales Invoices”) for users holding the SHOW_INTERCOMPANY_PGRN_SCREEN client-side permission. Edit shows Main Details, Account, Lines, Delivery Details, Payment, Department Hdr, Trace Document, Contra, Doc Link, Attachments, Export and Status — in the order set under Settings > Default Selection — with RESET, FINAL (only while the document is ACTIVE and DRAFT), SAVE (needs the update permission) and, for non-final documents when SHOW_DOCUMENT_DELETE_BUTTON is on, DELETE (two clicks). The edit form has no VOID button (it is commented out in the template); VOID is done from the listing.

Lines

Add a line with Search Item (consignment items only; the picker also offers a Search Serial Number box) or with KO For Purchase Order / Purchase Requisition / Purchase Invoice, each of which is present only when the company’s document-flow configuration enables a LINE flow from that document type into INTERNAL_PURCHASE_CONSIGNMENT_GRN (line-item-create.component.ts L106–L122). The header-level KO For tab lists consignment purchase orders with open lines for CSGGRN (line_open_queue_server_doc_type_1 = INTERNAL_PURCHASE_CONSIGNMENT_ORDER, _2 = INTERNAL_PURCHASE_CONSIGNMENT_GRN) and refuses a second document from a different entity or branch unless ENABLE_MULTIPLE_KO is on.

A line’s tabs: Item Details (Main Details, Delivery Instruction, Department, Doc Link, Delivery Details), Serial Number (for serial-number items, or any item flagged optional_sn), Batch Number, Bin Number, Costing Details, Pricing Details, Issue Link.

Configuration

Before you can use it

Applet settings

Settings live in four places. Application Settings routes to the shared field-configuration screen from blg-shared-utilities (app.routing.ts L21, L47; the applet’s own settings-container/field-configuration folder is an unrouted stub). The shared screen keys its tab sections by the applet code the platform shell stores at launch (applet-loader.component.ts L195), and its tab map has an entry for internalconsignmentGRNApplet that switches on the Payment, KO For, Department Hdr, Contra, Doc Link, Attachments, Export, Status, Delivery Details and Trace Document sections (shared ts L2425), so every tab-hide toggle below is actually on screen. It saves the whole form into the applet’s APPLET_SETTINGS extension (onSave(), shared ts L2686). Default Selection (applet-local, default-settings.component.ts L91–L96) saves DEFAULT_BRANCH, DEFAULT_LOCATION, DEFAULT_COMPANY and the drag-and-drop tab order CONSIGNMENT_GRN_DETAILS_TAB_ORDER into the same extension; Personalisation > Default Selection saves the same three defaults per user, and a personal default wins over the tenant default (consignment-grn-create.component.ts L75). Custom Status (applet-local) saves ENABLE_CUSTOM_STATUS_1..5, ENABLE_CUSTOM_STATUS_HDR_n, ENABLE_CUSTOM_STATUS_LINE_n, NAME_CUSTOM_STATUS_HDR_n and LIST_CUSTOM_STATUS_HDR_n. Printable Format Settings saves PRINTABLE.

All are tenant-wide except the personal defaults; only a user who can open the applet’s Settings can change them. Every toggle defaults to off (the shared screen patches undefined as falsy; the line-price keys go through shouldHideSetting(), whose hide-by-default list does not include this applet code, shared ts L2333–L2358), so a fresh tenant sees every tab and field until the first Save of Application Settings. Each key below is declared in applet-settings.model.ts, rendered, persisted and read by the applet.

Keys read by the applet without a control for this applet on any settings screen: ENABLE_DRAFT_LOCK_SERIAL_NUMBER_CHECKING (its shared toggle is fenced to the sales applets, shared html L2990; when set by another route it makes the serial pre-check also refuse serial numbers locked by another draft, effects L1298). Keys read without a model declaration: SHOW_DOCUMENT_DELETE_BUTTON (rendered ungated at shared html L1592, read straight from the APPLET_SETTINGS extension in consignment-grn-edit.component.ts L152–L161).

Declared but not usable: HIDE_MAIN_ARAP_TAB, ENABLE_CUSTOM_STATUS_LINE_n, NAME/LIST_CUSTOM_STATUS_LINE_n and the INCLUDE_* / ENABLE_* segment, dimension, profit-centre, project, SST and WHT keys are in the model but no component reads them; SHOW_VOID_BUTTON is in the model but is a client-side permission code, not a setting (repo commit 67e355a).

Document behaviour settings

There is no auto-final, no approval workflow, no FINAL_STATUS_GUID, no stock-validation toggle and no e-Invoice submission for this document (repo commit 67e355a, routes and settings components checked).

Settings in other applets that control this applet

Feature visibility / permissions

bl_applet_client_side_perm_dfn holds two rows for internalconsignmentGRNApplet (checked 2026-09-05): SHOW_TRANSACTION_DATE — without it the Transaction Date input on Main Details is disabled (main-details.component.html L145, ts L132–L134), so back-dating a receipt is a per-role grant — and HIDE_RETIRE_APPLET (shell). The code additionally checks, but the registry does not seed, these codes: SHOW_VOID_BUTTON (shows VOID even when HIDE_GENDOC_VOID_BUTTON is on), SHOW_INTERCOMPANY_PGRN_SCREEN (the Search tab), SHOW_DOC_NO_TENANT / COMPANY / BRANCH, SHOW_CLIENT_DOC_TYPE, SHOW_CLIENT_DOC_1..5, SHOW_DESCRIPTION, SHOW_ARAP_PNS / SETTLEMENT / DOC_OPEN / CONTRA / BAL, SHOW_COSTING_DETAILS, SHOW_LAST_PURCHASE_PRICE, the twenty SHOW_* line-price codes matching the HIDE_* keys above, SHOW_TAX_CONFIG_SELECTION, SHOW_WHT_CONFIG_SELECTION, and HIDE_PRICE (hides prices in the Line Items editor). They take effect only once seeded for this applet.

Server-side, create / read / update / delete of the document are governed by TNT_API_DOC_INTERNAL_PURCHASE_CONSIGNMENT_GRN_CREATE_TGT_GUID, _UPDATE_TGT_GUID, _READ_TGT_GUID and _DELETE_TGT_GUID (TntErpPermissions L7326–L7332), assigned through the Permission Set / User / Team / Role pages; the listing is filtered to the branches in the user’s permission targets.

Fields

Main Details

Account

Lines

Other line tabs: Serial Number (list, import, scan; shown for serial-number items and for items flagged optional_sn), Batch Number, Bin Number, Costing Details, Pricing Details, Issue Link; Item Details sub-tabs Delivery Instruction, Department, Doc Link, Delivery Details.

Delivery Details, Payment, Contra, Department Hdr

Delivery Details holds Tracking ID, Delivery Branch, Delivery Type and Delivery Location for the document. Payment records settlement lines (date and amount ≥ 0.01 required; card, voucher, transfer and cheque methods ask for their reference fields, add-payment.component.ts L91–L127). Contra (edit only) offsets the document against another open document of the same entity. Department Hdr tags the header with a department. Status (edit only) shows the custom statuses; Trace Document and Doc Link show the documents linked by knock-off.

Lifecycle and posting

FINAL is sent from the edit form or from the listing’s bulk FINAL (rows that are DRAFT and ACTIVE) as a posting-status update { posting_status: 'FINAL' }, plus validate_serial_signum_zero: true when ENABLE_SERIAL_NUMBER_VALIDATION_FINAL is on (edit ts L296–L332; listing ts L767–L800; effects L1263–L1345). With that setting on, the applet first validates every serial-number line through the inventory serial service (txn type PURCHASE, optionally checking draft locks) and refuses to send FINAL with the toast Unable to post the document to FINAL: Serial numbers are invalid. — a client-side check, not a backend rejection. Because the request carries no validate_stock_balance flag the backend validates stock (GenericDocumentService L390–L392), but for a +1 document the check can never fail (it only errors when the remaining balance would go negative, L2205–L2216).

VOID is sent from the listing’s bulk VOID (rows that are FINAL and ACTIVE) as { posting_status: 'VOID' } to the void endpoint (listing ts L1229–L1258; effects L1620–L1655). The controller first rejects the request with GENERIC_DOCUMENT_HAS_TARGET_LINKS — shown as Cannot VOID the Document. The document(s) have been knocked off with another document(s). — when any ACTIVE document link has this GRN as its source (GenericDocumentController L2925–L2950); a GRN that has been billed or issued against therefore cannot be voided until that later document is voided first.

Posting proof (backend at commit 871dbf5c96):

Two consequences worth knowing. First, the cost pool moves by the document’s Txn Amount: a consignment GRN keyed at RM 0 (common when the consignor’s price is not yet agreed) pulls the item’s moving-average cost down for everything in stock, and a later GIN at the agreed price then pushes it back up. Second, the GRN and the Consignment Return post to the consignment accounts, but the Consignment GIN does not — it falls back to the ordinary purchase / creditor accounts.

Related applets

• Consignment GIN Applet (Internal) — the outbound half; issues the consignment stock this GRN received.
• Consignment Purchase Order — the source document for the KO For tab; its open lines are closed by the GRN and reopened on VOID.
• Consignment Return (Internal) — returns consignment stock to the consignor; posts to the same consignment accounts.
• Consignment Billing and Consignor Purchase Billing — turn sold consignment stock into a purchase; a GRN they have knocked off cannot be voided.
• Internal Purchase Requisition and Internal Purchase Invoice — optional line-level knock-off sources when the document flow is enabled.
• Doc Item Maintenance — the Consignment Item flag that gates the item search.
• Supplier and Employee Maintenance — the consignor and the purchaser.
• Organisation — branches, locations, document numbering, document flows, fiscal periods and the posting configuration.
• Tax Configuration and Chart of Accounts — line tax codes and the CONSIGNMENT_STOCK / CONSIGNMENT_LIABILITY default GL codes.
• Stock Balance and Stock Report — where the received quantity and its cost effect show up.
• Creditor Report — lists the GRN among supplier-side documents.

Troubleshooting

Known housekeeping: the applet is on Angular 14 (migration issue closed by the toolchain commits); its FINAL error handler passes two arguments to String.includes() (effects L1406), so only FISCAL_PERIOD_LOCKED is matched by that clause (the serial codes are matched by the following clauses); and the auto pop-up after FINAL prints through INTERNAL_PURCHASE_ORDER_PRINT_SERVICE (edit ts L319), so the printable format must be one that service can render.

Related documentation

• Consignment Purchasing guide — the end-to-end process the GRN belongs to.
• Purchasing module and Inventory module.