02 — KPI Categories & Metrics Definition

Document: KPI Categories, Individual Metrics, Scoring Scales, Weights & Aggregation Module: KPI Matrix (Employee Performance Management) Target System: ERPat ERP (CodeIgniter 3 / PHP 8.2+) Status: Implemented — documentation reconciled to code Last Revised: June 2026 (aligned to modules/KpiMatrix/config/kpi_templates.php + modules/KpiMatrix/libraries/Kpi_calculation_engine.php)

Table of Contents

1. Overview & KPI Design Philosophy
2. How to Read a Metric Definition
3. Scoring Scale Standard
4. Normalization (As Implemented)
5. Category 1 — Attendance & Punctuality (ATT)
6. Category 2 — Task Performance (TSK)
7. Category 3 — Project Delivery (PRJ)
8. Category 4 — Support & Service Quality (TKT)
9. Category 5 — Behavioral Compliance (BHV)
10. Category 6 — Leave Management (LVE)
11. Category 7 — Professional Development (PRF)
12. Category 8 — Time Management (TMS)
13. Weight Distribution Templates
14. Composite Score Calculation
15. Rating Bands & Salary Mapping
16. Data Sufficiency & Edge Cases
17. Appendix A — Master Metric Register (29 Metrics)
18. Appendix B — Best-Practice Enhancements (Future)
19. Appendix C — Implementation Fidelity Notes

1. Overview & KPI Design Philosophy

The KPI Matrix organizes employee performance into 8 categories containing 29 metrics in total. Every metric is computed automatically from data ERPat already captures, normalized to a common 1.00–5.00 scale, weighted, and rolled up into a single composite score that drives review ratings and salary-progression recommendations.

This document is the single source of truth for metric semantics. The runtime definitions live in modules/KpiMatrix/config/kpi_templates.php (categories, metric metadata, thresholds, templates) and the formulas live in modules/KpiMatrix/libraries/Kpi_calculation_engine.php. When this document and code disagree, code wins and this document must be updated — see Appendix C for the known reconciliation list.

1.1 Design Principles

These principles are derived from current performance-management best practice (balanced scorecard, SMART KPIs, and the leading/lagging-indicator framework) and adapted to data ERPat actually holds:

1. Data-driven first. 25 of 29 metrics compute with zero manual grading. The remaining 4 are manual/semi-manual because the underlying signal (subjective quality, customer satisfaction, off-system training) does not yet exist as structured data — see Appendix B.
2. Balanced dimensions. Each category mixes the four performance dimensions so no single behavior dominates:
   • Quantity — how much was produced (task throughput, tickets resolved).
   • Quality — how good the output was (task quality, ticket satisfaction).
   • Efficiency — output relative to time/resource (resolution time, productive-hours ratio).
   • Reliability / Compliance — consistency and rule-adherence (attendance, schedule adherence, discipline).
3. Leading + lagging balance. Lagging indicators confirm results that already happened (attendance rate, task completion); leading indicators predict future performance (certifications, training, leave/overtime health as burnout signals). Both are tagged per metric so reviewers can act on leading signals before lagging ones deteriorate.
4. Bi-directional & normalized. Some metrics reward higher values (direction: higher); some penalize them (direction: lower). All are normalized onto the same 1.00–5.00 band so they can be compared and averaged fairly across units.
5. Configurable, not hard-coded. Category weights, metric weights, and scoring thresholds are stored per template and per template-metric (override_thresholds), so the same engine serves a developer, a call-center agent, and a production worker with different emphases.
6. Auditable. Every computed score persists its raw_value, the normalized score, and a JSON computation_log (inputs + formula + timestamp) in kpi_metric_scores, so any rating is fully reconstructable.

1.2 Avoiding Common KPI Pitfalls

2. How to Read a Metric Definition

Each metric below is documented with a consistent header block:

3. Scoring Scale Standard

All metrics normalize to a 1.00–5.00 continuous scale, stored as DECIMAL(4,2):

These bands are defined once in $config['kpi_rating_bands'] and consumed by both the engine (_get_rating_band()) and the UI badges. The 1–5 scale (not 0–100) is the canonical internal scale; raw values are only ever shown alongside the normalized score for transparency.

4. Normalization (As Implemented)

The engine method _normalize_score($raw_value, $thresholds, $direction) — which delegates to the pure Modules\KpiMatrix\Services\ScoreNormalizer (library) — converts a raw value to a 1.00–5.00 score using within-band linear interpolation, not a single global linear map. This is the authoritative algorithm:

