Alarm Service

Resource	Requires Authentication	Requires SignalR (Notifications)
/api/v1/alarms	Yes	Yes

GET /api/v1/alarms

Retrieves the list of current alarms.

Parameters

Property	Type	Description
stationId	uint	Filter by station identifier.
dataServerId	uint	Filter by data server identifier.
tagGroupId	uint	Filter by tag group identifier.
scenarioId	uint	Filter by scenario identifier.
callGroupId	uint	Filter by call group identifier.
alarmState	uint	Filter by alarm state.
inactiveMasked	uint	Filter inactive masked alarms.
offset	uint	Pagination offset.
limit	uint	Maximum number of items to return.
sort	string	"+id" for ascending sort on id; "-id" for descending sort on id.
search	string	Full-text search filter.

Response

HTTP 200 OK — PagingCollection<Alarm> (see PagingCollection and Alarm)

Example

Request:

GET /localhost/alertws/api/v1/alarms
Authorization: Bearer {access_token}

Response:

{
    "items": [
        {
            "dataServerId": 1,
            "path": "Random.Int1",
            "fullPath": "Matrikon.OPC.Simulation\\Random.Int1",
            "value": "102",
            "message": "Alarme TXT",
            "resetMessage": "Alarm TXT",
            "ackMessage": "Alarm TXT",
            "priority": 1,
            "state": 3,
            "masked": false,
            "alarmTime": "2019-04-29T09:07:42+02:00",
            "ackUser": "",
            "attachedFile": "",
            "resetAttachedFile": "",
            "ackAttachedFile": "",
            "comment": "",
            "id": 1,
            "name": "Random.Int1",
            "localizedName": "Random.Int1",
            "lastChange": "2019-04-29T06:46:04"
        },
        {
            "dataServerId": 1,
            "path": "Random.UInt2",
            "fullPath": "Matrikon.OPC.Simulation\\Random.UInt2",
            "value": "14486",
            "message": "Event Set",
            "resetMessage": "Event Reset",
            "ackMessage": "Event Set",
            "priority": 1,
            "state": 3,
            "masked": false,
            "alarmTime": "2019-04-29T08:38:29+02:00",
            "ackUser": "",
            "attachedFile": "",
            "resetAttachedFile": "",
            "ackAttachedFile": "",
            "comment": "",
            "id": 20,
            "name": "Random.UInt2",
            "localizedName": "Random.UInt2",
            "lastChange": "2019-04-25T10:19:50"
        }
    ],
    "paging": {
        "offset": 0,
        "limit": 10,
        "total": 2
    }
}

Subscribe to Alarms (SignalR)

After subscribing for alarms, only the new alarms which appear in Alert will be notified.

Type	Name (case sensitive)
Hub	alertHub
Function	onAlarm(alarm)

Callback parameters:

Property	Type	Description
alarm	Alarm	Alarm object received by notification.

POST /api/v1/alarms

Creates an alarm in Alert.

Request

• Content-Type: application/json

Body:

{
  "stationId": "<uint>",
  "dataServerId": "<uint>",
  "path": "<string>",
  "raised": "<bool>",
  "tagGroupId": "<uint>",
  "priority": "<uint>",
  "temporary": "<bool>",
  "eventCondition": {
    "value": "<string>",
    "transitory": "<bool>",
    "reactivatable": "<bool>",
    "resettable": "<bool>"
  },
  "value": "<string>",
  "location": {
    "latitude": "<double>",
    "longitude": "<double>",
    "horizontalAccuracy": "<double>",
    "altitude": "<double>",
    "verticalAccuracy": "<double>",
    "date": "<dateTime>",
    "beaconList": [
      {
        "id": "<string>",
        "name": "<string>",
        "type": "<string>",
        "accuracy": "<double>",
        "date": "<dateTime>"
      }
    ],
    "zone": "<string>"
  },
  "alarmDelay": "<uint>",
  "alarmMessage": "<string>",
  "alarmFormat": "<string>",
  "alarmShortMessage": "<string>",
  "alarmVocalMessageFile": "<string>",
  "alarmAttachedFile": "<string>",
  "alarmActions": [
    {
      "id": "<uint>",
      "type": "CallGroup",
      "scriptId": "<uint>",
      "parameter": "<string>",
      "flags": "<uint>"
    }
  ],
  "resetMessage": "<string>",
  "resetFormat": "<string>",
  "resetShortMessage": "<string>",
  "resetVocalMessageFile": "<string>",
  "resetAttachedFile": "<string>",
  "resetActions": [
    {
      "id": "<uint>",
      "type": "CallGroup",
      "scriptId": "<uint>",
      "parameter": "<string>",
      "flags": "<uint>"
    }
  ],
  "ackMessage": "<string>",
  "ackFormat": "<string>",
  "ackShortMessage": "<string>",
  "ackVocalMessageFile": "<string>",
  "ackAttachedFile": "<string>",
  "ackActions": [
    {
      "id": "<uint>",
      "type": "CallGroup",
      "scriptId": "<uint>",
      "parameter": "<string>",
      "flags": "<uint>"
    }
  ]
}

