> ## 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.

# BMC Helix ITSM

> Client-mode REST API connector for BMC Helix ITSM: open, look up, annotate and resolve incidents from plant events, raise problems, changes, tasks and service requests, find CMDB CIs, and reach any AR System form

Technical Preview

## Overview

A client-mode connector for the [BMC Helix ITSM platform REST API](https://docs.helixops.ai/bin/Service-Management/IT-Service-Management/BMC-Helix-ITSM/itsm252/Developing/Integrating-third-party-applications-with-BMC-Helix-ITSM-by-using-the-platform-REST-API/Overview-of-the-platform-REST-API/), which is the AR System (Remedy) REST API underneath. When a machine, line or edge gateway goes into alarm, the broker can open an incident through the `HPD:IncidentInterface_Create` form, find it again on `HPD:Help Desk`, add work info while the condition evolves and resolve it through `HPD:IncidentInterface` when it clears. Recurring faults can become problem investigations, planned work such as PLC firmware updates can become change requests with linked CIs, and spare parts can be ordered as service requests. Generic entry, merge, association and field-metadata events reach any other AR System form.

One connector carries 30 events (13 GET, 12 POST, 5 PUT; 15 writes, no DELETE). Topics use `itsm/bmc-helix-itsm/<object>/<verb>`; each response is published on `<source topic>/response`.

> [!NOTE]
>
> The template was checked against BMC's published REST API documentation and a local AR REST emulator. BMC does not publish an OpenAPI file for this API, and every BMC Helix tenant has its own host, so the template has **not** been run against a real tenant yet; status stays blocked until an authenticated smoke passes.

## Setup

1. Replace the placeholder `BASE_ADDRESS` (`https://your-tenant-restapi.onbmc.com`) with your REST host. BMC Helix SaaS tenants use `https://<tenant>-restapi.onbmc.com`; on-premises servers use their own REST host and port over HTTPS (plain HTTP answers `403` except for `/api/about` and `/api/version`).
2. Ask your BMC administrator for an integration user (an AR System user with a fixed or floating license and the Incident, Change, Problem or Asset permissions you need, plus a People record with support company and group for creating records).
3. Keep the username and password in broker secrets (for example `BMC_HELIX_USERNAME` and `BMC_HELIX_PASSWORD`) and build the login body in a LoT action with `GET SECRET`. Never retain topics that carry the password or the token.

## Authentication

The AR REST API uses a JSON Web Token. Publish a form-encoded body to `itsm/bmc-helix-itsm/auth/login`:

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{"body": "username=coreflux.integration&password=<password>"}
```

The response on `itsm/bmc-helix-itsm/auth/login/response` is the raw token text, valid for one hour. Send it as `token` in every other payload; the connector turns it into `Authorization: AR-JWT <token>`. Log in again before the hour is up, and publish `{"token":"..."}` to `itsm/bmc-helix-itsm/auth/logout` when the integration stops.

## Examples

Open an incident when a press overheats (`itsm/bmc-helix-itsm/incidents/create`):

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{"token": "<jwt>", "body": {"values": {"First_Name": "Coreflux", "Last_Name": "Integration", "Description": "Press 7 overtemperature (94 C)", "Impact": "3-Moderate/Limited", "Urgency": "2-High", "Status": "Assigned", "Reported Source": "Direct Input", "Service_Type": "Infrastructure Event", "z1D_Action": "CREATE"}}}
```

The response carries the new `Incident Number`. Add work info as the temperature falls (`itsm/bmc-helix-itsm/incidents/worklog/add`):

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{"token": "<jwt>", "body": {"values": {"Incident Number": "INC000000000701", "Description": "Spindle temp 88 C and falling", "Work Log Type": "General Information"}, "mergeOptions": {"mergeType": "DUP_NEW_ID"}}}
```

Find the interface record (`itsm/bmc-helix-itsm/incidents/interface/list`) and resolve it (`itsm/bmc-helix-itsm/incidents/interface/update`):

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{"token": "<jwt>", "query": "q=%27Incident%20Number%27%3D%22INC000000000701%22&fields=values(Request%20ID,Status)"}
```

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{"token": "<jwt>", "id": "<Request ID>", "body": {"values": {"Status": "Resolved", "Status_Reason": "No Further Action Required", "Resolution": "Temperature back to 61 C"}}}
```

Search values are sent as given, so URL-encode AR qualifications (`'Status' = "Assigned"` becomes `q=%27Status%27%20%3D%20%22Assigned%22`) and form names in `form` (`HPD:Help Desk` becomes `HPD%3AHelp%20Desk`). Lists page with `offset` and `limit` and sort with `sort=Submit%20Date.desc`.

> [!TIP]
>
> Field names such as `Service_Type`, `Status_Reason` or `Change Request Status` are BMC's defaults. Tenants are often customised, so read the real names with `itsm/bmc-helix-itsm/forms/fields/list` (`{"token":"...","form":"HPD%3AIncidentInterface_Create","query":"field_type=A"}`) before mapping plant data.

## Events

| Event | Method | Endpoint | Source topic | Write | Notes |
| - | - | - | - | - | - |
| `AboutGet` | `GET` | `/api/about` | `itsm/bmc-helix-itsm/server/about` | | Keyless smoke: AR System server info. Allowed without a token (and the only endpoint besides /api/version that answers over plain HTTP). |
| `TokenLogin` | `POST` | `/api/jwt/login` | `itsm/bmc-helix-itsm/auth/login` | | Get a JWT (valid 1 hour). body is a form-encoded STRING: "username=coreflux.integration\&password=..." (optional authString header not packaged). Response body is the raw token text; send it as payload field token on every other event. |
| `TokenLogout` | `POST` | `/api/jwt/logout` | `itsm/bmc-helix-itsm/auth/logout` | | Release the token when the integration stops. |
| `IncidentCreate` | `POST` | `/api/arsys/v1/entry/HPD:IncidentInterface_Create?fields=values(Incident%20Number)` | `itsm/bmc-helix-itsm/incidents/create` | Yes | Catalog 'POST entry/HPD:IncidentInterface\_Create'. body: \{"values":\{"First\_Name":"Coreflux","Last\_Name":"Integration","Description":"Press 7 overtemperature","Impact":"3-Moderate/Limited","Urgency":"2-High","Status":"Assigned","Reported Source":"Direct Input","Service\_Type":"Infrastructure Event","z1D\_Action":"CREATE"}}. 201 + Location; response values carry the Incident Number. |
| `IncidentCreateGet` | `GET` | `/api/arsys/v1/entry/HPD:IncidentInterface_Create/{value.json.id}` | `itsm/bmc-helix-itsm/incidents/create/get` | | Read back a create-interface record. id = Request ID from the Location header of IncidentCreate. |
| `IncidentsList` | `GET` | `/api/arsys/v1/entry/HPD:Help%20Desk?{value.json.query}` | `itsm/bmc-helix-itsm/incidents/list` | | Catalog 'GET entry/HPD:Help Desk'. query e.g. q=%27Status%27%3C%224%22%20AND%20%27Description%27%20LIKE%20%22%25Press%207%25%22\&fields=values(Incident%20Number,Status,Description)\&limit=20\&sort=Submit%20Date.desc (URL-encoded AR qualification). |
| `IncidentGet` | `GET` | `/api/arsys/v1/entry/HPD:Help%20Desk/{value.json.id}` | `itsm/bmc-helix-itsm/incidents/get` | | One incident on HPD:Help Desk by entry id (Entry ID / Request ID). |
| `IncidentUpdate` | `PUT` | `/api/arsys/v1/entry/HPD:Help%20Desk/{value.json.id}` | `itsm/bmc-helix-itsm/incidents/update` | Yes | Catalog 'PUT entry/HPD:Help Desk/\{id}'. body: \{"values":\{"Status":"In Progress"}}. 204. BMC recommends IncidentInterfaceUpdate for status changes so ITSM workflow runs. |
| `IncidentInterfaceList` | `GET` | `/api/arsys/v1/entry/HPD:IncidentInterface?{value.json.query}` | `itsm/bmc-helix-itsm/incidents/interface/list` | | Find the interface Request ID for an incident. query e.g. q=%27Incident%20Number%27%3D%22INC000000000701%22\&fields=values(Request%20ID,Status). |
| `IncidentInterfaceUpdate` | `PUT` | `/api/arsys/v1/entry/HPD:IncidentInterface/{value.json.id}` | `itsm/bmc-helix-itsm/incidents/interface/update` | Yes | Documented way to modify an incident. id = Request ID on HPD:IncidentInterface. body: \{"values":\{"Status":"Resolved","Status\_Reason":"No Further Action Required","Resolution":"Temperature back to normal"}}. 204. |
| `IncidentWorkLogAdd` | `POST` | `/api/arsys/v1/mergeEntry/HPD:WorkLog` | `itsm/bmc-helix-itsm/incidents/worklog/add` | Yes | Work info on an incident. body: \{"values":\{"Incident Number":"INC000000000701","Description":"Spindle temp 88 C and falling","Detailed Description":"...","Work Log Type":"General Information"},"mergeOptions":\{"mergeType":"DUP\_NEW\_ID"}}. |
| `IncidentWorkLogsList` | `GET` | `/api/arsys/v1/entry/HPD:WorkLog?{value.json.query}` | `itsm/bmc-helix-itsm/incidents/worklog/list` | | query e.g. q=%27Incident%20Number%27%3D%22INC000000000701%22\&sort=Submit%20Date.desc\&limit=20. |
| `ProblemCreate` | `POST` | `/api/arsys/v1/entry/PBM:ProblemInterface_Create?fields=values(Problem%20Investigation%20ID)` | `itsm/bmc-helix-itsm/problems/create` | Yes | Recurring machine faults. body: \{"values":\{"z1D\_Action":"PROBLEM","Status":"Draft","Investigation Driver":"High Impact Incident","First Name":"Coreflux","Last Name":"Integration","Company":"...","Description":"Press 7 overheats weekly","Impact":"2-Significant/Large","Urgency":"2-High"}}. |
| `ChangeCreate` | `POST` | `/api/arsys/v1/entry/CHG:ChangeInterface_Create` | `itsm/bmc-helix-itsm/changes/create` | Yes | body: \{"values":\{"z1D\_Action":"CREATE","First Name":"Coreflux","Last Name":"Integration","Description":"Firmware update line 2 PLCs","Impact":"3-Moderate/Limited","Urgency":"3-Medium","Status":"Draft","Company":"...","Location Company":"...","Change Type":"Change","Change Timing":"Normal"}}. 201 + Location. |
| `ChangesList` | `GET` | `/api/arsys/v1/entry/CHG:ChangeInterface?{value.json.query}` | `itsm/bmc-helix-itsm/changes/list` | | query e.g. q=%27Change%20Request%20Status%27%3D%22Scheduled%22\&limit=20 (field names vary by version; check FieldsList). |
| `ChangeUpdate` | `PUT` | `/api/arsys/v1/entry/CHG:ChangeInterface/{value.json.id}` | `itsm/bmc-helix-itsm/changes/update` | Yes | id = Request ID on CHG:ChangeInterface. body: \{"values":\{"Change Request Status":"Completed","Status Reason":"Final Review Complete"}}. 204. |
| `ChangeWorkLogAdd` | `POST` | `/api/arsys/v1/entry/CHG:WorkLog` | `itsm/bmc-helix-itsm/changes/worklog/add` | Yes | Work info on a change. body: \{"values":\{"Infrastructure Change ID":"CRQ000000000101","Description":"Line 2 PLC 3 flashed","Work Log Type":"General Information"}}. |
| `ChangeCIAssociate` | `POST` | `/api/arsys/v1/entry/CHG:Associations` | `itsm/bmc-helix-itsm/changes/associations/add` | Yes | Link a CI (asset) to a change. body: \{"values":\{...}} with the change id, CI reconciliation id and association type (field names from FieldsList on CHG:Associations). |
| `TaskCreate` | `POST` | `/api/arsys/v1/entry/TMS:Task` | `itsm/bmc-helix-itsm/tasks/create` | Yes | Task under an incident or change. body: \{"values":\{"TaskName":"Inspect press 7","Summary":"...","TaskType":"Manual","Status":"Pending","RootRequestName":"INC000000000701","RootRequestID":"INC000000000701","RootRequestInstanceID":"...","RootRequestFormName":"HPD:Help Desk","RootRequestMode":"0","Company":"...","Location Company":"..."}}. |
| `TasksList` | `GET` | `/api/arsys/v1/entry/TMS:TaskInterface?{value.json.query}` | `itsm/bmc-helix-itsm/tasks/list` | | query e.g. q=%27RootRequestID%27%3D%22INC000000000701%22\&limit=20. |
| `TaskUpdate` | `PUT` | `/api/arsys/v1/entry/TMS:TaskInterface/{value.json.id}` | `itsm/bmc-helix-itsm/tasks/update` | Yes | body: \{"values":\{"Status":"Closed"}}. 204. |
| `ServiceRequestCreate` | `POST` | `/api/arsys/v1/entry/SRM:RequestInterface_Create` | `itsm/bmc-helix-itsm/service-requests/create` | Yes | Spare-part or service request. body: \{"values":\{"z1D Action":"CREATE","Source Keyword":"Coreflux","TitleInstanceID":"\<offering instance id>","First Name":"...","Last Name":"...","Short Description":"Replace press 7 thermocouple","Status":"Submitted","Company":"..."}}. |
| `AssetCIsList` | `GET` | `/api/arsys/v1/entry/AST:BaseElement?{value.json.query}` | `itsm/bmc-helix-itsm/assets/cis/list` | | Find the CMDB CI for a plant asset (needs Asset Management). query e.g. q=%27Name%27%3D%22PRESS-07%22\&fields=values(Name,Reconciliation%20Identity,Status). |
| `EntriesList` | `GET` | `/api/arsys/v1/entry/{value.json.form}?{value.json.query}` | `itsm/bmc-helix-itsm/entries/list` | | Generic search on any form. form must be URL-encoded (e.g. HPD%3AHelp%20Desk); query uses q, fields, offset, limit, sort. |
| `EntryGet` | `GET` | `/api/arsys/v1/entry/{value.json.form}/{value.json.id}` | `itsm/bmc-helix-itsm/entries/get` | | Generic: one entry on any form. |
| `EntryAssociationsGet` | `GET` | `/api/arsys/v1/entry/{value.json.form}/{value.json.id}/assoc/{value.json.association}` | `itsm/bmc-helix-itsm/entries/associations/get` | | Generic: entries linked to an entry through an association. |
| `EntryCreate` | `POST` | `/api/arsys/v1/entry/{value.json.form}` | `itsm/bmc-helix-itsm/entries/create` | Yes | Generic create on any form. body: \{"values":\{...}}. 201 + Location. |
| `EntryUpdate` | `PUT` | `/api/arsys/v1/entry/{value.json.form}/{value.json.id}` | `itsm/bmc-helix-itsm/entries/update` | Yes | Generic modify. body: \{"values":\{...}}. 204. |
| `EntryMerge` | `POST` | `/api/arsys/v1/mergeEntry/{value.json.form}` | `itsm/bmc-helix-itsm/entries/merge` | Yes | Generic merge (upsert by qualification). body: \{"values":\{...},"mergeOptions":\{"mergeType":"DUP\_MERGE","multimatchOption":0},"qualification":"'Name' = "PRESS-07""}. |
| `FieldsList` | `GET` | `/api/arsys/v1.0/fields/{value.json.form}?{value.json.query}` | `itsm/bmc-helix-itsm/forms/fields/list` | | Field metadata for a form (names and ids to use in values and q). query e.g. field\_type=A or field\_ids=1,7,8 (not both). |

## Responses

Successful reads answer `200` with `entries` (lists) or `values` (one entry). Creates answer `201` with a `Location` header pointing at the new entry (plus the requested `fields=values(...)` in the body); updates answer `204` with no body. Errors come back as a JSON array of AR System messages (`messageType`, `messageNumber`, `messageText`, `messageAppendedText`).

## Not packaged

* All DELETE endpoints on purpose.
* Attachments (`/attach/{fieldName}`), menus, the simplified ITSM REST API, CMDB REST API (`/api/cmdb/v1`), Smart IT and Digital Workplace APIs.
* The incoming direction: BMC Helix can call outbound REST webhooks from workflow; those can post to a separate `ENABLE_SERVER` REST\_API connector.

## Suggested branches

`feat/rest-api-route-bmc-helix-itsm` for the broker template and `feat/docs-rest-api-bmc-helix-itsm` for this page.


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