1. Direction handling. Bands are matched directly against the authored threshold ranges — they are never relabelled or swapped. For direction = 'lower' metrics, only the within-band interpolation is reversed (step 3): a low raw value earns the high end of its band's score window. (The config authors every band quality-first, so a lower metric's best/lowest raw values already sit in the outstanding band.)

2. Band lookup. The raw value is matched against the five threshold bands. Each band maps to a score sub-range:

   Band	Score sub-range
   outstanding	4.50 – 5.00
   exceeds	3.50 – 4.49
   meets	2.50 – 3.49
   needs_improvement	1.50 – 2.49
   unsatisfactory	1.00 – 1.49

3. Interpolation within the band. Position inside the band's raw range determines the exact score. For higher metrics position runs from the band's min upward; for lower metrics it is reversed (the only place direction changes the result):

   position = (raw_value − band_min) / (band_max − band_min)          // direction = 'higher'
   position = (band_max − raw_value) / (band_max − band_min)          // direction = 'lower'
   score    = band_base + position × (band_ceiling − band_base)
   score    = CLAMP(score, 1.00, 5.00)

4. Out-of-range → clamp to global range. Before matching, the raw value is clamped into the authored global [min, max] range (the union of all defined bands). An out-of-range value therefore scores as the extreme band that owns that end of the scale — e.g. overtime_ratio at 200% (above the top authored value) lands in its worst band, not 5.00. There is no "above outstanding.max → 5.00" shortcut.

5. Null. A null raw value (insufficient data / division-by-zero) returns null and is excluded from the category aggregate (weight redistributed — see §14).

4.1 Bell-Curve (Target-Band) Metrics

Three metrics are healthiest at a moderate value, not a maximum: overtime_ratio, leave_utilization, and leave_balance. These are encoded with direction: higher but with non-monotonic thresholds so the outstanding band sits in the middle of the value range. Example — overtime_ratio:

Note: This "fold the bands" technique works with the current matcher but is fragile (the band labels no longer correspond to monotonic quality). A first-class direction: 'target' mode with an explicit ideal range is listed in Appendix B as the recommended hardening.

5. Category 1 — Attendance & Punctuality (ATT)

Code: ATT · Default weight (General Staff): 20% · Dimension focus: Reliability + Wellbeing Sources: attendance, attendance_metrics, Payslips_model, holidays

Attendance is the foundation of reliability. Note that _get_working_days() excludes weekends (Sat/Sun) and rows from the holidays table, so rates are measured against true scheduled working days, not raw calendar days.

5.1 att_rate — Attendance Rate

5.2 punctuality_rate — Punctuality Rate

5.3 absence_rate — Absence Rate

5.4 overtime_ratio — Overtime Utilization (bell-curve)

5.5 undertime_rate — Undertime Rate

6. Category 2 — Task Performance (TSK)

Code: TSK · Default weight (General Staff): 20% · Dimension focus: Quantity + Quality + Reliability Sources: tasks, activity_logs, kpi_manual_entries

Task assignment uses FIND_IN_SET(user_id, tasks.assigned_to) (comma-separated assignees) and status_id = 3 for completed. Balances volume (task_throughput) against quality (task_quality) and reliability (task_ontime).

6.1 task_completion — Task Completion Rate

6.2 task_ontime — On-Time Task Delivery

⚠️ Returns null (data limitation, C-10): tasks records no completion timestamp, so on-time delivery cannot be computed. Excluded from the composite until a completed_at exists. See Appendix C.

6.3 task_quality — Task Quality Score (semi-automated)

6.4 task_throughput — Task Throughput

7. Category 3 — Project Delivery (PRJ)

Code: PRJ · Default weight (General Staff): 10% · Dimension focus: Outcome + Reliability Sources: projects, project_members, tasks

Measures contribution to team delivery, distinct from individual tasks. Project membership resolves via project_members.user_id.

7.1 proj_completion — Project Completion Rate

7.2 proj_ontime — Project On-Time Delivery

⚠️ Returns null (data limitation, C-10): projects records no completion-date column, so on-time project delivery cannot be computed. Excluded from the composite. See Appendix C.

7.3 proj_contribution — Project Points Contribution

8. Category 4 — Support & Service Quality (TKT)

Code: TKT · Default weight (General Staff): 10% · Dimension focus: Efficiency + Quality Sources: tickets, ticket_comments, kpi_manual_entries

Tickets assigned via tickets.assigned_to = user_id; resolved = status = 'closed'.

