Purchase GRN Stock In Applet (Internal)

Put a delivery into stock, and update its cost, the moment it arrives, then match the supplier’s bill later on the invoice type that does not stock in. This is the posting sibling of the plain GRN, and each company should use one pair or the other: mixing the two double-counts stock.

Overview

The Purchase GRN Stock In Applet (Internal) records the physical receipt of goods from a supplier and books them into stock on FINAL. It is the receiving document for tenants that want inventory and cost updated the moment the goods arrive, with the supplier’s invoice matched later. Warehouse or receiving staff create it against a Purchase Order (or by searching items directly); finance follows it with a Purchase Invoice No Stock In.

This applet is one of two receiving documents on the purchase side and the two behave very differently in the backend:

Pick one pair per company and configure the Knock Off Configuration accordingly; mixing them double-counts stock (see Troubleshooting).

Where it fits

Modules: Purchasing and inventory.

Screens and menus

The applet has two menu items: Internal Purchase GRN Stock In (the document listing) and Line Items (every GRN Stock In line across documents; the File Export menu is present in the code but commented out).

Listing. Columns: Doc Short Code (PURGRNSI), Doc No (Tenant / Company / Branch), Invoice No and the other external references, Supplier Name, Branch, Transaction Date, posting status, AR/AP balance columns and ordered / received / outstanding quantity and amount columns; every column is governed by a HIDE_* setting with a matching SHOW_* permission (see Configuration). Toolbar buttons: FINAL (multi-select, DRAFT rows only), DISCARD (DRAFT rows), VOID (FINAL rows), SINGLE/MULTIPLE PRINT, and an opt-in DRAFT button that sends FINAL documents back to draft. A DEFAULT_TRANSACTION_DATE preset and the DEFAULT_STATUS filter shape the initial query.

Create form tabs: Search (intercompany, permission-gated), Main Details, Account, Lines, Delivery Details, Payment, KO For (Purchase Order), Department Hdr. CREATE is enabled once Main Details is valid, a supplier is selected and at least one line exists.

Edit form tabs (order configurable in Default Selection): Search Document (TEMP documents only: Search Purchase Order and Search Purchase GRN, which clones a FINAL GRN Stock In), Main Details, Account, Lines, Delivery Details, KO For (TEMP only), Payment, Department Hdr, TraceDocument, Contra, Doc Link, Export, Attachments, Status. Buttons: RESET, SAVE, FINAL, VOID, DISCARD and (when the applet extension SHOW_DOCUMENT_DELETE_BUTTON is set on the applet record) a two-click DELETE for non-FINAL documents. All tabs can be rendered as vertical expansion panels (VERTICAL_ORIENTATION).

Line editor (Add / Edit Line Item): Item Details (Main Details, Delivery Instruction, Child Items for grouped / bundle items, Department, Doc Link in edit mode, Multi Discount, Delivery Details), Serial Number / Batch Number / Bin Number (shown according to the item’s sub_item_type), Costing Details, Pricing Details, Issue Link. The Lines tab itself offers Search Item plus KO For Purchase Order / Requisition / Invoice sub-tabs.

Settings menu (System Configuration): Application Settings, Default Selection, Printable Format Settings, Branch Settings, Custom Status; the routes also expose Webhook, Feature Visibility, Release Notes, Applet Log and the shared permission listings (client-side permission, role pricing scheme link, permission wizard, permission set, user / team / role permission). Personalization: Default Selection and Sidebar.

Configuration

Before you can use it

