Alarms (Legacy)

Alarms are signals that something is wrong, requires attention or is in an undesirable state.

info

An instance of an Alarm is uniquely identifiable with a composition of the Alarm type and all references.

Alarm Types (Legacy)

Alarm

{
  organizationId: string,
  id: string,
  type: string,
  name: string,
  severity: AlarmSeverity,
  status: AlarmStatus,
  attributes: Record<string, string>,
  references: Record<string, string>,
  startUtc: datetime,
  endUtc: datetime,
  updatedUtc: datetime
}

AlarmStatus

{
  Active = 0,
  Cleared = 1
}

AlarmSeverity

{
  Indeterminate = 0,
  Warning = 1,
  Minor = 2,
  Major = 3,
  Critical = 4
}

CreateAlarmOptions

{
  references: Record<string, string>,
  attributes: Record<string, string>
}

UpdateAlarmOptions

{
  alarmId: string,
  type: string,
  status: AlarmStatus,
  severity: AlarmSeverity,
  references: Record<string, string>,
  attributes: Record<string, string>
}

info

alarmId, type and references can not be updated once the Alarm is created, and are used to identify the Alarm to update.

QueryAlarmOptions

{
  startUtc: datetime,
  endUtc: datetime,
  types: string[],
  severities: AlarmSeverity[],
  statuses: AlarmStatus[],
  references: Record<string, string>,
  attributes: Record<string, string>
}

createAlarm (Legacy)

Read-only Mode

This function is not available in read-only mode.

Creates a new Alarm.

createAlarm(type, name, severity, options)

Parameters

Name	Type	Description	Optional
type	string	The type of the Alarm.	❌
name	string	The name of the Alarm.	❌
severity	AlarmSeverity	The severity of the Alarm.	❌
options	CreateAlarmOptions	Options to create the Alarm with.	✔

Returns The created Alarm.

Example

var alarm = createAlarm(
  'high-temperature',
  'High Temperature',
  AlarmSeverity.Minor,
  {
    attributes: {
      source: 'udf'
    },
    references: {
      modelId: 'office-floor1'
    }
  });

updateAlarm (Legacy)

Read-only Mode

This function is not available in read-only mode.

Updates an existing Alarm.

updateAlarm(options)

Parameters

Name	Type	Description
options	UpdateAlarmOptions	Options to update the Alarm with.

info

An alarmId or type must be provided to identify the Alarm to update.

Returns The updated Alarm.

Example

// Update the severity of the 'high-temperature' Alarm
var alarm = updateAlarm({
  type: 'high-temperature',
  references: {
    modelId: 'office-floor1'
  },
  severity: AlarmSeverity.Major
});

getActiveAlarm (Legacy)

Gets an active Alarm for a specified type and references.

getActiveAlarm(type, references)

Parameters

Name	Type	Description	Optional
type	string	The Alarm type to retrieve.	❌
references	Record<string, string>	Optional references associated with the Alarm.	✔

Returns An Alarm with the specified type, references and with a status of Active. Returns null if no Alarm exists.

note

An Alarm must have all specified references to be returned.

Example

var alarms = getActiveAlarm({
  type: 'high-temperature',
  references: {
    modelId: 'office-floor1'
  }
});

getActiveAlarms (Legacy)

Gets all active Alarms matching the specified references. If no references are specified then all active alarms will be returned.

getActiveAlarms(references)

Parameters

Name	Type	Description	Optional
references	Record<string, string>	Optional references associated with the Alarm.	✔

Returns A collection of Alarms with the specified references and with a status of Active.

note

If references has been specified, an Alarm must have all specified references to be included.

Example

// Get all active alarms
var allAlarms = getActiveAlarms();

// Get all active alarms on a model
var alarms = getActiveAlarms({
  references: {
    modelId: 'office-floor1'
  }
});

getAlarmTypes (Legacy)

Gets a collection of all available Alarm types.

getAlarmTypes(typeFilter)

Parameters

Name	Type	Description	Optional
typeFilter	string	All Alarm types must match this specified filter.	✔

Returns A collection of types which meet the typeFilter string, or all if no typeFilter is specified.

Example

// Get all types for every existing Alarm
var allTypes = getAlarmTypes();

// Get all types for existing Alarms which contain 'temperature'
var filteredTypes = getAlarmTypes('temperature');

getAlarm (Legacy)

Gets an Alarm by its identifier.

getAlarm(alarmId)

Parameters

Name	Type	Description
alarmId	string	The identifier of the Alarm to retrieve.

Returns The Alarm with the specified identifier.

Example

var alarm = getAlarm('9a2ce419-c60d-4ea2-8e4a-beb539e5d9e9');

getAlarms (Legacy)

Gets a collection of alarms using optional query criteria.

getAlarms(options)

Parameters

Name	Type	Description
options	QueryAlarmOptions	Options for querying Alarms.

info

options must have either one or more types or references to identify the Alarms.

Returns A collection of Alarms which meet the query criteria.

Example

var alarms = getAlarms({
  type: 'high-temperature',
  references: {
    modelId: 'office-floor1'
  }
});