10. Alarm Service

Accessed via client.alarm(). It provides two functions: single-record and recent lookup of alarm events. If you need detailed statistics or alarm configuration (Config) CRUD, use the data gateway directly.

9.1 Method List

Method	Return Type	HTTP	Endpoint
get(alarm_seq)	AlarmResponseV5 or null	GET	/api/v5/alarm/{seq}
list(limit)	List<AlarmResponseV5>	GET	/api/v5/alarm?limit=...

limit ≤ 1000 is recommended. If you need more data, it is better to query the data gateway directly.

9.2 AlarmResponseV5 DTO

Includes the alarm body plus the JOIN results for location (tag/opc/site).

Alarm Body Fields

Field	Type	Description
alarm_seq	long	Alarm sequence (PK)
alarm_config_id	String	Alarm configuration ID
priority	String	Priority (HI_HI, HI, LO, LO_LO, TRIP)
description	String	Alarm message
is_on	String	Currently active or not (Y/N)
is_read	String	Read or not (Y/N)
on_timestamp	long	Occurrence time (milliseconds)
off_timestamp	long	Clear time (0 = not cleared)
on_duration	long	Duration (milliseconds)

Location JOIN Fields (included in the list response)

Field	Description
tag_id, tag_name, tag_description	Tag information
opc_id, opc_name	OPC information
site_id, site_name	Site information
tag_location	Asset path string (SITE > AREA > LINE > EQUIPMENT)

In the single-record get() response, only the mm_alarm body is populated, and the JOIN fields are often null. For UI display, using the list() result is recommended.

9.3 Alarm Priorities

Code	Meaning	Typical Color
HI_HI	Critical	Red
HI	Warning	Orange
LO	Info	Yellow
LO_LO	Recovery	Blue
TRIP	Trip (forced shutdown)	Black

9.4 Usage Examples

Recent Alarm List

import java.util.List;
import plantpulse.api.v5.dto.response.AlarmResponseV5;

List<AlarmResponseV5> alarms = client.alarm().list(50);
for (AlarmResponseV5 a : alarms) {
    System.out.printf("[%s] %s - %s (%s)%n",
        a.getPriority(),
        a.getSite_name(),
        a.getDescription(),
        a.getTag_location());
}

Example output:

[HI_HI] 대전공장 - Spindle 온도 임계치 초과 (SITE_DJ > A_0001 > L_0001 > CNC #1)
[HI]    대전공장 - 압력 상한 (SITE_DJ > A_0001 > L_0001 > Press #2)

Single-Record Lookup

AlarmResponseV5 alarm = client.alarm().get(12345L);
if (alarm != null) {
    System.out.println("발생 시각: " + alarm.getOn_timestamp());
    System.out.println("우선순위: " + alarm.getPriority());
    System.out.println("지속 시간: " + alarm.getOn_duration() + " ms");
}

Filtering Active Alarms Only (Client Side)

V5 does not support server-side active filtering, so handle it on the client.

import java.util.stream.Collectors;

List<AlarmResponseV5> active = client.alarm().list(500).stream()
        .filter(a -> "Y".equals(a.getIs_on()))
        .collect(Collectors.toList());

System.out.println("현재 활성 알람: " + active.size() + "건");

Grouping by Site

import java.util.Map;
import java.util.stream.Collectors;

Map<String, Long> bySite = client.alarm().list(1000).stream()
        .filter(a -> "Y".equals(a.getIs_on()))
        .collect(Collectors.groupingBy(
                AlarmResponseV5::getSite_id,
                Collectors.counting()));

bySite.forEach((siteId, count) ->
    System.out.printf("%s: %d건%n", siteId, count));

Count by Priority

Map<String, Long> byPriority = client.alarm().list(1000).stream()
        .collect(Collectors.groupingBy(
                AlarmResponseV5::getPriority,
                Collectors.counting()));

9.5 Application Scenarios

Scenario — Real-Time Alarm Dashboard

while (running) {
    List<AlarmResponseV5> alarms = client.alarm().list(100);

    long critical = alarms.stream()
            .filter(a -> "Y".equals(a.getIs_on()))
            .filter(a -> "HI_HI".equals(a.getPriority()))
            .count();

    updateDashboard(alarms, critical);
    Thread.sleep(1_000);
}

Scenario — Alarms from a Specific Asset Line Only

String targetLine = "SITE_DJ > A_0001 > L_0001";

List<AlarmResponseV5> lineAlarms = client.alarm().list(500).stream()
        .filter(a -> a.getTag_location() != null
                  && a.getTag_location().startsWith(targetLine))
        .collect(Collectors.toList());

Next Steps

• Tag Service — set alarm thresholds with patchAlarm
• Path Service — tree path of the asset where the alarm occurred