FAQ & Troubleshooting

Reference

FAQ & Troubleshooting

Answers to the questions operators ask most, a glossary of the terms this module uses, and where to look and who to contact when something isn't right.

Troubleshooting

I can't see the Analytics tab

Three things are required together: the module must be enabled (module_tenant_analytics = 1 in Manage Modules); your role must hold the tenant_analytics permission; and you must be an administrator on the platform's main database. Opening it from inside a tenant session (or as a non-admin) redirects you away.

The tab is there but shows no data

The fleet hasn't been swept yet. Populate it by waiting for the nightly cron, running it now with php erpat cron:run tenant_analytics_snapshot, running a manual sweep from the tab, or loading the demo data with php erpat db:seed TenantAnalyticsDemo. Also confirm the selected date is one that actually has data (use the Recent dates jump list).

The public API returns 404

By default the public API is off, and every endpoint returns 404 until an administrator enables tenant_analytics_public_api_enabled in Settings. Even when it's on, you'll also get 404 if there's no data for the requested date, or if you request an unknown metric group.

The API omits money and says "suppressed": true

That's small-n privacy suppression. When fewer tenants contributed to a group than tenant_analytics_min_aggregate_tenants, money fields are stripped so a single tenant's figures can't be inferred. It resolves once enough tenants are counted for that date, or if an administrator lowers the floor — but keep the floor sensible (3 is recommended in production).

The API says the date is out of the retention window

The public API only serves dates within [today − retention, today] and only in YYYY-MM-DD format (otherwise it returns a 422). Request a recent date, or raise tenant_analytics_retention_days if you legitimately need to look further back.

A tenant shows a "failed" status

The sweep couldn't connect to or measure that tenant's database — commonly a suspended database, a missing tenant database name, or a transient connection problem. Fix the cause, then use Re-sweep tenant on its row, or run a sweep and click Retry Failed. The application error log records the reason (lines tagged [tenant_analytics]).

A group shows "unavailable" for a tenant

That's expected, not an error: the tenant simply doesn't run that module or doesn't have the underlying table. Open the snapshot payload and check its meta.module_enabled map to confirm. It's how the module distinguishes “zero because there's nothing” from “zero because the feature is off”.

Coverage is below 100%

Some targeted tenants don't have a snapshot for the date — they failed, or a sweep was interrupted. Switch to the affected group, identify the missing tenants, resolve the cause, and re-sweep (a scoped manual sweep with Retry Failed, or a per-tenant re-sweep).

The aggregate looks wrong after I changed snapshots

Rebuild the platform rollups for that date with the Rebuild rollups button. A rebuild re-totals the snapshots you already have without re-measuring any tenant.

The nightly sweep didn't run

The job only runs if your server actually ticks the cron runtime and the module is enabled. Confirm it's registered with php erpat cron:list, run it manually with php erpat cron:run tenant_analytics_snapshot, and check the schedule in Settings → Setup → Cron Manager.

Can individual tenants see their own analytics here?

No. Tenant Analytics is a platform-operator tool with no tenant-facing surface and no employee self-service API. Tenants never see the module, and the public API only ever exposes the identifier-free platform aggregate — never a single tenant's numbers.

---

Glossary

Fleet

All the client tenants running on the platform, taken together.

Tenant

One client company, living in its own separate database (dash_<slug>).

Sweep

One pass over the fleet that measures each tenant and writes snapshots — nightly (cron) or manual (from the tab).

Snapshot

One tenant's measurement for one date and one metric group, stored as JSON in the main database.

Metric group

One of the seventeen measurement areas (overview, payslips, payrolls, employees, attendance, leaves, establishments, schedules, departments, de minimis, loans).

Rollup / aggregate

The platform-wide total for a date and group, with all tenant identifiers removed. The only data the public API can read.

Run

One sweep, recorded in the audit ledger with its counts, status, and timing.

Coverage

The share of targeted tenants that were successfully swept for a date.

Small-n suppression

Hiding money figures in the public aggregate when too few tenants contributed, so a single tenant can't be inferred.

Kill switch

The default-off tenant_analytics_public_api_enabled setting that turns the public API on or off.

Retention

How many days of snapshots are kept before the nightly sweep prunes them.

Meta block

The part of a snapshot payload recording which modules/tables were present, so a zero can be interpreted correctly.

Global-scope cron

A scheduled job that runs once on the main database and iterates the fleet itself — the only design that can reach inactive tenants.

---

Support & escalation

When troubleshooting, these are the places to look, in order:

1. The tab itself

   The KPI cards (coverage, failures, last run) and the per-tenant table's group-status column tell you at a glance what happened and to which tenant.

2. The system activity log

   Sweeps and settings changes are audited (run:tenant_analytics and update:tenant_analytics_settings), so you can see who ran what and when, with old and new setting values.

3. The run ledger & application error log

   The tenant_analytics_runs ledger records each sweep's outcome; the application error log captures per-tenant failure reasons (lines tagged [tenant_analytics]).

4. Escalate to the module owner

   For anything unresolved, contact the module owner, the ERPat Team. Include the date, the affected tenants, the group, and the status/error text you see.

Keep exploring