Stock Take

Count what is physically on the shelf at one location and compare it with what the stock ledger says: the session report puts the counted quantity beside the system balance and costs the difference. A stock take never changes a balance itself; the variance becomes a ledger movement only when someone raises a Stock Adjustment for it — keyed by hand, or loaded through the adjustment applet’s CSV File Import. There is no button here that creates one.

Your job, and the screen for it

Overview

The Stock Take applet is where you count what is physically on the shelf and compare it with what the stock ledger says. You open a session for one location, attach the devices that will do the counting, capture records (item, quantity, unit of measure, serial or batch number) by scanning or by typing, and then generate the session report: for every item the counted quantity beside the system balance, a tolerance band that allows for movements during the count, the serial numbers that are missing or unexpected, and the cost of the difference.

It is used by store and warehouse staff to count, by supervisors to run and close sessions, and by finance or audit to review variances and record reasons. It comes after the stock ledger has been built up by purchasing, sales and transfers, and before a Stock Adjustment — the stock take never changes a balance itself; it only measures the gap.

An Android companion app (repository akn-kotlin-mobile-stocktake) writes to the same sessions and records through the same endpoints and adds an offline mode; this page documents the web applet. The offline mode downloads the item list through a separate endpoint of its own, which asks for the inventory item read permission rather than a stock-take one — so a counter whose role holds only the stock-take permissions can count online but cannot prepare a handset for an offline count (read from the code, not tried).

Which stock take you are looking at. The registry holds three ACTIVE stock-take applets — StockTakev2 (this one, the wavelet-erp build), a customer-specific variant, and stockTakehq — each serving a different bundle, and two of them point their documentation link here. If your screens do not match this page, check the applet code in Tenant Admin before assuming the page is stale. Everything below was read against the build actually being served for StockTakev2 (see sources_read_at), which at the time of writing is four commits behind the repository: a listing refactor merged on 2026-09-18 has not been published, so the grids described here are the ones in front of you, not the ones in the source tree.

Where it fits

Screens and menus

The applet’s own menu has three entries plus the standard Settings and Personalization.

Stock Take Session — the session listing (Session Name, Session Code, Location, Company, Status, Start Date, Modified Date; 100 rows per page). + opens Create Session. Clicking a row opens Edit Session with four tabs:

• Details — the session header (see Fields).
• Devices — the counting devices attached to this session. + opens Create Device Session; clicking a row opens Edit Device Session, which has its own Details tab (device, brand, model, status, Remove) and Records tab. The device’s Records tab is where counting happens: with Automatically Scan Item To The Listing on it is the Scan Form; off it is a plain record listing whose + opens Add Item (an item search) and then Create Record Session (the structured entry form).
• Records — every record in the session across all devices (Item Name, Item Code, Device Name, Quantity, UOM, Modified Date). Clicking a row opens Edit Record Session (quantity and serial number editable; Remove).
• Report — GENERATE (first time) / REGENERATE, UPLOAD REASON, a search with a Report Type filter, and the variance grid with an inline-editable Reason column. Edits to Reason are saved by the session’s SAVE button.

UPLOAD REASON opens Upload report excel file: choose a Report Type, EXPORT the variance report to .xlsx, fill in TotalQty and reason, drop the file back and press Fill the reason.

Devices — the device master (Device Name, Device Code, Brand, Model, Status, Modified Date). + opens Create Device; a row opens Edit Device (same fields plus audit fields and a Delete button). Only ACTIVE devices can be attached to a session.

Report — a cross-session listing grouped by location (Date, Session Name, Status, Status Variance) with Download, which exports the grid to Excel. Clicking a row opens the same Edit Session screen.

Settings — Field Settings and Default Selection under System Configuration, then the shared Permission Wizard, Permission Set, User Permission, Role Permission, Team Permission, Client-Side Permission, Feature Visibility and Webhook screens, and the Release Notes / Audit Trail developer tools.

Personalization — shows a Default Selection entry; see Configuration for why it does not open.

Configuration

Before you can use it

Applet settings

