Managing Alarms and Events

Overview
Historian includes Alarms and Events (A&E) archiving to provide the ability to retrieve and store Alarms and Events Data from any OPC-compliant A&E server through the OPC Classic Alarms and Events collector.
Alarms are generally defined as tags going into an abnormal condition. For example, an alarm could be set on a boiler when it reaches a specified temperature. Alarms usually have a well-defined life cycle, which is defined by the individual data sources the alarms are collected from (iFIX, for example). They enter an alarm state, are generally acknowledged, and then return to normal.
Events are generally defined as activities in a system that occur only once. For example, a user logging on to a device is an event. When viewing this data in Historian, each event is returned as a record. The Historian REST API provide API’s to store, retrieve, backup, restore, and delete alarms and events data.
Add Alarm or Event
Add alarm API allows you to create alarm in Historian Server.
METHOD POST
URI 
https://<historianservername>:443/historian-rest-api/v1/alarms/create
SAMPLE URI 
https://<historianservername>:443/historian-rest-api/v1/alarms/create
Payload
{
   "DataSource":"Simulation",
   "AlarmsInfo":[
      {
         "ItemId":"GF7DQL63E_Simulation.Simulation00001",
         "Source":"Simulation",         
         "DataSourceName":"Simulation",
         "Tagname":"GF7DQL63E_Simulation.Simulation00001",
         "AlarmType":4,
         "EventCategory":"SimCategory",
         "ConditionName":"Simulation",
         "SubConditionName":"Simulation",
         "StateTransitionTime":"2022-09-21T5:58:00.000Z",
         "StartTime":"2022-09-21T5:58:00.000Z",
         "EndTime":"2022-09-21T6:58:00.000Z",
         "AckTime":"2022-09-21T6:58:00.000Z",
         "TimeStamp":"2022-09-21T5:58:00.000Z",
         "Message":"This is simulation alarm",
         "Severity":100,
         "Actor":"Simulator",
         "Quality":3
      }
   ]
}
SAMPLE CURL COMMAND 
curl -i -H "Accept: application/json" -i -H "Content-Type: application/json" -H "Authorization: Bearer ” -d “{
   \"DataSource\":\"Simulation\",
   \”AlarmsInfo\”:[
      {
         \”ItemId\”:\”GF7DQL63E_Simulation.Simulation00001\”,
         \”Source\”:\”Simulation\”,         
         \”DataSourceName\”:\”Simulation\”,
         \”Tagname\”:\”GF7DQL63E_Simulation.Simulation00001\”,
         \”AlarmType\”:4,
         \”EventCategory\”:\”SimCategory\”,
         \”ConditionName\”:\”Simulation\”,
         \”SubConditionName\”:\”Simulation\”,
         \”StateTransitionTime\”:\”2022-09-21T5:58:00.000Z\”,
         \”StartTime\”:\”2022-09-21T5:58:00.000Z\”,
         \”EndTime\”:\”2022-09-21T6:58:00.000Z\”,
         \”AckTime\”:\”2022-09-21T6:58:00.000Z\”,
         \”TimeStamp \”:\”2022-09-21T5:58:00.000Z\”,
         \”Message\”:\”This is simulation alarm\”,
         \”Severity\”:100,
         \”Actor\”:\”Simulator\”,
         \”Quality\”:3
      }
   ]
}” -X PUT https://:443/historian-rest-api/v1/ alarms/create
Table 1. Query Parameters
Parameter Data Type Description
DataSource VT_BSTR The collector interface name associated with the alarm or event.
ItemId VT_BSTR The OPC ItemID of the alarm. This contains the source address of the data access tag with which the alarm is associated. This can contain a NULL value if an alarm is not associated with a tag.
Source VT_BSTR The unique identifier used by the OPC A&E Collector for the alarm or event.
DataSourceName VT_BSTR The collector interface name associated with the alarm or event.
Tagname VT_BSTR The Historian tag name associated with the alarm. This value is NULL unless the tag is also collected by Historian
AlarmType VT_BSTR

The alarm type:

  • Alarms: In Historian, the full life cycle of an alarm is stored as a single record in the alarm archive.
  • Alarm_History: The separate transitions for all alarms. One row per transition is returned.
  • Events: The simple and tracking events.
