Purchase Requisition (Internal)

Record what your company needs to buy, for which branch and from which preferred supplier, before anyone contacts a supplier; purchasing then raises the purchase order from it. Finalising moves no stock and posts no journal, it only opens the lines for a purchase order, and approvals stay off until someone sets them up.

Overview

A purchase requisition is your company’s formal way of saying “we need to buy this.” Before a supplier is contacted, a requester records what is needed, how much, for which branch and from which preferred supplier; a manager approves it if your company has switched approvals on; purchasing then raises a Purchase Order from it. Think of it as a pre-approved shopping list: the requisition is the internal request, the purchase order is the commitment to the supplier.

The Purchase Requisition (Internal) applet is where requesters create requisitions, approvers act on them (Approval Request / Approval History), operations review lines across documents (Line Items, Line Items Queue) and administrators configure fields, approval routing and printing. It is a record-only document: server document type INTERNAL_PURCHASE_REQUISITION (short code PURREQ) carries quantity signum 0 and amount signum 0 — finalising it moves no stock and posts no journal. What FINAL does do is put the requisition’s lines in the open queue so a Purchase Order can knock them off.

Approvals here are optional and off until you build them — a tenant with no Approval Settings row raises, finalises and converts requisitions with nobody signing anything. Where this applet differs from its inventory cousin, the Stock Requisition, is that it gives you the whole loop from the UI: Approval Settings and Branch Designation are read by the backend when a requisition is submitted, approvers get e-mails and an Approval Request queue, and the first approval recorded sets the requisition to FINAL — later levels still run, for the record. FINAL is never blocked while an approval is pending. The details are in Lifecycle and effects and in the Document Approvals guide.

Where it fits

Module: Purchasing.

Screens and menus

Walkthrough video of the applet.

The sidebar filter is generic: for every menu the applet computes HIDE_<STATE>_MENU (an applet setting) and SHOW_<STATE>_MENU (a client-side permission) and hides the item when the setting is on and the permission is absent. Only the two approval SHOW_…_MENU codes are registered (see Feature visibility).

Listing. Columns: Doc Short Code, Doc No (Tenant / Company / Branch), Posting Status, Status, Print Status, Branch Code, Currency, Supplier Name, Description, Purchaser, Amount Txn, ARAP columns, Qty Ordered / Received / Outstanding, Amount Ordered / Received / Outstanding, dates, Created / Modified by, Client Doc Type / 1–5, Quotation / Order / Delivery Order / Invoice / Others references, GL Dimension, Segment, Profit Center, Project, Remarks, References, KO Doc From / To. Buttons: + (create), FINAL, VOID, SINGLE/MULTIPLE PRINT, and the ag-grid export bar. The listing’s format drop-down is switched off, so listing print always uses the applet’s default printable (Printable Format Settings), never a branch’s; the Export tab inside a requisition starts from the branch’s default printable and falls back to the applet’s.

Create screen — tabs Main Details, Account, Line Items, then Delivery Details, Payment, Department Hdr and KO For, each of the last four hidden by its HIDE_…_TAB setting. CREATE saves a TEMP document and converts it to ACTIVE; RESET clears the draft.

Edit screen — tabs in the order set by Default Selection → Details Tab Ordering: Main Details, Account, Lines, Delivery Details, KO For (TEMP documents only), ARAP, Payment, Department Hdr, TraceDocument, Contra, Doc Link, Attachment, Export, Generic Doc Approval. Buttons: RESET and FINAL (DRAFT documents), SAVE, DISCARD (ACTIVE + DRAFT). With VERTICAL_ORIENTATION (or a personal DEFAULT_ORIENTATION of VERTICAL) the tabs become expansion panels; the EXPAND_* settings choose which panel opens first.

Approval Request lists the approval requests addressed to the logged-in employee — for every document type, not only requisitions, so a purchase order waiting for the same person appears here too; read the document number before approving — with the document number, company, entity, date, amount, approver, status and remarks. Select a row and click Approve or Reject; a dialog collects remarks. Opening a row shows Main Details and Lines read-only.

Line Items Queue shows open-queue rows (Txn Date, Base Qty, Balance Qty, Knock Off Qty, Outlet PO / SO balance, Outlet Balance) and an APPROVE button. Rows with zero knock-off quantity cannot be selected. See Lifecycle for what the approval does — and does not — change.

Configuration

Before you can use it

Applet settings

Settings live in five places; all are tenant-wide except the last:

