BMC Helix ITSM

Technical Preview

Overview

A client-mode connector for the BMC Helix ITSM 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.

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

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).
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).
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:

{"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):

{"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):

{"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):

{"token": "<jwt>", "query": "q=%27Incident%20Number%27%3D%22INC000000000701%22&fields=values(Request%20ID,Status)"}

{"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.

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.

Quick Start

Coreflux MQTT Broker

LoT Language

Coreflux HUB

VS Code - LoT Notebooks

Coreflux Portal

Using AI with Coreflux

Product Updates

Overview

Setup

Authentication

Examples

Events

Responses

Not packaged

Suggested branches

​Overview

​Setup

​Authentication

​Examples

​Events

​Responses

​Not packaged

​Suggested branches

Overview

Setup

Authentication

Examples

Events

Responses

Not packaged

Suggested branches