Alarms manipulation

Availability table

Controller availability
Module	Available
module.scripts
module.keycloak

alarms controller

Library to interact with the module alarms. (see alarms insertion).

alarms.acknowledge(id: <string | string[]>)

Acknowledges an alarm or a list of alarms

Arguments:

id – Identifier, a.k.a. serial

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.addJournal(id: <string | string[]>, text: string, user: string, status?: string)

Adds journal entry to alarm

Arguments:

id – Identifier, a.k.a. serial
text – Content of the journal entry
user – User author of the entry
status – Status of the entry: success, error, warning or info (default)

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.clear(id: <string | string[]>)

Remove an alarm or a list of alarms.

Arguments:

id – Identifier, a.k.a. serial

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.create(alarm: Alarm)

Create a new alarm created with an AlarmBuilder(). It is directly added to the live collection without being processed by the pre-insertion rules (see alarms direct insertion.)

Added in version 1.4.0.

Arguments:

alarm – Alarm()

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.create(alarmBuilder: AlarmBuilder)

Create a new alarm from an AlarmBuilder(). It is directly added to the live collection without being processed by the pre-insertion rules (see alarms direct insertion.)

Added in version 2.1.0.

Arguments:

alarmBuilder – AlarmBuilder()

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.create(severity: <number | string>, summary: string, location: string, source: string, serial: string, tags: string[], additionalData?: object, hideUntil?: number, forceHide?: boolean)

Creates an alarm.

It is directly added to the live collection without being processed by the pre-insertion rules (see alarms direct insertion.)

Deprecated since version 1.4.0: Use alarms.newAlarmBuilder() and alarms.create() instead.

Arguments:

severity – Either an integer or the ID of a severity defined in the configuration (e.g. root.severities.critical)
summary – Human-readable description
location – Geographical location of the alarm (e.g. Room ABC)
source – Source that triggered the alarm (e.g. root.devices.camera-123)
serial – Identifier, a.k.a. serial
tags
additionalData
hideUntil – Timestamp at which to hide the alarm, expressed in milliseconds
forceHide – Indicates whether the alarm should be hidden.

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.createGroup(groupId: string, visibleIfNoChildren: boolean, fields: object[], actions: object[])

Remove a group if the group is not static

Arguments:

groupId – Identifier of the group.
visibleIfNoChildren – Indicates whether the group should be hidden when it has no member.
fields –
Override some or all the field generation define on module.alarms.
actions –
Override some or all the action handling define on module.alarms.

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.edit(id: <string | string[]>, summary: string, location: string, source: string, hideUntil: number, forceHide: boolean, additionalData: object)

Edits an alarm or a list of alarms

Arguments:

id – Identifier, a.k.a. serial
summary – Human-readable description
location – Geographical location of the alarm (e.g. Room ABC)
source – Source that triggered the alarm (e.g. root.devices.camera-123)
hideUntil – Timestamp at which to hide the alarm, expressed in milliseconds
forceHide – Indicates whether the alarm should be hidden.
additionalData

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.editAdditionalData(id: <string | string[]>, additionalData: object)

Edits the additional data of an alarm or a list of alarms

Arguments:

id – Identifier, a.k.a. serial
additionalData

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.editForceHide(id: <string | string[]>, forceHide: boolean)

Edits the forceHide. field of an alarm or a list of alarms

Arguments:

id – Identifier, a.k.a. serial
forceHide – Indicates whether the alarm should be hidden.

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.editHideUntil(id: <string | string[]>, hideUntil: number)

Edits the inhibition time of an alarm or a list of alarms

Arguments:

id – Identifier, a.k.a. serial
hideUntil – Timestamp at which to hide the alarm, expressed in milliseconds

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.editLocation(id: <string | string[]>, location: string)

Edits the location of an alarm or a list of alarms

Arguments:

id – Identifier, a.k.a. serial
location – Geographical location of the alarm (e.g. Room ABC)

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.editSource(id: <string | string[]>, source: string)

Edits the source of an alarm or a list of alarms

Arguments:

id – Identifier, a.k.a. serial
source – Source that triggered the alarm (e.g. root.devices.camera-123)

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.editSummary(id: <string | string[]>, summary: string)

Edits the summary of an alarm or a list of alarms