8.1 ticket_resolved — Ticket Resolution Rate

✅ Resolved (C-1, Jun 2026): the engine previously emitted a raw count scored against % thresholds; it now computes a true resolution rate. See Appendix C.

8.2 ticket_response — Average Response Time

8.3 ticket_resolution — Average Resolution Time

8.4 ticket_satisfaction — Ticket Satisfaction (manual)

9. Category 5 — Behavioral Compliance (BHV)

Code: BHV · Default weight (General Staff): 10% · Dimension focus: Compliance Sources: discipline_entries, leave_applications

This is an inverse category — fewer infractions = higher score. Discipline entries map to a user via FIND_IN_SET(user_id, discipline_entries.employee_ids).

9.1 discipline_score — Disciplinary Score

9.2 leave_compliance — Leave Compliance

9.3 policy_adherence — Policy Adherence Score (derived)

Note: policy_adherence is a composite of two other BHV metrics. If all three are enabled in a template, discipline is effectively double-counted; consider disabling policy_adherence where discipline_score + leave_compliance already carry the category (see C-4).

10. Category 6 — Leave Management (LVE)

Code: LVE · Default weight (General Staff): 5% · Dimension focus: Wellbeing + Reliability Sources: leave_credits, leave_applications

Rewards healthy leave behavior — taking enough rest without exhausting entitlements or filing emergencies. Two of three metrics are bell-curve.

10.1 leave_utilization — Leave Credit Utilization (bell-curve)

10.2 unplanned_leave — Unplanned Leave Rate

10.3 leave_balance — Leave Balance Health (bell-curve)

11. Category 7 — Professional Development (PRF)

Code: PRF · Default weight (General Staff): 10% · Dimension focus: Development (all leading indicators) Sources: Certifications_model, kpi_manual_entries

Development metrics are leading indicators — investment now predicts capability later.

11.1 cert_count — Active Certifications

11.2 skill_growth — Skill Coverage Ratio (manual)

✅ Resolved (C-2, Jun 2026): config previously declared this automated while the engine used manual entry; config is now automated=false to match. Full automation (role→skillset coverage) is tracked as B-4.

11.3 training_hours — Training Hours (manual)

11.4 training_completion — Training Completion Rate (manual)

12. Category 8 — Time Management (TMS)

Code: TMS · Default weight (General Staff): 15% · Dimension focus: Efficiency + Reliability Sources: Timesheets_model, project_time, attendance, attendance_metrics

12.1 timesheet_util — Timesheet Compliance Rate

12.2 timesheet_accuracy — Productive Hours Ratio

12.3 schedule_adherence — Schedule Adherence

13. Weight Distribution Templates

Five role-based templates ship as defaults in $config['kpi_template_weights']. Each distributes the 8 category weights to total 100%. Within a category, metric weights (kpi_template_metrics.weight) determine the blend.

Template Rules

1. All 8 categories carry a weight; 0 disables a category for that role.
2. Category weights must sum to exactly 100% (validated on save).
3. Within a category, metric weights are blended via a weighted average over non-null metrics (see §14) — they need not pre-sum to 100; the engine normalizes by the sum of present weights.
4. Disabled or null-valued metrics redistribute their weight to the remaining metrics in the category automatically.
5. Thresholds may be overridden per template-metric via override_thresholds (JSON) — used to role-calibrate volume metrics like task_throughput.

14. Composite Score Calculation

The engine (compute_composite()) computes a two-level weighted average, skipping null metrics at both levels.

14.1 Category Score

category_score = Σ(metric_score × metric_weight) / Σ(metric_weight)   ── over non-null metrics only

If every metric in a category is null, the category is omitted entirely and its weight is redistributed.

14.2 Composite Score

composite_score = Σ(category_score × category_weight) / Σ(category_weight)   ── over present categories
rating_band     = band(composite_score)

Worked example (General Staff):

category_scores:  ATT=4.08(20)  TSK=3.75(20)  PRJ=3.50(10)  TKT=4.20(10)
                  BHV=5.00(10)  LVE=3.60(5)   PRF=3.00(10)  TMS=3.80(15)
composite = (4.08·20 + 3.75·20 + 3.50·10 + 4.20·10 + 5.00·10 + 3.60·5 + 3.00·10 + 3.80·15) / 100
          = 388.6 / 100 = 3.89  →  exceeds_expectations

14.3 Persistence

compute_composite() returns composite_score, rating_band, category_scores (JSON), metrics_computed, metrics_total, and data_sufficiency_pct. These are saved to kpi_composite_results and snapshotted into kpi_score_history for trend analysis.

