KPI Definitions
The formula editor allows creating and editing KPI definitions using FEL (Formula Engine Language) expressions. Each KPI definition includes a unique kpiId, display name, unit, formula expression, and optional alert thresholds.
FEL supports standard arithmetic, trigonometric functions, conditional expressions, and windowed aggregations (avg, sum, min, max over configurable time windows). Formulas reference node values using path syntax (e.g., /data/meter/U * /data/meter/I).
Definitions are managed via the kpiDefinition endpoint: list, getByKpiId, upsert, and deleteByKpiId. A seedMvp method bootstraps the standard KPI set for new objects.
KPI Constants
Per-object business parameters that feed into KPI formulas. These are numeric values that change infrequently (annually or per contract renewal) and are set by administrators:
| Item | Description |
|---|
| Grid CO2 Emission Factor | t CO2/MWh — carbon intensity of grid electricity |
| BESS Investment | UAH — total CAPEX for battery storage system |
| Annual BESS Value | UAH/year — yearly economic value from BESS operations |
| EMS Investment | UAH — total CAPEX for the Energy Management System |
| Annual EMS Savings | UAH/year — yearly cost savings from EMS optimization |
| Total Electricity Cost | UAH/year — annual electricity expenditure |
| Total COGS | UAH/year — Cost of Goods Sold (denominator for energy cost share) |
| Production Units | units — total output for energy intensity calculation |
| Total Uptime Hours | hours/year — equipment operational time (for MTBF) |
| Total Calendar Hours | hours/year — typically 8760 |
| Equipment Failures | events/year — unplanned failure count |
| Total Downtime Hours | hours/year — cumulative unplanned downtime |
| Incidents per Year | events/year — safety/operational incident count |
| Automated Actions | count — EMS-executed control actions |
| Total Actions | count — all control actions (auto + manual) |
EMS Policies
Automated reaction rules that trigger when monitored KPI scores cross configured thresholds. Each policy defines: a unique policyId, the target KPI or node path, condition expression, action to execute, and priority level.
Example policies: "If BESS SOC drops below 15%, switch to max_reserve mode", "If grid import exceeds 90% of contracted power, activate peak_shave strategy", "If PV forecast shows surplus, pre-charge BESS to 90% before peak hours".
Policies are managed via emsPolicy.list, emsPolicy.upsert, and emsPolicy.deleteByPolicyId endpoints.
Roles & Users
The platform uses role-based access control (RBAC) with four predefined roles:
| Item | Description |
|---|
| Admin |
Full access to all features, settings, user management, and device configuration |
| Operator |
Can view all dashboards, acknowledge alarms, and execute approved control commands |
| Viewer | Read-only access to dashboards, analytics, and reports |
| Director | Viewer permissions plus ability to approve/reject optimization plans |
Users are provisioned by administrators. Each user is assigned to one or more objects and inherits role permissions for those objects only.
Personalization
Users can customize their experience through the personalization settings:
- Theme — light or dark mode (dark is default for control room environments)
- Categories — show/hide sidebar navigation categories based on role needs
- Layout — compact or comfortable spacing for dashboard cards
- Dashboard Default — choose which dashboard loads after object selection
- Notification Preferences — email and push notification settings per alarm severity