Administration
Tune retention and sweeping, manage who can do what, keep the nightly cron ticking, and decide whether to expose the platform aggregate through the default-off public API — with the safeguards that keep individual tenants private.
Settings
Open the Settings button on the Analytics tab (requires the
tenant_analytics_configure permission). Five settings control retention, sweeping
and the public API:
| Setting | Default | Range | What it does |
|---|---|---|---|
Retention daystenant_analytics_retention_days |
400 | 1–3650 | How many days of snapshots to keep. The nightly sweep prunes anything older. It also bounds how far back the public API will serve a date. |
Include inactive tenantstenant_analytics_include_inactive |
On (1) | On / Off | When on, sweeps cover suspended and archived tenants too, so the fleet total reflects the whole platform. When off, only active tenants are swept. |
Sweep batch sizetenant_analytics_sweep_batch_size |
3 | 1–20 | How many tenants a manual sweep processes per request. Lower is gentler on the servers; higher finishes faster. 3 is a safe default. |
Public API enabledtenant_analytics_public_api_enabled |
Off (0) | On / Off | The kill switch for the public aggregate API. Off by default. While off, every public endpoint returns 404. |
Minimum aggregate tenantstenant_analytics_min_aggregate_tenants |
1 | 1–1000 | Small-n privacy floor. If fewer than this many tenants contributed to a group's
aggregate, money figures are omitted from the public API and the response is flagged
suppressed: true. 3 is recommended in production. |
module_tenant_analytics. Saving the five
settings above records an audit-log entry (see Audit logging).
Permissions
Three permissions gate the module, under the System: Tenant Analytics category in Roles. Grant them to platform-operator roles; administrators hold them by default.
| Permission | Unlocks |
|---|---|
tenant_analytics | View the Analytics tab (KPIs, snapshots table, aggregate panel). Required for everything else. |
tenant_analytics_run | Run manual sweeps, re-sweep a tenant, and rebuild rollups. |
tenant_analytics_configure | Open and save the settings above. |
On top of a permission, the tab always requires an administrator on the main database — a tenant session is redirected away.
The nightly cron job
The module ships one scheduled job on ERPat's Advanced Cron runtime. It is what keeps the tab populated with no manual effort.
| Property | Value |
|---|---|
| Slug | tenant_analytics_snapshot |
| Schedule | 0 3 * * * — daily at 03:00 |
| Scope | Global (runs once on the main database and loops the fleet itself) |
| Timeout / memory | 1800 seconds / 512 MB |
| Enabled by default | Yes (but self-skips if the module is off) |
Each night it sweeps every targeted tenant, writes their snapshots, rebuilds the platform rollups for the date, prunes snapshots past the retention window, and closes the run in the audit ledger.
# See it in the registered job list
php erpat cron:list
# Run the full nightly sweep on demand
php erpat cron:run tenant_analytics_snapshotmodule_tenant_analytics is on.
The public aggregate API
An optional, keyless, read-only JSON API can serve the platform aggregate at
/api/v1/analytics/… — useful for a public status page, an investor
dashboard, or a marketing "numbers" widget. It is off by default and must be switched on
deliberately.
| Endpoint | Returns |
|---|---|
GET /api/v1/analytics/groups | The available metric groups and the latest date with data. |
GET /api/v1/analytics/summary?date=YYYY-MM-DD | A headline number per group for one date. |
GET /api/v1/analytics/{group}?date=YYYY-MM-DD | One group's full platform aggregate for a date. |
Full request/response detail is on Reference.
Enabling it
-
Decide it's appropriate
Remember what the aggregate reveals: platform scale — how many tenants you run, total payroll volume, fleet headcount. Only enable it if publishing those totals is acceptable.
-
Set the small-n floor first
Raise Minimum aggregate tenants to at least 3 so money figures are suppressed whenever too few tenants would make a single tenant's numbers guessable.
-
Turn the switch on
Set Public API enabled to On and save. The tab's badge flips to API on and the endpoints start responding. Turn it back off any time — every endpoint immediately returns 404 again.
Security & the privacy model
Because the API is unauthenticated, the module is built so that per-tenant information can never leak through it. Four layers combine:
The public API ships disabled and returns 404 until an administrator
deliberately enables tenant_analytics_public_api_enabled.
The API only reads the tenant_analytics_rollups table, which
physically contains no tenant IDs, slugs, names, or module maps. Building a rollup keeps only
numeric totals and drops every text/boolean value — a per-tenant identifier cannot
survive into it.
When fewer than the configured minimum number of tenants back a group,
money fields are stripped and the response is marked suppressed: true, so a
single tenant's figures can't be inferred.
A dedicated public rate-limit guard throttles the anonymous endpoints, and every request is written to the standard API request log for monitoring.
The per-tenant snapshots table on the tab is never exposed publicly — it lives behind the main-database admin session and the permissions above.
Audit logging
Sensitive actions leave an entry in the platform's system activity log:
| Event | Severity | When |
|---|---|---|
Tenant Analytics sweep executedrun:tenant_analytics |
info | Once per manual sweep batch and per re-sweep, with counts and whether it was a dry run. |
Tenant Analytics settings updatedupdate:tenant_analytics_settings |
warning | Whenever the five settings are saved, recording old and new values and the operator. |