Alarms and status

Alarm Grid `<smart-alarm-grid>`

AlarmGrid is an ISA-18.2 alarm summary.

JavaScript TypeScript Angular React Vue Blazor

<smart-alarm-grid> · 7 properties, 9 methods, 6 events · source/modules/smart.alarmgrid.js

Usage in React

The React wrapper is the AlarmGrid component: every property is a prop, every event a prop named on<Event> that receives the CustomEvent, and the methods are called on the element through a ref.

import { AlarmGrid } from 'smart-industrial/react/alarmgrid';

const ref = useRef<AlarmGrid>(null);

<AlarmGrid ref={ref} defaultSort={'time'}
    onAcknowledge={(event: CustomEvent) => console.log(event.detail)} />

// methods are called on the wrapper the ref holds, which calls the element
ref.current?.acknowledge(42);

Properties

Prop	Type, default	Description
`alarms`	array	Sets or retrieves the alarm records as [{ id, tag, area, message, priority, active, acknowledged, shelvedUntil, suppressed, outOfService, timestamp }]. Only id is required. The alarm state is derived from the record, so the application updates active and acknowledged and the summary derives the state. timestamp and shelvedUntil may be epoch milliseconds, a Date or ISO 8601 text; priority may be a number or a number written as text. Flags written as the text "false", "0", "no" or "off" are false. A shelved alarm returns by itself when shelvedUntil passes - the grid sets a timer for the nearest expiry, cleared when it leaves the page. Entries that are not objects are ignored. Assign a new array to update the component; an array modified in place is deep-equal to the current one and does not trigger a redraw. When the update keeps the same alarms in the same order, the rows are patched in place, so the keyboard stays where it was; otherwise the table is rebuilt and the keyboard returns to the same alarm.
`defaultSort`	AlarmGridDefaultSort priority-then-time	Sets or retrieves the order rows are presented in.
`filters`	object	Sets or retrieves which alarms are shown, as { state, priority, area, tag }. state is one state name or an array of names; priority is the largest priority number to include, so 2 shows priorities 1 and 2; area is matched exactly; tag is matched as a case-insensitive substring. Filters change the rows but not counts(), which still returns the totals for the whole alarm list.
`shelveDuration`	number 1800000	Sets or retrieves the default duration in milliseconds for which shelve shelves an alarm. A shelved alarm returns by itself when its shelvedUntil passes, without an update from the application.
`showCounts`	boolean true	Sets or retrieves whether the counts strip is shown above the rows: the number of alarms in each state for the whole list, not the filtered view - unacknowledged always, and the returned-to-normal, acknowledged, shelved, suppressed and out-of-service counts when there are any. With no alarms it shows the empty message. The same numbers are returned by counts().
`showStateColumn`	boolean true	Sets or retrieves whether the derived state has its own column. The property is read when the default columns are built, so set it before the component is initialized.
`timestampFormat`	AlarmGridTimestampFormat time	Sets or retrieves how the alarm time is written.

Methods

Method	Description
`acknowledge(id: string \| number): void`	Reports that an alarm was acknowledged. Raises the event and does not change the record; the application writes the acknowledgement to the control system. `id` string \| number The alarm's id.
`acknowledgeAll(): void`	Reports every outstanding alarm as acknowledged, with one event per alarm. Only the two unacknowledged states are outstanding; shelved, suppressed and out-of-service alarms are not affected.
`alarmById(id: string \| number): object`	Returns the alarm record with the given id. Look up alarms by id rather than by row index, because the grid is sorted and filtered and a row index changes when either changes. `id` string \| number The alarm's id.
`selectedAlarms(): object[]`	Returns the alarm records whose rows are selected (with selection on). Use it rather than getSelection(), which returns the table's own row keys, not the alarm ids: pass each record's id to acknowledge() or shelve().
`counts(): object`	Returns the number of alarms in each state, before filtering, plus outstanding and total. The counts describe the whole alarm list, not the current view.
`outOfService(id: string \| number, outOfService?: boolean): void`	Reports that an alarm should be taken out of service or returned to service. Out of service is a maintenance decision and takes precedence over every other state. `id` string \| number The alarm's id. `outOfService` boolean Defaults to true.
`shelve(id: string \| number, duration?: number): void`	Reports that an alarm should be shelved until a given time. Shelving is an operator decision with an expiry; suppression is a design decision without one. `id` string \| number The alarm's id. `duration` number How long, in milliseconds. Defaults to shelveDuration.
`suppress(id: string \| number, suppressed?: boolean): void`	Reports that an alarm should be suppressed by design, for a plant state in which it is not meaningful. `id` string \| number The alarm's id. `suppressed` boolean Defaults to true.
`unshelve(id: string \| number): void`	Reports that a shelved alarm should be returned before its shelf expires. `id` string \| number The alarm's id.