• Company, branch and locations in Organisation. Branch, Company and Location are required on the header; Delivery Branch / Delivery Location default to them. Stock is booked to the line’s delivery location, else the line’s store, else the header location, else the branch’s default location (InventoryTransactionLineFactory), so every receiving branch needs a default location.
• Default GL codes for the company: INVENTORY_NOT_INVOICED, CREDITOR_NOT_INVOICED and, when tax lines exist, INPUT_TAX (company GL-code links, set up through Chart of Account / the company’s default GL mapping). Without CREDITOR_NOT_INVOICED the journal job throws MISSING_DEFAULT_GL_CODE: CREDITOR_NOT_INVOICED; without INVENTORY_NOT_INVOICED the purchase lines are silently omitted: with no tax on the GRN nothing is left and the job fails with NO_JOURNAL_CREATED, but if some lines (or tax lines) still resolved, the accrual line is built from them and the journal posts short with no error. The job fails with TOTAL_DEBITS_AND_TOTAL_CREDITS_NOT_BALANCES only when the supplier has no AR/AP type.
• Knock Off Configuration for the company (Organisation → Company → Knock Off Configuration): an enabled INTERNAL_PURCHASE_ORDER → INTERNAL_PURCHASE_GRN_STOCK_IN row so POs appear in KO For, and an INTERNAL_PURCHASE_GRN_STOCK_IN → INTERNAL_PURCHASE_INVOICE_NO_STOCK_IN row so FINAL GRNs are queued for the invoice. The same row’s second posting status decides whether the auto-created PI No Stock In is DRAFT or FINAL.
• Suppliers in Supplier; the entity’s AR/AP type is read but overridden to CREDITOR_NOT_INVOICED for this document type.
• Items in Doc Item Maintenance / Inv Item Maintenance: only basic / alias items with an inventory item link (or serialised coupons) create inventory transactions; grouped and bundle items post through their component links.
• Tax codes in Tax Configuration if input tax is captured on lines.
• Running numbers for INTERNAL_PURCHASE_GRN_STOCK_IN are assigned by the backend on FINAL.
• Backend permissions: TNT_API_DOC_INTERNAL_PURCHASE_GRN_STOCK_IN_CREATE / READ / UPDATE / DELETE_TGT_GUID. The KO For and Search Purchase Order screens additionally read the …_DELIVERY_BRANCH_READ target so a user can receive into a delivery branch they are not a member of.

Applet settings

Where settings live:

Master settings are changed by OWNER / ADMIN users through the Settings menu or the gear’s master mode; personal mode on the gear and Personalization are open to every user. Defaults: every toggle below is off / empty unless the row says otherwise — the shared screen patches the stored value or false, and the document code treats an absent key as “not hidden”.

The table lists the keys that are shown on a settings screen or gear, saved, and actually used by this applet.

Custom Status (ENABLE_ / NAME_ / LIST_CUSTOM_STATUS_HDR_1…5) adds up to five header status pickers to the Status tab; they label a GRN and gate nothing (see Workflow / approval below).

Read at runtime without a model declaration (set them through a gear or by API): HIDE_KO_FOR_TAB, HIDE_MAIN_PAYMENT_TAB, HIDE_DEPARTMENT_HDR_TAB, HIDE_MAIN_CONTRA_TAB, HIDE_MAIN_ARAP_TAB, EXPAND_PAYMENT, EXPAND_STATUS, HIDE_LISTING_BRANCH, HIDE_TRANSACTION_DATE (listing columns), SHOW_DRAFT_BUTTON (opt-in listing button that returns FINAL documents to DRAFT; also a permission code), HIDE_LINE_ITEM_PRICING (Lines-tab price columns, paired with the INTERNAL_PURCHASE_GRN_DISPLAY_PRICING permission), DISABLE_ADD_WHEN_KO (blocks Search Item once a knock-off exists), SHOW_ITEM_STOCK_BALANCE, DISABLE_ITEM_LISTING, HIDE_MULTI_DISCOUNT, ENABLE_DRAFT_LOCK_SERIAL_NUMBER_CHECKING, DISABLE_DEFAULT_SETTING_ADVANCE_SEARCH, FUZZY_SEARCH_COLUMNS, DEFAULT_STATUS.

Read without any control for this applet code (declared and consumed, but gated out of the shared screen and on no gear): ENABLE_SERIAL_NUMBER_VALIDATION_FINAL (the flag it sends on FINAL is irrelevant here because the lines are signum +1 and always validated, but it also makes FINAL first ask the serial-number check about every serialised line and stop with Unable to post the document to FINAL: Serial numbers are invalid. if any serial comes back invalid; that pre-check is the key’s one real effect in this applet, and nothing on its settings screens can switch it), SERIAL_NUMBER_QTY_FOLLOW_BASIC_QTY, HIDE_CREDIT_LIMIT, HIDE_EXTERNAL_REMARKS, HIDE_FILE_EXPORT_MENU, ENABLE_FILTER_BY_TODAYS_TXN, DEFAULT_ORIENTATION, DEFAULT_DECIMAL_STEP (derived from the precision), and the fifteen MANDATORY_* keys (MANDATORY_QUOTATION / ORDER / DELIVERY_ORDER / INVOICE / OTHERS and their _DATE twins, MANDATORY_BIN_NUMBER, MANDATORY_SEGMENT / DIMENSION / PROFIT_CENTER / PROJECT) that add Validators.required to the external-document and department fields.