Settings live in an applet-local Field Settings screen (Settings › Field Settings), not on the shared Application Settings screen used by the document applets. The screen is one form; SAVE saves the whole form as the applet’s settings, so all settings are tenant-wide and apply to every user. Anyone who can open the applet’s Settings menu can change them; there is no per-setting permission.

Every control starts with no value, so on a fresh tenant each toggle is off until the first SAVE.

Stored but read by nothing. Check serialized item from item extension is rendered and saved, but nothing uses it — both entry screens decide “serialised” from the item’s sub-item type SERIAL_NUMBER regardless of the toggle.

Declared but not rendered. The quantity delimiter is in the settings model and form but its input is commented out of the template; the Scan Form always splits quantity*code on a hard-coded *.

Default Selection (Settings) shows Default Branch and Default Location drop-downs, but the component is routed without the container that supplies the applet record: choosing a value throws on an undefined container and SAVE emits to no listener. Nothing in this applet reads DEFAULT_BRANCH / DEFAULT_LOCATION, and neither key has a backend reader. Personalization › Default Selection has no route at all — the link falls through to the wildcard redirect and reopens the session listing.

Session behaviour settings

This applet is not a generic document: there are no posting, printable, e-Invoice or approval toggles. The only behaviour switches are the WORKFLOW_PROCESS_GUID and Do The Stock During Opening Store rows above.

Settings in other applets that control this applet

Feature visibility / permissions

Client-side permission. Exactly one is defined for this applet: COST_COLUMN_VIEW (Cost Column View, ACTIVE). Granting or withholding it changes nothing — so the Cost Value and Total Cost columns render for everyone who can open the Report tab, including the people you would have used this permission to keep away from cost. If cost has to be hidden, it has to be done by not granting the report-line read permission at all. No HIDE_* / SHOW_* pairs exist in this applet.

Server-side permissions (Settings › Permission Wizard / Permission Set / User, Role, Team Permission). Each object has its own OWNER / ADMIN / MEMBER / CREATE / UPDATE / DELETE / READ family; a tenant owner or admin passes every check.

The applet shell asks the permission inquiry endpoint for API_TNT_DM_STOCK_TAKE_SESSION_HDR_READ, …_CREATE, TNT_TENANT_ADMIN and TNT_TENANT_OWNER at start-up; the results are loaded into the store but no screen or button in this applet is gated by them — denial surfaces as a backend error when the call is made. The report-line read permission decides what the Report tab shows; it hides the figures from the screen, and is not a lock on them.

Fields

Session — Create Session / Details tab

The form asks for a name, a code, a location and an optional description; everything else on the tab is filled in for you. Four of those fields carry a consequence you cannot see while you are typing.

Workflow Status and Workflow Resolution are read-only on create — they show the linked process’s default status — and on edit the status becomes a drop-down of the transitions available from where it currently is. Both are empty when no WORKFLOW_PROCESS_GUID is set, and nothing anywhere enforces them.

Session Start Date and Session End Date are disabled controls maintained from record timestamps; they are the window the report measures over, and Lifecycle and effects explains why that matters more than any other field on this screen. Created By and Modified By show the subject GUID rather than a name.

A worry you can put down. The two date controls hold their value as a bare YYYY-MM-DD string, with the time of day dropped, and SAVE reads them back — which looks exactly like a screen that flattens your count window to midnight every time you press SAVE. It does not. The update effect re-fetches the session from the server and copies only nine fields from the form onto it — code, name, location, company, branch, description, status, workflow status, workflow resolution — so the dates on the wire are always the server’s own. The form’s value never reaches the database, and sessions do not end up flattened to midnight.

The same nine-field copy is why every session SAVE writes the branch back as null: this applet never sets a branch, and a branch set through the API is cleared the first time anyone presses SAVE on the screen.

Device master — Create Device / Edit Device

A device is a name, a code and an optional brand / model. The code is the field that matters: the Android companion app registers its own hardware id there on first login, so the device list in a tenant that uses the app is part inventory of scanners and part audit trail of handsets.

Session device — Create Device Session / Edit Device Session

