Reports
Generate and download water-data reports. Pick a report, configure the date / interval / units / format, then download (PDF or Excel) or preview it. The report itself is rendered by the server — the frontend only builds a URL.
- Route:
/reports→ReportsV2Page+ subpages (libs/reportsV2/) - Sidebar gate:
DISABLE_REPORTSpermission (individual report types are gated per-service — see Access) - Library:
libs/reportsV2/(current) — the route has no wrapper guard
Which reports library is which
| Library | Status | Where it runs | What it is |
|---|---|---|---|
reportsV2 | Current | production + demo, /reports | Routed multi-page generator (this page) |
reports | Standalone apps | rwi, uwms, lakepulse, /reports | Older single-page tabbed generator (same backend) |
legacyReports | Dead | Nowhere | Empty scaffolding — referenced by nothing |
Both live libraries hit the same backend GET {baseUrl}/report; reportsV2 is a
routed-UI rewrite of the standalone reports page.
Three ways in
Summary: The landing chooser offers frequent presets, executive reports, or a wizard. All three end by building a
/reportURL that the server renders as PDF/Excel (download) or HTML (iframe preview).
| Path | Subpage | What it does | On click |
|---|---|---|---|
/reports | ReportMainSelectionPage | The chooser (frequent cards, executive cards, "Create new") | A card prefills params and routes to its page |
/reports/frequent_reports/:reportId | FrequentReports | A preset report with 5 inline-editable fields | Edit a field inline; Download |
/reports/summary_report | SummaryReportPage | Daily / Weekly / Monthly summary (PDF only) | Pick range; Download |
/reports/water_balance | WaterBalanceReportPage | Daily / Monthly water-balance report | Pick range + format; Download |
/reports/new_report | NewReportPage | The 4-step wizard (below) | Continue through steps; Download |
The new-report wizard
Four steps (NewReportPage), with a breadcrumb of chosen values:
- Report Type — Flowmeter / Stock / GW Level / Quality / Rain Water / Energy (filtered by your services).
- Time & Date — interval (5 min / hour / day / month) + single or multiple date(s).
- Categories & Units — searchable unit picker (Rain Water auto-selects all and skips this step).
- Format & Export — Excel / PDF, with a live preview.
Each Continue validates that step's fields before advancing.
The one endpoint
Everything funnels into a single URL built client-side and opened in the browser
(there is no apiClient call):
GET {baseUrl}/report?useShift=true&reportType=…&reportFormat=…&service=…
&jwt=<token>&startDate=…&format=v2[&endDate&unitIds&startTime&endTime]
reportFormatdrives the behaviour, same endpoint:pdf/xlsx→ download (window.open);html→ preview (loaded in an<iframe>).- Units come from your
loginResponsein local storage (services → subCategories → units), not an API.
Because the report is fetched by window.open / an iframe (not apiClient), the
token is passed as a jwt query parameter — it lands in browser history. Flag
if you touch this.
Access & gating
| Layer | Rule |
|---|---|
/reports route | Unguarded (no PermissionWrapper) |
| Sidebar entry | Gated by the DISABLE_REPORTS permission |
| Report types | Shown only if your services include that category |
| Rain Water | Requires RWI; Summary requires DAILY_SUMMARY; Water Balance card requires WATER_BALANCE |
The standalone
reportslib (rwi/uwms/lakepulse) instead gates onNOT_GENERAL_REPORT/EXECUTIVE_SUMMARY_REPORT— keysreportsV2doesn't use.
Edge cases & guards
| Case | Handling |
|---|---|
| Validation | Missing fields block the download ("Please fill in: …") |
| Rain Water | Auto-selects all units and skips the Units step |
| Unit soft-limit | > 5 units shows a "will take longer" warning (non-blocking) |
| Preview staleness | Changing params after a preview shows a "Refresh Preview" button |
| Date limits | Interval-specific maxDateRange (5 min → 6 days, daily → 30, monthly → 12) |
| Server errors | Surface inside the downloaded file / iframe (no client-side error UI) |
Underlying libraries
reportsV2 pulls in no client-side charting, PDF, or Excel library — rendering
is entirely server-side.
| Purpose | Library |
|---|---|
| Date picker | AppDatePickerSelection |
| Dates | moment |
| UI | @mui/material (MUI 7), @iconify/react |
| Export | the browser (window.open / <iframe>) |
Code reference
| File | Role |
|---|---|
ReportsV2Page.jsx | Layout shell + <Outlet /> + provider |
store/reportStore.jsx | Params + buildReportUrl |
helper/reportHelper.js | Report types, intervals, validation, gating |
subpages/ReportMainSelectionPage.jsx | The chooser |
subpages/NewReportPage.jsx · NewReportStepContents.jsx | The 4-step wizard |
subpages/{WaterBalance,Summary,Frequent}*.jsx | The dedicated report pages |
components/Report*Selector.jsx · ReportPreviewComponent.jsx | Field selectors + iframe preview |
Related
- Water Balance — the source of the water-balance report
- Permissions —
DISABLE_REPORTSand per-service gating - Application Routes · Applications → Standalone apps