Declared and rendered but never read (saved and ignored): EXPAND_DELIVERY_TRIPS, EXPAND_MAIN_ARAP, EXPAND_POSTING, and the 41 model-only keys (DISALLOW_DUPLICATE_INVOICE, SHOW_VOID_BUTTON, DEFAULT_TOGGLE_COLUMN, HIDE_MAIN_DETAILS_*, ENABLE_ / INCLUDE_ dimension, SST and WHT flags, and the line-level custom status keys). The gears also carry HIDE_REASON, SHOW_GL_DIMENSION, SHOW_SEGMENT, SHOW_PROFIT_CENTER, SHOW_PROJECT as settings; the listing reads the last four as opt-in column settings or permissions.

Document behaviour settings

• Posting is not configurable in the applet: FINAL is fixed at quantity +1 / amount −1 (see Lifecycle). The FINAL request carries at most two flags, and neither changes what the server does here: validate_serial_signum_zero (from ENABLE_SERIAL_NUMBER_VALIDATION_FINAL), because a +1 document’s serials are always checked, and validate_stock_balance: true (when SHOW_ITEM_STOCK_BALANCE is on), which is already the backend default and only checks negative-signum lines.
• Serial numbers before FINAL: on every line save the applet calls validateMultiSerialNumbers with txn_type: PURCHASE and server_doc_types: [INTERNAL_PURCHASE_GRN_STOCK_IN, INTERNAL_PURCHASE_INVOICE]; serials already live in the company are flagged and the FINAL button is disabled while a line carries an invalid serial. Batch lines must have batch quantities that add up to the line quantity.
• Status flow options: SHOW_DRAFT_BUTTON (setting or permission) exposes the FINAL → DRAFT action; HIDE_GENDOC_* hide FINAL / VOID / DISCARD; SHOW_DOCUMENT_DELETE_BUTTON on the applet’s APPLET_SETTINGS extension exposes DELETE.
• Printables: Jasper templates from Printable Format Settings; default from Branch Settings → Printable Format, else PRINTABLE. The PRINTABLE_FORMAT_WITH_NO_PRICE permission restricts the Export picker to templates in the no_price category. Export offers EXPORT AS PDF only (CSV / DOCX / ZIP are commented out) and is disabled for VOID documents.
• Workflow / approval: none wired. Custom Status is a label, not a gate.
• e-Invoice: not applicable to this document type.

Feature visibility / permissions

51 client-side permissions are defined for this applet and 48 of them are used: the SHOW_* counterparts of the listing columns (SHOW_DOC_NO_TENANT / COMPANY / BRANCH, SHOW_CLIENT_DOC_TYPE, SHOW_CLIENT_DOC_1…5, SHOW_TRANSACTION_DATE, SHOW_ARAP_PNS / SETTLEMENT / DOC_OPEN / CONTRA / BAL, SHOW_AMOUNT_TXN_MAIN_LISTING, SHOW_DESCRIPTION), the line price / quantity / tax columns (SHOW_UNIT_PRICE_*, SHOW_UNIT_DISCOUNT*, SHOW_AMOUNT_*, SHOW_DISCOUNT_AMOUNT_EXCL_TAX, SHOW_QTY_BASE / UOM, SHOW_UOM_TO_BASE_RATIO, SHOW_TAX_CONFIG_SELECTION, SHOW_WHT_CONFIG_SELECTION, SHOW_LAST_PURCHASE_PRICE, SHOW_COSTING_DETAILS, SHOW_TOTAL_TXN_AMOUNT, SHOW_TOTAL_SST_VAT_GST_AMOUNT), SHOW_ACCOUNT_TAB_DETAILS, SHOW_EXPORT_TAB, SHOW_DRAFT_BUTTON, SHOW_INTERCOMPANY_PGRN_SCREEN (the create form’s intercompany Search tab), ALLOW_TO_CREATE_EDIT_ACCOUNT (create / edit suppliers from the picker), PRINTABLE_FORMAT_WITH_NO_PRICE, and INTERNAL_PURCHASE_GRN_DISPLAY_PRICING (unit price, tax, discount and amount columns on the Lines tab and the Line Items listing; OWNER / ADMIN rank passes automatically).

