Balance scorecard metrics

Configuration is versioned per BSC fiscal cycle. Document id: balance-score-card-metrics-{cycle_id} (e.g. balance-score-card-metrics-2026).

API: balance_score_card_metrics on GET / PATCH /v1/scorecard/configurations?cycle_id=….

Which cycle’s metrics apply to a calendar month matches the fiscal cycle from resolve_cycle_id in bsc_cycle.py. See Fiscal cycles & locks.

Structure

• KPM: top-level category, weight_percent (sum 100).
• KPI: under a KPM, breakdown_percent (sum 100 within KPM).
• Effective weight: kpm.weight_percent × kpi.breakdown_percent / 100
• Total BSC: Σ (effective weight × kpi_score / 100), then round up to 2 decimals (round_bsc_up).

Working days

Per-employee schedules are stored in tbl_employee_schedules (see Employee schedules). Each month document has a cached working_days count: days assigned a day code with is_working_day: true.

Resolution (api/app/services/employee_schedules.py):

resolve_working_days_for_employee(employee_id, year, month)
  → schedule.working_days if a saved schedule exists
  → else weekdays_in_calendar_month(year, month)   # Mon–Fri count fallback

API: GET /v1/scorecard/employee-schedules/working-days/{employee_id}?year=&month=

BSC KPI calculation: bsc_employee_compute.py calls resolve_working_days_for_employee() per employee-month before attendance KPIs. See User-month calculation.

Attendance KPI score:

(working_days − violation_count) / working_days × 100

• Tardiness KPI: tbl_attendance_issues where type_of_violation = "Tardiness".
• Absenteeism KPI: type_of_violation = "Absenteeism".

Compliance

mean(SBS sbs_percentage_score as 0–100) − (productivity_issue_count × 1%)

Each productivity issue in the period subtracts 1 percentage point (floor at 0).

Attitude towards work (ATW)

Three impacts: Team, Other Departments, Company (one KPI each in config).

Per employee, per period, per impact:

1. Points earned = sum of final_score from ATW entries for that impact.
2. Target = 100 points per impact.
3. KPI score (0–100) = min(100, points_earned) — progress toward the 100-point goal.
4. Config breakdown % on each impact KPI is the weight within the Attitude KPM (e.g. Team 40%, Other Departments 20%, Company 40%).

Productivity KPIs

All driven by SBS entries, Non-SBS entries, productivity issues, and (when configured) task delivery.

BSC 2025 metrics (legacy quantity)

KPI key	Source
quantity_of_output	Combined SBS + Non-SBS quantity_score (+ eval ratio when applicable)
integrity	Non-SBS quantity_score (+ eval ratio)
accuracy	auditors_score (SBS + Non-SBS)
compliance	SBS checklist score − 1% × productivity issues

BSC 2026+ metrics (revised productivity formulas)

Same four KPI keys and weights. See Fiscal cycles & locks §3 for formulas.

KPI key	BSC 2026+ compute
quantity_of_output	Task delivery (source task_delivery)
integrity	SBS + Non-SBS quantity_score
accuracy	SBS + Non-SBS checklist score
compliance	100% − 1% × productivity issues

Code

• api/app/services/balance_score_card_calculation.py
• api/app/schemas/balance_score_card_kpi_source.py
• UI: web/src/pages/scorecard/configurations/ (tab: Balance Scorecard Metrics)