Stock Level Monitoring Applet

Overview

Stock Level Monitoring watches the quantity on hand at each location against an optimal level and a maximum level that you set per item category, and e-mails a list of people when anything falls below or rises above them. It is a pure alerting applet: it reads stock balances and writes nothing back to inventory, creates no documents and posts no journals.

Think of it as the warning half of Stock Replenishment. The two applets share the same template → event → run shape and the same Rules Logic / Negation Logic controls (this applet’s own source says the controls were ported from there). Replenishment acts — it raises purchase orders and transfers. Monitoring only tells you.

Where it fits

Screens and menus

The Template and Run screens each open into a view with four sub-sections: Locations, Companies, Categories, and (on a run) Emails. The Event view has Locations, Companies, Categories and Entities. Categories is the one that carries numbers — one row per item category, with an editable Optimal Stock Value and Maximum Stock Value.

Both grids label those two columns "(MYR)". They are not money: the backend compares them against bl_inv_current_location_stock_balance.qty_ledger, a quantity. Read them as units.

Listings load a fixed window and extend it with a More action rather than paging server-side, and the menu file records that Release Notes was routed but unreachable until its entry was added — both are visible in menu-items.ts and the listing components.

Screenshots needed

No screenshots exist for this applet. A capture session should take: the Template listing; a Template view showing the Categories grid with Optimal and Maximum values and the Negation Logic control; the Default Optimal / Maximum Stock Value pair with the inline warning callout; an Event view with Recurring ticked and the recurrence editor open; the Run view with the Run Processor button; and the run’s Emails section. A scratch tenant is required — the Emails section shows real entity e-mail addresses.

Configuration

Before you can use it

Applet settings

Settings are applet-local, and there are effectively none.

• Settings → Field Settings is the unbound eight-toggle stub — Unit Discount, SST/VAT/GST, WHT, Blanket Order, Segment, G/L Dimension, Profit Center, Project — with no form group, no formControlName and a SAVE button with no click handler. The labels belong to a sales-document settings screen and have nothing to do with stock monitoring. No exposed control found (routes and settings components checked at commit 12cab54f).
• Settings → Default Selection and Personalization → Default Selection offer Default Branch and Default Location, and do persist them (saveMasterSettingsInit / savePersonalSettingsInit, with a RESET that writes nulls). But DEFAULT_BRANCH and DEFAULT_LOCATION are declared in applet-settings.model.ts and read nowhere else in the applet — no screen pre-selects anything from them. They are declared, rendered and persisted, but not consumed, so nothing changes when you set them.
• Settings → Release Notes shows the applet’s release notes.

Everything that actually changes behaviour lives on the template, the event and the run, not in Settings. That is the part to configure:

Feature visibility / permissions

bl_applet_client_side_perm_dfn holds zero rows for stockLevelMonitoringApplet (checked 2026-09-14), and the applet checks no HIDE_* / SHOW_* keys, so the Feature Visibility screen has nothing to gate. Access is entirely server-side, through TntErpPermissions:

Fields

Template → Create

The template view adds Creation Date, Created By, Modified Date and Modified By as read-only fields, plus the Locations, Companies, Entities and Categories sections.

Event → Create

Run → view shows Run Name, Description and Status, the Locations, Companies and Categories snapshots, and the Emails list (Entity Name, Email, Updated Date, Actions).

Lifecycle and effects

This applet writes only its own three header tables and their link tables. No stock movement, no journal, no document. Quantity and amount signums do not apply — there is no generic document and no data-consistency object of the financial kind; the DCOs under StockLevelMonitoringDataConsistencyObjects/ validate the template, event and run rows themselves.

How a run is triggered. There are exactly two paths, and both insert into the STOCK_LEVEL_MONITORING_RUN_PROCESSOR queue:

1. Creating an event. StockLevelMonitoringEventHdrService.create inserts a queue event carrying the event GUID, with ExecutionStrategy.RUN_NOW if the event’s start date is now or in the past and INSERT_TO_QUEUE if it is in the future. Updating an event does not re-queue anything.
2. Pressing Run Processor on a run (GET …/stock-level-monitoring-run-hdrs/backoffice-ep/manual-run/{guid}), which queues the run GUID RUN_NOW.

What the processor does. StockLevelMonitoringRunProcessor.processEvent branches on which GUID it was given:

• event GUID — loads the event; if the event has no template_hdr_guid it logs an error and stops. Otherwise it creates a run header from the template and the event, then processes it.
• run GUID with a template — processes that run.
• run GUID with no template — logs “Monitoring run without a template is not supported” and returns an empty result. A run created by hand and never linked to a template can never produce anything.

Processing a run (processRun):

1. Snapshot the template’s locations, companies and entities onto the run, but only where the run has none yet — so a run that has been edited keeps its own scope.
2. Snapshot the template’s category links onto the run the same way. The event’s own category links are deliberately not used: they hold category groups, not categories with stock values.
3. Resolve Negation Logic from the run, falling back to the template.
4. When negation is ENABLED, replace the picked categories with every other active category in the same label lists, each carrying the template’s default optimal and maximum values.
5. detectBreaches — for each category link with at least one of the two values set, for each item in that category, for each of the run’s locations, read bl_inv_current_location_stock_balance.qty_ledger (null treated as zero) and compare. Below optimal is UNDERSTOCK; above maximum is OVERSTOCK. Understock wins when both would apply, and the triple (item, location, breach type) is de-duplicated.
6. Write breach_count, detected_at and the full breaches list into the run header’s property_json.
7. Send the alert e-mail.

The alert e-mail. Recipients are the entities linked to the run, reduced to those with a non-blank email on bl_fi_mst_entity_hdr. Sender and subject come from the run header, falling back to the platform default sender and a built-in subject. The subject and body were copied from the template when the run was created, so changing the template does not rewrite an alert already sent. Every send is recorded in the e-mail history table. The e-mail service never throws — a failure is returned on the result, logged, and the run still completes.

Nothing displays the result. The breach list exists in the run header’s property_json and in the e-mail. The applet never reads property_json, breach_count or the e-mail history — there is no screen anywhere in it that shows what a run found.

Related applets

• Stock Replenishment Applet — the same template / event / run shape, and the same Rules Logic and Negation Logic controls, but it acts on the shortfall by creating purchase orders and transfers instead of e-mailing.
• Stock Balance Applet — reports on the same qty_ledger figures this applet compares against.
• Stock Availability Applet — the interactive way to answer “how much is at this location right now”.
• Item Maintenance — where the item categories this applet monitors are defined.
• Organisation Applet — the companies and locations a template can scope to.

Troubleshooting

Related documentation

• Inventory module