Response

HTTP 200 OK — The created object identifier (integer).

Example

Request:

POST /localhost/alertws/api/v1/alarms
Authorization: Bearer {access_token}
Content-Type: application/json

Body:

{
  "stationId": 1,
  "dataServerId": 1,
  "path": "test",
  "raised": true,
  "tagGroupId": 0,
  "priority": 1,
  "temporary": false,
  "eventCondition": {
    "value": "ConditionValue",
    "transitory": true,
    "reactivatable": false,
    "resettable": true
  },
  "value": "ElementValue",
  "location": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "horizontalAccuracy": 1.5,
    "altitude": 10.0,
    "verticalAccuracy": 1.0,
    "date": "2024-01-29T12:00:00Z",
    "beaconList": [
      {
        "id": "beacon123",
        "name": "Beacon 1",
        "type": "Undefined",
        "accuracy": 2.0,
        "date": "2024-01-29T12:05:00Z"
      },
      {
        "id": "nfc456",
        "name": "NFC Beacon 2",
        "type": "Nfc",
        "accuracy": 1.0,
        "date": "2024-01-29T12:10:00Z"
      }
    ],
    "zone": "Zone1"
  },
  "alarmDelay": 30,
  "alarmMessage": "Alarm Message",
  "alarmFormat": "Alarm Format",
  "alarmShortMessage": "Short Alarm Message",
  "alarmVocalMessageFile": "alarm_voice.mp3",
  "alarmAttachedFile": "alarm_attachment.txt",
  "alarmActions": [
    {
      "id": 1,
      "type": "ExecuteCommand",
      "scriptId": 101,
      "parameter": "CommandParameter",
      "flags": 0
    },
    {
      "id": 2,
      "type": "StopCommand",
      "scriptId": 102,
      "parameter": "StopParameter",
      "flags": 1
    }
  ],
  "resetMessage": "Reset Message",
  "resetFormat": "Reset Format",
  "resetShortMessage": "Short Reset Message",
  "resetVocalMessageFile": "reset_voice.mp3",
  "resetAttachedFile": "reset_attachment.txt",
  "resetActions": [
    {
      "id": 3,
      "type": "ExecuteCommand",
      "scriptId": 103,
      "parameter": "ResetCommandParameter",
      "flags": 2
    },
    {
      "id": 4,
      "type": "CallGroup",
      "scriptId": 104,
      "parameter": "GroupParameter",
      "flags": 3
    }
  ],
  "ackMessage": "Acknowledgment Message",
  "ackFormat": "Acknowledgment Format",
  "ackShortMessage": "Short Acknowledgment Message",
  "ackVocalMessageFile": "ack_voice.mp3",
  "ackAttachedFile": "ack_attachment.txt",
  "ackActions": [
    {
      "id": 5,
      "type": "PlaySound",
      "scriptId": 105,
      "parameter": "SoundParameter",
      "flags": 4
    },
    {
      "id": 6,
      "type": "CallUser",
      "scriptId": 106,
      "parameter": "UserParameter",
      "flags": 5
    }
  ]
}

Response:

197

GET /api/v1/alarms/histories

Retrieves the list of alarm histories.

Parameters