1. Shared Application Settings — the table below.
2. Inline gear — a gear icon is embedded on 20 screens (listing, edit header, main details, account, entity details, billing / shipping contact, supplier edit, line items grid, item details, line doc link, department header, payment, payment edit, ARAP, export, doc link, line-items queue). It shows only when the user has switched on Personalization → Default Selection → Enable Inline Applet Config (ENABLE_INLINE_APPLET_CONFIG, personal). 100 keys are editable there; they are the same tenant-wide values.
3. Default Selection (applet-local) — Default Branch, Default Location (and the branch’s company) and Details Tab Ordering (PURCHASE_REQUISITION_DETAILS_TAB_ORDER, drag-and-drop of the 14 edit tabs).
4. Printable Format Settings — the default printable (PRINTABLE).
5. Personal Default Selection — Default Branch, Default Location, Enable Inline Applet Config (overrides the tenant defaults for that user).

Anyone with access to the applet’s Settings menu can change them; the applet has no separate settings permission. Values are read by the document screens only after the first Save — a fresh tenant sees every tab and column until Application Settings has been saved once.

Every key in the table is rendered on the shared screen and/or a gear, saved, and read by the applet. Defaults are the shared screen’s initial value: unchecked (false) for toggles, empty for selections, unless stated.

DEFAULT_POSTING_STATUS and DEFAULT_STATUS are on the shared Application Settings screen and set what the lists show when they open: DEFAULT_STATUS filters the main listing, DEFAULT_POSTING_STATUS both the main listing and Line Items. Set the posting status to DRAFT for a desk that only chases unfinished requisitions; leave it at All when people look for finalised ones, or they will think a requisition has vanished.

Keys read at runtime that the Application Settings screen does not offer for this applet (they cannot be set there): DEFAULT_TOGGLE_COLUMN (one- or two-column layout of the listing and line screens), HIDE_EMPLOYEE_RANKING (Branch Designation › Employee Ranking tab), the two relabel switches — branch to job group, company to entity — (labels on the Branch Designation screens), HIDE_QUOTATION / HIDE_ORDER / HIDE_DELIVERY_ORDER / HIDE_INVOICE / HIDE_OTHERS, SHOW_REMARKS_MAIN_LISTING, SHOW_REFERENCE_MAIN_LISTING (listing columns), HIDE_LISTING_BRANCH (listing column, on the listing’s gear), HIDE_SETTLEMENT_TAB (on the Payment tab’s gear), HIDE_SUPPLIER_CATEGORY_TAB, HIDE_SUPPLIER_LOGIN_TAB, HIDE_SUPPLIER_PAYMENT_CONFIG_TAB (on the supplier editor’s gear), and the menu keys HIDE_LINE_ITEMS_MENU and HIDE_LINE_ITEMS_QUEUE_MENU. Application Settings does offer DISABLE_ITEM_LISTING (item picker), SHOW_DOCUMENT_DELETE_BUTTON (saved, but the edit screen has no delete button), HIDE_QTY_MAIN_LISTING and HIDE_AMOUNT_MAIN_LISTING (also on the listing’s gear), HIDE_APPROVAL_REQUEST_MENU and HIDE_APPROVAL_HISTORY_MENU.

Declared but never read (saving them changes nothing): INCLUDE_* and ENABLE_* for SST / WHT / dimension / profit centre / project / segment, ENABLE_CUSTOM_STATUS_* (15 keys), the filter-by-today’s-transactions switch, the e-invoice expand toggle.

ENABLE_EDITING_UNIT_PRICE_STD does work here: the line form’s Unit Price STD box is read-only until it is on, and its switch is on the shared Application Settings screen. Turn it on only if requesters are expected to quote a price; otherwise the price the item master gives is the one the purchase order inherits.

Document behaviour settings

Settings in other applets that control this applet

Feature visibility / permissions

Server-side (targeted) permissions checked by the applet: TNT_API_DOC_INTERNAL_PURCHASE_REQUISITION_READ_TGT_GUID (branch targets filter the listing and the branch drop-down), …_CREATE_TGT_GUID (the + button), …_UPDATE_TGT_GUID (SAVE), …_DELIVERY_BRANCH_READ, plus TNT_TENANT_ADMIN / TNT_TENANT_OWNER which bypass all three. The backend additionally requires API_TNT_DM_ERP_GEN_DOC_LINE_OPEN_QUEUE_APPROVE (or owner / admin) for the Line Items Queue APPROVE, and TNT_DM_ERP_GEN_DOC_APPROVAL_CONVERSION_MONITOR_READ for the PO-side monitor check.