Arguments:

id – Identifier, a.k.a. serial
summary

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.escalate(id: <string | string[]>, severity: <number | string>)

Escalates an alarm or a list of alarms

Arguments:

id – Identifier, a.k.a. serial
severity – Either an integer or the ID of a severity defined in the configuration (e.g. root.severities.critical)

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.exists(serial: string)

Verify if an alarm with this serial already exists.

Added in version 2.1.0.

Arguments:

serial – Identifier, a.k.a. serial

Returns:

An object that contains attribute :

success (boolean) Indicates whether the alarms exists.
message (string) Contains additional information about the operation’s success or failure.

alarms.getHistory(filter: string, view: string, quickFilter?: object[], quickSort?: object[])

Get the history alarms matching the filter and quickFilter.

Added in version 2.1.0.

Arguments:

filter – The itemId of the filter to use to get the alarms. For example root.alarms.filters.all
view – The itemId of the view to use to get the alarms. The alarms found will only contains field present on the view. For example root.alarms.view.default
quickFilter –
A list of filter to apply to a column. An AND operation will be applied between the filter and quickFilter.

A quick filter as the following format:
- field: The field on which apply the filter.
- content: The value to use to filter the column.
- operation: The operation to apply. See filters for the detail.
For example, to filter a particular serial:
```
{
    "operation": "EQUAL",
    "field": "serial",
    "content": "example-alarm"
}
```
quickSort –
A list of sort to apply to a column.
- field: The field on which apply the sort.
- operation: The operation to apply. Either ASC or DESC.
For example, to sort with the most recent entry first:
```
{
    "operation": "DESC",
    "field": "operationTime"
}
```

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.
content.value (iterator[ScriptHistoryAlarm]) The list of alarms found.

alarms.getLive(filter: string, view: string, quickFilter?: object[])

Get the live alarms matching the filter and quickFilter.

Added in version 2.1.0.

Arguments:

filter – The itemId of the filter to use to get the alarms. For example root.alarms.filters.all
view – The itemId of the view to use to get the alarms. The alarms found will only contains field present on the view. For example root.alarms.view.default
quickFilter –
A list of filter to apply to a column. An AND operation will be applied between the filter and quickFilter.

A quick filter as the following format:
- field: The field on which apply the filter.
- content: The value to use to filter the column.
- operation: The operation to apply. See filters for the detail.
For example, to filter a particular serial:
```
{
    "operation": "EQUAL",
    "field": "serial",
    "content": "example-alarm"
}
```

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.
content.value (list[ScriptAlarm]) The list of alarms found.

alarms.insert(alarm: Alarm)

Insert a new alarm created with an AlarmBuilder(). It is added to the live collection after being processed by the pre-insertion rules (see alarms insertion).

Added in version 1.4.0.

Arguments:

alarm – Alarm()

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.insert(alarmBuilder: AlarmBuilder)

Insert a new alarm from an AlarmBuilder(). It is added to the live collection after being processed by the pre-insertion rules (see alarms standard insertion.).

Added in version 2.1.0.

Arguments:

alarmBuilder – AlarmBuilder()

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.insert(severity: <number | string>, summary: string, location: string, source: string, serial: string, tags: string[], additionalData?: object, hideUntil?: number, forceHide?: boolean)

Inserts an alarm.

It is added to the live collection after being processed by the pre-insertion rules (see alarms standard insertion.)

Deprecated since version 1.4.0: Use alarms.newAlarmBuilder() and alarms.insert() instead.

Arguments:

severity – Either an integer or the ID of a severity defined in the configuration (e.g. root.severities.critical)
summary – Human-readable description
location – Geographical location of the alarm (e.g. Room ABC)
source – Source that triggered the alarm (e.g. root.devices.camera-123)
serial – Identifier, a.k.a. serial
tags
additionalData
hideUntil – Timestamp at which to hide the alarm, expressed in milliseconds
forceHide – Indicates whether the alarm should be hidden.

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.joinGroup(id: <string[] | string>, groupId: string)

Add an alarm or a list of alarms to the specified group

Arguments:

id – Identifier, a.k.a. serial
groupId – Identifier of the group.

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.leaveGroup(id: <string[] | string>, groupId: string)

