> For the complete documentation index, see [llms.txt](https://help.resouris.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.resouris.com/job-planning/kpi-dashboard.md).

# Job-planning KPI dashboard

## What it is

A pre-built dashboard bundling all **15 Guidelines §6.12 monitoring KPIs** in one place. Automatically provisioned on every new tenant install (v1.7.4+); existing tenants get it via a one-shot backfill script (`scripts/provision-hcs-kpi-preset-dashboard.py`).

## Where to find it

**Platform features → Dashboards** — the preset appears as **"HCS Job Planning KPIs"** in the tenant-scope dashboards list.

Access is gated on `admin.job_plan_monitoring.read` — default-granted to `tenant_admin` and `rostering_manager`.

## The 15 KPIs, on 16 widgets

### Staffing + review currency

1. **Team plan coverage** — % services with a current team job plan.
2. **Staff plan review current** — % HCS staff with plan agreed + reviewed within 12mo.
3. **Plan objective alignment** — % active plans with recorded objectives (`job_plan.objectives_jsonb`, MIG-206).

### SPA + activity distribution

4. **SPA allocation core** — % HCS staff meeting Guidelines §5.1 Table 2 SPA minimum.
5. **Category distribution** — DCC / SPA / ANR / ED PA totals by activity category.
6. **Additional activity** — activity recorded outside a Job Plan entitlement (last 90 days).

### Workforce

7. **Vacancy / absence / turnover** — three percentages: vacancy from `staff.state`, absence from `staff_extended_leave` EXISTS, turnover from archived staff in last 12mo.
8. **Accreditation readiness** — % staff with current accreditations + count expiring in next 90 days.
9. **Competency + supervision** — % staff whose held competencies cover the required set.

### Statutory + delivery

10. **Statutory / safety roles** — job plans with vs without allocated time in statutory/safety categories.
11. **Planned vs delivered** — variance buckets (green ≤5%, amber 5-15%, red >15%) from the latest quarter's reconciliation snapshots (MIG-204).
12. **Turnaround / reporting** — median + P90 elapsed hours from ordered → reported (last 30 days).

### Capacity + demand

13. **Capacity utilisation** — assigned PAs / planned PAs × 100% (last 30 days).
14. **Demand vs capacity gap** — staffed PAs − demand PAs (positive = surplus).
15. **Job plans overdue for review** — count of overdue + due-within-30-days (reads MIG-195 `job_plan_review_schedule` view).

## Under the hood

* Widgets ship as first-party plugin adapters (`adapters/widgets_hcs_job_planning/widgets.py`).
* Dataset producers live in `application/job_plan_monitoring/kpi_{1_5, 6_10, 11_15}.py` — the DA layer is the single source of truth for KPI shape. Widget classes never contain SQL (F6 lock).
* The preset bundle definition lives at `PRESET_DASHBOARD_BUNDLE` in `kpi_11_15.py` — updating widget list order or layout there flows through to every install.
* KPI 1-5 datasets are also exposed as `hcs_kpi_*` DB views (MIG-206) with `security_invoker=true` so per-tenant RLS on underlying tables applies.
* KPI SQL fingerprints are locked at `tests/ui/kpi_snapshots/kpi_N.sql.snap` — any drift blocks CI.

## Backfilling existing tenants

Once per deployment:

```bash
DATABASE_URL='postgres://...' .venv/Scripts/python.exe scripts/provision-hcs-kpi-preset-dashboard.py
```

Idempotent. Prints a summary of tenants that received the preset.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.resouris.com/job-planning/kpi-dashboard.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.