10. Alarm-Service
Der Zugriff erfolgt über client.alarm(). Es werden Funktionen zur Abfrage, Aggregation, Bestätigung sowie zum Ausblenden und Ausnehmen von Alarmen aus dem Service bereitgestellt. Alle Methoden geben ApiResult<T> zurück — wenn isOk() wahr ist, wird der Wert über getData() abgerufen. Die Verwaltung der Alarmkonfiguration (Config) erfolgt über client.alarmConfig().
9.1 Methodenübersicht
| Methode | Rückgabetyp | HTTP | Endpunkt |
|---|---|---|---|
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 können aufgerufen werden, sofern ein Token vorliegt. Da V5-Token nur für die Rollen ADMIN · API ausgestellt werden, gibt es in V5 keine separate Unterscheidung wie «Alle Bestätigungen sind ADMIN» in der Konsole.
Es handelt sich um
limit ≤ 1000.
In dem Pfad wurde read auf den Namen reduziert. Der Server zeichnet eine Bestätigung pro Alarm auf — Bestätigung.
9.2 AlarmResponse DTO
Enthält den Alarmkörper sowie die JOIN-Ergebnisse der Position (Tag/OPC/Site).
Felder des Alarmkörpers
| Feld | Typ | Beschreibung |
|---|---|---|
alarm_seq | long | Alarm-Sequenz (PK) |
alarm_config_id | String | Alarm-Konfigurations-ID |
priority | String | Priorität (INFO, WARN, ERROR) |
description | String | Alarmmeldung |
is_on | Boolean | Aktueller Aktivstatus |
acknowledged | Boolean | Ob bestätigt |
acknowledged_by | String | Bestätigende Person — Login-ID oder Mitarbeiter-ID |
acknowledged_by_type | String | Art des Bestätigenden (USER, EMPLOYEE) |
acknowledged_at | Long | Bestätigungszeitpunkt (Millisekunden) |
on_timestamp | long | Eintrittszeitpunkt (Millisekunden) |
off_timestamp | Long | Rücktrittszeitpunkt (null = nicht zurückgetreten) |
on_duration | long | Dauer (Millisekunden) |
off_reason | String | Rücktrittsgrund — Alarm-Rücktrittsgrund |
band | String | Ausgelöster Band |
Ausgeblendete Ereignisse sind in dieser Zeile nicht enthalten. Diese werden über suppressed() gelesen.
Position-JOIN-Felder (in List-Antworten enthalten)
| Feld | Beschreibung |
|---|---|
tag_id, tag_name, tag_description | Tag-Informationen |
opc_id, opc_name | OPC-Informationen |
site_id, site_name | Site-Informationen |
tag_location | Asset-Pfad-String (SITE > AREA > LINE > EQUIPMENT) |
9.3 Alarm-Priorität
| Code | Anzeige |
|---|---|
INFO | Information |
WARN | Warnung |
ERROR | Kritisch |
9.4 Anwendungsbeispiele
Aktuelle Alarmliste
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());
}
}
Aktive Alarme
List<AlarmResponse> active = client.alarm().active("SITE_000001", 500).getData();
System.out.println("현재 활성 알람: " + active.size() + "건");
Unbestätigte aktive Alarme
long unacked = client.alarm().active("SITE_000001", 500).getData().stream()
.filter(a -> !Boolean.TRUE.equals(a.getAcknowledged()))
.count();
Alarmbestätigung
Die bestätigende Person ist der Token-Benutzer. read_user_id wird als null gesetzt — wenn ein anderer Name als der Token-Benutzer eingegeben wird, erfolgt ein HTTP 422. Falls bereits jemand bestätigt hat, erfolgt ein HTTP 409 alarm.already_acknowledged und der ursprüngliche Eintrag bleibt bestehen.
ApiResult<Boolean> r = client.alarm().readOne(12345L, null);
Wenn die Bestätigung mit dem Namen eines Mitarbeiters erfolgt (wie in Vor-Ort-Apps), wird der Mitarbeiter im Request-Header X-PP-Performed-By übertragen. In diesem Fall bleibt acknowledged_by_type als EMPLOYEE stehen.
Versandhistorie
Dies ist die Versandhistorie ohne Lesebestätigung — 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()));
Ausgeblendete Ereignisse
Ereignisse, die durch temporäres Ausblenden, Design-Unterdrückung oder Ausschluss aus dem Service verborgen sind. Alle Filter können null verwenden.
| Argument | Wert |
|---|---|
kind | SHELVED, SUPPRESSED_BY_DESIGN, OUT_OF_SERVICE |
design_reason | MAINTENANCE, REPAIR (bei SUPPRESSED_BY_DESIGN) |
ref_id | Ursachen-ID — ALARM_SHELVE_…, Kalender-ID, Wartungsauftrags-ID, ALARM_OUT_OF_SERVICE_… |
active | true = momentan aktiv |
limit | 1~1000 (Standard 200) |
var hidden = client.alarm().suppressed("SUPPRESSED_BY_DESIGN", "ASSET_ID", "REPAIR", null, true, 100);
Service-Ausschluss und Rückkehr
Schreibzugriffe sind nur mit einem ADMIN-Token möglich. Es gibt keine automatische Rückkehr. Wenn die Rückkehr-Inspektion abgelehnt wird, erfolgt ein HTTP 422 und der Service-Ausschluss bleibt bestehen.
| Ablehnung | HTTP | Code |
|---|---|---|
| Bereits im Service-Ausschluss | 409 | alarm.oos.already |
| Ungültiger Grundwert · Notiz · geplante Rückkehr | 422 | alarm.oos.reason_invalid · memo_required · window_invalid |
| Rückkehr-Inspektion fehlgeschlagen | 422 | alarm.oos.return_not_normal · return_no_value |
| Rückkehr ohne Grund | 422 | alarm.oos.note_required |
| Bereits zurückgekehrt | 409 | alarm.oos.already_returned |
Wenn force als true gesetzt wird und note übermittelt wird, erfolgt die Rückkehr unter Umgehung der Inspektion (return_check = FORCED). Die Gründe sind SENSOR_REMOVED, EQUIPMENT_REMOVED, CALIBRATION, MODIFICATION, OTHER. Für OTHER sowie Sicherheits- und Umweltalarme ist eine Notiz zwingend erforderlich.
var r = client.alarm().returnToService("ALARM_OUT_OF_SERVICE_000001", false, null);
Alarm-Konfigurations-ID
Neue Alarm-Konfigurations-IDs werden vom Server vergeben (ALARM_CONFIG_ + 6 Stellen). Diese werden über GET /api/v5/alarm/config/new-id empfangen und verwendet; die Erstellung mit einer selbst gewählten ID führt zu einem HTTP 422 alarm.invalid.alarm_config_id. Bandalarme werden nicht über die API erstellt — sie werden durch die Alarmkonfiguration (patchAlarm) des Tags erstellt. Der Versuch, einen Band über POST /alarm/config zu erstellen, führt zu einem HTTP 409 alarm.band.edit_on_tag.
Bei der Band-Konfiguration eines Tags sollte keine ID erfunden werden; stattdessen wird in GET /api/v5/alarm/config/list/by-tag?tag_id=… nach einem Eintrag gesucht, bei dem alarm_config_priority gleich BAND ist. In der Änderungshistorie (/alarm/config/{alarm_config_id}/revisions) kann alarm_config_id in einer Zeile eines Tags, das noch keine Band-Konfiguration hat, als null erscheinen.
Alarm-Systemleistung
Es gibt keine SDK-Methoden. Das Auslesen erfolgt direkt über V5 — GET /api/v5/alarm/performance?scope_type=SITE&scope_id=…&days=7. Weitere Metriken finden Sie unter Alarmleistung.
Nächste Schritte
- Tag-Service — Einstellung von Alarmgrenzwerten über
patchAlarm - Path-Service — Baumstruktur-Pfad der Anlagen, in denen Alarme auftreten