Attaching a device to a session is a pick from the ACTIVE master devices; brand and model come across read-only, the per-session status defaults to ACTIVE, and Remove detaches the device and is disabled once the session is Closed.

The session device records who is logged in, and every record created through it carries that device — which is how the Records tab groups a count by who took it. A record saved without one is invisible on that tab and still counted by the report; see Troubleshooting.

Record — Create Record Session (structured entry; ENABLE_AUTO_SCAN off)

Item Name, Item Code and EAN Code are filled by the lookup and cannot be edited. The form saves two ways — SAVE & CONTINUE keeps the item on screen so you can add another serial or correct the quantity, SAVE & NEW clears it for the next item; both write immediately, so there is no draft to lose and no way to undo a record except to delete it from the Records tab.

Record — Scan Form (ENABLE_AUTO_SCAN on)

Remarks is free text on the form and stays editable inline in the grid afterwards — it is the only field on a record you can correct without opening the record — but it travels no further than the record: the Reason column on the variance report is a different field on a different table, and nothing copies one to the other.

Grid columns: Quantity (in the selected UOM), Record Status (IN PROGRESS, VALIDATION IN PROGRESS, VALID, INVALID, CREATED), Remarks, SN# / Batch #.

Record — Edit Record Session

Item Name, Item Code, EAN Code and audit fields are read-only. Quantity is editable for non-serialised items; for serialised items the Serial Number field is edited instead and the quantity is recomputed as the number of comma-separated serials. UOM can be changed from the item’s UOM list. SAVE and Remove are disabled once the session is Closed.

Report line — where each number on the Report tab comes from

This is the grid an auditor reads, and it is the one screen in the applet whose numbers you cannot check by looking at anything else. Every column is one of three things: a value the report generator stored, a value the browser derives from two stored values, or — in two cases — both, computed in different units.

All quantity columns — and only the quantity columns — are divided by the item’s largest MULTI_UOM conversion factor, so they read as pack counts while the stored line stays in base units.

What a regeneration does not refresh

GENERATE and REGENERATE run the same statement; the second time it upserts on (session, item). The update half of that upsert names fourteen columns, and three of the columns it inserted are not among them:

• The serials you counted. Refreshed never. The ledger’s serials are refreshed. So all three serial columns are a comparison between a live ledger and a frozen count, and a serial added, removed or corrected after the first GENERATE will not change SN Variance no matter how many times you regenerate. The only way to rebuild it is to delete the report lines through the API.
• Item code and item name, as above.

Counted quantities, both balances, the band, the cost and the UOM columns are refreshed, and remarks is deliberately left alone so reasons survive a regeneration.

The Excel round trip does not close

Export writes no, itemCode, eanCode, itemName, TotalQty, MaxQty, MinQty, EMPQty, systemSerialNumber, STSerialNumber, SNVariance, variance1, variance2, costValue, totalCost, reason to a sheet named data. Import reads three of them — itemCode, TotalQty and reason — and writes the quantity and the reason onto the matching report line in batches of 1,000.

For an item with no MULTI_UOM lines that works exactly as it looks. For an item that has them, the two halves key on different things and the round trip cannot complete:

• the export writes the item code into itemCode;
• the import builds its list of acceptable keys from the largest UOM’s barcode for any item with conversions, and rejects the whole file on the first key it does not recognise, with this item code X is not exist.

So exporting the variance report, changing nothing, and importing it back fails on the first multi-UOM item in the sheet. To use the upload at all you have to replace the itemCode column with each item’s largest-UOM barcode by hand, and then TotalQty is read as a pack count and multiplied back by the conversion before it is stored. Two further consequences worth knowing before you plan around this screen: an uploaded TotalQty replaces the counted quantity on the report line without touching a single record, so the report and the records it was built from no longer agree; and the next REGENERATE overwrites it from the records again, silently. Reasons survive that; uploaded quantities do not.

A count sheet produced outside BigLedger and keyed on pack barcodes imports cleanly — which is the shape the import was plainly written for. It is the export from the button immediately above it that does not fit.

