Administration & Controls
The settings, permissions, rate schedules, receipt controls, scheduled jobs and integrations that sit behind the daily procedures — and the reasoning behind the ones that look inconvenient on purpose.
Module settings
Settings → Water Utility. Fourteen keys, grouped into tabs. They arrive with the schema rather than with the demo data, because the module reads them while it runs — a database that has migrated always has them, whether or not anyone loaded sample data.
| Setting | Ships as | What it controls |
|---|---|---|
| App name | MyWater | The brand shown in the customer app and portal. |
| Official receipt mode | manual | manual: the teller types a number from the printed booklet and the system only checks it is unused. system: the module issues the next number itself. |
| Due days | 15 | Due date = end of period + N days. |
| Penalty rate | 10% | Percentage applied once to an overdue amount. |
| Disconnection grace days | 7 | Days past due before an account may be raised for disconnection. |
| Reconnection threshold | 0 | 0 = the balance must be settled in full before reconnection. A positive figure allows reconnection once the balance is at or below it. |
| Senior discount enabled | 1 (on) | RA 9994 is a statutory entitlement, so this ships on. The rate and ceiling are tariff configuration — see the note below. |
| Reader app enabled | 0 (off) | The route-book capture app for meter readers. |
| Portal enabled | 0 (off) | The OTP customer portal and the MyWater app. |
| SMS provider | none | The platform ships no SMS gateway. Choose and configure one before relying on text notices or OTP by SMS. |
| Field Service bridge | 0 (off) | Mirrors service orders into Field Service work orders. |
| Core invoice mirror | 0 (off) | Optionally mirrors a posted bill as a draft invoice in the core finance ledger. |
| AI assist | 0 (off) | Assisted reading review. Off by design. |
| AI data-privacy acknowledgement | 0 | Not granted until an administrator acknowledges it in the UI. |
Permissions and the duty separations
Thirty-eight keys in nine categories, declared by the module and injected into the Roles editor while it is enabled — disable the module and they disappear from the editor rather than lingering as unassignable clutter.
| Category | Base key | Covers |
|---|---|---|
| Accounts | water_utility_account | Billing accounts — and, deliberately, zones and service connections too: someone who may manage accounts may manage the taps they sit on. There is no separate connection permission. |
| Meters & Connections | water_utility_meter | The meter registry and its installation history. |
| Reading | water_utility_reading | Cycles, route books, and capturing reads. |
| Reading | water_utility_reading_validate | Validating and rejecting reads, resolving exceptions, closing cycles. |
| Billing | water_utility_tariff | Drafting tariffs, versions and tiers. |
| Billing | water_utility_tariff_approve | Approving a tariff version. |
| Billing | water_utility_bill_run | Creating and computing bill runs. |
| Billing | water_utility_bill_run_approve | Approving and posting a run; cancelling a posted bill. |
| Collections | water_utility_cashiering | Receipts, teller batches, promises to pay. |
| Collections | water_utility_payment_void | Voiding an official receipt. |
| Enforcement | water_utility_service_order | Service orders, notices, disconnection and reconnection. |
| Advisories | water_utility_advisory | Drafting and publishing advisories. |
| Reports | water_utility_reports | The reports hub, the exports, and the KPI dashboard. |
| Administration | water_utility_settings | The module settings, OR mode, booklet ranges. |
Most base keys also carry explicit _create, _update and _delete children, which the Roles editor groups underneath them.
The three separations that matter
A billing clerk computes a run; a supervisor approves and posts it. Give one person both and nobody checks the month's money before it reaches customers.
A teller writes receipts; voiding one is a supervisor's act, with a mandatory reason. The voided number is retained forever.
A tariff version prices every peso billed under it, so approving one is a checker's act. The system additionally refuses to let the person who drafted a version approve their own.
Building and approving a tariff
A tariff belongs to a customer class. It holds versions, each with an effective date and a board-resolution reference; each version holds tiers. The version whose effective date is the latest one on or before the billing date is the one that prices the bill.
The LWUA shape
| Charge type | Meter size | From | To | Amount | Meaning |
|---|---|---|---|---|---|
minimum | — | 0 | 10 | ₱235.00 | Fallback minimum for any size with no row of its own. |
minimum | 1/2" | 0 | 10 | ₱235.00 | Covers the first 10 cu.m for a half-inch meter. |
minimum | 3/4" | 0 | 10 | ₱470.00 | Larger connection, larger minimum. |
per_cum | — | 10 | 20 | ₱25.50 | Shared consumption block. |
per_cum | — | 20 | 30 | ₱28.00 | |
per_cum | — | 30 | 40 | ₱31.00 | |
per_cum | — | 40 | (open) | ₱34.00 | The open-ended top block. |
That is the shape the demo ships, and it is worth understanding because it is not obvious: the minimum varies by meter size, while the consumption blocks are shared across all sizes. The two are resolved independently — a size-specific minimum does not hide the shared blocks.
- Block bounds: from is inclusive, to is exclusive. Consumption sitting exactly on a boundary bills entirely in the lower block.
- The catch-all minimum is not optional. Validation also checks the set a meter size with
no rows of its own would fall back to. Without a minimum at
meter_size = —, that set has no minimum and does not start at zero, and the version will not validate. - Exactly one open-ended top block, and it must be last — otherwise consumption above the last bound has no rate.
Approving a version
Draft it
Create the version with its effective date, board resolution reference and approving authority, then enter the tiers. You can copy the tiers from an earlier version and edit the amounts.
Validate
Run the validator. It checks every meter size for gaps, overlaps, a block that ends before it starts, a missing or duplicated minimum, and the open-ended top block. The database cannot express these rules, so this check is the only thing between a mis-keyed tier set and a month of wrong bills.
Simulate
Price a sample consumption against the draft and read the resulting lines. Do this with a real customer's last month before you approve.
Approve
Needs
water_utility_tariff_approve, and cannot be done by the person who drafted it.
The senior citizen discount
The module ships the discount enabled but with no rate configured, and no ceiling. That is not an oversight. The statutory percentage and the consumption ceiling under RA 9994 must be verified per district against the current implementing rules, so the module refuses to invent them — an unconfigured rate produces no discount line at all rather than a plausible-looking guess.
Until you configure it, a flagged senior account's bill records the refusal reason
no_rate_configured in its snapshot, so anyone reviewing the bill can see exactly why
the discount was withheld. Configure the rate and ceiling in your tariff and the line appears on
the next run.
Official receipts and numbering
The module keeps its own number sequences for accounts, bills, receipts and service orders. The receipt series is the one under external scrutiny.
| Mode | Behaviour | Use when |
|---|---|---|
manual (ships as) | The teller types the number from a pre-printed booklet. The system verifies it is not already used and does not advance any internal counter. | Your district issues accountable forms on paper — the usual Philippine posture. |
system | The module issues the next number in the series itself. | Your OR posture has been signed off for system-generated numbering. |
Two rules hold in either mode: a receipt number is never reissued, and a void keeps the number — the row stays, marked voided, with its reason and the person who voided it.
Scheduled jobs
| Slug | Schedule | Responsibility |
|---|---|---|
wu_daily_servicing | 20 1 * * * | Ages receivables, breaks promises whose date has passed, refreshes the enforcement candidate list. It never writes a penalty — the penalty is derived for display and materialises once, as a line on the next bill. |
wu_expire_portal_tokens | */30 * * * * | Sweeps expired customer-portal OTP and session tokens. |
wu_field_sync | */15 * * * * | Reconciles service orders with Field Service work orders. No-ops when the bridge is off. |
wu_portal_payment_sync | */10 * * * * | Reconciles payments started from the customer app. No-ops when the portal is off. |
Inspect them with php erpat cron:list; run one by hand with php erpat cron:run <slug>.
Notifications
Nine events are sent automatically. Seven go to the customer, two to your staff. They arrive in the ERPat bell and by email, and are grouped under the Water Utility category in Settings → Notifications.
| Event | Goes to | Sent when |
|---|---|---|
| Bill is ready | Customer | A bill is posted. |
| Bill due soon | Customer | The nightly sweep, a set number of days before the due date. Skipped for accounts already on the enforcement ladder. |
| Bill past due | Customer | An overdue notice is issued. Not repeated once the notice is on file. |
| Payment received | Customer | A receipt is issued — at the teller window or from an imported gateway settlement. |
| Disconnection notice | Customer | A disconnection order is raised. |
| Service reconnected | Customer | A reconnection order is completed. |
| Advisory published | Customers in the targeted zones | An advisory is published, from the screen or over the API. |
| Bill run awaiting approval | Staff who can approve a bill run | A run finishes computing. Whoever computed it usually cannot approve it, so this is how the approver finds out. |
| Reading flagged | Staff who can validate readings | A reading fails a plausibility check. Sent once per finding, not once per cycle. |
Who actually receives a customer notification
The account's portal login, plus the client's primary contact. An account that has neither — only a billing email or mobile number on the account record — receives nothing, because ERPat's notification system addresses people, not bare addresses. If your customers should be notified, give them a portal login.
An advisory reaches every portal user in the targeted zones, up to 500 per advisory. Beyond that the notification stops and the shortfall is written to the application log. The advisory itself still appears for everyone on the customer portal and in MyWater, which remain the complete surface for it.
Text messages are separate. There is no SMS notification channel — SMS is used only for customer-portal one-time passcodes, and only when you configure a provider (see Module settings).
The audit trail
Roughly seventy distinct events are recorded to the system log — every create, update, status change, approval, posting, void, notice service and settings change, each with the acting user and the before/after values. A sample of what is captured:
Note that even viewing a meter-reading photo is logged. Evidence images are customer-premises photographs, and who looked at one is a privacy-relevant fact.
Integrations
Field Service
Service orders always live in this module's own ledger. When the bridge is enabled, raising one also creates a Field Service work order and remembers the link on the Water Utility side only — so the module continues to work exactly the same with Field Service switched off or uninstalled.
Core invoice mirror
Off by default. When enabled, a posted bill is also mirrored as a draft invoice in the core finance ledger for districts that consolidate there. The water bill remains the source of truth either way.
Customer portal and the MyWater app
Two tiers. A guest customer verifies by OTP and gets a scoped, expiring token that can view bills and pay. A customer with a full account signs in properly and gets the offline-capable MyWater app. Either way, every request is scoped to the accounts that customer actually owns.
SMS
The platform ships no SMS gateway. Until you choose and configure a provider, OTP-by-SMS and text notices are unavailable — email and printed service remain.
The two API surfaces
| Surface | Prefix | Who calls it | Authorised by |
|---|---|---|---|
| Integration API | /api/v1/water-utility/* | Another system — a cash-collection partner, a reporting warehouse | OAuth scopes water_utility:read / water_utility:write |
| End-User API | /v1/api/water-utility/* | The customer app, on behalf of one signed-in person | The signed-in identity, scoped to the accounts they own |
Data protection
- Meter photographs are premises imagery. They default to internal visibility and every view is logged.
- Reader GPS is captured to confirm a read happened at the tap, not to track staff. Treat the retention period as a policy decision your district must make.
- Portal tokens are credentials. They are stored as digests, are short-lived, and are swept on a schedule. They are never exported and never included in demo data.
- Senior citizen IDs are sensitive personal information. They are collected only where the discount is claimed.