system.alarm

system.alarm reads the alarm system and, with the operator role, acts on it. The reading functions are open to any role; acknowledging and shelving are done as whoever runs the script, and recorded under their name. See Alarms for states and severities, and The system API for how calls run.

Every function here is a gateway call, so it is not available in an expression tag.

Types

interface ScadexAlarm {
  id: string;
  name: string;
  tagPath: string;
  severity: number;                 // 1 (least) to 1000 (most)
  state: "normal" | "active" | "acknowledged" | "cleared";
  enabled: boolean;
  activatedAt: number | null;       // epoch ms the alarm last went active
  value: number | null;             // the value that raised it, when numeric
  shelvedUntil: number | null;
}

interface ScadexAlarmEvent {
  alarmId: string;
  alarmName: string;
  tagPath: string;
  severity: number;
  kind: "active" | "acknowledged" | "cleared" | "shelved" | "unshelved";
  timestamp: number;                // epoch ms
  value: number | null;
  by: string | null;                // who acknowledged or shelved it
}

States: active is unacknowledged, acknowledged is still active, cleared means the condition went away with the acknowledgement outstanding.

Reading

active

active(filter?: { tagPath?: string; minSeverity?: number }): ScadexAlarm[]

Parameter	Type	Meaning
filter.tagPath	string	Only alarms on this tag, or on tags under this folder or instance
filter.minSeverity	number	Only alarms of at least this severity

Alarms standing now (state active or acknowledged), most severe first, then most recently activated. Any role.

var urgent = system.alarm.active({ tagPath: 'Line1', minSeverity: 500 });
return urgent.length === 0 ? 'Line 1 clear' : urgent[0].name;

list

list(filter?: { tagPath?: string; state?: ScadexAlarm["state"] }): ScadexAlarm[]

Parameter	Type	Meaning
filter.tagPath	string	This tag, or the tags under this folder or instance
filter.state	string	Only alarms in this state

Every alarm defined, with its current state. Any role.

history

history(filter?: { from?: ScadexTime; to?: ScadexTime; tagPath?: string; limit?: number }): ScadexAlarmEvent[]

Parameter	Type	Meaning
filter.from, filter.to	Date, epoch ms or ISO 8601	The period
filter.tagPath	string	This tag, or the tags under it
filter.limit	number	At most this many events; 100 when left out, clamped to 1 to 1,000

What alarms did, newest first. The gateway fetches at most 1,000 events for the period and then applies tagPath and limit, so a narrow tagPath over a busy period can return fewer than limit events. Any role.

Acting

These three need the operator role. A viewer's script fails with Acknowledging alarms needs the operator role, and this script runs as viewer. (and the same wording for shelving and unshelving). In a dry run they do nothing, return their neutral value, and report what they would have done.

acknowledge

acknowledge(ids: string | string[]): number

Parameter	Type	Meaning
ids	string or string[]	One alarm id, or a list. Required

Acknowledges the alarms, as the person running the script, and returns how many were acknowledged. Only an alarm in state active or cleared counts; others are passed over. In a dry run it returns 0 and reports Acknowledge N alarms: <ids>.

var ids = system.alarm.active({ tagPath: event.params.Motor }).map(function (a) { return a.id; });
var done = system.alarm.acknowledge(ids);
return { toast: done + ' acknowledged' };

shelve

shelve(id: string, minutes: number): void

Parameter	Type	Meaning
id	string	The alarm. Required
minutes	number	How long; more than 0 and at most a week (10,080)

Hides the alarm from the active list for that long; it still records. Error: minutes must be more than 0 and at most a week (10,080).

unshelve

unshelve(id: string): void

Ends a shelve early.