-
Notifications
You must be signed in to change notification settings - Fork 5
Alarm & Events API
Alarm & Events API, exposing A&E data from SAS/SCADA systems, released to prod ultimo November 2023. Data is available in the API with a few (2-5) minutes delay after the event has happened in the source system.
Original data source is SAS/SCADA system on facility, but source for pipelines to Omnia is copy of these data provided in databases on office/corporate network, as show in the EA Architecture Diagram.
The API is found in Equinor API portal, here (sign in required).
The API is released before data from all facilities is implemented, use the GetSources end point to se which facilities are available in the API. Per December 2023 data is provided for 14 facilities (Norway), work will be continued to add further EPN and EPI facilities.
The access is restricted per facility. Systems and/or persons having access to Timeseries for a certain facility, will have access to Alarms & Events for the same facility.
Teams that intend to utilize the Alarm & Events data through the API, please make a request to Omnia Industrial IoT via Services@Equinor, here. Tick the "Alarm & Events in Omnia" check box.
In order to access the API, this API permission is needed. API: omnia-iiot-ae-api-production, Permission: AE.Read. The Omnia Ind IoT will provide that, ref bullet above.
Data returned in API is shortly described in table below.
| Parameter | Description | Example |
|---|---|---|
| Facility | Facility code, as fetched from GetSources. | |
| sourceName | The source for the data you want to query. It may be equal to a "tag" / functional location, but this is not standardized. Will differ from facility to facility. | 19* - To get all A&E from system 19 |
| description | The [tag] description | |
| startTime | The start time for events you will retrieve, should be used in most cases to reduce the result set returned. Format - date-time (as date-time in RFC3339). | 2023-06-29T00:00:00 |
| endTime | Format - date-time (as date-time in RFC3339). | 2023-06-30T23:59:59 |
| eventType | OPC: Simple, Tracking or Condition | |
| eventCategory | OPC: EventCategoryName. Other: Name of EventCategory of originating EventLog: Operator, System, Process, Alarm… | |
| message | Event description: On, Off, Start, Stop, Running, Open, Close, Opened, Closed etc. | |
| severity | Severity as received from datasource | |
| priority | Priority, harmonized according to TR1494; Mapping table Severity - Priority - Priority Text (pr. facility) | 1 - Safety Critical alarms, 2 - Critical alarms, 3 - Less Critical alarms, 4 - Non-Critical alarms |
| condition | Alarm | Event identifier: HH, H, L, LL, Alarm, Limit, Value, Deviation, Manual, Forced, Blocked… |
| activeState | State; on or off | True, False |
| ackedState | Acked, Acknowledged, Unacknowledged etc. | True, False |
| alarmState | New, Active, Acked, Hidden, Shelved, Normal, Return, Inactive. Harmonized according to TR1494 |
In order to ensure effective use of the API, limiting the result set to what is actually of interest, the filtering capabilities should be used. Filtering can be applied on all the above mentioned attributes. Facility and sourceName are mandatory, the latter may be "*" for "all".
GET https://api.gateway.equinor.com/iiot/ae/v1/sources HTTP/1.1
Host: {host}
Connection: keep-alive
Authorization: Bearer {accessToken}Response:
{
"items": [{
"facility": "AHA"
}, {
"facility": "ASGA"
}, {
"facility": "ASGB"
}, {
"facility": "GFA"
}, {
"facility": "GFB"
}, {
"facility": "GFC"
}, {
"facility": "GKR"
}, {
"facility": "HD"
}, {
"facility": "KRIS"
}, {
"facility": "MLA"
}, {
"facility": "NOR"
}, {
"facility": "OSF"
}, {
"facility": "TROA"
}, {
"facility": "VIS"
}]
}Get first event (limit=1) from source "19DP2154A" at Åsgard A after a given time. "otherFields" included, so that we can see how data looked in the source before harmonized in Omnia.
GET https://api.gateway.equinor.com/iiot/ae/v1/events/ASGA?sourceName=19DP2154A&startTime=2024-01-24T08:30:00&sort=Asc&includeOtherFields=true&limit=1 HTTP/1.1
Host: {host}
Connection: keep-alive
Authorization: Bearer {accessToken}Response:
{
"items": [{
"timestamp": "2024-01-24T08:30:01.0800000Z",
"sourceName": "19DP2154A",
"description": "Fiscal Metering Topside Subsea",
"eventType": "Condition",
"eventCategory": "SystemAlarm",
"message": "Forrige WriteOnChange ikke eksekvert",
"severity": null,
"priority": 2,
"condition": null,
"alarmState": "DigAlActive",
"ackedState": false,
"activeState": true,
"suppressedOrShelved": false,
"node": "PCU132",
"processArea": null,
"actiontime": null,
"otherFields": {
"dB_ID": 415776853,
"priority": "Pri 2",
"eventType": "Systemalarm",
"acked": false,
"priority_NR": 2,
"eventType_NR": 1,
"alarmState_NR": 5,
"alarmLevel_NR": 7,
"eventSubType_NR": 0,
"origin": "PIO.01.000.0111.0115.PT.~0001",
"members": "",
"suppState": 1,
"redunRole": 2,
"cause": 1,
"seq": 6169,
"eventId": "00000000-0000-0080-8000-000018c84055"
}
}],
"totalCount": 8,
"continuationToken": "eyJPZmZzZXQiOjF9"
}Get latest Priority 2 Alarm from KRIStin. The clue to get the latest is "sort=Desc".
GET https://api.gateway.equinor.com/iiot/ae/v1/events/KRIS?sourceName=*&sort=Desc&includeOtherFields=false&priority=2&limit=1
HTTP/1.1
Host: {host}
Connection: keep-alive
Authorization: Bearer {accessToken}Response:
{
"items": [{
"timestamp": "2024-01-24T09:19:10.0550000Z",
"sourceName": "18TT3303",
"description": "Oppstrøms choke, brønn 3, ramme P",
"eventType": "Condition",
"eventCategory": "ProcessAlarm",
"message": "H",
"severity": null,
"priority": 2,
"condition": "WH",
"alarmState": "Aktiv",
"ackedState": false,
"activeState": true,
"suppressedOrShelved": false,
"node": "S04-PS74",
"processArea": "Subsea",
"actiontime": null
}],
"continuationToken": "eyJPZmZzZXQiOjF9"
}Use != to exclude specific items from list, here 2 sources are excluded (result not shown).
GET https://api.gateway.equinor.com/iiot/ae/v1/events//GFA?sourceName=*&sort=desc&SourceName!=AHYT-Q-ACOF&SourceName!=FIELDBUS&limit=200&startTime=2023-02-02T02:00:00&endTime=2023-02-19T02:00:00
HTTP/1.1
Host: {host}
Connection: keep-alive
Authorization: Bearer {accessToken}As an alternative to using the API to pull for A&E, you may configure an EventHub and instruct our API to stream data to that hub continuously as we receive data from the data sources. Currently EventHub is the only receiving hub supported.
Configure a receiving EventHub in your own subscription, and use this endpoint to instruct API where to stream data. The connection string provided must have write access.
POST https://api.gateway.equinor.com/iiot/ae/v1/streaming/destinationCall streaming/subscriptions to instruct which facilities to stream data for. There is no filtering capabilities, so all Alarms & Events from each faciity will be streamed to destination.
POST https://api.gateway.equinor.com/iiot/ae/v1/streaming/subscriptions/{facility}Terminate (delete) streaming for a given facility using the endpoint DEL streaming/facilities.
DEL https://api.gateway.equinor.com/iiot/ae/v1/streaming/subscriptions/{facility}