Property	Type	Description
stationId	uint	Filter by station identifier.
dataServerId	uint	Filter by data server identifier.
tagGroupId	uint	Filter by tag group identifier.
callGroupId	uint	Filter by call group identifier.
userId	uint	Filter by user identifier.
offset	uint	Pagination offset.
limit	uint	Maximum number of items to return.
from	dateTime	Start date/time filter (ISO-8601).
to	dateTime	End date/time filter (ISO-8601).
sort	string	"+id" for ascending sort on id; "-id" for descending sort on id.
search	string	Full-text search filter.

Response

HTTP 200 OK — PagingCollection<AlarmHistory> (see PagingCollection and AlarmHistory)

Example

Request:

GET /localhost/alertws/api/v1/alarms/histories
Authorization: Bearer {access_token}

Response:

{
    "items": [
        {
            "id": 1,
            "tagId": 69,
            "tagName": "Random.Int11",
            "message": "Matrikon.OPC.Simulation.1.Random.Int11",
            "priority": 3,
            "alarmTime": "2024-03-21T09:01:45+01:00",
            "ackTime": "2024-03-21T09:03:14+01:00",
            "resetTime": "2024-03-21T09:03:14+01:00",
            "alarmDuration": "00:01:29",
            "reactionDuration": "00:01:29",
            "interventionDuration": "00:00:00",
            "comment": ""
        },
        {
            "id": 2,
            "tagId": 70,
            "tagName": "Random.Int4",
            "message": "Matrikon.OPC.Simulation.1.Random.Int4",
            "priority": 3,
            "alarmTime": "2024-03-21T09:02:42+01:00",
            "comment": ""
        }
    ],
    "paging": {
        "offset": 0,
        "limit": 10,
        "total": 2
    }
}

GET /api/v1/alarms/statistics

Retrieves the list of alarm statistics.

Parameters

Property	Type	Description
stationId	uint	Filter by station identifier.
dataServerId	uint	Filter by data server identifier.
tagGroupId	uint	Filter by tag group identifier.
callGroupId	uint	Filter by call group identifier.
userId	uint	Filter by user identifier.
offset	uint	Pagination offset.
limit	uint	Maximum number of items to return.
from	dateTime	Start date/time filter (ISO-8601).
to	dateTime	End date/time filter (ISO-8601).
sort	string	"+id" for ascending sort on id; "-id" for descending sort on id.
search	string	Full-text search filter.

Response

HTTP 200 OK — PagingCollection<AlarmStatistic> (see PagingCollection and AlarmStatistic)

Example

Request:

GET /localhost/alertws/api/v1/alarms/statistics
Authorization: Bearer {access_token}

Response:

{
    "items": [
        {
            "id": 69,
            "tagName": "Random.Int11",
            "message": "Matrikon.OPC.Simulation.1.Random.Int11",
            "priority": 3,
            "code": 69,
            "failureNumber": 4,
            "failureTotalTime": "00:13:38",
            "failureMeanTime": "00:03:24"
        }
    ],
    "paging": {
        "limit": 10,
        "total": 1
    }
}

GET /api/v1/alarms/interventions

Retrieves the list of alarm interventions.

Parameters

Property	Type	Description
stationId	uint	Filter by station identifier.
dataServerId	uint	Filter by data server identifier.
tagGroupId	uint	Filter by tag group identifier.
callGroupId	uint	Filter by call group identifier.
userId	uint	Filter by user identifier.
offset	uint	Pagination offset.
limit	uint	Maximum number of items to return.
from	dateTime	Start date/time filter (ISO-8601).
to	dateTime	End date/time filter (ISO-8601).
sort	string	"+id" for ascending sort on id; "-id" for descending sort on id.
search	string	Full-text search filter.

Response

HTTP 200 OK — PagingCollection<AlarmIntervention> (see PagingCollection and AlarmIntervention)

Example

Request:

GET /localhost/alertws/api/v1/alarms/interventions
Authorization: Bearer {access_token}

Response:

{
    "items": [
        {
            "id": 45,
            "user": "Dupont",
            "interventionNumber": 5,
            "reactionMeanTime": "00:23:06",
            "interventionMeanTime": "03:52:45"
        }
    ],
    "paging": {
        "limit": 10,
        "total": 1
    }
}