Module: Asset Performance Management v1.0.0
What is Asset Performance Management?
Asset registry, KPI tracking, OEE monitoring, and performance alerts for Perfex CRM
This module installs into modules/asset_performance_management/ and adds its own admin menus, permissions, and database tables — without editing Perfex CRM core files.
Who should use this module?
- Admins — activate the module, configure Settings, assign roles, and manage integrations.
- Operators / day-to-day staff — create and update records (orders, attendance, shipments, messages, etc.).
- Managers / approvers — review queues, approve workflows, and monitor dashboards/KPIs.
- Finance / compliance / ops leads — run reports, exports, and audit trails when the module supports them.
What you can achieve
- Keep all related work in one place inside Perfex CRM instead of spreadsheets.
- Control who can view, create, edit, approve, or export with role permissions.
- Use dashboards and reports to see status, bottlenecks, and history.
- Connect to other CRM data (customers, invoices, items, staff) where the module integrates.
Recommended learning path
- Read How to Install and activate the module.
- Skim Features so you know what screens exist.
- Complete the Quick Start checklist on this page (Settings → masters → first sample record).
- Open each screen guide under Screen-by-screen guides when you need step-by-step help.
- Check Version & Changelog after upgrades for new options.
Tip: Train one admin first, then create a limited role for operators so they only see the screens they need.
5-minute Quick Start
Follow this short path the first time you use Asset Performance Management:
- Activate — Setup → Modules → activate Asset Performance Management (run Upgrade if prompted).
- Permissions — Setup → Staff → Roles → enable view/create/edit (and approve/settings if needed) for this module.
- Settings — Open Asset Performance Management → Settings and save company defaults, prefixes, and integrations.
- Master data — Create the first required masters (products, warehouses, templates, channels, accounts, routes, etc.).
- First transaction — Create one sample record end-to-end (save → submit/approve → complete) and confirm it appears in lists/reports.
- Cron — If the module uses alerts, sync, queues, or AI, confirm Perfex CRM cron is scheduled on the server.
Module documentation index
Start here — full guides for Asset Performance Management:
- Overview & How to Use — what it is, who uses it, daily workflow
- Quick Start Guide — first 5 minutes + printable how-to
- How to Install — upload, activate, permissions, verify
- Features (Full Detail) — every capability explained
- FAQ & Tips — common questions and best practices
- Version & Changelog — version history
Screen-by-screen guides (each tab explained)
Click a menu item below for step-by-step instructions on that Asset Performance Management screen:
- APM Dashboard
- Asset Categories
- Assets
- KPI Definitions
- KPI Readings
- Downtime Events
- OEE Calculator
- Maintenance Schedules
- Work Orders
- Maintenance Calendar
- Performance Alerts
- Analytics & Reports
- Integration
- Import KPI Readings
- Settings
How to use in Perfex CRM (daily operations)
- Sign in to the admin area with a role that includes Asset Performance Management permissions.
- Open Asset Performance Management (sidebar) or search for Asset Performance Management in the admin menu.
- Start on the Dashboard (if available) to see open tasks, pending approvals, and KPIs.
- Review Settings after upgrades — new options may need defaults for your company.
- Create or import master data first; most modules block transactions until masters exist.
- Run the main business flow (create → submit → approve → post/complete) using the screens listed in Admin menu below.
- Use Reports / Analytics screens to reconcile stock, finance, compliance, or SLA metrics.
- For integrations (API, EDI, gateways, tax), confirm credentials in Settings and monitor logs or webhook delivery screens.
- Train staff with role-based access — give approvers approve permissions only, operators create/edit on their area.
- If something fails overnight, check Perfex CRM cron ran and open the module log / failed queue screen if present.
Admin menu — where to work
Open the Asset Performance Management section in the admin sidebar. Screens your staff may use (depending on role):
- Analytics & Reports
- API Keys
- APM Dashboard
- Asset Categories
- Asset Performance
- Assets
- Downtime Events
- Import KPI Readings
- Integration
- KPI Definitions
- KPI Readings
- Maintenance Calendar
- Maintenance Schedules
- OEE Calculator
- Performance Alerts
- Settings
- Webhooks
- Work Orders
Screens map — what each menu is for
These are the admin screens registered by Asset Performance Management. Click a name in the Knowledge Base for a full how-to, or open the path in admin.
| # | Screen | Admin path | Guide |
|---|---|---|---|
| 1 | APM Dashboard | admin/asset_performance_management | How to use |
| 2 | Asset Categories | admin/asset_performance_management/asset_performance_management_categories | How to use |
| 3 | Assets | admin/asset_performance_management/asset_performance_management_assets | How to use |
| 4 | KPI Definitions | admin/asset_performance_management/asset_performance_management_kpi_definitions | How to use |
| 5 | KPI Readings | admin/asset_performance_management/asset_performance_management_kpi_readings | How to use |
| 6 | Downtime Events | admin/asset_performance_management/asset_performance_management_downtime_events | How to use |
| 7 | OEE Calculator | admin/asset_performance_management/asset_performance_management_oee | How to use |
| 8 | Maintenance Schedules | admin/asset_performance_management/asset_performance_management_maintenance_schedules | How to use |
| 9 | Work Orders | admin/asset_performance_management/asset_performance_management_work_orders | How to use |
| 10 | Maintenance Calendar | admin/asset_performance_management/asset_performance_management_maintenance_calendar | How to use |
| 11 | Performance Alerts | admin/asset_performance_management/asset_performance_management_alerts | How to use |
| 12 | Analytics & Reports | admin/asset_performance_management/asset_performance_management_analytics | How to use |
| 13 | Integration | admin/asset_performance_management/asset_performance_management_integration | How to use |
| 14 | Import KPI Readings | admin/asset_performance_management/asset_performance_management_import | How to use |
| 15 | Settings | admin/asset_performance_management/asset_performance_management_settings | How to use |
Detailed guide — features, workflows, API & FAQ
Features
Phase 1 ✅
| Feature | Description |
|---|---|
| --------- | ------------- |
| Asset Categories | Master data for grouping assets |
| Asset Registry | Full asset lifecycle with criticality, location, status |
| KPI Definitions | Pre-seeded OEE, Availability, Performance, Quality, MTBF, MTTR |
| KPI Readings | Manual/sensor/import readings with breach detection |
| Performance Alerts | Auto-generated alerts on threshold breaches |
| Dashboard | KPI cards, charts, recent alerts |
Phase 2 ✅
| Feature | Description |
|---|---|
| --------- | ------------- |
| Downtime Events | Track planned/unplanned downtime with reason codes |
| OEE Calculator | Calculate Availability × Performance × Quality |
| MTBF/MTTR | Auto-compute reliability metrics from failures |
| Manufacturing Sync | Hook into Manufacturing downtime & IoT readings |
| Asset Links | Link assets to Manufacturing workstations |
| Auto KPI Storage | Store calculated OEE metrics as KPI readings |
Phase 3 ✅
| Feature | Description |
|---|---|
| --------- | ------------- |
| Maintenance Schedules | Time/meter-based PM with due dates and priorities |
| Work Orders | Full lifecycle: draft → scheduled → in progress → completed |
| Spare Parts | Link Perfex CRM items to work orders |
| Maintenance Calendar | Monthly view of PM and work orders |
| PM Alerts | Auto-alert on overdue or due-soon maintenance |
| Cron Integration | Daily PM alert check |
Phase 4 ✅
| Feature | Description |
|---|---|
| --------- | ------------- |
| Analytics Overview | KPI summary, OEE trend chart, top performing assets |
| OEE Trends | 30/60/90-day presets with per-asset line charts |
| Asset Scorecard | Rank assets by composite performance score |
| KPI Comparison | Benchmark readings against targets with variance |
| PDF/CSV Export | Export all analytics reports |
| Multi-Plant Filter | Filter by MPM plants or plant/site field |
Phase 5 ✅
| Feature | Description |
|---|---|
| --------- | ------------- |
| REST API | Read/write assets, KPI readings, alerts, downtime events |
| API Keys | Scoped keys with rate limiting |
| Webhooks | kpi.breach, alert.created, asset.status_changed events |
| IoT Gateway | CSRF-excluded sensor ingestion endpoint |
| CSV Import | Bulk KPI readings upload |
| Cold Chain Link | Shared equipment via asset links |
| MPM Integration | Plant picker syncs to plant_site |
---
Database Tables
| Table | Purpose |
|---|---|
| ------- | --------- |
apm_asset_categories | Asset type master |
apm_assets | Asset registry |
apm_kpi_definitions | KPI templates with thresholds |
apm_kpi_readings | Time-series performance data |
apm_alerts | Performance alerts |
apm_downtime_events | Downtime tracking |
apm_downtime_reason_codes | Downtime reason master |
apm_asset_links | External entity links (workstations) |
apm_activity_logs | Audit trail |
apm_maintenance_schedules | Preventive maintenance schedules |
apm_work_orders | Maintenance work orders |
apm_work_order_parts | Spare parts on work orders |
apm_report_snapshots | Saved analytics snapshots |
apm_api_keys | REST API keys |
apm_webhooks / apm_webhook_deliveries | Outbound webhooks |
apm_integration_logs | Integration event log |
apm_import_batches | KPI CSV import batches |
---
Permissions
| Feature ID | Capabilities |
|---|---|
| ------------ | ------------- |
apm_dashboard | view |
apm_asset_categories | view, create, edit, delete |
apm_assets | view, create, edit, delete |
apm_kpi_definitions | view, create, edit, delete |
apm_kpi_readings | view, create, edit, delete |
apm_downtime_events | view, create, edit, delete, end |
apm_oee | view, calculate |
apm_maintenance_schedules | view, create, edit, delete |
apm_work_orders | view, create, edit, delete, complete |
apm_alerts | view, create, edit, delete, resolve |
apm_analytics | view |
apm_integration | view |
apm_api | view, create, delete |
apm_webhooks | view, create, edit, delete |
apm_settings | view, edit |
---
Design Principles
- Zero core changes — All behaviour via
modules/asset_performance_management/+ hooks - Incremental phases — Future features via DB migrations (v101, v102…)
- Optional integrations — Works standalone; enhanced via hooks to Manufacturing, MES, Cold Chain
- Auto-upgrade —
apm_maybe_upgrade_database()runs on admin_init
See [docs/ROADMAP.md](docs/ROADMAP.md) for the full phase plan.
---
How to Use
First setup
- Review Asset Categories (defaults are seeded).
- Create Assets with type, criticality, location/plant, and status.
- Review KPI Definitions — set targets and min/max thresholds.
- Enable auto alerts in Settings.
Daily workflow
- Log KPI Readings (manual, CSV import, API, or IoT gateway).
- Record Downtime Events; use the OEE Calculator when needed.
- Plan Maintenance Schedules and create Work Orders (attach spare parts from Perfex items).
- Monitor Alerts and review Analytics (export PDF/CSV).
- Use Maintenance Calendar for the monthly PM view.
Optional integrations
- Manufacturing / Cold Chain asset links
- REST API keys + webhooks
- IoT sensor ingestion endpoint
Features
- Asset Registry — categories, criticality, location, lifecycle status
- KPI Definitions & Readings — OEE, Availability, Performance, Quality, MTBF, MTTR + custom
- Performance Alerts — threshold breaches and overdue PM
- Downtime Events — reason codes, duration, planned/unplanned
- OEE Calculator — Availability × Performance × Quality
- Maintenance Schedules & Work Orders — PM lifecycle + spare parts
- Maintenance Calendar — monthly schedule view
- Analytics — overview, OEE trends, scorecard, KPI comparison, PDF/CSV
- REST API, Webhooks, CSV Import, IoT Gateway
- Dashboard widget + granular staff permissions
Permissions
Assign under Setup → Staff → Roles:
| Feature | Capabilities |
|---|---|
| Dashboard | view |
| Asset Categories / Assets / KPI Definitions / KPI Readings | view, create, edit, delete |
| Downtime Events | view, create, edit, delete, end |
| OEE | view, calculate |
| Maintenance Schedules | view, create, edit, delete |
| Work Orders | view, create, edit, delete, complete |
| Alerts | view, create, edit, delete, resolve |
| Analytics / Integration | view |
| API Keys | view, create, delete |
| Webhooks | view, create, edit, delete |
| Settings | view, edit |
Cron Jobs
PM overdue alerts and webhook retries run through Perfex CRM cron. Example:
* * * * * php /path/to/perfex_crm/index.php cron/index > /dev/null 2>&1
Uninstall
- Deactivate the module under Setup → Modules.
- Click Uninstall.
- All
apm_*tables and module options are removed.
Core Perfex CRM data is not touched.
After activation — configuration checklist
- Go to Setup → Modules and activate Asset Performance Management.
- Tables, seed data (categories, KPIs, downtime reasons), and options are created automatically.
- Assign permissions under Setup → Staff → Roles.
- Open Asset Performance → Settings and configure prefixes, targets, and integrations.
- Perfex CRM 2.3+ (3.0+ recommended)
- PHP 7.4+ (8.1+ recommended)
- MySQL 5.7+ / MariaDB 10.3+ (InnoDB)
- PHP extensions: mysqli, json, mbstring, curl, fileinfo
One-time setup (first time only)
- Setup → Modules → activate Asset Performance Management.
- Setup → Staff → Roles → assign Asset Performance Management permissions (view, create, edit, delete, approve, export, settings as needed).
- Open Asset Performance Management → Settings and complete company defaults, prefixes, integrations, and notification options.
- Create master data (warehouses, products, templates, accounts, routes, etc.) before processing live transactions.
- Enable Perfex CRM cron (
php /path/to/perfex/index.php cron/index) for sync, retries, alerts, and scheduled jobs. - Optionally enable REST API / webhooks in module settings if you integrate external systems.
Tips for success
- Always configure Settings before creating live transactions.
- Create master data (items, warehouses, templates, channels, accounts) first — most modules block incomplete records.
- Use a test/sample record before going live with real customers or production stock.
- Separate roles: operators create/edit; managers approve; finance/reporting get view/export only.
- After any module upgrade, reopen Settings and confirm new options have sensible defaults.
- If overnight jobs fail, verify Perfex CRM cron and check the module log / failed queue screen.
Common questions (FAQ)
Where do I find the module after activation?
In the admin sidebar look for Asset Performance Management. If missing, your role may lack view permission — fix under Setup → Staff → Roles.
Do I need to edit core Perfex CRM files?
No. Keep all custom code under modules/asset_performance_management/. Activate/deactivate from Setup → Modules.
What happens if I uninstall?
Deactivate keeps data. Uninstall usually removes module tables/options (see the Install article). Core customers, invoices, and items are not deleted by well-built modules.
Why can't my staff see a screen?
Almost always a permissions issue. Give the role at least view on that feature, then ask the user to log out and back in.
Reports/export buttons do nothing
Confirm the role has export (or view reports) permission, and that filters return at least one row. Try PDF/CSV from a wider date range.
Perfex CRM Knowledge Base — detailed usage guide generated from module README, HOW_TO_USE, and documentation.