One more thing to check before you sign an exported sheet. For a multi-UOM item the export’s variance1 column is not the Variance you see on screen. The grid decides which side of the band the count falls on using pack counts throughout; the export makes the same decision by comparing the base-unit counted quantity against the pack-unit Min and Max. Above a handful of units that test always takes the over maximum branch, so the exported Variance reads Max − Counted whether or not the count is inside the band — an item comfortably within tolerance can leave the building with a variance printed against it. variance2, TotalQty, MinQty, MaxQty and EMPQty in the same file are all correct; it is the one column. Single-UOM items are unaffected.

Lifecycle and effects

Statuses. A session is OPEN or CLOSED (the two values the Status drop-down offers). The backend accepts any string and its report generator additionally recognises COMPLETED; there is no state machine — Closed is chosen from the drop-down and saved.

What Closed does.

• In the web applet: the session SAVE button, device Remove, record SAVE / Remove, the + on record listings and GENERATE / REGENERATE / UPLOAD REASON are disabled. The lock is the screen’s: the server checks that a record’s session, item and device exist, not whether the session is Closed, so the API (and the mobile app) can still write records to a Closed session. Closing therefore stops counting on this screen only; tell anyone counting on a handset that the session is closed.
• On the server: when a session is saved as CLOSED from the web applet, the server reads the Do The Stock During Opening Store setting from the applet’s stored settings — failing with Applet Settings Not Found! if the key was never saved, after the status change has already been saved — and sets the session’s Status Variance: YES or NO by the rule in the settings table, NA for any save that is not Closed. The key is not written unless somebody has opened this applet’s Settings screen and saved it, so a tenant that never has gets that error on every close and the session is left with no verdict at all. Save the setting once, before your first count.
• Treat Status Variance as a flag, not a finding. Three things narrow what it can tell you. It evaluates one report line — whichever comes back first, in no particular order. And with the toggle off the comparison treats an exact match as a difference whenever the stored figure carries trailing decimal places, which it always does. A session whose first line balances to the penny can still be reported YES. Read the Report tab’s Variance columns instead.
• Reopening: the web applet offers no way back from Closed (SAVE is disabled); the API accepts a status of OPEN on the same endpoint.

There is no snapshot — the expected quantity is recomputed every time you press GENERATE

This is the question a stock take exists to answer and the one the screen cannot: what was the system expecting, and as at when?

Nothing is taken at the moment you open the session. Creating a session stores a name, a code and a location and reads no stock at all. The expected quantity is worked out from scratch, from the stock ledger, at the moment you press GENERATE or REGENERATE — so two generations minutes apart can legitimately produce different expected quantities for an item nobody counted, because the ledger moved in between.

And the window it measures over is derived from your counting, not from your intent. The start and end dates are disabled fields the applet maintains: the first record created in the session stamps the start date, every later record create or edit moves the end date forward, and deleting records recomputes both from whatever records remain. No screen lets you set them by hand. Three consequences a reader has to know before they defend a number:

• Edit one record tomorrow and the whole report changes. Moving date_end extends the movement window, so the next REGENERATE re-bands Min, Max and EMP Quantity for every item in the report, including items you never touched.
• A count that runs overnight measures the whole night. Everything that posts at that location between the first scan and the last edit is inside the band.
• Movements dated exactly on the boundary are counted nowhere. The opening balance takes movements dated before the start, and the in-window sums take movements dated after the start and before the end — both strictly. A line whose timestamp equals either boundary falls into neither.

Report generation. GENERATE / REGENERATE require the session to be OPEN, CLOSED or COMPLETED (otherwise STOCKTAKE STATUS SHOULD BE CLOSED OR COMPLETED!), a location, and both a start and an end date (refused if either is missing). They then write one report line for every non-deleted item in the tenant — not the items at that location, and not the items you counted:

• opening balance = the stock ledger at the location strictly before the start date, from the latest brought-forward figure;
• inbound / outbound = movements in and out dated strictly between the start and end dates;
• Min = opening + outbound, Max = opening + inbound, system closing balance = opening + both;
• counted quantity = sum of the session’s non-deleted records for the item; counted serials = their serials; system serials = every serial with a positive balance at the location, with no date filter;
• unit cost = the moving-average cost on the most recent movement at that location before the start date, defaulting to 0; the cost method is always moving average.

