Maximo

Back to integration overview

Maximo is currently the only supported maintenance-system provider. This page covers its connection, Asset and Configuration Item profiles, query behavior, and update targets.

Provider setup

Set MaintenanceSystemIntegration:Provider to Maximo. Configure the provider under MaintenanceSystemIntegration:Providers:Maximo:

Setting	Requirement	Purpose
`BaseUri`	Required	Absolute HTTP(S) URI for the Maximo object-structure API, ending in `/api/os/`.
`ApiKey`	Required	Maximo API key, sent in the `apikey` header.
`HealthEndpoint`	Required	Relative endpoint requested during the startup connection check.
`Profile`	Optional; default `Asset`	Selects the `Asset` or `ConfigurationItem` profile.
`Site`	Site-specific	Replaces `{Site}` in profile queries and is sent in asset updates and work orders.
`WorkOrderEndpoint`	Optional; default `cxintmxwodetail/?lean=1`	Resource used to create work orders.

Equipment requests use the static object structure for the selected profile: MXAPIASSET for Asset, and CXMXAPIAUTHCI for ConfigurationItem.

Profiles

The selected profile section must exist under MaintenanceSystemIntegration:Providers:Maximo:

Asset identifies Maximo items by assetnum.
ConfigurationItem identifies Maximo items by cinum.

Both profiles support these settings:

Setting	Validation and default	Purpose
`ActiveStatus`	Required; default `OPERATING`	Active-status metadata.
`InactiveStatus`	Required; default `DECOMMISSIONED`	Inactive-status metadata.
`Query:Select`	Required; profile-specific default	OSLC fields and nested fields returned by Maximo.
`Query:Where`	Required; profile-specific default	OSLC filter. Every `{Site}` token is replaced with `Site`.
`Query:PageSize`	Positive; default `20`	Items requested per page. The provider follows `nextPage` links.
`Location:Resolver`	Default `Hierarchy`; required for CI	Uses hierarchy-first resolution when `Hierarchy`; other values prefer the location field.
`Location:SystemId`	Required for CI	Filters hierarchy elements to one Maximo location system.
`Location:PathSeparator`	Required; default `\`	Joins hierarchy nodes into an OT Backup location path.
`Selection:ElementsField`	Required when `Selection` exists	Response field containing elements used to include or exclude an item.
`Selection:ElementIndex`	Optional; zero or greater	Specific array element to evaluate. Omit to evaluate all elements.
`Selection:MatchField`	Required when `Selection` exists	Field read from the selected element.
`Selection:ExpectedValue`	Required when `Selection` exists	Case-insensitive value that `MatchField` must equal.
`UpdateTarget:Mode`	Default `EndpointAndIdentifier`	Selects the resource used for Maximo updates.

Preserve all fields needed by location resolution and field mappings when overriding Query:Select. Selection filters items after Maximo returns them. If ElementIndex is configured, confirm that the Maximo object structure returns elements in a stable, intentional order.

Update targets

Mode	Behavior
`EndpointAndIdentifier`	Builds the target from the selected profile's static object structure and `assetnum` or `cinum`.
`ReturnedHref`	Uses the item's `href` or `_href`. Include `href` in `Query:Select` if it is not returned by default.

For ReturnedHref, an absolute URL is accepted only when its scheme, host, and port match BaseUri. If Maximo does not return an href, the provider falls back to EndpointAndIdentifier.

Asset example

Put site-specific values and secrets in a protected override file.

{
  "MaintenanceSystemIntegration": {
    "Provider": "Maximo",
    "Providers": {
      "Maximo": {
        "BaseUri": "https://maximo.example/maximo/api/os/",
        "ApiKey": "<Maximo API key>",
        "HealthEndpoint": "health",
        "Profile": "Asset",
        "Site": "<site>",
        "Asset": {
          "Query": {
            "PageSize": 20
          },
          "Location": {
            "Resolver": "Hierarchy",
            "SystemId": "",
            "PathSeparator": "\\"
          },
          "Selection": {
            "ElementsField": "rel.assetlocation",
            "MatchField": "siteid",
            "ExpectedValue": "<site>"
          },
          "UpdateTarget": {
            "Mode": "EndpointAndIdentifier"
          }
        }
      }
    }
  }
}

Configuration Item example

Set Profile to ConfigurationItem and add the following profile under the Maximo provider. Replace the location-system and shop placeholders.

"ConfigurationItem": {
  "Query": {
    "Select": "cinum,description,status,changedate,href,rel.cilocation{location,address,addressline1},rel.cxlochierarchy{location,systemid,parent,lochierarchyid},cispec{assetattrid,alnvalue,refobjectid}",
    "Where": "ASSETLOCSITEID=\"{Site}\" and CILOCATION=\"*\" and status=\"OPERATING\"",
    "PageSize": 20
  },
  "Location": {
    "Resolver": "Hierarchy",
    "SystemId": "<location system>",
    "PathSeparator": "/"
  },
  "Selection": {
    "ElementsField": "rel.cxlochierarchy",
    "ElementIndex": 0,
    "MatchField": "location",
    "ExpectedValue": "<shop location>"
  },
  "UpdateTarget": {
    "Mode": "ReturnedHref"
  }
}