Most integration failures in maintenance don't look like failures. The API stays up. Records keep syncing. Dashboards keep rendering. Then three months later someone in finance asks why the asset depreciation schedule doesn't match the CMMS, or an auditor pulls a work order and the attached inspection photo is gone, or the predictive model starts flagging the wrong pumps because the sensor tag format changed and nobody noticed.
That's the thing about integrations between a CMMS, a BAS, an ERP, a procurement system, and whatever analytics layer sits on top — they fail quietly. The data keeps moving, it's just moving wrong. And by the time the damage shows up downstream, you're reconstructing six weeks of history trying to figure out which system started lying first.
A maintenance data contract is how you stop that. It's a written, enforceable agreement about the shape, meaning, quality, and delivery guarantees of the data crossing a system boundary. Not a diagram. Not a Slack thread. A contract — with a schema, validation rules, SLA tiers, and a runbook for when it breaks. This post is about building those, and about the organizational standards that make them stick when IT and procurement are holding the other end.
Why integrations rot even when they "work"
The usual story: two systems get connected during an implementation project. A vendor or internal engineer maps fields, tests a few records, declares victory, and moves on. Nobody owns the contract between those systems because, technically, there wasn't one — just an understanding that lived in someone's head and left when they changed jobs.
Then the business changes underneath the integration. Procurement adds a new vendor code format. A site renames its asset hierarchy during a cleanup. The BAS vendor pushes a firmware update that changes how a sensor reports units. Each of these is a completely reasonable thing to do. None of them get communicated to the people who depend on the old format. The integration doesn't throw an error — it just starts carrying subtly wrong data, because the receiving system was built to accept whatever it got.
Across a lot of multi-site operations, the rot accelerates with every system you add. Two systems have one boundary. Five systems have potentially ten. You don't have to connect all of them, but the ones you do connect each need a contract, and without a standard way of writing those contracts, every integration becomes a bespoke, undocumented snowflake that only one person understands.
The deeper problem is that nobody agreed on what the data means. The CMMS thinks "completed" means the technician closed the work order. Finance thinks it means the cost was reconciled. The analytics layer thinks it means the asset is back in service. Same word, three definitions, and the integration faithfully passes a status that means something different on each side.
The three things worth putting under contract first
You can't contract everything on day one, and you shouldn't try. Start with the three data types that cause the most expensive cross-system damage when they drift:
Eliminate downtime with proactive maintenance.
Openfixit helps you plan, track, and complete maintenance efficiently—maximizing asset reliability.
- Centralized asset management
- Automated maintenance scheduling
- Inventory and parts tracking
No credit card required
Assets. The asset record is the spine. If the asset ID, hierarchy, class, and criticality don't agree across CMMS, ERP, and the sensor layer, nothing downstream can be trusted. A predictive model trained on one asset taxonomy will quietly misroute predictions when procurement uses a different one. Asset drift is the most common root cause of "the numbers don't match" arguments between maintenance and finance.
Work orders. This is where state, cost, labor, and evidence all converge. Work orders flow outward to finance (cost), to analytics (reliability metrics), and to vendor scorecards (SLA performance). A work-order schema that's loose about status definitions, timestamp meanings, or cost field mapping will corrupt every one of those downstream uses at once.
Evidence. Photos, measurements, inspection results, calibration certificates, signatures. This is the data most likely to go missing in an integration because it's often large, stored separately from the structured record, and treated as an afterthought. When evidence breaks the link to its work order, you lose auditability — and you usually find out during an audit, which is the worst possible time.
What a canonical schema actually looks like
A canonical schema is the single agreed definition of a data type that every system maps to and from. Instead of CMMS-to-ERP and CMMS-to-analytics each having their own private mapping, both systems translate into the canonical form. This matters because it turns an N-to-N mapping problem into an N-to-one problem. Add a sixth system and you write one new mapping, not five.
Here's a stripped-down canonical work-order schema as an example of the level of specificity a contract needs. Vague field names are where contracts die.
| Field | Type | Required | Definition / Rule |
|---|---|---|---|
workorderid | string | yes | Globally unique, immutable. Never reused after closure. |
asset_id | string | yes | Must resolve to an active record in the canonical asset registry. |
status | enum | yes | One of: open, in_progress, completed, verified, cancelled. completed = field work done, not cost-reconciled. |
priority | enum | yes | safety, urgent, routine — mapped from site triage rules. |
created_ts | ISO 8601 UTC | yes | System time of creation. UTC only, no local time. |
completed_ts | ISO 8601 UTC | conditional | Required when status ≥ completed. Must be ≥ created_ts. |
labor_minutes | integer | no | Wrench time only. Excludes travel unless flagged. |
cost_total | decimal | no | Currency-tagged. Null until reconciled, never zero-as-unknown. |
evidence_refs | array | conditional | Required for safety/compliance work. Each ref must resolve. |
Notice the small decisions that prevent big problems. cost_total is explicitly null when unknown rather than zero — because a bunch of zeros will silently deflate your cost-per-asset reporting and nobody questions it. Timestamps are UTC-only because mixed local times across sites in different zones produce "work completed before it started" errors that waste hours to trace. The status enum has an explicit definition for completed so finance and analytics can't each invent their own interpretation.
This diagram shows where each system translates to the canonical form, where validation and contract tests run, and how runbook alerts are triggered when a contract breaks.
The evidence schema needs the same rigor: every evidence object carries its own ID, a hard reference back to the work order, a capture timestamp, a type, and a checksum. The checksum is what lets you prove a file wasn't swapped or corrupted in transit — exactly the kind of thing that surfaces in audit-admissibility disputes.
Contract tests: the part everyone skips
A schema on a wiki page is a suggestion. A schema enforced by automated tests is a contract. Contract tests are small checks that run against the data crossing the boundary and fail loudly when something violates the agreed shape or rules. This is the single highest-leverage practice in this whole post, and it's the one most teams skip because it feels like engineering overhead.
Run these in two places: when data leaves the producing system (does it match what we promised to send?) and when it arrives at the consuming system (does it match what we promised to accept?). Checking both ends catches the case where a producer changes its output and claims it still conforms — the consumer-side test calls the bluff.
A practical contract test suite for a work-order integration should cover:
-
Schema conformance — every required field present, every type correct, every enum value in the allowed set
-
Referential integrity — every
assetidresolves to a live asset; everyevidencerefresolves to an actual file -
Business-rule validation —
completedtsnot beforecreatedts; safety-priority work orders have evidence attached; cost is null-or-valid, never zero-as-placeholder -
Volume/freshness checks — record counts within expected ranges; no sudden drop to zero (a stalled sync that doesn't error)
-
Drift detection — field distributions compared to baseline; a sudden appearance of unexpected status values or a new tag format gets flagged before it propagates
Run contract tests at both producer and consumer CI gates so regressions are caught before they hit production.
The volume and freshness checks matter more than people expect. The most dangerous integration failure isn't bad data — it's no data, arriving silently. A sync that quietly stops at 2 a.m. and resumes at 9 a.m. with a backlog won't throw an error, but you'll have a seven-hour hole in your reliability metrics that nobody flagged. A freshness test expecting a record at least every 15 minutes catches that immediately.
This discipline overlaps heavily with post-install verification work — if you want the tactical version, the checklist in Don't ship bad integrations with sample queries and latency tests is a good companion to the contract-test approach described here.
SLA tiers: not every integration deserves the same promises
A common mistake is treating all integrations as equally critical. They aren't, and pretending they are wastes effort and money. A life-safety alarm feed and a monthly cost-rollup to accounting have wildly different tolerances for latency and downtime. Tiering your contracts lets you spend your reliability budget where it matters.
| Tier | Example integration | Latency target | Freshness | Error budget | On-break response |
|---|---|---|---|---|---|
| Tier 1 – Critical | Safety alarms, critical-asset sensor feeds | < 30 sec | Real-time | ~99.9% | Page on-call immediately |
| Tier 2 – Operational | Work-order sync CMMS↔ERP, vendor dispatch | < 5 min | Near-real-time | ~99.5% | Alert within 15 min, fix same day |
| Tier 3 – Analytical | Reliability metrics, PM history to BI | < 1 hour | Hourly/daily | ~99% | Next-business-day fix |
| Tier 4 – Batch | Monthly cost rollups, depreciation feeds | Daily window | Daily/weekly | best-effort | Fix before next cycle |
The point of the tier isn't the exact numbers — it's that you've decided and written them down. When a Tier 3 analytics feed is three hours late, nobody panics and pages the on-call engineer. When a Tier 1 safety feed is 45 seconds late, somebody absolutely does. Without tiers, every alert feels equally urgent, which means none of them really do, and people start ignoring the lot.
One pattern worth naming: integrations tend to get over-promised at implementation and under-maintained afterward. Someone commits to real-time for a feed that only needs hourly, builds a fragile system to hit it, then spends years firefighting an SLA nobody actually needed. Tier your contracts to the real downstream requirement, not to what sounds impressive in a project kickoff.
Runbooks: what happens when the contract breaks
A contract without a runbook is a contract that generates 2 a.m. guesswork. When a contract test fails, the person who gets paged — often an IT on-call engineer who doesn't know maintenance — needs to know what broke, how bad it is, and exactly what to do. That's the runbook's job.
A good contract-break runbook is short and mechanical. For each contract, it should specify:
-
What triggered this — which test failed, against which boundary, with the actual failing payload sample
-
Blast radius — which downstream systems and reports consume this data, so the responder knows who's affected
-
Immediate containment — pause the sync, quarantine the bad batch, or let it through with a flag, depending on tier
-
Diagnosis path — the three or four most common causes for this specific contract, in order of likelihood
-
Rollback procedure — how to revert to the last known-good state and replay held records once fixed
-
Who to notify — maintenance ops owner, data owner, and the producing-system vendor if it's their change
The containment decision is the one people get wrong. For a Tier 1 feed you almost never want to pause — stale safety data is worse than slightly-malformed safety data you can still interpret. For a Tier 2 financial sync, you do pause, because letting a known-bad cost batch into the ERP creates reconciliation work that takes ten times longer to unwind than the outage. The runbook encodes that judgment so the on-call person doesn't have to make it half-asleep.
A realistic failure pattern: a BAS firmware update changes a temperature sensor from reporting whole degrees to tenths, formatted as a string with a trailing character the CMMS parses as zero. No error thrown. The drift-detection test catches that the field distribution collapsed toward zero, pages the data owner, the runbook points straight at "recent BAS change — check sensor payload format," and the bad batch gets quarantined before it poisons three weeks of trend data. Without the test and runbook, that's the kind of thing you discover when a chiller runs cold for a month and your model never flagged it.
Making operations, IT, and procurement actually enforce this
This is where most of these programs die. Maintenance writes beautiful schemas, IT owns the pipes, procurement owns the vendor contracts, and nobody owns the contract between the data. The technical artifact is the easy part. Getting three functions to enforce it is the hard part.
A few things that make enforcement real:
Put the data contract in the procurement contract. When you buy a new BAS, sensor platform, or CMMS module, the canonical schema and SLA tier become a procurement deliverable — not a nice-to-have. The vendor is contractually obligated to conform to your schema and to notify you before changing their output format. This is the single most effective lever, because it moves enforcement from "please don't break our integration" to "you're in breach of contract if you do."
Assign a data owner per contract, separate from the system owner. The system owner keeps the CMMS running. The data owner is accountable for whether the work-order contract holds. These are different jobs. When they're merged, the data contract always loses to keeping-the-lights-on.
Version your contracts and treat changes as change-management. A schema change is a change to every system downstream of it. Run it through the same governance you'd use for any cross-site process change. The approach in the CMMS change-management playbook for standardizing processes across sites applies directly — a contract change needs the same review, communication, and rollback discipline as any other standardized process.
Store the contracts where people can find them. Schemas, tier definitions, and runbooks belong in your governed knowledge base, versioned and discoverable, not scattered across repos and email threads. The structure described in designing a multi-site maintenance knowledge-management system with proper taxonomy and versioning is exactly where these artifacts should live, so the next engineer doesn't rebuild the mapping from scratch.
A short real scenario
A regional operator running about 14 industrial sites had a recurring fight between maintenance and finance. Every month-end, the cost-per-asset numbers from the CMMS didn't reconcile with the ERP, and both teams spent the better part of a week arguing over which system was right. The root cause turned out to be embarrassingly small: the CMMS passed cost_total as zero whenever a work order closed before parts were reconciled, and the ERP treated those zeros as real. Thousands of zero-cost work orders were quietly deflating the asset-cost picture.
They didn't fix it by building a bigger integration. They fixed it by writing one contract: cost_total is null-until-reconciled, never zero; a contract test rejects any record using zero-as-unknown; and a runbook tells the on-call person to hold the batch and ping finance when the test trips. The month-end reconciliation argument dropped from roughly a week to under a day, and the drift-detection test has since caught two other silent format changes before they caused problems. Total engineering effort was a couple of weeks — far less than the recurring time both teams were burning every single month.
When this is worth it — and when it isn't
Full contract-and-test discipline makes sense when you're running multiple integrated systems across more than a handful of sites, when data crosses between maintenance, finance, and procurement, or when you're leaning on that data for compliance, audits, or predictive models. At that scale, the silent-rot problem is expensive and recurring, and contracts pay for themselves the first time they catch a format change before it propagates.
It's overkill for a single-site operation running one CMMS with no real integrations, or for a genuinely throwaway one-time data pull. Writing a canonical schema, tiered SLA, and runbook for a report you'll run once is ceremony for its own sake. The honest test is: does wrong data crossing this boundary create expensive, hard-to-trace downstream damage? If yes, contract it. If the blast radius is one spreadsheet one person reads, skip it.
The teams that get burned are the ones in the middle — enough systems and sites that the rot is real, but still treating every integration as a one-off handshake that lives in someone's memory. That's the gap data contracts close. Not by adding more technology, but by making the agreements between your systems explicit, testable, and enforceable — so the next firmware update, vendor change, or hierarchy cleanup fails loudly on day one instead of quietly for a quarter.
Ready to optimize your maintenance operations?
Join 2,000+ facilities using Openfixit to reduce unplanned outages, extend asset life, and improve operational efficiency.