Connecting Predictive Maintenance Alerts to IBM Maximo: What We Learned in Six Deployments

The Maximo REST API is well-documented. The undocumented part is which asset attributes your maintenance planner actually reads before deciding to dispatch a technician — and which work order field configurations determine whether a predictive alert shows up in the right queue or disappears into an unmonitored inbox. After six CMMS integrations, here is what we know that the official documentation doesn't say.

The Work Order vs. Service Request Distinction Matters

Maximo has two paths for creating maintenance records: Service Requests (SR) and Work Orders (WO). They look similar from the outside but route differently in most organizations. Service Requests go through an approval workflow — a planner reviews them before a WO is generated. Work Orders go directly into a technician's queue (depending on work type configuration). For predictive maintenance alerts, you almost always want to generate a WO directly rather than an SR. An SR requires a human to review and approve before any action happens, which adds latency and creates a queue that is often reviewed only once per shift.

The complication: generating a WO directly requires knowing the correct Work Type, Asset Number, and Location hierarchy in Maximo. The Work Type determines which maintenance group sees the work order. If EdgeRun generates a WO with Work Type "PM" (Planned Maintenance) and the predictive alerts are actually triaged by the "CM" (Corrective Maintenance) group, the work orders land in the wrong queue. Finding this out requires talking to the maintenance manager, not reading the API docs.

Asset Number Synchronization Is the Hardest Part

EdgeRun assigns asset IDs to monitored equipment during installation — typically based on a serial number or a plant-assigned tag number. Maximo has its own Asset Number field, which may or may not match the plant tag number, depending on how the CMMS was configured and how many years of data migration have occurred. We have seen Maximo installations where the asset numbers are legacy codes from a 1990s paper-based system that no longer correspond to anything on the nameplate.

Before the integration can generate correctly attributed work orders, there needs to be a lookup table mapping EdgeRun asset IDs to Maximo Asset Numbers. Building this table correctly requires physical verification — walking the floor with both systems open and matching equipment to records. It is a two-hour task for 50 assets, but it is a prerequisite for integration that most deployment timelines don't account for. We now build this table walk explicitly into our installation project plan as "Asset Mapping Day."

Priority Field Configuration Controls Alert Visibility

Maximo work order priority is a numeric field (typically 1–5 in most configurations, but this varies by organization). The predictive maintenance alert needs to land at a priority that is high enough to appear in the planner's active queue but not so high that it triggers emergency response procedures. In the six deployments we've done, the correct priority has ranged from 2 to 4, and the only way to find the right number is to ask the maintenance manager which priority level triggers which response.

We use a mapping table that converts EdgeRun anomaly severity (Low, Medium, High, Critical) to Maximo priority values that are configured per site during integration setup. The default mapping is: High → Priority 2, Medium → Priority 3, Low → Priority 4. This has required adjustment at three of the six sites — once because the customer used a 1-10 priority scale instead of 1-5, once because Priority 2 at their facility triggered a safety-critical work approval process, and once because their planner only monitored the Priority 1 queue for predictive maintenance and everything else was handled reactively.

The Long Description Field Is Where the Useful Information Goes

Maximo work orders have a Short Description (100 characters) and a Long Description (unlimited). The Short Description is what maintenance planners see in the list view. The Long Description is what they see when they open the work order. Both need to contain different information, optimized for how maintenance planners actually use Maximo.

In our experience, the most effective Short Description format is: "[Asset ID] — [Failure Mode] — [Estimated Time to Failure]". For example: "P-107 — Bearing Outer Race Defect — Est. 18-36h." This gives the planner enough information to prioritize the work order from the list view without opening it. The Long Description should contain: current anomaly score vs. threshold, the specific frequency components that triggered the alert, the asset's recent load profile, and a link to the EdgeRun dashboard showing the full trend. We encode the dashboard link as a URL in the Long Description field, which Maximo renders as a clickable hyperlink in most interface versions from 7.6 onward.

OPC-UA vs. REST API: Why the Integration Architecture Matters

Maximo supports integration through REST APIs (via the Maximo Application Framework's REST layer), through the Integration Framework's message queues, and through direct database connectors. Most newer Maximo integrations use the REST API because it is the most maintainable path. However, when the factory's OT network is air-gapped or has restricted outbound connectivity, the REST API call from EdgeRun's edge gateway to Maximo may be blocked by network policy.

In those cases, the cleaner architecture is to have EdgeRun publish work order events to an OPC-UA server that sits inside the OT network, and then have a separate integration middleware component (running in the IT network where Maximo lives) subscribe to those OPC-UA events and translate them to Maximo REST calls. This two-segment architecture adds complexity but respects the OT/IT network segmentation that most manufacturing security policies require. We have built this architecture at two sites with ISA/IEC 62443 compliance requirements.

Testing the Integration Before Go-Live

Every Maximo integration should be tested with synthetic work orders before any live asset anomalies are used to generate production records. The test procedure: generate a test work order with a known-synthetic asset ID and a description that clearly marks it as a test, then verify it appears in the correct queue with the correct priority and that the Long Description URL resolves correctly. Then verify the work order can be closed and that the closure is visible in EdgeRun's dashboard history.

The closure confirmation step is frequently overlooked and always causes problems later. If EdgeRun generates a work order but has no confirmation that the work was completed, the asset's maintenance history is incomplete and the anomaly model doesn't learn from the event. Maximo's WORKORDER table has a STATUS field that changes from WAPPR to WMATL to INPRG to COMP as a work order progresses. We poll this status field periodically and update the asset's last service record in EdgeRun when the WO reaches COMP status. This feedback loop is important for keeping the baseline calibration current after maintenance events — as described in our article on baseline calibration.

SAP PM Integration: The Key Differences

For plants running SAP Plant Maintenance rather than Maximo, the integration architecture is similar but the terminology and data model differ. SAP PM uses Notifications (equivalent to Maximo Service Requests) and Orders (equivalent to Work Orders). The functional location hierarchy in SAP — Plant, Functional Location, Equipment — is more rigid than Maximo's site/asset structure. The Equipment Number in SAP PM is the field that must match EdgeRun's asset ID, and equipment master records must be active (not technically complete) for orders to be created against them.

We have one SAP PM integration in active use. The approach uses SAP's RFC (Remote Function Call) interface via a middleware layer rather than direct API integration, because the SAP system at that site was running ECC 6.0 without the newer S/4HANA REST API layer. For newer S/4HANA installations, the OData API for maintenance notifications is the cleaner path.