Predictive Maintenance Operations
Predictive Maintenance is a platform operations capability for equipment health, anomaly review, maintenance recommendations, and model-management workflows. Industry modules such as facility operations, HeatOps, data-center operations, and SemiOps can use it when rotating equipment, filters, chillers, pumps, compressors, AHUs, UPS systems, or other maintained assets need a governed health workflow.
The code uses /pdm as the API namespace. In user-facing documentation and UI copy, describe the capability as Predictive Maintenance unless an API path or permission string is being shown.
Current service boundary
Predictive Maintenance is implemented across several runtime surfaces:
| Surface | Current role |
|---|---|
| FactVerse frontend | Provides dashboard, equipment, fleet, vibration, efficiency, maintenance, anomaly, energy, onboarding, template, threshold, advisory inbox, and model console views. |
factverse-mod-pdm backend | Provides the predictive maintenance backend slice for dashboard data, equipment profiles, health snapshots, anomaly events, maintenance records, energy baselines, advisory workflow, onboarding, sensor ingest, templates, reliability metrics, and rule-set status. |
| Core backend | Provides bridge code for tenant context, equipment directory, work-order outcome integration, and model lifecycle console aggregation. |
| AI Engine | Provides baseline training, anomaly detection, trend forecast, remaining useful life prediction, health scoring, vibration and temperature diagnosis, fleet diagnosis, XS770A payload processing, and AI-assisted pipeline calls. |
| DFS | Prepares source data, connector mappings, sync history, quality review, and governed datasets before the maintenance workflow depends on live operational data. |
The predictive maintenance backend slice is still in a staged extraction. Present it as a platform capability used by vertical modules; independent vertical-product packaging remains outside the current slice.
What users can do today
The current application exposes these user workflows:
| Workflow | What users can review or perform |
|---|---|
| Dashboard | Overall equipment health, active anomalies, maintenance status, energy baselines, and reliability summaries. |
| Equipment profiles | Equipment list, profile detail, latest health snapshot, health history, advisory mode, and main equipment ID bridge lookup. |
| Sensor onboarding | Create equipment, create sensors from templates, complete onboarding, run all-in-one onboarding, push readings through REST, or import CSV history. |
| Vibration source | Ingest vibration and temperature data, including composite values from XS770A-style payloads. |
| Health index | Review health index history, latest running-state health index, summary across equipment, operating schedule, and fault signature library. |
| Anomalies | List all anomalies, review anomalies by equipment, and resolve anomaly events with a resolution note. |
| Advisory inbox | Review pending advisories, reject false positives, snooze items, create linked work orders, and record work-order outcomes. |
| Maintenance | Review equipment maintenance records and maintenance schedule. |
| Energy | Review active energy baselines related to equipment operation. |
| Failure modes | Review tenant-scoped failure-mode catalog, hydrate alert failure-mode details, and inspect failure-mode distribution. |
| Reliability | Review MTBF, MTTR, availability, advisory precision, recall, and CSV export for spreadsheet review. |
| Criticality | Review criticality matrix and attention list for prioritized maintenance planning. |
| Templates | Create, edit, version, apply, submit, approve, publish, retire, and audit equipment analysis templates. |
| Model console | Read current model assignment, model state, recent lifecycle events, and retraining blockers per managed equipment. |
Before you start
Prepare the data and ownership model before using the workflow:
| Requirement | Notes |
|---|---|
| Tenant context | All production workflows must run under the correct tenant. Several APIs resolve tenant context server-side. |
| Permissions | Read surfaces use pdm:read. Write surfaces such as profile update, advisory action, template changes, and maintenance record creation use pdm:write. |
| Equipment identity | Equipment should have a stable equipment ID, type, location, manufacturer, model, and optional bridge to the main equipment directory. |
| Sensor mapping | Vibration, temperature, current, pressure, energy, or other signals must map to the right equipment and units. |
| History depth | Baselines, trend models, remaining-life estimates, and confidence indicators depend on enough chronological history. |
| Work-order owner | Decide which team accepts advisories, creates work orders, and records outcome labels after field work. |
| Data foundation | Use DFS when source systems need connector setup, mapping, quality review, and sync observability. |
For source data setup, see Getting Started with DFS and Prepare Predictive Maintenance Signal History.
Open Predictive Maintenance
The current frontend exposes these routes:
| View | Route |
|---|---|
| Dashboard | /pdm/dashboard |
| Equipment list | /pdm/equipment |
| Equipment detail | /pdm/equipment/:id |
| Fleet components | /pdm/components |
| Fleet circular view | /pdm/circular |
| Vibration | /pdm/vibration |
| Efficiency | /pdm/efficiency |
| Maintenance | /pdm/maintenance |
| Anomalies | /pdm/anomalies |
| Energy | /pdm/energy |
| Reports | /pdm/reports |
| Settings | /pdm/settings |
| Vibration source | /pdm/vibration-source |
| Onboarding | /pdm/onboarding |
| Automatic analysis | /pdm/auto-analysis |
| Templates | /pdm/templates |
| Fleet | /pdm/fleet |
| Compare | /pdm/compare |
| Thresholds | /pdm/thresholds |
| Advisory inbox | /pdm/advisory/inbox |
| Model console | /pdm/model-console |
Onboard equipment and sensors
Use onboarding when a new asset needs to join the predictive maintenance workflow:
- Create the equipment profile with name, type, location, manufacturer, model, and equipment ID.
- Choose a sensor template or provide manual sensor definitions.
- Create sensors and verify default thresholds.
- Complete onboarding to check equipment, sensor count, resolved analysis configuration, and ingestion options.
- Send a small sample of readings through REST or CSV import.
- Confirm the equipment appears in the dashboard and health index views.
Supported onboarding templates include single-sensor and dual-sensor XS770A-style layouts, generic vibration and temperature, and temperature-only. The reading ingest endpoints accept batch REST payloads and CSV files in long or pivoted format.
Prepare signal history
The predictive maintenance workflow depends on consistent time-series signals:
| Signal type | Typical use |
|---|---|
| Vibration RMS | Health index, ISO grade, anomaly detection, vibration and temperature diagnosis. |
| Acceleration peak | Bearing-impact indicators and crest-factor calculation. |
| Temperature | Joint vibration and temperature diagnosis, health scoring, advisory context. |
| Current, power, pressure, COP, efficiency | Feature-level anomaly scoring and equipment-specific diagnosis. |
| Operating schedule | Running-state filtering and health-index interpretation. |
| Maintenance records | Reliability metrics, advisory validation, and work-order feedback. |
Use DFS mappings and Data Quality in DFS Lite to verify units, timestamps, equipment IDs, and stale values before relying on the output.
Review equipment health
Start from the dashboard, then open equipment detail:
- Review dashboard totals and the health distribution.
- Open the equipment profile.
- Check the latest health snapshot.
- Review health history for the selected period.
- Check the health-index trend, ISO grade, crest factor, kurtosis, predicted days to service, and running-state filter when available.
- Compare related equipment through fleet or compare views.
Health index endpoints return history, latest running-state health, and a summary across equipment. If no data is available, the latest-health endpoint can return a no-data message, so operators should confirm source coverage before treating a healthy default as a real equipment state.
Detect and diagnose anomalies
The AI Engine supports multiple analysis paths:
| AI workflow | Input | Output |
|---|---|---|
| Baseline training | Equipment ID, equipment class, feature list, optional training data, and training window. | Model ID, training status, data points used, and readiness state. |
| Anomaly detection | Sensor data window and optional model ID. | Anomaly score, threshold, severity, anomaly type, feature contributions, and model version. |
| Trend forecast | Feature history, horizon, confidence interval, and optional threshold. | Forecast points, predicted threshold date, days to threshold, and maintenance recommendation. |
| Remaining useful life | Health-index history and failure threshold. | Remaining days, confidence, model method, degradation rate, predicted failure date, and trend data. |
| Health score | Dimension scores and weights. | Composite health score, grade, dimension contribution, and summary. |
| Vibration and temperature diagnosis | Equipment template, sensor position, latest reading, and optional history. | Severity, diagnosis, likely fault modes, recommendation, ISO grade, and evidence. |
| Fleet diagnosis | Multiple readings for the same equipment type. | Per-equipment diagnosis, fleet statistics, and outlier detection. |
| XS770A payload processing | Three-axis velocity, acceleration, temperature, and metadata. | Composite vibration RMS, peak vibration, crest factor, quick anomaly flag, and health-score estimate. |
Use the diagnosis result as a review input. Field action should still be confirmed by a maintenance owner, especially when the model is newly trained, source data is sparse, or equipment templates have not been approved.
Manage advisories and work orders
The advisory workflow connects anomaly review to maintenance action and feedback:
- Open Predictive Maintenance > Advisory Inbox.
- Filter pending advisories.
- Review linked alert, equipment, failure mode, health index, proposed action, priority, and SLA.
- Reject clear false positives with a reason, or snooze advisories that need later review.
- Create or link a work order when action is accepted.
- When the work order closes, record the advisory outcome and optional root cause or override reason.
- Review precision and outcome statistics over time.
The work-order outcome path is important because it turns field feedback into model and rule calibration evidence. A predictive maintenance-linked work order should include an outcome label when it closes.
Tune rules and templates
Predictive Maintenance supports rule-set observability and equipment analysis templates:
| Surface | Purpose |
|---|---|
| Rule-set status | Shows whether the current tenant overlay is active, empty, or quarantined. |
| Rule-set view | Shows the loaded pdm: overlay, including thresholds, health-band overrides, and advisory rules. |
| Analysis configuration | Resolves configuration by equipment, facility, equipment type, then system default. |
| Templates | Store health profile, algorithm configuration, monitoring configuration, version history, approval status, and application history. |
| Template approval | Submit, approve, reject, publish, retire, and audit template changes before operational use. |
Treat rules and templates as governed operating assets. Review changes before applying them to equipment, and keep threshold changes traceable to data quality, fault evidence, or field feedback.
Review reliability and criticality
Use reliability and criticality views during planning reviews:
| View | What to check |
|---|---|
| Reliability metrics | MTBF, MTTR, availability, failure rate, advisory precision, advisory recall, and advisory outcome counts. |
| Reliability CSV | Spreadsheet export for maintenance meetings and audit packs. |
| Failure-mode catalog | Effective tenant catalog with tenant overrides replacing defaults. |
| Failure-mode distribution | Distribution by equipment type and lookback window. |
| Criticality matrix | Risk ranking matrix for maintenance prioritization. |
| Attention list | Top equipment requiring attention, capped by the selected limit. |
These views support maintenance planning and governance. They should be read with the source data window, strategy filters, and work-order outcome completeness in mind.
Integrate with CMMS and operations systems
The module includes CMMS configuration and webhook surfaces:
| Integration | Current support |
|---|---|
| SAP Plant Maintenance | Default field mapping for work order ID, equipment ID, status, description, diagnosis, and priority. |
| IBM Maximo | Default field mapping for work order, asset, status, description, failure code, and priority. |
| Infor EAM | Default field mapping for work order ID, equipment ID, status, and description. |
| Custom REST API | Configurable mapping and webhook path. |
Configure CMMS integration only after the equipment ID model, work-order ownership, and field mapping are confirmed. The connection test checks endpoint reachability and records sync status; it should be followed by a controlled integration test before production use.
API surface
Predictive maintenance APIs are grouped under /api/v1/pdm:
| Group | Example endpoints |
|---|---|
| Dashboard | /dashboard |
| Equipment | /equipment, /equipment/{equipmentId}, /equipment/{equipmentId}/profile, /equipment/{equipmentId}/health, /equipment/{equipmentId}/health/history |
| Numeric bridge | /equipment/by-id/{mainId}/profile, /equipment/by-id/{mainId}/health, /equipment/by-id/{mainId}/health/history |
| Health index | /health-index, /health-index/latest, /health-index/summary, /operating-schedule, /fault-signatures |
| Onboarding and ingest | /onboarding/templates, /onboarding/equipment, /onboarding/sensors, /onboarding/complete, /onboarding/quick, /sensors/readings/batch, /sensors/readings/import |
| Anomalies | /anomalies, /equipment/{equipmentId}/anomalies, /anomalies/{anomalyId}/resolve |
| Maintenance | /equipment/{equipmentId}/maintenance, /maintenance/schedule |
| Energy | /energy/overview |
| Advisory | /advisory, /advisory/by-alert-id, /advisory/by-workorder/{workOrderId}, /advisory/{id}/work-order, /advisory/{id}/outcome, /advisory/{id}/reject, /advisory/{id}/snooze, /advisory/outcome-stats, /advisory/precision |
| Failure modes | /failure-modes, /failure-modes/by-alert-ids, /failure-modes/distribution |
| Reliability | /reliability-metrics, /reliability-metrics.csv |
| Criticality | /criticality/matrix, /criticality/attention |
| Rule set and config | /config/rule-set, /config/rule-set-status, /config/rule-set-status/all, /config/resolve, /config/list, /config/resolve-all |
| Analysis and templates | /analysis/upload, /analysis/{jobId}, /analysis/{jobId}/create-template, /analysis/save-result, /analysis/compare, /analysis/batch, /analysis/history, /analysis/health-map, /analysis/priority, /analysis/calendar, /templates |
| SOP and CMMS | /sop, /sop/match, /cmms, /cmms/test, /cmms/webhook |
| Model console | /model-console |
AI Engine predictive maintenance endpoints include:
| Endpoint | Purpose |
|---|---|
/ai/pdm/train | Train a baseline model for equipment features. |
/ai/pdm/baseline/{model_id}/status | Check model training status. |
/ai/pdm/detect | Run anomaly detection with feature contribution output. |
/ai/pdm/forecast | Forecast a feature trend and estimate threshold timing. |
/ai/pdm/health-score | Calculate a composite health score. |
/ai/pdm/rul/predict | Predict remaining useful life from health-index history. |
/ai/pdm/diagnose | Run vibration and temperature diagnosis for one asset. |
/ai/pdm/fleet-diagnose | Run batch diagnosis for similar equipment. |
/ai/pdm/templates | List diagnosis equipment templates. |
/ai/pdm/templates/{equipment_type} | Get an equipment diagnosis template. |
/ai/pdm/ingest/xs770a | Process XS770A-style vibration payloads. |
Validation checklist
Before using predictive maintenance output in a maintenance meeting or work-order decision, confirm:
- equipment IDs are mapped consistently across FactVerse, source systems, CMMS, and work orders;
- sensor channels use the expected units and axis definitions;
- timestamp order, timezone handling, and data freshness are acceptable for the decision;
- enough running-state data exists for baseline and trend interpretation;
- the equipment template or rule overlay is active and not quarantined;
- advisory decisions are tied to a responsible reviewer;
- work-order closure captures outcome labels so the feedback loop can improve future recommendations.