Seeded but never checked: SHOW_FINAL_BUTTON, SHOW_DISABLE_EDITING_AMOUNT_TXN_SETTING, IPGRN_HIDE_TRACKING_ID_AND_PERMIT_NO. Checked but not seeded: SHOW_GENDOC_FINAL_BUTTON, SHOW_GENDOC_VOID_BUTTON, SHOW_GENDOC_DISCARD_BUTTON (the re-show pairs of the HIDE_GENDOC_* settings), SHOW_LISTING_BRANCH, SHOW_QTY_MAIN_LISTING, SHOW_QUOTATION / ORDER / DELIVERY_ORDER / INVOICE / OTHERS, SHOW_GL_DIMENSION / SEGMENT / PROFIT_CENTER / PROJECT — until they are seeded a tenant-wide hide of those items cannot be reopened per role.

Feature Visibility and Webhook are the shared screens; the applet adds nothing to them.

Fields

Main Details

Account

Lines

Of the line editor’s other tabs, Pricing Details lists the purchase unit price the item carries in each pricing scheme, for reference while you price the line; Doc Link and Multi Discount are optional.

Delivery Details, Payment, Contra

Lifecycle and effects

Statuses: DRAFT (new documents; SAVE keeps them here) → FINAL → VOID. DRAFT documents can be DISCARDED (listing or edit form, confirmation dialog) and FINAL documents can be returned to DRAFT with the opt-in DRAFT button. FINAL is a separate step from Save (with a one-second delay and a serial pre-check); a second FINAL is refused with HTTP 403 “Generic Document has already been posted to FINAL”. VOID and DRAFT are refused (“cannot be changed to VOID because it has already been linked with the following documents: PURINVNSI-…”, or “to draft” for DRAFT) when a downstream document has knocked this one off. DELETE (edit form, non-FINAL only, two clicks) deletes the document; only the screen stops you deleting a FINAL one. Search Purchase GRN clones a FINAL GRN Stock In into a new document.

What posting does:

What FINAL actually does:

1. Validation: forex rate; serial numbers — no duplicates within the document, count equal to the line quantity, and because this is stock coming in, every serial must not already exist in the company; bins; a refusal when the transaction date is inside a LOCK_ALL / LOCK_TXN period. Stock-balance checks apply only to negative lines.
2. Update the header, assign running numbers, set the finalised date.
3. Start the main posting job, which applies the company’s include / exclude list and sets off the inventory, journal, knock-off, tax and webhook jobs. The inventory job marks the stock as posted and refreshes the current stock balance; the journal job posts the entries above; the knock-off job opens the GRN Stock In lines for the PI No Stock In and, if automatic conversion is switched on for your tenant, creates that invoice.

Related applets

• Purchase Invoice No Stock In (Internal) — the invoice that follows this document (quantity 0 / amount −1); on FINAL it moves the liability from Creditor Not Invoiced / Inventory Not Invoiced to the trade creditor, but only when it carries a link to a GRN Stock In.
• Purchase GRN (Internal) — the non-posting receipt for tenants that book stock on the Purchase Invoice; the intercompany Search tab in this applet actually creates that document type, not a GRN Stock In (see Troubleshooting).
• Purchase Invoice (Internal) — the other stock-moving purchase document (+1 / −1); never pair it with a GRN Stock In for the same delivery.
• Purchase Order (Internal), Purchase Requisition (Internal) — knock-off sources. An open PO → GRN Stock In queue row shows as incoming quantity only on Stock Availability’s Details screens; the main Available figure leaves purchase orders out until the goods are received.
• Purchase Return (Internal) — takes received goods back out of stock and debits the supplier; Purchase GIN (Internal) only documents the dispatch.
• Purchase GRN Supplier Access (Internal), Supplier Delivery Order — supplier-facing counterparts. Note the registry’s documentation_url for this applet currently points at the supplier-access page.
• Stock Availability, Stock Balance, Stock Adjustment — where the posted quantities and costs are visible and corrected.
• Supplier, Organisation, Chart of Account, Doc Item Maintenance, Inv Item Maintenance, Tax Configuration — master data and default GL codes the posting depends on.

Troubleshooting

Related documentation

• Purchasing module
• Purchase Invoice No Stock In (Internal) — the invoice leg of this pair
• Purchase GRN (Internal) — the non-posting alternative
• Standard procurement workflow — where receiving sits in the PO → GRN → invoice flow