Sending Alerts to External CMMS

Overview

This document outlines how Turbomechanica forwards alerts to an external CMMS system and how updates to service requests (SR) can be handled when changes occur on the CMMS side.

1. Sending an Alert to CMMS

When an alert is triggered in our system, it can be forwarded to the external CMMS system as a service request.

Request Payload

The API sends the following JSON payload when an alert is forwarded:

Required Fields:

ALERT_ID (string): Unique identifier for the alert triggering the service request.
FACILITY_ID (string): Facility ID associated with the service request.
USER_EMAIL (string): Email address of the user reporting the issue.
ALERT_LEVEL (string): Severity level of the alert (e.g., Critical, High, Medium, Low).
ALERT_IDENTIFIER (string): Unique identifier related to the specific alert type.
CUSTOMER_ASSET_ID (string): Unique identifier of the customer asset requiring service.
SR_REQUEST_DATE (string, UTC format): Date and time the service request is submitted.
ALERT_INSIGHT (string): Additional details or insights related to the alert.
MECHADEMY_URL (string): Link to Alert on Turbomechanica platform.

Example Request

{
  "ALERT_ID": "ABC123",
  "FACILITY_ID": "FAC001",
  "USER_EMAIL": "user@example.com",
  "ALERT_LEVEL": "Critical",
  "ALERT_IDENTIFIER": "SENSOR_FAILURE",
  "ALERT_INSIGHT": "Sensor XYZ reports abnormal readings.",
  "CUSTOMER_ASSET_ID": "ASSET-1234",
  "SR_REQUEST_DATE": "2024-04-19T10:00:00.000Z",
  "MECHADEMY_URL": "https://next.turbomechanica.ai/facility/1/equipment/5/events/3"
}

Expected Response

Upon successfully creating a service request, the external system will return a response confirming the request status.

Success Response

{
  "ALERT_ID": "ABC123",
  "ORG_ID": "12345",
  "SR_TICKET_ID": "SR-98765",
  "STATUS": "Success"
}

Response Fields:

ALERT_ID: The original alert identifier provided in the request.
ORG_ID: The organization ID associated with the service request. (Optional)
SR_TICKET_ID: The unique ID of the created service ticket. (Optional)
STATUS: "Success" indicating successful service request creation.
Valid Values for STATUS:
- Success: Indicates the service request was successfully created.
- Failure: Indicates the service request creation failed.
- Queued: Indicates the service request is queued for processing.

Failure Response

{
  "ALERT_ID": "ABC123",
  "STATUS": "Failure",
  "STATUS_REASON": "Invalid customer asset ID"
}

Response Fields:

ALERT_ID: The original alert identifier provided in the request.
STATUS: "Failure" indicating unsuccessful service request creation.
STATUS_REASON: A descriptive message explaining the reason for failure.

2. Updating an Alert When SR is Updated in CMMS

When the service request is updated on the external system, our system must be notified to update the corresponding alert.

Update Request Payload

The update request allows modification of various SR fields:

{
  "SR_TICKET_ID": "SR-98765",  // Optional
  "SRSTATUS": "IN_PROGRESS",
  "SRFINISHDATE": "2024-04-20T15:30:00.000Z",
  "WORKLOGS": [
    {
      "LOGID": "LOG001",
      "LOGCREATEDDATE": "2024-04-19T11:00:00.000Z",
      "LOGDESCRIPTION": "Technician assigned.",
      "LOGLONGDESCRIPTION": "Technician John Doe has been assigned to inspect the sensor issue."
    }
  ],
  "SROWNER": "JohnDoe",
  "SRREPORTEDPRIORITY": 2,
  "WONUMBER": "WO-56789",
  "WODESCRIPTION": "Replace faulty sensor"
}

Valid Values for SRSTATUS

FAILED: Indicates that the service request update has failed.
ACKNOWLEDGED: Indicates that the service request has been acknowledged by the responsible party.
RESOLVED: Indicates that the service request has been resolved.
IN_PROGRESS: Indicates that the service request is currently being worked on.
DISCARDED: Indicates that the service request has been discarded and will not be processed further.
QUEUED: Indicates that the service request update is queued for processing.

Update API Endpoints

Update Using SR ID

PATCH https://$ORG_BASE_URL/service-requests/external/{external_sr_ticket_id}

Update Using ALERT ID

PATCH https://$ORG_BASE_URL/service-requests/external/alert/{alert_id}

Authentication

The API requires authentication using either of the following methods:

AuthBearer
JWTAuth

Response Schema

The API returns a response confirming whether the update was successful or failed.

Success Response

{
  "id": 0,
  "alert": 0,
  "name": "string",
  "description": "string",
  "external_id": "string",
  "status": 0,
  "created_at": "2025-02-24T06:41:08.194Z",
  "acknowledged_at": "2025-02-24T06:41:08.194Z",
  "dispatched_at": "2025-02-24T06:41:08.194Z",
  "resolved_at": "2025-02-24T06:41:08.194Z",
  "logs": {},
  "work_orders": {},
  "updated_at": "2025-02-24T06:41:08.194Z",
  "asset_id": "string",
  "insights": "string",
  "level": 0,
  "owner": "string"
}

Failure Response (Alert Not Found)

{
  "detail": "Not Found"
}

A 404 Not Found response is returned if no alert is found for the given external_sr_ticket_id or alert_id, following the standard Django Ninja response pattern.

Authentication & Security

All API requests must include a valid authentication token in the Authorization header.
Unauthorized requests will return a 401 Unauthorized response.
API keys or tokens should be securely stored and never exposed publicly.

Turbomechanica Docs