Getting Started

Getting Started

Enable the module, create its tables, grant the right people access, and switch on the nightly auto-calculation — then confirm the sidebar group appears before you design your first scorecard.

Prerequisites — the data the engine reads

The KPI Matrix does not collect new operational data. It reads what other modules already capture and scores it. So the more of the source modules you actually use, the more of the 29 metrics compute automatically (the rest fall back to manual entry or are simply skipped). The engine reads:

Activation — four steps

1. Create the tables

   Run the module migrations from the project root. They are idempotent and reversible and are tracked in the module's own migrations_kpi_matrix table — nine KPI tables are created, no core tables are altered.

   php erpat migrate:modules
   # (or) php erpat migrate:latest

2. Turn the module on

   Go to Settings → Manage Modules and enable KPI Matrix (this sets module_kpi_matrix = 1). The module is category Performance and can be disabled again at any time.

3. Grant permissions

   In Settings → Roles, give the relevant roles the KPI Matrix permissions (they appear under the Staffing: KPI Matrix group only while the module is on):

   • kpi_matrix — Access. A member-scope dropdown (Disable / All / Specific). Lets a manager see other people's KPIs within their scope. Every employee can already see their own KPIs without it.
   • kpi_matrix_manage — Manage. A simple on/off. Unlocks the whole manager workspace and every create/edit/delete/calculate/approve action.

   See the full matrix on Permissions & Roles.

4. Verify the routes and the menu

   Confirm the module's controllers resolved through the HMVC layer, then check the sidebar.

   php erpat route:list   # look for kpi_matrix, kpi_cycles, kpi_templates, kpi_salary

   A user with kpi_matrix_manage should now see a KPI Matrix group in the left sidebar.

   ⚠️

   After enabling or upgrading, the group only appears in the saved left menu once you run Settings → Left Menu → Restore to default (the customization editor keeps a stored copy of the menu that must be refreshed).

Switch on nightly auto-calculation (recommended)

You can always calculate a cycle by hand (the Calculate button — see Review Cycles), but the module ships a nightly cron job so scores compute themselves as soon as a period ends.

php erpat cron:list                        # confirm the job is registered
php erpat cron:run auto_calculate_kpi_cycles   # run it once, now
php erpat cron:dry-run auto_calculate_kpi_cycles

Your first cycle — the shortest path

Once the module is on and you hold kpi_matrix_manage, the fastest way to see real scores:

1. Create a Template

   KPI Matrix → Templates → Add Template. Tick the metrics you want, set category weights to total 100%, Save. Full detail on KPI Templates.

2. Open a Review Cycle

   KPI Matrix → Review Cycles → Add Review Cycle. Pick the template, a cadence (monthly/quarterly/…), and the start/end dates. See Review Cycles.

3. Assign employees

   KPI Matrix → Team Matrix → Assign Employees. Choose the cycle, the template, and the people (optionally a reviewer). See Assignments.

4. Enter any manual metrics

   If your template uses manual metrics (e.g. Ticket Satisfaction), open an assignment and add those values. Optional. See Manual Entries.

5. Calculate

   On the cycle (while it is Open) click Calculate, or wait for the nightly job. Scores, ratings and salary recommendations appear.

6. Review the results

   Read the Overview dashboard and Team Matrix, drill into anyone's detail, then approve/reject on Recommendations.

Next steps