Remove an alarm or a list of alarms from the specified group

Arguments:

id – Identifier, a.k.a. serial
groupId – Identifier of the group.

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.lockSeverity(id: <string | string[]>, severity: <number | string>)

Locks the severity of an alarm or a list of alarms

Arguments:

id – Identifier, a.k.a. serial
severity – Either an integer or the ID of a severity defined in the configuration (e.g. root.severities.critical)

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.newAlarmBuilder(serial: string, severity: <string | number>)

Create a new alarm builder.

Added in version 1.4.0.

Arguments:

serial – Identifier, a.k.a. serial
severity – Either an integer or the ID of a severity defined in the configuration (e.g. root.severities.critical)

Returns:

An alarm builder of type AlarmBuilder()

alarms.removeGroup(groupId: string)

Remove a group if the group is not static

Arguments:

groupId – Identifier of the group.

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.runActionRule(id: string, data: object, delay: number)

Runs an alarms actions (action.alarms). The data are the parameters passed to the action when run.

Arguments:

id – Identifier, a.k.a. serial
data – The parameters to pass to the action rule. This is a json object.
delay – The delay to add between the call and the real execution. The method will return immediately

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.tag(id: <string | string[]>, tag: string)

Tags alarms

Arguments:

id – Identifier, a.k.a. serial
tag

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.unacknowledge(id: <string | string[]>)

Un-acknowledges an alarm or a list of alarms

Arguments:

id – Identifier, a.k.a. serial

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.unlockSeverity(id: <string | string[]>)

Unlocks the severity of an alarm or a list of alarms

Arguments:

id – Identifier, a.k.a. serial

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

alarms.untag(id: <string | string[]>, tag: string)

Remove a tag from an alarm.

Arguments:

id – Identifier, a.k.a. serial
tag

Returns:

An object that contains attribute :

success (boolean) Indicates whether the operation was successful.
message (string) Contains additional information about the operation’s success or failure.

Alarm

class alarms.Alarm()

An unmodifiable alarm created by AlarmBuilder()

AlarmBuilder

class alarms.AlarmBuilder()

A builder to create an alarm

AlarmBuilder.addAdditionalData(key?: string, value?: object, additionalData?: object)

Add an additional data entry on the alarm

Arguments:

key

value

additionalData

Returns:

An alarm builder of type AlarmBuilder()

AlarmBuilder.addJournal(journal: string)

Add the initial journal entry

Arguments:

journal

Returns:

An alarm builder of type AlarmBuilder()

AlarmBuilder.addJournals(journals: string[])

Add the initial journal entry

Arguments:

journals

Returns:

An alarm builder of type AlarmBuilder()

AlarmBuilder.addTag(tag: string)

Add a tag on the alarm

Arguments:

tag

Returns:

An alarm builder of type AlarmBuilder()

AlarmBuilder.addTags(tags: string[])

Add multiple tags on the alarm

Arguments:

tags

Returns:

An alarm builder of type AlarmBuilder()

AlarmBuilder.build()

Build and return the alarm

Returns:

An alarm of type Alarm()

AlarmBuilder.getAcknowledgement()

Return the acknowledgement state of the alarm

Returns:

The acknowledgement state of the alarm

AlarmBuilder.getAdditionalData()

Return the additional data of the alarm

Returns:

The additional data of the alarm

AlarmBuilder.getForceHide()

Return the force hide of the alarm

Returns:

The force hide of the alarm

AlarmBuilder.getHideUntilMS()

Return the hide until of the alarm in milliseconds

Returns:

The hide until of the alarm in milliseconds

AlarmBuilder.getHideUntilNS()

Return the hide until of the alarm in nanoseconds

Returns:

The hide until of the alarm in nanoseconds

AlarmBuilder.getInitialJournal()

Return the initial journal entries of the alarm

Returns:

The list of initial journal entries of the alarm

AlarmBuilder.getLocation()

Return the location of the alarm

Returns:

The location of the alarm

AlarmBuilder.getParent()

Return the parent of the alarm

Returns:

The parent of the alarm

AlarmBuilder.getSerial()

Return the serial of the alarm

Returns:

The serial of the alarm

AlarmBuilder.getSeverity()

Return the severity of the alarm

Returns:

