10. Alarm Service
Access via client.alarm(). Provides alarm inquiry · aggregation, confirmation, and hidden occurrence · service exclusion. All methods return ApiResult<T> — if isOk() is true, values are obtained via getData(). Alarm configuration (Config) management is handled by client.alarmConfig().
9.1 Method List
| Method | Return Type | HTTP | Endpoint |
|---|---|---|---|
get(alarm_seq) | ApiResult<AlarmResponse> | GET | /api/v5/alarm/{alarm_seq} |
list(limit) | ApiResult<List<AlarmResponse>> | GET | /api/v5/alarm?limit=... |
active(site_id, limit) | ApiResult<List<AlarmResponse>> | GET | /api/v5/alarm/active |
search(criteria) | ApiResult<List<AlarmResponse>> | GET | /api/v5/alarm/search |
readOne(alarm_seq, read_user_id) | ApiResult<Boolean> | PUT | /api/v5/alarm/{alarm_seq}/read |
batchRead(alarm_seqs, read_user_id) | ApiResult<AlarmBatchReadResponse> | POST | /api/v5/alarm/batch/read |
readAll(user_id) | ApiResult<Boolean> | POST | /api/v5/alarm/read/all |
deliveries(alarm_seq) | ApiResult<List<AlarmDeliveryResponse>> | GET | /api/v5/alarm/{alarm_seq}/deliveries |
suppressed(kind, asset_id, design_reason, ref_id, active, limit) | ApiResult<List<AlarmSuppressedResponse>> | GET | /api/v5/alarm/suppressed |
outOfService(active) | ApiResult<List<AlarmOutOfServiceResponse>> | GET | /api/v5/alarm/out-of-service |
takeOutOfService(request) | ApiResult<AlarmOutOfServiceResponse> | POST | /api/v5/alarm/out-of-service |
returnToService(out_of_service_id, force, note) | ApiResult<AlarmReturnToServiceResponse> | POST | /api/v5/alarm/out-of-service/{out_of_service_id}/return |
readOne · batchRead · readAll can be called if a token is provided. Since V5 tokens are issued only for ADMIN · API roles, the «Check All is ADMIN» distinction found in the console does not separately exist in V5.
It is
limit ≤ 1000.
In the path, read represents only the name. The server records one confirmation per alarm — Confirmation.
9.2 AlarmResponse DTO
Includes the alarm body and the result of the location (tag/opc/site) JOIN.
Alarm Body Fields
| Field | Type | Description |
|---|---|---|
alarm_seq | long | Alarm sequence (PK) |
alarm_config_id | String | Alarm configuration ID |
priority | String | Priority (INFO, WARN, ERROR) |
description | String | Alarm message |
is_on | Boolean | Currently active status |
acknowledged | Boolean | Whether it has been confirmed |
acknowledged_by | String | Confirmer — Login ID or Employee ID |
acknowledged_by_type | String | Confirmer type (USER, EMPLOYEE) |
acknowledged_at | Long | Confirmation time (milliseconds) |
on_timestamp | long | Occurrence time (milliseconds) |
off_timestamp | Long | Clearance time (null = Not cleared) |
on_duration | long | Duration (milliseconds) |
off_reason | String | Clearance reason — Alarm Clearance Reason |
band | String | Triggered band |
Hidden occurrences are not in this row. Read them via suppressed().
Location JOIN Fields (Included in 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) |
9.3 Alarm Priority
| Code | Display Text |
|---|---|
INFO | Info |
WARN | Warning |
ERROR | Critical |
9.4 Usage Examples
Recent Alarm List
import java.util.List;
import plantpulse.api.v5.dto.response.AlarmResponse;
import plantpulse.api.v5.result.ApiResult;
ApiResult<List<AlarmResponse>> result = client.alarm().list(50);
if (result.isOk()) {
for (AlarmResponse a : result.getData()) {
System.out.printf("[%s] %s - %s (%s)%n",
a.getPriority(),
a.getSite_name(),
a.getDescription(),
a.getTag_location());
}
}
Active Alarms
List<AlarmResponse> active = client.alarm().active("SITE_000001", 500).getData();
System.out.println("현재 활성 알람: " + active.size() + "건");
Unconfirmed Active Alarms
long unacked = client.alarm().active("SITE_000001", 500).getData().stream()
.filter(a -> !Boolean.TRUE.equals(a.getAcknowledged()))
.count();
Alarm Confirmation
The confirmer is the token user. Set read_user_id as null — entering a name different from the token user results in HTTP 422. If someone has already confirmed it, HTTP 409 alarm.already_acknowledged occurs, and the first record is maintained.
ApiResult<Boolean> r = client.alarm().readOne(12345L, null);
When confirming with an employee name, as in field apps, include the employee in the request header X-PP-Performed-By. In that case, acknowledged_by_type remains as EMPLOYEE.
Delivery History
Delivery records without read indicators — recipient_type · recipient_id · recipient_name · channel(CONSOLE, EMAIL, SMS, APP) · sent_at.
client.alarm().deliveries(12345L).getData().forEach(d ->
System.out.println(d.getRecipient_name() + " / " + d.getChannel()));
Hidden Occurrences
Occurrences hidden by temporary hiding, design suppression, or service exclusion. All filters can use null.
| Argument | Value |
|---|---|
kind | SHELVED, SUPPRESSED_BY_DESIGN, OUT_OF_SERVICE |
design_reason | MAINTENANCE, REPAIR (when SUPPRESSED_BY_DESIGN) |
ref_id | Cause ID — ALARM_SHELVE_…, Calendar ID, Maintenance Order ID, ALARM_OUT_OF_SERVICE_… |
active | true = Currently on |
limit | 1~1000 (Default 200) |
var hidden = client.alarm().suppressed("SUPPRESSED_BY_DESIGN", "ASSET_ID", "REPAIR", null, true, 100);
Service Exclusion and Return
Writing can only be performed with an ADMIN token. There is no automatic return. If the return inspection is rejected, HTTP 422 occurs and service exclusion is maintained.
| Rejection | HTTP | Code |
|---|---|---|
| Already under service exclusion | 409 | alarm.oos.already |
| Invalid reason value · memo · scheduled return | 422 | alarm.oos.reason_invalid · memo_required · window_invalid |
| Return inspection failure | 422 | alarm.oos.return_not_normal · return_no_value |
| Returning but no reason provided | 422 | alarm.oos.note_required |
| Already returned | 409 | alarm.oos.already_returned |
Set force to true and provide note to bypass inspection and return (return_check = FORCED). Valid reasons are SENSOR_REMOVED, EQUIPMENT_REMOVED, CALIBRATION, MODIFICATION, OTHER. Memos are mandatory for OTHER and safety/environmental alarms.
var r = client.alarm().returnToService("ALARM_OUT_OF_SERVICE_000001", false, null);
Alarm Configuration ID
New alarm configuration IDs are issued by the server (ALARM_CONFIG_ + 6 digits). Receive and use them via GET /api/v5/alarm/config/new-id; creating one with a manually devised ID results in HTTP 422 alarm.invalid.alarm_config_id. Band alarms are not created via API — they are created by the tag's alarm configuration (patchAlarm), and attempting to create a band via POST /alarm/config results in HTTP 409 alarm.band.edit_on_tag.
For tag band settings, do not devise an ID; find the one where alarm_config_priority is BAND in GET /api/v5/alarm/config/list/by-tag?tag_id=…. In the change history (/alarm/config/{alarm_config_id}/revisions), alarm_config_id may be null in rows for tags that do not yet have a band setting.
Alarm System Performance
There are no SDK methods. Read directly via V5 — GET /api/v5/alarm/performance?scope_type=SITE&scope_id=…&days=7. For metrics, see Alarm Performance.
Next Steps
- Tag Service — Set alarm thresholds via
patchAlarm - Path Service — Tree path of assets where alarms occurred