Ledger Balance Monitoring and Threshold Alerts

Purpose and use

This manual describes how a Corebanq deployment watches a ledger balance against thresholds set by the institution, and what happens when a threshold is reached. Its principal use is supervising the total of public customer deposits against the limits that apply to the licence under which the institution operates.

Who uses this. Compliance and risk staff, who receive the alerts and act on them; finance, who agree the thresholds; deployment operators, who configure them.

How it works. The check runs on every posting, whichever way the balance moves: a journal or direct entry, or a transfer settling onto a customer account. A settlement always carries its base-currency value — converted through the FX rates for a foreign-currency account — and a settlement that cannot be converted is refused rather than booked with no base-currency movement, so the control group above the account is measured on every deposit. Whenever a monitored ledger moves — directly, or through a subledger that rolls up into it — the balance before and after the posting are compared against that ledger's threshold rules, most severe first. The first rule the new balance satisfies is the level reached; if the balance before the posting did not satisfy it, the posting crossed it and an alert goes to the named recipients. A balance that then stays above the limit does not alert again on every further posting — the next alert comes when the next level is crossed. The alert states the balance, the threshold that was reached, and when. The alert is queued with the posting and delivered right after the posting is booked, so notification problems never delay or fail a posting. There is no separate polling job: a limit is crossed the moment the posting that crosses it is booked.

What operators do. Configure which ledgers are monitored, the threshold levels, the action at each level and who is notified, then verify by exercising each level that the right people receive the right message.

Outcomes and side effects. An alert is a notification, not a control: reaching a threshold does not stop business. The suspend level is today delivered as an alert as well — see The suspend action — so no posting is refused by monitoring; stopping deposits remains an operator decision taken on the alert.

Related manuals: Ledgers, General ledger integration, Notifications.

What is monitored

Monitoring is configured per ledger account code, under ledgers.balance_monitoring. Each monitored ledger carries a description explaining what is being watched and a list of threshold rules.

The deployment's principal monitor is the public customer deposits control group, 221 — Customer Deposits (Available) – Type A Customer: every Type A customer, every currency. Customer deposits are a liability of the institution, and in this ledger a liability carries a positive credit balance, so a deposit threshold is a positive limit with an "at or above" comparison: the balance reaching seventy-five million means deposits have risen to seventy-five million. (Older configurations keyed the monitor on the CHF leaf 2211 with negative "at or below" limits; that convention no longer matches the ledger and must not be reintroduced. An environment seeded with the old ladder keeps those rows in its application configuration until the current seed retires them — the seed lists them under _deleted — so check the ledger configuration screen for stale 2211/2212 monitors after upgrading.)

Which balance is compared. A licence limit is a base-currency figure. A ledger that aggregates several currencies — 221 sums CHF and EUR children — or that is itself kept in a foreign currency is therefore compared on its base-currency balance (balance_lcy, revalued at posting time); a base-currency leaf is compared on its own posted balance. The balance chart plots the same figure, so the line and the limit lines share one scale.

All amounts are held in minor units — a limit of seventy-five million Swiss francs is configured as seven billion five hundred million.

Threshold rules

Each rule states:

Configuring several levels with widening recipient lists is the usual pattern: an early level informs compliance, a later level adds risk, and a final level suspends the ledger. The deployment's configured levels for public deposits are seventy-five, eighty-five and ninety-five million, with a suspend action beyond them.

Thresholds are configuration. Finance and compliance can retune the levels, the recipients or the actions for an environment without a code release; a change applies within about thirty seconds on every instance, and every change to the configuration is itself an auditable change. A configuration that cannot be read keeps the last good ladder; if there is none, monitoring is off and the error is logged until it is fixed.

What an alert contains

An alert is rendered from a message template in the deployment's default language and carries the facts a recipient needs to act without opening the system:

• The ledger's code and its description, so the recipient knows what has moved.
• The current balance, formatted in major units, with its currency.
• The threshold that was reached, formatted the same way.
• The timestamp at which the comparison was made.
• The institution's name, taken from the deployment's own configuration.

The alert is delivered through the platform's existing notification subsystem rather than a separate mail path, so it is subject to the same sender configuration, branding and delivery handling as every other message the platform sends. See Notifications.

The suspend action

suspend marks the level beyond which the institution would be operating outside its licence conditions — for public deposits, one hundred million. Today it does not block postings. Reaching it sends the alert configured on the rule (to compliance and risk in the Audax configuration) and is drawn as the solid limit line on the deposit charts; refusing further deposits, and lifting that refusal, remain deliberate operator actions.

Making suspend a hard control — the ledger refusing postings until an operator lifts the suspension, recorded in the audit trail — is an outstanding deliverable. Until it lands, treat the suspend alert as the signal to stop, not as the stop itself.

Dashboard presentation

Both operator screens draw the ladder over the deposit balance:

• The Admin UI home page plots the daily balance of 221 with the three alert levels as marker lines (the Public deposit limit items) and the latest value written at the end of the line.
• The Configurator dashboard (multi-ledger balance tile) plots any monitored ledger with its full ladder — dashed lines for the alert levels, a solid line for the suspend limit — taken from the balance-history chart, which returns the ledger's thresholds from the same ledgers.balance_monitoring configuration the alerting uses, so the lines drawn and the alerts that fire cannot disagree.

Both charts plot the daily balance snapshots; the live balance is on the ledger list of the Admin UI home page and in the Configurator ledger browser.

Where the snapshots come from — an outstanding item. There is no automatic end-of-day capture yet: nothing in the platform writes a ledger balance snapshot on its own. Snapshots exist only when generated on request through the ledger balance-history generation operation (POST /v1/ledgers/history/generate), which writes one row per day for a ledger and date range from its posted entries and can be re-run safely. Until scheduled daily capture is delivered, an operator (or an external scheduler calling that operation) must generate the snapshots the charts plot; the alerting itself does not depend on snapshots — it runs on the posting path.

Acceptance checks

1. Each configured threshold, exercised in turn, produces an alert to the recipients named at that level.
2. An alert states the ledger, the current balance, the threshold reached and the timestamp.
3. A balance breaching several levels at once triggers the most severe rule, not the mildest.
4. Sign convention is correct: rising customer deposits trigger the deposit thresholds, and a deposit in a foreign currency counts at its base-currency value.
5. Reaching the suspend level sends its alert; the institution's procedure for stopping deposits is triggered by that alert (the hard control is an outstanding deliverable).
6. Alerts are delivered by e-mail through the platform's notification subsystem with the configured sender, after the posting that crossed the level is booked. A delivery failure never affects the posting; it is retried with growing gaps (five attempts over about eight minutes) and, if every attempt fails, the alert is parked in the outbox with its error for operators to act on — later alerts are not held up behind it.
7. Changing a threshold in configuration takes effect without a code release and is auditable.