Skip to main content

Alarm

Represents an alarm triggered by abnormal asset conditions or sample results.
export interface Alarm {
  id: string;
  parameter: string;
  site: {
    id: string;
    name?: string;
  };
  first_detected: string;
  acknowledged_status: boolean;
  linked_recommendations: {
    id: string;
    title?: string;
  }[];
  created_at_datetime: string;
  updated_at_datetime: string;
}

Fields

id
string
required
Unique identifier for the alarm
parameter
string
required
The parameter that triggered the alarm (e.g., “Iron Content”, “Viscosity”, “Water Contamination”)
site
object
required
Reference to the site where the alarm was triggered
first_detected
string
required
ISO 8601 timestamp when the alarm was first detected
acknowledged_status
boolean
required
Indicates whether the alarm has been acknowledged by a user
  • true: Alarm has been acknowledged
  • false: Alarm is unacknowledged and requires attention
linked_recommendations
array
required
Array of recommendations linked to this alarm
created_at_datetime
string
required
ISO 8601 timestamp when alarm record was created
updated_at_datetime
string
required
ISO 8601 timestamp when alarm record was last updated

Alarm Workflow

1

Detection

Alarm is automatically triggered when a monitored parameter exceeds thresholds
2

Notification

Relevant personnel are notified of the alarm
3

Acknowledgment

User acknowledges the alarm, setting acknowledged_status to true
4

Action

User creates or links recommendations to address the root cause

AlarmFilters

Filter options for querying alarms.
export interface AlarmFilters {
  search?: string;
  parameter?: string;
  acknowledged_status?: string;
  site?: string;
}

Fields

Search term for general text search across alarm fields
parameter
string
Filter by specific parameter type
acknowledged_status
string
Filter by acknowledgment status
  • "true": Show only acknowledged alarms
  • "false": Show only unacknowledged alarms
  • Omit to show all alarms
site
string
Filter by site ID

AlarmAnalytics

Comprehensive analytics for alarm monitoring and forecasting.
export interface AlarmAnalytics {
  total_alarms: number;
  alarm_trend: {
    growth: number;
    percentage: number;
  };
  open_overdue_alarms: number;
  open_overdue_trend: {
    growth: number;
    percentage: number;
  };
  forecast_alarms: number;
  forecast_trend: {
    growth: number;
    percentage: number;
  };
}

Fields

total_alarms
number
required
Total number of alarms in the system
alarm_trend
object
required
Trend data for total alarms compared to previous period
open_overdue_alarms
number
required
Number of alarms that are open and overdue for action
open_overdue_trend
object
required
Trend data for open/overdue alarms
forecast_alarms
number
required
Predicted number of alarms for the next period based on historical trends
forecast_trend
object
required
Trend data for forecasted alarms

Usage Example

import type { Alarm, AlarmFilters, AlarmAnalytics } from '@/types';

// Query unacknowledged alarms for a specific site
const filters: AlarmFilters = {
  site: 'site_123',
  acknowledged_status: 'false'
};

const alarms: Alarm[] = await getAlarms(filters);

// Process alarms
alarms.forEach((alarm: Alarm) => {
  console.log(`Alarm: ${alarm.parameter}`);
  console.log(`Site: ${alarm.site.name}`);
  console.log(`First Detected: ${alarm.first_detected}`);
  console.log(`Acknowledged: ${alarm.acknowledged_status}`);
  console.log(`Linked Recommendations: ${alarm.linked_recommendations.length}`);
});

// Display analytics
const analytics: AlarmAnalytics = await getAlarmAnalytics();

console.log(`Total Alarms: ${analytics.total_alarms}`);
console.log(`Alarm Trend: ${analytics.alarm_trend.percentage}%`);
console.log(`Open/Overdue: ${analytics.open_overdue_alarms}`);
console.log(`Forecast: ${analytics.forecast_alarms} alarms predicted`);

Common Alarm Parameters

Triggered when wear metal concentrations exceed normal thresholds:
  • High Iron (Fe)
  • Elevated Copper (Cu)
  • Abnormal Chromium (Cr)
  • Excessive Aluminum (Al)
Triggered by contamination detection:
  • Water contamination
  • Fuel dilution
  • Glycol presence (coolant leak)
  • High soot levels
Triggered by changes in oil properties:
  • Viscosity increase/decrease
  • High particle counts
  • Abnormal TAN (Total Acid Number)
  • Low TBN (Total Base Number)
Triggered by operational conditions:
  • Overdue sampling
  • Missed maintenance
  • Critical asset status change

Acknowledgment Flow

import { acknowledgeAlarm } from '@/actions/alarms';

// Acknowledge an alarm
const result = await acknowledgeAlarm(alarmId);

if (result.success) {
  console.log('Alarm acknowledged successfully');
  
  // Optionally link a recommendation
  await linkAlarmToRecommendation(alarmId, recommendationId);
}
Acknowledging an alarm does not close it—it indicates that the alarm has been reviewed and action is being taken. Link recommendations to track corrective actions.

Sample Types

Sample analysis results trigger alarms

Recommendation Types

Alarms are linked to recommendations for corrective action

Build docs developers (and LLMs) love