The severity of the alarm, either an integer or the ID of a severity

AlarmBuilder.getSource()

Return the source of the alarm

Returns:

The source of the alarm

AlarmBuilder.getSummary()

Return the summary of the alarm

Returns:

The summary of the alarm

AlarmBuilder.getTags()

Return the tags of the alarm

Returns:

The list of tags of the alarm

AlarmBuilder.getTimestampMS()

Return the timestamp of the alarm in milliseconds

Returns:

The timestamp of the alarm in milliseconds

AlarmBuilder.getTimestampNS()

Return the timestamp of the alarm in nanoseconds

Returns:

The timestamp of the alarm in nanoseconds

AlarmBuilder.setAcknowledgement(acknowledgement: boolean)

Set the acknowledgement state of the alarm

Arguments:

acknowledgement

Returns:

An alarm builder of type AlarmBuilder()

AlarmBuilder.setForceHide(forceHide: boolean)

Set the force hide of the alarm

Arguments:

forceHide

Returns:

An alarm builder of type AlarmBuilder()

AlarmBuilder.setHideUntilMS(hideUntil: number)

Set the hide until of the alarm in milliseconds

Arguments:

hideUntil

Returns:

An alarm builder of type AlarmBuilder()

AlarmBuilder.setHideUntilNS(hideUntil: number)

Set the hide until of the alarm in nanoseconds

Arguments:

hideUntil

Returns:

An alarm builder of type AlarmBuilder()

AlarmBuilder.setLocation(location: string)

Define the location of the alarm

Arguments:

location

Returns:

An alarm builder of type AlarmBuilder()

AlarmBuilder.setParent(parent: string)

Set the parent of the alarm

Arguments:

parent

Returns:

An alarm builder of type AlarmBuilder()

AlarmBuilder.setSerial(serial: string)

Define the serial of the alarm

Arguments:

serial

Returns:

An alarm builder of type AlarmBuilder()

AlarmBuilder.setSeverity(severity: <string | number>)

Define the severity of the alarm

Arguments:

severity

Returns:

An alarm builder of type AlarmBuilder()

AlarmBuilder.setSource(source: string)

Define the source of the alarm

Arguments:

source

Returns:

An alarm builder of type AlarmBuilder()

AlarmBuilder.setSummary(summary: string)

Define the summary of the alarm

Arguments:

summary

Returns:

An alarm builder of type AlarmBuilder()

AlarmBuilder.setTimestampMS(timestamp: number)

Set the timestamp of the alarm in milliseconds

Arguments:

timestamp

Returns:

An alarm builder of type AlarmBuilder()

AlarmBuilder.setTimestampNS(timestamp: number)

Set the timestamp of the alarm in nanoseconds

Arguments:

timestamp

Returns:

An alarm builder of type AlarmBuilder()

AlarmHistoryIterator

class alarms.AlarmHistoryIterator()

A history alarm iterator

JournalEntry

class alarms.JournalEntry()

An unmodifiable journal entry

JournalEntry.id

The unique identifier of the journal entry as a hexadecimal string (69d89ba68e35fae249da81ae).

The type of the field is string.

JournalEntry.text

The content of the journal.

The type of the field is string.

JournalEntry.timestamp

The timestamp.Timestamp() when the journal was added.

The type of the field is Timestamp.

JournalEntry.status

The status of the journal.

The type of the field is string.

JournalEntry.user

The user that created the journal.

The type of the field is string.

ScriptAlarm

class alarms.ScriptAlarm()

An unmodifiable alarm returned by the module alarms

ScriptAlarm.id

The unique identifier of the alarm.

The type of the field is string.

ScriptAlarm.serial

The unique identifier of the alarm.

The type of the field is string.

ScriptAlarm.firstTimestamp

timestamp.Timestamp() of first occurrence.

The type of the field is Timestamp.

ScriptAlarm.lastTimestamp

timestamp.Timestamp() of last occurrence.

The type of the field is Timestamp.

ScriptAlarm.severity

The importance of the alarm.

The type of the field is number.

ScriptAlarm.summary

The description of the alarm.

The type of the field is string.

ScriptAlarm.location

Where the alarm occurs.

The type of the field is string.

ScriptAlarm.source

The origin of the alarm.