Plan for the volume. One line per item in the catalogue means a 5,000-SKU retailer writes 5,000 report lines per session and rewrites all of them on every REGENERATE, however few items were counted. The report-line table is by a wide margin the largest thing this applet writes, and the great majority of its lines are items with no count, no movement and a zero cost. The Report tab pages 100 rows at a time, so use the Scanned Items report type — it shows only items with a count — rather than paging through the catalogue.

A regeneration overwrites counted quantities, balances, the band and cost on existing lines but keeps the remarks, so reasons survive a REGENERATE; quantities uploaded through the Excel screen do not, and neither the counted serials nor the item’s name and code are refreshed at all (see What a regeneration does not refresh).

Reason upload validates every itemCode against the current report (this item code X is not exist stops the whole import; Some fields(Phy qty or item code) are empty lists blank rows), then updates the report lines in batches of 1000, setting the counted quantity and the remarks. It changes the report line only — the records are untouched.

What posting does: nothing. Sessions, devices, records and report lines are not documents. There is no journal and no stock movement — nothing here writes to the stock ledger; the report only reads it. There is no VOID; a session can be deleted only through the API (the Edit Session screen has no Delete button). The report line and the session header both carry a family of planned-adjustment columns that nothing reads or writes — see What it will not do. Converting a variance into a stock movement is a manual Stock Adjustment, and that document is where the moving average is actually corrected.

Backend validation that can reject a save: a session is refused if its company, branch or location does not exist, or if its workflow process, process status or resolution does not exist; a record is refused if its session, item or bin does not exist, if its device does not exist (checked only when a device is supplied), if its item code is empty, or if the same record appears twice in a multi-create. Nothing on the server checks that a quantity is positive, that serial count equals quantity, or that the device belongs to the session.

Nothing runs in the background

Most applets in the platform hand work to a job processor: finalising a document queues a primary processor that fans out to secondaries, and the queue is what makes the consequences happen. This applet has none. No background job belongs to stock take; nothing runs after you save, and nothing waits to.

That is the reason for several things the screen never tells you: no overnight job recalculates a report, nothing sweeps sessions left Open, nothing warns that a session has been counted and never closed, nothing notifies an approver, and no variance ever becomes a movement on its own. Every figure on this page is computed by the request that asked for it.

What it will not do

• It will not change a stock balance. Not on close, not on approval, not ever. The report line even carries fields for a planned adjustment — adjust type, quantity, status, reference, remarks and the adjusting document, and an adjustment status on the session — and nothing uses any of them. They are carried on what the API returns, so an integration can set and read them — but no BigLedger behaviour acts on the value.
• It will not tell you which items to count. There is no count sheet, no cycle-count schedule, no ABC selection and no blind-count mode: the Report tab shows the system quantity next to the counted one from the first generation onward.
• It will not stop someone counting into a Closed session. The record and device validators check existence and references, not the parent session’s status, so the API and the mobile app can still write.
• It will not check a quantity is positive, that the serial count matches the quantity, or that the device belongs to the session. Those rules live in the two web entry forms only.

Related applets

• Stock Adjustment (Internal) — the document you raise, by hand, for each variance you decide to write on or off; the stock take itself moves nothing.
• Stock Balance and Stock Availability — the live view of the ledger the report compares against; use them to investigate a variance line.
• Stock Report — the Stock Balance With Serial report is a printable count sheet for a location.
• Inventory Item Maintenance — scan codes, UOM barcodes and serial / batch types decide whether a scan is recognised and how it is validated.
• Organisation — locations and their companies; the permission targets for sessions.
• Workflow Design — the optional process behind Workflow Status / Resolution.
• Warehouse Management System — bundles this applet for counting inside the WMS.

Troubleshooting

Related documentation

• Inventory module — where stock takes sit in the receive → move → count → adjust cycle.
• Stock Adjustment (Internal) — posting the variances you accept.
• Stock Availability — investigating a variance line before adjusting.