CMMS Troubleshooting
Use this guide when CMMS Operations, multi-provider consolidation, data integration, attachment sync, or AI Agent workflows behave differently from the customer expectation.
Start with the visible symptom, then check source freshness, mapping, identity, permissions, and synchronization logs.
Troubleshooting Flow
Prerequisites
| Requirement | Why it matters |
|---|---|
| Issue example | Troubleshooting should use a real work-order ID, provider ID, and affected user |
| Source access | The team needs access to the source CMMS or EAM record for comparison |
| Sync history | Import, handoff, write-back, and retry logs show where the workflow changed state |
| Mapping version | Field, status, priority, and asset mappings must be tied to a version or effective date |
| Permission context | User role, service account, tenant, site, and provider scope affect most failures |
| Reviewer | A business owner should approve fixes that affect operational meaning |
Source Data Inputs
| Input | Use |
|---|---|
| Work-order ID and provider ID | Finds the source record and normalized record |
| Tenant and site | Confirms scope and routing |
| User or service identity | Checks permissions and audit records |
| Source status and common status | Diagnoses lifecycle mapping problems |
| Asset reference | Diagnoses MDM and alias issues |
| Sync log | Shows import, retry, write-back, and error state |
| Attachment metadata | Diagnoses missing or inaccessible evidence |
Common Symptoms
| Symptom | First checks |
|---|---|
| Work order is missing | Connector sync time, source filter, provider ID, required fields, and rejected rows |
| Status looks wrong | Source status, mapping table, common lifecycle, and mapping version |
| Work order appears twice | Provider ID, source work-order ID, retry behavior, duplicate rule, and import window |
| Asset link is wrong | Alias mapping, retired asset rule, location hierarchy, and steward decision |
| Assignment does not update | Provider ownership rule, write-back permission, transition rule, and sync error |
| Attachment is missing | Attachment import, ECM metadata, file access, file size, and document link |
| Dashboard count differs from provider | Refresh cadence, filter scope, source status mapping, and stale data |
| AI Agent answer is outdated | Dataset refresh, cache time, evidence scope, and source citation |
Diagnose Missing Work Orders
- Confirm the work order exists in the source provider.
- Confirm the connector ran after the source record was created or updated.
- Check rejected rows and mapping errors.
- Confirm required fields are present.
- Confirm tenant, site, provider, and status filters.
- Search by source work-order ID and common work-order ID.
- Re-run the import or route the exception to the data owner.
Diagnose Status Problems
- Compare source status and common status.
- Check whether the provider status value is mapped.
- Review transition history.
- Check canceled, blocked, completed, closed, and reopened edge cases.
- Confirm whether status was imported, manually changed, synchronized, or written back.
- Update mapping only after the operations owner approves the meaning.
Diagnose Asset Identity Problems
- Compare source asset ID, location, and equipment name.
- Check the MDM alias table.
- Review steward decisions for merge, split, or re-point actions.
- Check retired and replacement asset rules.
- Confirm whether the work-order record needs reprocessing after MDM changes.
Diagnose Permission Problems
| Failure point | Check |
|---|---|
| User cannot view work order | User role, tenant, site, provider, and status scope |
| Connector cannot read source | Provider credential, IP allowlist, endpoint, role, and expiry |
| Handoff is rejected | Required fields, provider permission, and ownership rule |
| Write-back fails | Field permission, transition rule, service identity, and provider response |
| AI Agent cannot draft action | Tool scope, review gate, and action boundary |
Expected Output
Each troubleshooting case should end with:
- symptom and affected records;
- root cause category;
- source evidence;
- fix applied or owner assigned;
- validation result;
- prevention note when the same issue may recur.
Validation Checklist
- The affected work order can be found by source ID and common ID.
- Source status and common status are explained.
- Asset identity resolves to the intended operating object.
- Sync history shows the latest import or write attempt.
- User or service account permissions match the intended workflow.
- The fix is verified with at least one real record.