WinCCOA WebComponent Dashboard — wui-alert-data

This package is part of the workspace for the WinCC Open Architecture WebComponent Dashboard, built using Lit and managed with Nx.

Usage information and reference details can be found in the WinCC OA documentation.

Overview

Live alarm subscription and history queries for WinCC OA. The AlertService is a tsyringe singleton; the same connect() call from multiple consumers shares one underlying server subscription via shareReplay({ refCount: true }).

Services

import { AlertService } from '@wincc-oa/wui-alert-data/alert-service.js';
import type { Alert } from '@wincc-oa/wui-models/interfaces/wui-alert/alert.js';
import { container } from 'tsyringe';

const alertService = container.resolve(AlertService);

alertService.connect().subscribe((alerts: Alert[]) => {
  const active = alerts.filter((a) => a.direction); // see direction semantics below
});

Alert fields:

| Field | Type | Description | | ---------------- | ---------- | --------------------------------------------------------------------------------------------------- | | dpeName | string | Full DP name e.g. System1:Foo.float | | text | string | Alarm text (may be "") | | color | string | Hex alarm color, e.g. "#FF0000" — ready to use as a CSS color (see Alarm colors) | | prior | number | Priority number, e.g. 60 | | abbr | string | Class abbreviation, e.g. "A" (Alert), "I" (Info) | | direction | boolean | true = CAME (active), false = WENT (cleared) | | ackState | AckState | Acknowledgment state | | ackable | boolean | Whether the alarm can be acknowledged | | formattedValue | string | Value with unit, e.g. "3.69 m/s²" |

Direction semantics — read this carefully: direction === true means the alarm CAME (is currently active). direction === false means it WENT (cleared). This is the opposite of what most people guess; filter on direction === true for an "active alarms" list.

connect(filter?) filter caveat: the optional filter is forwarded to the backend as etm.alert.connect { filter }. The backend rejects glob patterns (e.g. Foo_*.float). For wildcard semantics, omit the filter and filter client-side.

Acknowledging is a dpSet of value 2 to the alarm-handling attribute on the affected DP. It requires write permission:

oaRxJsApi.dpSet(`System1:${dpName}:_alert_hdl.._ack`, 2).subscribe();

dpName is the bare DPE name (without the System1: prefix), e.g. Foo.float.

alertService.getAlertArchive(startDate, endDate, filter, maxResults /* default 1000 */).subscribe((archive) => {
  // archive.alerts: { [id: string]: Alert } — same shape as connect()
});

alertService.listFilters().subscribe((filters) => {
  // [{ dp, name, label }, …] — includes a synthetic "Unfiltered" entry first
});

Alarm colors

Alert.color is a hex string (e.g. "#FF0000") that the standard backend handler resolves from the configured color name. Drop it directly into a CSS color slot:

html`<ix-pill variant="custom" background=${alert.color}>${alert.abbr}</ix-pill>`;
html`<ix-icon style="color: ${alert.color}" name="warning-rhomb-filled"></ix-icon>`;

When you have a color name instead — typically when reading alert range configuration or subscribing directly to a DP's alarm-color attribute (:_alert_hdl.._act_state_color) — resolve it through the theme's --oa-color--<name> CSS variables. See @wincc-oa/wui-oarxjs-context README for the dpconnectalertcolor context binding that automates this for context-generator pipelines.

License

MIT