> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# IBM Maximo Manage

> Client-mode REST API connector for a curated IBM Maximo Manage (MAS) object-structure slice: work orders from alarms, meter readings, approved WO query, asset PATCH

Technical Preview

## Overview

A client-mode connector for a **curated CMMS / EAM** slice of the [IBM Maximo Manage REST/JSON APIs](https://www.ibm.com/docs/en/maximo-manage/cd?topic=reference-maximo-manage-rest-apis) (object structures under `https://YOUR_MAXIMO_HOST/maximo`):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST mxapiwodetail (work order from alarm) | `POST /api/os/mxapiwodetail?lean=1` | Create WO (lean JSON) |
| POST mxapimeterreading (run hours, counts) | `POST /api/os/mxapimeterreading?lean=1` | Meter reading; some installs need `x-method-override: SYNC` |
| GET mxapiwodetail?oslc.where=status=APPR | `GET /api/os/mxapiwodetail?oslc.where=status="APPR"&…` | Approved work orders |
| PATCH mxapiasset/\{id} | `PATCH /api/os/mxapiasset/{id}?lean=1` | Update asset; alternate POST + `x-method-override: PATCH` |

`BASE_ADDRESS` is `https://{host}/maximo` (no trailing slash; endpoints already include `/api/os/...`). Topics use `cmms/ibm-maximo-manage/<object>/<verb>`.

> [!NOTE]
>
> Prefer Hub secrets for API keys and passwords. This template has not been verified against a live Maximo Manage host. Status remains blocked until an authenticated live smoke succeeds.

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — IBM Maximo Manage (curated CMMS slice)
# Auth: apikey header {value.json.apikey} (or Basic via config)
# BASE_ADDRESS: https://YOUR_MAXIMO_HOST/maximo

DEFINE ROUTE IbmMaximoManageRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_MAXIMO_HOST/maximo"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Createworkorder
        WITH SOURCE_TOPIC "cmms/ibm-maximo-manage/mxapiwodetail/create"
        WITH DESTINATION_TOPIC "cmms/ibm-maximo-manage/mxapiwodetail/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/os/mxapiwodetail?lean=1"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "apikey" "{value.json.apikey}"
            ADD "properties" "*"
        WITH BODY "{payload}"
    ADD EVENT Createmeterreading
        WITH SOURCE_TOPIC "cmms/ibm-maximo-manage/mxapimeterreading/create"
        WITH DESTINATION_TOPIC "cmms/ibm-maximo-manage/mxapimeterreading/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/os/mxapimeterreading?lean=1"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "apikey" "{value.json.apikey}"
            ADD "properties" "*"
        WITH BODY "{payload}"
    ADD EVENT Listapprovedworkorders
        WITH SOURCE_TOPIC "cmms/ibm-maximo-manage/mxapiwodetail/list_appr"
        WITH DESTINATION_TOPIC "cmms/ibm-maximo-manage/mxapiwodetail/list_appr/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/os/mxapiwodetail?oslc.where={value.json.oslc_where}&oslc.select={value.json.oslc_select}&lean=1&oslc.pageSize={value.json.page_size}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "apikey" "{value.json.apikey}"
    ADD EVENT Patchasset
        WITH SOURCE_TOPIC "cmms/ibm-maximo-manage/mxapiasset/patch"
        WITH DESTINATION_TOPIC "cmms/ibm-maximo-manage/mxapiasset/patch/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/os/mxapiasset/{value.json.id}?lean=1"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "apikey" "{value.json.apikey}"
            ADD "properties" "*"
        WITH BODY "{payload}"
```

## Parameters

| Parameter | Required | Description |
| - | - | - |
| `BASE_ADDRESS` | Yes | `https://{host}/maximo` — Manage host, no trailing slash |
| `apikey` (MQTT JSON) | Yes\* | Maximo API key for the `apikey` request header (\*or use Basic config) |
| `USERNAME` / `PASSWORD` | Alt | Basic/LDAP via `WITH USERNAME` + `WITH PASSWORD GET SECRET "MAXIMO_PASSWORD"` |
| `oslc_where` | For list | e.g. `status="APPR"` (URL-encode as needed by your broker) |
| `oslc_select` | For list | e.g. `*` or `wonum,status,description,assetnum` |
| `page_size` | For list | `oslc.pageSize` value |
| `id` | For PATCH | Asset REST id (e.g. ASSETUID) |
| `{payload}` | POST/PATCH | Lean JSON body for the object structure |

## Authentication

* **API key (preferred for MAS 8.8+):** header `apikey: <key>`. Do not rely on maxauth for Manage integrations.
* **Basic / LDAP:** configure USERNAME + PASSWORD (GET SECRET) on `REST_API_CONFIG`.
* Prefer Hub secrets. Never commit real credentials.

## MQTT topics

| Event | Source topic | Method |
| - | - | - |
| Create WO | `cmms/ibm-maximo-manage/mxapiwodetail/create` | POST |
| Meter reading | `cmms/ibm-maximo-manage/mxapimeterreading/create` | POST |
| List APPR WOs | `cmms/ibm-maximo-manage/mxapiwodetail/list_appr` | GET |
| Patch asset | `cmms/ibm-maximo-manage/mxapiasset/patch` | PATCH |

Responses publish on the same topic with `/response` appended.

## Example payloads

**List approved work orders (smoke):**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "apikey": "YOUR_MAXIMO_API_KEY",
  "oslc_where": "status=\"APPR\"",
  "oslc_select": "*",
  "page_size": "5"
}
```

**Create work order from alarm:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "apikey": "YOUR_MAXIMO_API_KEY",
  "description": "IIoT alarm — high vibration Zone A",
  "siteid": "BEDFORD",
  "assetnum": "11430",
  "priority": 2,
  "worktype": "CM"
}
```

## Notes and version quirks

* Use `lean=1` so JSON bodies do not require namespaces.
* `properties: *` on writes asks Maximo to return selected fields in the create/update response.
* Native HTTP PATCH may not be enabled on every install; IBM docs often show `POST` + `x-method-override: PATCH` (+ optional `patchtype: MERGE`). Fork the Patchasset event if needed.
* Meter readings via `MXAPIMETERREADING` can require `x-method-override: SYNC` on some systems; an alternate is nested `assetmeter` updates on `MXAPIASSET`.
* Object structures must be enabled / authorized for the API user in Maximo.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [IBM Maximo REST API Guide — API keys](https://ibm-maximo-dev.github.io/maximo-restapi-documentation/authentication/apikey/)
* [Filtering with oslc.where](https://ibm-maximo-dev.github.io/maximo-restapi-documentation/query/filtering/)
* [Create and update resources](https://ibm-maximo-dev.github.io/maximo-restapi-documentation/crud/create_and_update/)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.