Events

The data of an event is in event.detail. acknowledge, shelve, unshelve, suppress and outOfService are requests: the alarm grid keeps the record in alarms as it is until the application writes the result back. stateChange follows each of them at once and carries the action with the state the alarm still has.

Event	Description and detail
`onAcknowledge` acknowledge	This event is triggered when acknowledge or acknowledgeAll is called. The grid has no acknowledge control of its own, so the application provides the button that calls them. The record is not changed: handle this event and write the acknowledgement back through the alarms property once the control system has confirmed it. `id` string \| number The alarm's id. `alarm` object The alarm record.
`onOutOfService` outOfService	This event is triggered when an alarm is taken out of or put back into service. `id` string \| number The alarm's id. `outOfService` boolean The requested state.
`onShelve` shelve	This event is triggered when an alarm is shelved. `id` string \| number The alarm's id. `shelvedUntil` number When the shelf expires, as a timestamp. `duration` number How long the shelf is, in milliseconds.
`onStateChange` stateChange	This event is triggered together with the event of acknowledge, shelve, unshelve, suppress and outOfService, so that an application can log these actions in one handler. acknowledgeAll raises only acknowledge events. `id` string \| number The alarm's id. `action` string Which action was taken. `state` string The alarm's state at the time of the action. `alarm` object The alarm whose state changed.
`onSuppress` suppress	This event is triggered when an alarm is suppressed by design. `id` string \| number The alarm's id. `suppressed` boolean The requested state.
`onUnshelve` unshelve	This event is triggered when an alarm is taken back off the shelf. `id` string \| number The alarm's id.

Types

`type AlarmGridDefaultSort`

'priority-then-time' | 'time' | 'tag' | 'none'

`type AlarmGridTimestampFormat`

'time' | 'datetime' | 'iso' | 'relative'

CSS variables

The component declares 2 CSS variables; the CSS page shows how to set them.

--smart-alarm-grid-height --smart-table-cell-padding

Method	Description
`acknowledge(id: string \| number): void`	Reports that an alarm was acknowledged. Raises the event and does not change the record; the application writes the acknowledgement to the control system. `id` string \| number The alarm's id.
`acknowledgeAll(): void`	Reports every outstanding alarm as acknowledged, with one event per alarm. Only the two unacknowledged states are outstanding; shelved, suppressed and out-of-service alarms are not affected.
`alarmById(id: string \| number): object`	Returns the alarm record with the given id. Look up alarms by id rather than by row index, because the grid is sorted and filtered and a row index changes when either changes. `id` string \| number The alarm's id.
`selectedAlarms(): object[]`	Returns the alarm records whose rows are selected (with selection on). Use it rather than getSelection(), which returns the table's own row keys, not the alarm ids: pass each record's id to acknowledge() or shelve().
`counts(): object`	Returns the number of alarms in each state, before filtering, plus outstanding and total. The counts describe the whole alarm list, not the current view.
`outOfService(id: string \| number, outOfService?: boolean): void`	Reports that an alarm should be taken out of service or returned to service. Out of service is a maintenance decision and takes precedence over every other state. `id` string \| number The alarm's id. `outOfService` boolean Defaults to true.
`shelve(id: string \| number, duration?: number): void`	Reports that an alarm should be shelved until a given time. Shelving is an operator decision with an expiry; suppression is a design decision without one. `id` string \| number The alarm's id. `duration` number How long, in milliseconds. Defaults to shelveDuration.
`suppress(id: string \| number, suppressed?: boolean): void`	Reports that an alarm should be suppressed by design, for a plant state in which it is not meaningful. `id` string \| number The alarm's id. `suppressed` boolean Defaults to true.
`unshelve(id: string \| number): void`	Reports that a shelved alarm should be returned before its shelf expires. `id` string \| number The alarm's id.