Getting Started
Bring the module online in the right order — schema, switch, permissions, sample data — then walk the sample district end to end so you know what a healthy month looks like before you touch a real customer.
Before you begin
- Admin access to Settings → Manage Modules and to the Roles editor.
- Shell access to run
php erpatcommands, or someone who has it. - A decision on your official-receipt posture. The module ships in
manualOR mode on purpose — it will not mint receipt numbers for you until you deliberately switch it. Involve whoever answers to COA before you change that. - Your board-approved tariff schedule, with the resolution number, if you intend to bill real customers. You can explore everything else without it.
Step 1 — Create the tables
The module owns 27 tables and creates them through its own migrations. From the project root:
php erpat migrate:modules
This runs against the primary database and every active tenant database, and it is safe to run again — each migration checks before it changes anything. It also seeds the module's functional settings (due days, penalty rate, grace period, OR mode and the rest) at their shipped defaults. Those are configuration the module reads while it runs, so they arrive with the schema rather than with the sample data.
Step 2 — Switch the module on
Go to Settings → Manage Modules and enable Water Utility. The sidebar group appears immediately.
module_water_utility — and it governs the whole module. There is deliberately no
per-feature toggle for reading, billing or collections: below the module switch, who sees what
is a permission decision, not a settings decision.
Step 3 — Grant access
Open the Roles editor. With the module enabled you will see nine Water Utility permission categories. Assign them by job, not by seniority — the separations below exist to keep one person from being able to both create and bless the same money.
| Job | Grant | Do not grant |
|---|---|---|
| Customer service / registry clerk | Billing Accounts (+ create/update), Meters & Installations | anything under Billing or Collections |
| Meter reader | Reading Cycles & Capture (+ create/update) | Validate Readings & Exceptions |
| Reading supervisor | Reading Cycles & Capture, Validate Readings & Exceptions | — |
| Billing clerk | Tariffs & Versions, Bill Runs & Bills (+ create/update) | Approve & Post Bill Runs, Approve Tariff Versions |
| Billing supervisor / GM | Approve & Post Bill Runs, Approve Tariff Versions | — |
| Teller | Cashiering & Collections (+ create/update) | Void Official Receipts |
| Cashiering supervisor | Cashiering & Collections, Void Official Receipts | — |
| Enforcement / field coordinator | Service Orders & Enforcement (+ create/update) | — |
| Management / analyst | Reports & Dashboard | — |
| Module administrator | Water Utility Settings, Advisories | — |
Approve Tariff Versions
is a newer permission and starts out held by no role at all. That is intended: approving a rate
schedule that prices every bill should be a deliberate appointment. Until you grant it, drafts can
be written but not approved.
Step 4 — Load the sample district
The module ships a demo seeder that builds one coherent district you can actually drive: two zones, six taps with meters and accounts, a completed June reading cycle, two approved tariffs, a posted bill run with four priced bills, two receipts in a closed teller batch, an overdue notice, a promise to pay, a disconnection order and a published advisory.
php erpat db:seed WaterUtilityDemo --dry-run # see the plan, change nothing php erpat db:seed WaterUtilityDemo # load it
Everything it creates is prefixed WU-DEMO-, so it is obvious on every screen. To take it back out:
php erpat db:seed WaterUtilityDemo --remove
Removal is a soft delete — the rows are marked deleted, never destroyed — and it only claims
rows it can still identify by their WU-DEMO- code. Re-running the seeder afterwards
restores the same demo rather than creating a second copy. You can also drive both from
Settings → Maintenance → Seeders if you would rather not use the shell.
WU Demo · …), six accounts, four bills and two receipts. That is
exactly what you want on a training or evaluation database and exactly what you do not want
mixed into real books.
Step 5 — Take the guided walk
With the demo loaded, follow this route. It takes about ten minutes and covers every screen.
-
Accounts →
WU-DEMO-ACCT-0003The commercial account (an eatery). Note its customer, its connection, its meter, and its outstanding balance of ₱1,330.00 — a partly-paid bill.
-
Connections & Meters
Six taps across two zones, each with one installed meter. Zone 2 has taps and accounts but no cycle yet — that is the "not billed this month" case on purpose.
-
Reading → cycle
WU-DEMO-CY-202606A closed June cycle over zone 1, with one route book, four reads, and two exceptions — one resolved high (the eatery refilled its tank) and one open low (confirm occupancy).
-
Billing → tariffs
Two approved, effective-dated schedules. Open the residential one and read the tiers: a ₱235.00 minimum covering the first 10 cu.m, then blocks at ₱25.50 / ₱28.00 / ₱31.00, and an open-ended block above 40 cu.m.
-
Billing → bill run
WU-DEMO-BR-202606Posted, 4 bills, 84.000 cu.m, ₱3,239.00. Open bill
WU-DEMO-BILL-000003and read its lines — the minimum, three full blocks, and 13 cu.m billed above the top block. -
Collections → batch
WU-DEMO-CB-01A closed teller batch holding two receipts totalling ₱1,439.00 — one settling a bill in full, one partial. Then open Aging and see the ₱1,800.00 still outstanding.
-
Enforcement
One overdue notice, one active promise to pay holding the eatery off the ladder, and one open disconnection order on the account that never paid.
-
Advisories & Reports
A published interruption advisory targeted at zone 1, and five reports with live numbers to look at: billing register, collection summary, aging, exceptions and route completion.
Step 6 — Review the settings
Open Settings → Water Utility. Everything ships at a safe default; the four that matter most on day one are below. The full list is in Administration → Settings.
| Setting | Ships as | Why it matters |
|---|---|---|
| Official receipt mode | manual | The system will not generate OR numbers until you switch it. Deliberate — a receipt series is a controlled document. |
| Due days | 15 | Due date = end of the billing period + this many days. |
| Penalty rate | 10% | Applied once to an overdue amount; it materialises as a line on the next bill, never as a daily charge. |
| Disconnection grace days | 7 | Days past due before an account may be raised for disconnection. |
Step 7 — Switch on the background jobs
Four scheduled jobs keep the module honest. They only do work when their feature is switched on, so leaving them registered is harmless.
| Job | Runs | What it does |
|---|---|---|
wu_daily_servicing | 01:20 daily | Ages the receivables, breaks promises whose date has passed, and surfaces enforcement candidates. |
wu_expire_portal_tokens | every 30 min | Sweeps expired customer-portal OTP and session tokens. |
wu_field_sync | every 15 min | Keeps service orders in step with Field Service work orders, when that bridge is enabled. |
wu_portal_payment_sync | every 10 min | Reconciles payments started from the customer app. |
Confirm they are registered with php erpat cron:list, and make sure a cron runtime is actually ticking on the server.