Getting Started
Install the module, let the migration build its three main-database tables, switch it on, grant the right operators access, and populate the Analytics tab — either with demo data or a first fleet sweep.
Prerequisites
- PHP 8.2+ and a working ERPat platform install.
- Platform / main-database admin access. You must be an administrator working on the main platform database, not inside a tenant session. The Analytics tab redirects away if opened from a tenant session.
- Access to Settings → Manage Modules (to enable the module) and to the Roles editor (to grant permissions).
- A ticking cron runtime if you want the nightly sweep to populate data automatically — otherwise you can run sweeps manually (see below).
Activation — three steps
-
Run the module migration
From the project root. The migration is idempotent and reversible, and is tracked in the module's own
migrations_tenant_analyticstable. It creates the three tables in the main database only — on a tenant connection it safely does nothing.php erpat migrate:modules # (or) php erpat migrate:latest -
Enable the module
Go to Settings → Manage Modules and switch on Tenant Analytics (grouped under System). This sets
module_tenant_analytics = 1. With the module on, an Analytics tab appears on the Tenants list page for operators who also hold thetenant_analyticspermission. -
Grant access in Roles
In Roles, assign the Tenant Analytics permissions to the operator roles that need them. Administrators see everything by default. See Granting access below.
What the migration creates
One migration builds three tables, all in the main/primary database:
| Table | What it holds |
|---|---|
tenant_analytics_snapshots |
One JSON row per tenant × date × metric group — the raw
measurements. Includes each tenant's identity (client_id,
company_slug) so operators can drill into a single tenant. |
tenant_analytics_rollups |
The platform-wide aggregate per date × group, containing no tenant identifiers at all. This is the only table the public API can read. |
tenant_analytics_runs |
The sweep audit ledger — one row per sweep (nightly or manual) with counts, status, timing, and a resume cursor for chunked manual runs. |
availability.tenant_database = false, so the tab and these tables never appear
on a tenant database. Provisioning a new tenant runs the migration on that tenant's
connection, where it is a deliberate no-op.
Granting access in Roles
While the module is enabled, three permissions appear in the Roles editor under the
System: Tenant Analytics category. The base tenant_analytics permit is the
master key — the tab and every action require it; the other two layer on top.
| Permission | Grants the operator… |
|---|---|
tenant_analyticsbase |
Read / view the Analytics tab — the KPI cards, the per-tenant snapshots table, and the platform-aggregate panel. Without it, the tab does not appear. |
tenant_analytics_run |
Run sweeps — the "Run snapshot now" console, re-sweeping a single tenant, and rebuilding the platform rollups for a date. |
tenant_analytics_configure |
Edit settings — retention, include-inactive, batch size, the public-API switch, and small-n money suppression. |
Load demo data (optional but recommended)
To explore the tab and the API before running a real fleet sweep, load the bundled demo dataset. It seeds three pseudo-tenants × three metric groups of snapshots, one completed demo run, and matching platform rollups — all into the three main-database tables.
# Seed the demo data (main database)
php erpat db:seed TenantAnalyticsDemo
# Preview without writing
php erpat db:seed TenantAnalyticsDemo --dry-run
# Remove it again (soft-delete only — never touches real analytics)
php erpat db:seed TenantAnalyticsDemo --removedemo run source, a "demo":true rollup marker), so
--remove soft-deletes exactly the demo rows and never clobbers real fleet data.
It also refuses to overwrite a real rollup that already exists for a date.
Get your first real data
Right after enabling the module, the tab has nothing to show until the fleet has been swept at least once. You have three ways to populate it:
If your cron runtime is ticking, the tenant_analytics_snapshot
job runs at 03:00 and fills in yesterday's picture automatically.
Force a full sweep now from the command line:
php erpat cron:run tenant_analytics_snapshot.
Use the Run snapshot now button on the Analytics tab for a guided, chunked sweep with a live console. See Daily Operations.
Verify the install
-
Open the tab
Go to Settings → Tenants and select the Analytics tab. You should see the KPI cards, a date and metric-group selector, a per-tenant snapshots table, and the platform-aggregate panel.
-
Confirm data appears
After a sweep (or the demo seed), the snapshots table lists tenants and the aggregate panel shows a JSON payload with a "tenants counted" line. Switch the metric group and date to confirm the panels refresh.
-
Check the public API is off
The aggregate panel shows an API off badge by default. That is expected — the public API ships disabled. Turn it on deliberately from Settings when you are ready (see Administration).