The type of the field is string.

ScriptAlarm.tags

The tags associated with the alarm.

The type of the field is string[].

ScriptAlarm.additionalData

Complementary information about the alarm.

The type of the field is object.

ScriptAlarm.acknowledged

Flag to indicate if the alarm was acknowledge by an user.

The type of the field is boolean.

ScriptAlarm.hideUntil

timestamp.Timestamp() until the alarm will be shown again to the user.

The type of the field is Timestamp.

ScriptAlarm.forceHide

Flag to indicate if this alarm was hidden to the user.

The type of the field is boolean.

ScriptAlarm.journal

The journal documenting the action done by the user or system.

The type of the field is JournalEntry[].

ScriptAlarm.count

The number of occurrence (create) of this alarm.

The type of the field is number.

ScriptAlarm.origSeverity

The severity of the alarm if it wasn’t locked.

The type of the field is number.

ScriptAlarm.isSeverityLocked

Flag to indicate that the severity is locked.

The type of the field is boolean.

ScriptAlarm.highestSeverity

The highest severity that the alarm took until now.

The type of the field is number.

ScriptAlarm.lowestSeverity

The lowest severity that the alarm took until now.

The type of the field is number.

ScriptAlarm.parent

The parent of this alarm.

The type of the field is string.

ScriptAlarm.children

The list of the children of this alarm if it is a group.

The type of the field is string[].

ScriptHistoryAlarm

class alarms.ScriptHistoryAlarm()

An unmodifiable alarm returned by the module alarms

ScriptHistoryAlarm.id

The unique identifier of the alarm as a hexadecimal string (69d89ba68e35fae249da81ae).

The type of the field is string.

ScriptHistoryAlarm.serial

The unique identifier of the alarm.

The type of the field is string.

ScriptHistoryAlarm.firstTimestamp

timestamp.Timestamp() of first occurrence.

The type of the field is Timestamp.

ScriptHistoryAlarm.lastTimestamp

timestamp.Timestamp() of last occurrence.

The type of the field is Timestamp.

ScriptHistoryAlarm.severity

The importance of the alarm.

The type of the field is number.

ScriptHistoryAlarm.summary

The description of the alarm.

The type of the field is string.

ScriptHistoryAlarm.location

Where the alarm occurs.

The type of the field is string.

ScriptHistoryAlarm.source

The origin of the alarm.

The type of the field is string.

ScriptHistoryAlarm.tags

The tags associated with the alarm.

The type of the field is string[].

ScriptHistoryAlarm.additionalData

Complementary information about the alarm.

The type of the field is object.

ScriptHistoryAlarm.acknowledged

Flag to indicate if the alarm was acknowledge by an user.

The type of the field is boolean.

ScriptHistoryAlarm.hideUntil

timestamp.Timestamp() until the alarm will be shown again to the user.

The type of the field is Timestamp.

ScriptHistoryAlarm.forceHide

Flag to indicate if this alarm was hidden to the user.

The type of the field is boolean.

ScriptHistoryAlarm.journal

The journal documenting the action done by the user or system.

The type of the field is JournalEntry[].

ScriptHistoryAlarm.count

The number of occurrence (create) of this alarm.

The type of the field is number.

ScriptHistoryAlarm.origSeverity

The severity of the alarm if it wasn’t locked.

The type of the field is number.

ScriptHistoryAlarm.isSeverityLocked

Flag to indicate that the severity is locked.

The type of the field is boolean.

ScriptHistoryAlarm.highestSeverity

The highest severity that the alarm took until now.

The type of the field is number.

ScriptHistoryAlarm.lowestSeverity

The lowest severity that the alarm took until now.

The type of the field is number.

ScriptHistoryAlarm.parent

The parent of this alarm.

The type of the field is string.

ScriptHistoryAlarm.children

The list of the children of this alarm if it is a group.

The type of the field is string[].

ScriptHistoryAlarm.operationType

The operation that was done for this entry.

The type of the field is string.

ScriptHistoryAlarm.operationTime

timestamp.Timestamp() of when the operation was done.

The type of the field is Timestamp.

ScriptHistoryAlarm.historyId

The unique identifier of the history entry as a hexadecimal string (69d89ba68e35fae249da81ae).

The type of the field is string.