15. Rating Bands & Salary Mapping

The composite rating maps to a salary-step recommendation via $config['kpi_default_step_mapping']. Recommendations are advisory and require approval — see 04_SALARY_INTEGRATION.md.

Step changes are capped by the kpi_salary_max_step_increase setting (default 2). Consecutive-rating detection is provided by Kpi_score_history_model::get_consecutive_rating().

16. Data Sufficiency & Edge Cases

16.1 Data Sufficiency

_check_data_sufficiency() computes coverage = (metrics_total − metrics_null) / metrics_total × 100. Coverage ≥ 60% marks the result data_sufficient = true; below that, the composite is still produced but flagged as low-confidence (surface this in the UI and exclude from rankings).

16.2 Division by Zero / Insufficient Data

Each calculator returns raw_value = null when its denominator is zero (no scheduled days, no tasks, no tickets, no credits). Null metrics are excluded from aggregation and weight is redistributed — they never score 1.00 by default.

16.3 Probationary / New Employees

Employees with < 60% data coverage (typically < ~2 months tenure in the period) should be flagged "Insufficient Data" in the UI and excluded from forced ranking. First-cycle reviews may apply relaxed thresholds via override_thresholds.

16.4 Extended Leave

An employee on leave for the majority of the period will legitimately show null/low operational metrics. Flag "Extended Leave," keep the available metrics for partial assessment, and allow a reviewer override note on the assignment (reviewer_notes, final_override_score).

16.5 Inverse & Bell Metrics

• Inverse (lower): thresholds inverted at normalization (§4).
• Bell (overtime_ratio, leave_utilization, leave_balance): healthiest in the middle band (§4.1).

Appendix A — Master Metric Register (29 Metrics)

Legend: ✅ Automated · ◐ Semi-automated (auto + manual fallback) · ✋ Manual entry · Lag = lagging indicator · Lead = leading indicator. Coverage: 24 fully automated · 1 semi-automated (task_quality) · 4 manual (ticket_satisfaction, skill_growth, training_hours, training_completion) = 29.

Appendix B — Best-Practice Enhancements (Future)

These are recommendations, not implemented behavior. They raise the matrix toward best-in-class without changing the current scoring contract. Each can be added as a new metric or a new engine mode behind config.

Appendix C — Implementation Fidelity Notes

Reconciliation items where code and config currently disagree, or where the implementation is incomplete. These are the authoritative to-do list for the next implementation pass; do not "fix" the docs to hide them.

C-9 detail — column corrections (verified against dash_ahm)

Data Limitations (source data gaps)

These are not bugs — the operational tables simply don't capture the needed signal yet:

1. No completion timestamp on tasks/projects. task_ontime and proj_ontime return null until a completed_at (tasks) / completion date (projects) is recorded. Recommended: add a completed_at column set when status_id→3 / status→completed, or log a completed action to activity_logs. This would also let task_throughput/task_quality/proj_contribution anchor on completion date instead of created_date.
2. task_quality rework detection. It looks for activity_logs rows with log_for='task', action='reopened', but task events aren't currently written to activity_logs, so rework is always 0 (quality ≈ 100% for anyone with completed tasks). Treat as a manual-leaning metric until task status changes are logged.
3. discipline_score has no severity input. Scored purely by incident count (each formal action drops one band). If severity is later added to discipline_entries, restore severity-weighting.

Security hardening (Jun 2026)

A controller/model security audit found and fixed:

Deployment note (D-1) — stale KPI tables in dev DB

The current migration (20260604185300_create_kpi_matrix_tables.php) is the schema source of truth, but each _create_* method short-circuits if the table already exists (SHOW TABLES LIKE … return;). In dash_ahm, only 6 of 9 KPI tables exist and they are from an older schema (e.g. kpi_employee_assignments.user_id/assignment_status, kpi_metric_scores.metric_code, kpi_composite_results.rating_label/data_completeness_pct) — incompatible with the current models/engine (which use employee_id/status, metric_key, rating_band/data_sufficiency_pct). The module cannot run against dash_ahm until the KPI tables are reconciled. Options: (a) drop the 6 stale kpi_* tables and re-run the migration (recreates all 9 with the correct schema; safe only if there is no real KPI data — destructive, requires explicit sign-off), or (b) write an ALTER migration to rename/add the drifted columns. The 3 missing tables (kpi_manual_entries, kpi_score_history, kpi_salary_recommendations) would be created by simply re-running the migration.