Client-side permissions (50 registered for this applet): INTERNAL_PURCHASE_REQUISITION_DISPLAY_PRICING (a show permission with a hide default: the price columns of the Lines grid and the Line Items menu are hidden for every role that does not hold it), ALLOW_TO_CREATE_EDIT_ACCOUNT, SHOW_APPROVAL_REQUEST_MENU, SHOW_APPROVAL_HISTORY_MENU, SHOW_EXPORT_TAB, SHOW_GENERIC_DOC_APPROVAL_TAB, SHOW_PRINT_BUTTON, SHOW_TRANSACTION_DATE (unlocks the Transaction Date picker — without it the date is fixed at creation), SHOW_COSTING_DETAILS, SHOW_LAST_PURCHASE_PRICE, SHOW_DESCRIPTION, SHOW_DOC_NO_TENANT/COMPANY/BRANCH, SHOW_CLIENT_DOC_TYPE, SHOW_CLIENT_DOC_1…5, SHOW_ARAP_* (5), SHOW_GL_DIMENSION, SHOW_SEGMENT, SHOW_PROFIT_CENTER, SHOW_PROJECT, SHOW_TAX_CONFIG_SELECTION, SHOW_WHT_CONFIG_SELECTION, and the 16 price / quantity SHOW_* codes. Each SHOW_* re-enables what the matching HIDE_* setting hides, per role.

Checked in code but not registered (granting them is impossible until they are): SHOW_GENDOC_FINAL_BUTTON, SHOW_GENDOC_VOID_BUTTON, SHOW_LINE_ITEMS_MENU, SHOW_LINE_ITEMS_QUEUE_MENU, SHOW_LISTING_BRANCH, SHOW_QTY_MAIN_LISTING, SHOW_AMOUNT_MAIN_LISTING, SHOW_QUOTATION / SHOW_ORDER / SHOW_DELIVERY_ORDER / SHOW_INVOICE / SHOW_OTHERS, SHOW_REMARKS_MAIN_LISTING, SHOW_REFERENCE_MAIN_LISTING, ALLOW_LINE_ITEM_EDIT, HIDE_PRICE. Registered but never checked by this applet’s code: IPR_HIDE_TRACKING_ID_AND_PERMIT_NO.

Feature Visibility and the permission screens under Settings are the shared components (webhooks, permission sets, user / team / role permissions, role → pricing-scheme link).

Fields

Main Details

Account — Entity Details (Entity Id required, Entity Name, Status, Entity Type, Identity Type, ID Number, Currency, Description, Email, Phone Number — all read-only from the supplier), Bill To and Ship To address and contact blocks.

Lines (Item Details) — Item Code / Name (picker; grouped, serial, batch and bin items open their sub-tab), Quantity Base (required, ≥ 1), Quantity by UOM, UOM to Base Ratio, Unit Price STD excl. / incl. tax, by UOM, Unit Discount (by UOM), Unit Price Net, STD Amount, Discount Amount, Amount Net (required), SST/GST/VAT code and Tax Amount, WHT code and amount, Unit Price Transaction incl. tax, Txn Amount (required), Remarks, Last Purchase Price; reference fields Jobsheet / Purchase Quotation / Purchase GRN / Purchase Order / Purchase Requisition / Supplier Delivery Order No. Sub-tabs: Grouped Item, Serial / Batch / Bin Number, Costing Details, Pricing Details, Issue Link, Delivery Details, Delivery Instructions, Department, Doc Link. Prices may be zero; a requisition may carry zero prices.

Delivery Details — Tracking ID, Shipping Branch, Delivery Type, Shipping Location.

Department Hdr — Segment, G/L Dimension, Profit Centre, Project (copied to lines).

Payment — settlement lines (method, amount, date). Present because the form is cloned from the invoice family; a requisition has no ARAP balance, so these lines have no accounting effect.

Generic Doc Approval › Create Approval — Select Submitter (employee entity, required by the backend), Submitter Designation / Code / Name (filled from the approval setting and employee), Doc No, Doc Type, Amount Txn (from the document), Approval Setting (required; only settings whose server doc type is INTERNAL_PURCHASE_REQUISITION), Total Required Approval Levels (from the setting).

Lifecycle and effects

Statuses. Status TEMP → ACTIVE on CREATE; posting status DRAFT → FINAL (listing or edit-screen FINAL, or the last approval) → VOID (listing, FINAL + ACTIVE rows only). DISCARD (edit screen; ACTIVE + DRAFT only — a FINAL document cannot be discarded) removes a never-finalised requisition. Only ACTIVE documents can be edited.

Posting proof block

Knock-off. KO For › Jobsheet lists open-queue rows INTERNAL_JOBSHEET → INTERNAL_PURCHASE_REQUISITION, copies the selected lines into the draft and creates the document links on CREATE. Selecting a jobsheet also copies its header details into Main Details; the delivery branch does not follow the branch. In panel (vertical) view the Jobsheet panel is additionally gated by the company flow config — but by the wrong row: its visibility follows Jobsheet → Sales Invoice, not Jobsheet → Purchase Requisition.

Approval workflow (the part that is enforced by the backend):

