CMMS Work-Order Adapters
FactVerse CMMS Operations can connect to downstream CMMS and EAM systems through governed work-order adapters. Use this guide when a customer wants FactVerse to create, hand off, synchronize, or monitor maintenance work while an existing provider remains in place.
Work-order adapters are different from field protocol adapters. Work-order adapters exchange maintenance records with systems such as Maximo, SAP Plant Maintenance, Honeywell Forge, custom REST services, or webhook endpoints. Field protocol adapters such as BACnet, Modbus, and SNMP bring equipment point values into the asset and work-order context.
Prerequisites
Before configuring a work-order adapter, confirm:
- the downstream CMMS or EAM owner and the intended system of record;
- approved service-account access, credential storage, and rotation rules;
- network reachability from the deployed FactVerse environment to the provider endpoint;
- sample open, assigned, completed, canceled, failed, and reopened work orders;
- asset, location, site, plant, or functional-location identifiers for mapping;
- provider status and priority values that need to appear in the common work-order lifecycle;
- the approved write boundary: read-only, draft, handoff, synchronization, or write-back.
Adapter Selection Flow
Supported Adapter Profiles
| Adapter profile | Use when | Typical direction | Key preparation |
|---|---|---|---|
| Webhook | A downstream or middleware system accepts event payloads and returns status through an inbound webhook | FactVerse push, provider callback | Target URL, shared secret, payload contract, retry policy |
| Generic REST | A provider or customer exposes a project-specific REST API | Configurable push and pull | Base URL, auth mode, push path, pull path, field map, response shape |
| IBM Maximo | The customer uses Maximo work orders, assets, sites, and status values | Push created work orders and pull changed status | Maximo root URL, API key, site or org defaults, asset mapping, status mapping |
| SAP Plant Maintenance | The customer uses SAP maintenance orders, equipment, functional locations, and plant scope | Push maintenance orders and pull status changes | SAP OData root, Basic or API key auth, plant, order type, CSRF write behavior |
| Honeywell Forge | A customer engagement uses Honeywell Forge or an IBMS profile through an approved overlay | Overlay-specific push, pull, asset, or alarm path | Forge base URL, API key or OAuth2 client credentials, overlay payload contract |
Adapter availability still depends on the deployed product scope, customer access approval, provider version, and the final integration contract. Treat each profile as an implementation starting point, not as a substitute for provider discovery.
Core Adapter Model
Every work-order adapter should be planned around the same operating contract:
| Capability | What to confirm |
|---|---|
| Push work order | Which FactVerse work orders should be handed off or created in the provider, and which fields are required |
| Pull status updates | Which provider statuses, assignees, and timestamps should update the common work-order view |
| Health check | What endpoint or probe shows that the provider connection is reachable |
| Asset mapping | How FactVerse equipment maps to provider asset, location, site, or functional-location identifiers |
| Sync log | How success, failure, retry, and provider response messages are reviewed |
| Ownership rule | Whether the provider remains system of record, FactVerse acts as primary workspace, or the workflow is read-only |
Configuration Inputs
Prepare these inputs before enabling an adapter:
| Input | Why it matters |
|---|---|
| Adapter type | Selects the integration profile, such as webhook, rest, maximo, sap-pm, or a customer overlay profile |
| Base URL or endpoint | Defines where requests are sent and how network access is allowed |
| Authentication | Defines service-account access, token handling, credential rotation, and provider audit ownership |
| Field mapping | Maps FactVerse work-order fields to provider fields and preserves source values for traceability |
| Status mapping | Maps provider statuses into common CMMS lifecycle states without losing the original source status |
| Asset mapping | Connects FactVerse equipment IDs to provider asset, location, site, or functional-location IDs |
| Pull cadence | Defines how often status changes are read back, or whether the provider sends webhook callbacks |
| Write boundary | Defines whether the adapter is read-only, draft-only, handoff-only, or approved for write-back |
Generic REST Adapter
Use Generic REST when a customer, provider, middleware layer, or contractor system exposes a project-specific REST API. This profile fits systems outside the packaged profiles while still offering a stable work-order API.
Confirm:
- base URL and network allowlist;
- authentication mode: none for a private test stub, bearer token, Basic auth, or API key header;
- push path and HTTP method;
- pull path, timestamp parameter, result array shape, and status fields;
- field map from FactVerse work-order fields to provider JSON keys;
- external ID field returned after successful creation;
- health-check path and expected response.
Generic REST should be treated as a configurable adapter framework. The customer-specific API contract still needs review before production rollout.
IBM Maximo Adapter
Use the Maximo profile when the customer manages maintenance through IBM Maximo and wants FactVerse to exchange work-order records with the Maximo work-order API.
Typical Maximo preparation:
| Area | Prepare |
|---|---|
| Access | Maximo root URL and API key sent through the approved header path |
| Work-order create | Description, long description, priority, status, external reference, site, org, asset, and location fields |
| Priority mapping | Map FactVerse priorities to Maximo work priorities, with deployment review for local vocabulary |
| Status mapping | Map common states such as created, assigned, in progress, completed, and canceled to the customer's Maximo status model |
| Pull changes | Confirm the changed-date window, selected fields, page size, and handling for customized statuses |
| Asset identity | Map FactVerse equipment to Maximo assetnum, location, site, and org where needed |
Maximo deployments often customize status values, object structures, and required fields. Validate mappings with real open, completed, canceled, blocked, and reopened records before go-live.
SAP Plant Maintenance Adapter
Use the SAP PM profile when the customer manages maintenance orders in SAP S/4HANA Plant Maintenance and wants FactVerse to hand off or synchronize maintenance work.
Typical SAP PM preparation:
| Area | Prepare |
|---|---|
| Access | SAP OData service root and approved Basic or API key authentication |
| Write flow | CSRF token and session-cookie handling for create or update requests |
| Scope | Maintenance plant, order type, equipment, and functional-location fields |
| Work-order create | Description, order type, plant, priority, and traceability reference |
| Status mapping | Map SAP order status codes into common FactVerse lifecycle states while keeping the raw SAP status visible |
| Pull changes | Confirm last-change timestamp format, selected fields, and provider-side filters |
SAP environments differ by gateway configuration, SSO policy, extensions, and order type. Confirm the final service surface with the customer's SAP owner.
Honeywell Forge and Overlay Profiles
Honeywell Forge or IBMS-style integrations should be treated as customer-approved overlay profiles. The profile can use API key or OAuth2 client credentials, but endpoint shape, payload fields, and operating direction depend on the engagement.
Use this path when:
- the customer has approved Forge access and credentials;
- the payload shape is confirmed by the customer or integration partner;
- asset master ownership, alarm flow, and work-order ownership are agreed;
- write-back or handoff behavior is explicitly in scope.
Do not assume every Forge engagement has the same endpoints or permissions. Document the customer-approved profile before enabling production synchronization.
Field Protocol Boundary
BACnet, Modbus, and SNMP are not downstream CMMS work-order adapters. They are used to bring equipment point values, controller status, UPS readings, environmental measurements, or managed-device state into FactVerse context.
Use field protocol adapters when the workflow needs:
- current equipment readings during triage;
- condition evidence on an asset or work order;
- signal inputs for Facility Operations or Predictive Maintenance;
- operational context for Agent-assisted explanation.
Use a work-order adapter when the workflow needs to exchange work-order records with a downstream maintenance system.
Validation Checklist
- Adapter type and provider ownership are confirmed.
- Required credentials, endpoints, firewall rules, and service accounts are approved.
- Asset mappings are tested against real equipment and location examples.
- Status and priority mappings preserve the original provider values.
- Push, pull, health check, sync log, retry, and failure paths are tested.
- Write-back behavior is limited to approved fields and roles.
- Operators can see whether a work order is native, handed off, synchronized, failed, or waiting for provider action.
- The customer has reviewed test records before production rollout.
Troubleshooting
| Symptom | Check |
|---|---|
| Adapter health check fails | Endpoint, network allowlist, TLS, credentials, token expiry, and provider availability |
| Work order is not pushed | Enabled adapter, asset mapping, required fields, provider permission, and sync log error |
| Provider status does not update | Pull cadence, last-sync time, provider timestamp field, status mapping, and inbound webhook callback |
| External ID is missing | Provider response field, external ID mapping, creation success response, and retry behavior |
| Asset appears unmatched | Provider asset ID, location ID, site or org, MDM alias, and retired asset rules |
| Write-back is rejected | Provider transition rule, field permission, review gate, and service-account scope |