EventCategory VT_BSTR The OPC event category of the alarm or event.
ConditionName VT_BSTR The OPC condition of the alarm. Does not apply to event data. This value combined with the Source value comprises an alarm.
SubConditionName VT_BSTR The OPC subcondition of the alarm. Does not apply to event data. This value represents the state of the alarm.
StateTransitionTime VT_DBTimeStamp The time the state of the tag was generated.
StartTime VT_DBTimeStamp The start time or timestamp of the alarm or event.
EndTime VT_DBTimeStamp The end time of the alarm. Does not apply to event data.
AckTime VT_DBTimeStamp The time the alarm was acknowledged. Does not apply to event data.
TimeStamp VT_DBTimeStamp The time the alarm was generated.
Message VT_BSTR The message attached to the alarm or event.
Severity VT_I4 The severity of the alarm or event. Stored as an integer value with a range of 1–1000.
Actor VT_BSTR The operator who acknowledged the alarm, or caused the tracking event.
Quality VT_I4 The quality of the alarm or event.
Table 2. Response Parameters
Parameter Data Type Required? Description
ErrorCode Integer Yes For example, ErrorCode = 0 implies the operation was successful.
ErrorMessage String Yes For example, NULL.
Query Alarm or Event
The following table contains the query parameters for alarms and events data.
METHOD POST
URI 
https://<historianservername>:443/historian-rest-api/v1/alarms/query
SAMPLE URI 
https://<historianservername>:443/historian-rest-api/v1/alarms/query
Payload: 
{
  "AlarmType":"4",
  "StartTime":"2022-10-30T3:30:00.000Z",
  "EndTime":"2022-10-31T4:30:00.000Z",
  "DataSourceName":"GF7DQL63E_Simulation",
  "MaxRecords":50
}
Response: 
{"ErrorCode":0,"ErrorMessage":null,"Data":[{"Description":"This is a simulated alarm.","Source":"Simulation00001_ALM","Start Time":"2022-10-30T03:30:00.000Z","End Time":"2022-10-30T03:30:02.000Z","Condition":"Simulated","Sub Condition":"OK","Event Category":"SimCategory","Severity":0,"Modified Time":"2022-10-30T03:30:02.000Z","Quality":3}]}
SAMPLE CURL COMMAND 
curl -i -H "Accept: application/json" -i -H "Con tent-Type: application/json" -H "Authorization: Bearer ” -d “{
  \”AlarmType\”:\”4\”,
  \”StartTime\”:\”2022-10-30T3:30:00.000Z\”,
  \”EndTime\”:\”2022-10-31T4:30:00.000Z\”,
  \”DataSourceName\”:\”GF7DQL63E_Simulation\”,
  \”MaxRecords\”:50
}
” -X PUT https://:443/historian-rest-api/v1/ alarms/ query
Table 3. Query Parameters
Parameter Description Required? Values
DataSourceName The collector interface name associated with the alarm or event. false
AlarmType Classifies this AlarmInfo as an alarm or an event. Enter 1 for an event and 4 for an alarm. yes
StartTime The start time or time stamp of the alarm or event. yes
EndTime The end time of the alarm. This does not apply to event data. yes
MaxRecords Maximum records returned false
Table 4. Response Parameters
Parameter Data Type Required? Description
ErrorCode Integer Yes For example, ErrorCode = 0 implies the operation was successful.
ErrorMessage String Yes For example, NULL.
Delete Alarms or Events
This REST API allows to purge the alarms between time frame.
METHOD POST
URI 
https://<historianservername>:443/historian-rest-api/v1/alarms/delete
SAMPLE URI 
https://<historianservername>:443/historian-rest-api/v1/alarms/delete
Payload
https://<historianservername>:443/historian-rest-api/v1/alarms/delete
Payload:
{
  "StartTime":"2022-09-21T5:58:00.000Z",
  "EndTime":"2022-09-21T6:58:00.000Z"
}
SAMPLE CURL COMMAND 
curl -i -H "Accept: application/json" -i -H "Con tent-Type: application/json" -H "Authorization: Bearer ” -d “{
\"StartTime\":\"2022-09-21T5:58:00.000Z\",
  \"EndTime\":\"2022-09-21T6:58:00.000Z\"
}” -X PUT https://:443/historian-rest-api/v1/ alarms/delete
Table 5. Query Parameters
Parameter Description Required? Values
StartTime The start time or time stamp of the alarm or event. Yes
EndTime The end time of the alarm or event. Yes
Table 6. Response Parameters
Parameter Data Type Required? Description
ErrorCode Integer Yes For example, -26 A&E Server not connected
ErrorMessage String Yes For example, NULL.
Backup Alarms or Events

This REST API allows to create a copy of the alarm data in an offline file that can be restored later. The alarms are not removed from the online system.

METHOD POST
URI 
https://<historianservername>:443/historian-rest-api/v1/alarms/backup
SAMPLE URI 
https://<historianservername>:443/historian-rest-api/v1/alarms/backup
Payload
{
 "BackupFileName":"C:\\Proficy Historian Data\\Archives\\abc.zip,
  "StartTime":"2022-09-21T5:58:00.000Z",
  "EndTime":"2022-09-21T6:58:00.000Z"
}
SAMPLE CURL COMMAND 
curl -i -H "Accept: application/json" -i -H "Con tent-Type: application/json" -H "Authorization: Bearer ” -d “{
\"BackupFileName\":\"C:\\Proficy Historian Data\\Archives\\abc.zip\",
\"StartTime\":\"2022-09-21T5:58:00.000Z\",
  \"EndTime\":\"2022-09-21T6:58:00.000Z\"
}” -X PUT https://:443/historian-rest-api/v1/ alarms/ backup
Table 7. Query Parameters
Parameter Description Required? Values
BackupFileName Path of the backup file. Yes C:\\Proficy Historian Data\\Archives\\abc.zip
StartTime The start time or time stamp of the alarm or event. Yes
EndTime The end time of the alarm or event. Yes
Table 8. Response Parameters
Parameter Data Type Required? Description
ErrorCode Integer Yes For example, -26 A&E Server not connected.
ErrorMessage String Yes For example, NULL.
Restoring Alarms or Events

Restoring alarms to a running system makes them available for query and analysis. You can restore alarms that have been backed up previously..

METHOD POST
URI 
https://<historianservername>:443/historian-rest-api/v1/alarms/restore
SAMPLE URI 
https://<historianservername>:443/historian-rest-api/v1/alarms/restore
Payload:
C:\\Proficy Historian Data\\Archives\\abc.zip
SAMPLE cURL COMMAND 
curl -i -H "Accept: application/json" -i -H "Con tent-Type: application/json" -H "Authorization: Bearer ” -d  “C:\\Proficy Historian Data\\Archives\\abc.zip”  -X PUT https://:443/historian-rest-api/v1/ alarms/ restore
Table 9. Query Parameters
Parameter Description Required? Values

C:\\Proficy Historian Data\\Archives\\abc.zip

 Path of the restore file. Yes C:\\Proficy Historian Data\\Archives\\abc.zip
Table 10. Response Parameters
Parameter Data Type Required? Description
ErrorCode Integer Yes For example, 10 invalid parameter.
ErrorMessage String Yes For example, NULL.