1. Create approval (Generic Doc Approval tab, +, Save) — records the document, submitter entity and approval setting. Refused if the document does not exist or already has an approval.
2. Submit For Approval — the submission is rejected when: the submitter entity is missing (SUBMITTER_ENTITY_HDR_GUID_IS_NULL); the approval setting is missing (APPROVAL_SETTING_GUID_IS_NULL); no branch designation with the submitter’s designation code exists for that approval setting (Submitter designation_code is not created…); that designation has no approver links (There is no approver assigned…); the approvers cover fewer distinct levels than Total Required Approval Levels (EmployeeBranchDesignationLink_IS_NOT_FULLY_CONFIGURED); or the submitter has a resign date in the past (SUBMITTER_IS_RESIGNED). On success the header becomes PENDING_APPROVAL and the approval is queued for processing.
3. Processing builds the approval sequence — one row per approver per level up to the required levels, quorum = min(approvers at that level, configured quorum) — writes a SUBMITTED / RESUBMITTED history row, then creates the approval requests for the lowest level and e-mails each approver (template GENERIC_DOC_APPROVAL_PENDING_APPROVAL_NOTIFICATION; the mail contains a decision-form link). Failures are recorded as Processor Posting Status / Sequence Posting Status (PROCESSOR_FAIL_APPROVAL_SETTING_NOT_FOUND, PROCESSOR_FAIL_APPROVAL_SEQUENCE_IS_EMPTY, FAILED_TO_INSERT_TO_QUEUE, …) and are visible as columns on the Generic Doc Approval tab.
4. Approve / Reject (Approval Request menu or the e-mail form) — records the decision and remarks. Approve marks the same-level sequence rows APPROVED, bumps the quorum count, deletes the acting request and re-runs the sequencing: when the quorum is met the current level’s remaining requests are deleted and the next level’s requests are created; when every level is approved and the required level count is reached, the header gets its final-approval date, status APPROVED and the remarks are concatenated. Reject sets the header REJECTED with the rejection date and remarks, deletes the sequence rows and all requests, and e-mails the submitter. Resubmit restarts from step 3. There is no Withdraw button.
5. Auto-FINAL. After an approval is recorded the requisition itself is set to FINAL through the normal FINAL path, with its validations. The test that triggers it is satisfied by any approval, so the requisition is finalised at the first approval action, not only at the last level. Later levels still run for the record. If that FINAL is refused — the transaction date is in a locked period, say, or a foreign-currency rate is missing — the refusal is only written to the server log: the approval shows APPROVED and the requisition stays DRAFT, with no message on any screen. After approving, check that the requisition’s posting status is FINAL, and finalise it by hand once the cause is fixed.

What the workflow does not do: nothing stops a user from clicking FINAL on the listing or edit screen without any approval — FINAL never reads the approval status. Hide the FINAL button from requesters (HIDE_GENDOC_FINAL_BUTTON; with SHOW_GENDOC_FINAL_BUTTON unregistered nobody can re-enable it) if approval is meant to be mandatory.

Line Items Queue › APPROVE marks the selected open-queue rows approved (permission …_LINE_OPEN_QUEUE_APPROVE). On its own it is a marker. It becomes a gate when the Purchase Order applet’s SHOW_APPROVED_PR_LINE is on (PO Application Settings, panel KO For Purchase Requisition): the PO’s Add Line Item › KO For Purchase Requisition tab then lists only approved rows. That is the way to let a buyer turn only approved lines of a requisition into an order. The gate covers that tab only: the PO’s header-level KO For › Purchase Requisition does not apply the filter, so hide or avoid it where approval must hold.

PR → PO conversion (backend). The backend can map a FINAL requisition to a new purchase order (amount signum 0; DRAFT, or FINAL with running numbers and posting when the flow configuration says FINAL) and sync the links. It refuses non-FINAL sources (SOURCE_DOCUMENT_NOT_FINAL) and already-converted ones (SOURCE_DOCUMENT_ALREADY_KO). It is reachable through the API, and through a scheduled job a tenant may subscribe to; this applet exposes none of it — the PO applet’s KO For is the normal path.

Related applets

• Purchase Order (Internal) — the next document; knocks requisition lines off, carries the Approval Monitor rule and its own approval flow.
• Purchase Quotation (Internal) — can be raised from requisition lines before the order.
• Purchase GRN (Internal) — optional line-level knock-off target for a requisition.
• Purchase Invoice (Internal) — end of the chain; the requisition number is carried on PO and invoice lines as a reference.
• Stock Requisition (Internal) — the inventory-side request; same signums, Approval Settings screen present but no way to submit against it there.
• Purchase Report — reporting.
• Supplier, Employee, Organisation, Doc Item Maintenance, Tax Configuration — master data the form depends on.
• Workflow Design — designs the process whose statuses appear in Workflow Status.

Troubleshooting

Related documentation

• Purchasing module
• Standard procurement workflow
• Purchase Order (Internal) — approval and Approval Monitor on the order side