# Alarms

# GET Retrieve Alarm Definitions

# /definitions/alarms

# Description

Retrieves the list of latest (based on version number) alarm definitions. The result can be filtered by providing the filter parameter. The result can be limited by providing the limit parameter (default is 100). Deleted definitions can be included by setting the includeDeleted parameter to true.

# Parameters

Name	Located in	Description	Required	Schema
limit	query	Limit the number of returned values. Defaults to 100 if not specified	No	LimitClause
includeDeleted	query	Whether to return a definition that has been marked as deleted	No	-
filter	query	A boolean expression used to filter the results	No	WhereClause

# Responses

Code	Description	Schema
200	Success	AlarmDefinitions
400	Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc	ServiceErrors
404	Not found. One or more resources were not found, response may contain details about missing resources	ServiceErrors
5XX	Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors	ServiceErrors

# POST Add a New Alarm Definition

# /definitions/alarms

# Description

Adds a new alarm definition. It needs to be either a new alarmDefinitionId or the provided version property needs to conform to the semantic versioning rules for definitions. Otherwise the request will be rejected. Note that there is NO update of a definition. If changes need to be made, at least a major version increase is required. Therefore, there is also no PUT operation on this endpoint.

# Payload

{
  "alarmDefinitionId": "abb.ability.Unique.Identificator",
  "version": "1.0.0",
  "state": {
    "acknowledgeTimeStamp": {
      "dataType": "string"
    },
    "category": {
       ...
       "limitState": {
             "dataType" : "string",
             "enum" : ["low", "high", "none"]

        }
    }
  }
}

On the Top level of the definition there are only tree properties allowed:

alarmDefinitionId - string - mandatory
version - string - semantic verion format - mandatory
state - object - optional

The state object may contain variables only - no properties, no default values are allowed. Variables inside the alarm's state follow the same approach that the regular type definition variables do.

# Responses

Code	Description	Schema
201	Definition was added to database	AlarmDefinition
400	Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc	ServiceErrors
409	Conflict - definition with this id already exists
5XX	Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors	ServiceErrors

# GET Retrieve an Alarm Definition

# /definitions/alarms/{alarmDefinitionId}

# Description

Gets latest (based on its version) alarm definition based on versions for specific alarmDefinitionId. Deleted alarm definition can also be retrieved by this operation, if the includeDeleted flag is set to true.

# Parameters

Name	Located in	Description	Required	Schema
alarmDefinitionId	path	definition id	Yes	string
includeDeleted	query	Whether to return a definition that has been marked as deleted	No	-

# Responses

Code	Description	Schema
200	Success. Retrieve object models by filter criteria.	AlarmDefinition
404	Not found. One or more resources were not found, response may contain details about missing resources	ServiceErrors
5XX	Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors	ServiceErrors

# DELETE Delete an Alarm Definition

# /definitions/alarms/{alarmDefinitionId}

# Description

Marks the alarm definition as deleted. No new instances can be created and no new versions added. The alarm definition will stay in the database though, as this is a soft delete. To delete the entity completely (hard delete), please contact the Operations Team.

# Parameters

Name	Located in	Description	Required	Schema
alarmDefinitionId	path	definition id	Yes	string

# Responses

Code	Description	Schema
204	Alarm definition was successfully deleted.
404	Not found. One or more resources were not found, response may contain details about missing resources	ServiceErrors
5XX	Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors	ServiceErrors

# GET Get Alarm Definition Versions

# /definitions/alarms/{alarmDefinitionId}/versions

# Description

Retrieves a list of available versions for the given alarmDefinitionId. In order to retrieve the versions of a soft-deleted definition the includeDeleted flag has to be set to "true".

# Parameters

Name	Located in	Description	Required	Schema
alarmDefinitionId	path	definition id	Yes	string
includeDeleted	query	Whether to return a definition that has been marked as deleted	No	-

# Responses

Code	Description	Schema
200	Success	AlarmVersions
404	Not found. One or more resources were not found, response may contain details about missing resources	ServiceErrors
5XX	Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors	ServiceErrors

# GET Get Alarm Definition by Version Number

# /definitions/alarms/{alarmDefinitionId}/versions/{version}

# Description

Retrieves a specific alarm definition identified by alarmDefinitionId. Additionally, a version number needs to be supplied which can be partial (e.g., 1 or 1.1) which means that the latest sub version of that version will be returned (e.g., 1.2.5 or 1.1.3). In order to retrieve the specified version of a soft-deleted definition the includeDeleted flag has to be set to "true".

# Parameters

Name	Located in	Description	Required	Schema
alarmDefinitionId	path	definition id	Yes	string
version	path	(Partial) version number	Yes	string
includeDeleted	query	Whether to return a definition that has been marked as deleted	No	-

# Responses

Code	Description	Schema
200	Success. Retrieve object models by filter criteria.	AlarmDefinition
404	Not found. One or more resources were not found, response may contain details about missing resources	ServiceErrors
5XX	Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors	ServiceErrors

← Overview Attributes →