Aurora Application Programming Interface (API)

API Filter

The API exists as an endpoint on the Aurora Server and allows for the retrieval of live and historical data by filter or individual tag.  A filter can be created in Aurora by grouping a set of tags together for retrieval through the API.

Note:  each filter is limited to 40 tags.  If you need a filter with more than 40 tags then contact Blue Pillar Customer Support and we can create them on your behalf.

How to setup a filter:

  1. Select the  trending option in the application header and Aurora Platform will display the Trending modal 

Trending Modal  

  1. Select a tag by clicking on the tag row and Aurora Platform will display the tag in the “Select a tag from the grid to the left” area 

Note:  the column headers have filter options so that the list of tags can be reduced to a more granular list.

 

  1. Repeat step 2 until you have selected all the desired tags for the API Filter

  

  1. Type a Filter Name in the Save Tag Selection field
  2. Click the Save option and the Aurora Platform has a stored API Filter available for use 

Note:  API Filters must be setup on each individual server. 

API Authentication

The API uses basic authentication consisting of a user name and password.  It is suggested that a user is created in Aurora specifically for API use and granted access to all systems containing tags that will be retrieved through the API. 

How to setup a header with basic authentication:

  1. Build a string of the form username:password
  2. Base64 encode the string
  3. Supply an “Authorization” header with content “Basic ” followed by the encoded string.
  4. For example, a user name of “test” with a password of “test” would be test:test which is dGVzdDp0ZXN0 after encoding. The request header should contain “Authorization: Basic dGVzdDp0ZXN0”.

API Methods

Method

V1 Route

V2 Route

Description

GET

/v1/filters

/v2/filters

Gets Filters owned by the authenticated user. Includes all associated tags and tag detail.

GET

/v1/filters/{filterId}/Historical

/v2/filters/{filterId}/Historical

Gets historical data for the tags associated with the provided filter.

GET

/v1/filters/{filterId}/Live

/v2/filters/{filterId}/Live

Gets live data for the tags associated with the provided filter.

GET

/v1/tags/{tagId}/Historical

/v2/tags/{tagId}/Historical

Gets historical data for the provided tag. 

GET

/v1/tags/{tagId}/Live

/v2/tags/{tagId}/Live

Gets live data for the provided tag.

POST

/v1/tags/{tagId}?value={tvalue}

/v2/tags/{tagId}?value={tvalue}

Attempts to update the value for the provided tag.

POST

/v1/tags/Historical

/v2/tags/Historical

Allows insert of data to our telemetry tables for Minute, QuarterHour, Hour and Day for one or more existing tags.

GET

/v1/alarms

/v2/alarms

Returns a list of current alarms. 

GET

/v1/alarms/{alarmId}

/v2/alarms/{alarmId}

Returns the current state for the provided alarm.

GET /filters

Description:  Gets Filters owned by the authenticated user. Includes all associated tags and tag detail.

Parameters:  None

Supported Types:  application/json

Sample Request:  GET ../API/v1/filters

Responses:  A successful request will return a HTTP status code of 200 and a response containing a filters object.  See the Error Codes and Responses section for a full list of HTTP status codes and error codes. 

GET /filters/{filterId}/Historical

Description:  Gets historical data for the tags associated with the provided filter. 

Parameters

Name

Located In

Description

Required

FilterId

Path

The id of the filter containing the list of tags to return.

Yes

Interval

Query string

Interval of the data to be returned.  Valid values are ‘Minute’, ‘QuarterHour’, ‘Hour’ and ‘Day’.

Yes

Start

Query string

Starting date/time range of data to retrieve.

Yes

End

Query string

Ending date/time range of data to retrieve.

Yes

DateRangeType

Query string

Identifies the time zone to use when applying the Start and End date range.  Valid values are ‘UTC’ and ‘Site’.  If not set, the default is ‘Site’.

No

Supported Types: 

  • application/json
  • text/csv 

Sample Request: 

GET ../API/v1/filters/{filterId}/Historical?Interval=QuarterHour&DateRangeType=Site&Start=2016-07-26 01:00:00&End=2016-07-27 01:00:00

Responses:  A successful request will return a HTTP status code of 200 and a response containing a historical data object.  See the Error Codes and Responses section for a full list of HTTP status codes and error codes. 

GET /filters/{filterId}/Live

Description:  Gets live data for the tags associated with the provided filter. 

Parameters

Name

Located In

Description

Required

FilterId

Path

The id of the filter containing the list of tags to return.

Yes

Supported Types:  application/json

Sample Request:  GET ../API/v1/filters/{filterId}/Live

Responses:  A successful request will return a HTTP status code of 200 and a response containing a live data object.  See the Error Codes and Responses section for a full list of HTTP status codes and error codes.

GET /tags/{tagId}/Historical

Description:  Gets historical data for the provided tag.

Parameters

Name

Located In

Description

Required

TagId

Path

The id of the tag to return.

Yes

Interval

Query string

Interval of the data to be returned.  Valid values are ‘Minute’, ‘QuarterHour’, ‘Hour’ and ‘Day’.

Yes

Start

Query string

Starting date/time range of data to retrieve.

Yes

End

Query string

Ending date/time range of data to retrieve.

Yes

DateRangeType

Query string

Identifies the time zone to use when applying the Start and End date range.  Valid values are ‘UTC’ and ‘Site’.  If not set, the default is ‘Site’.

No

Supported Types: 

  • application/json
  • text/csv 

Sample Request: 

GET ../API/v1/tags/{tagId}/Historical?Interval=QuarterHour&DateRangeType=Site&Start=2016-07-26 01:00:00&End=2016-07-27 01:00:00

Responses:  A successful request will return a HTTP status code of 200 and a response containing a historical data object.  See the Error Codes and Responses section for a full list of HTTP status codes and error codes.

GET /tags/{tagId}/Live

Description:  Gets live data for the provided tag.

Parameters

Name

Located In

Description

Required

TagId

Path

The id of the tag to return.

Yes

Supported Types:  application/json

Sample Request:  GET ../API/v1/tags/{tagId}/Live

Responses:  A successful request will return a HTTP status code of 200 and a response containing a live data object.  See the Error Codes and Responses section for a full list of HTTP status codes and error codes.

POST /tags/{tagid}?value={value}

Description:  Attempts to update the value for the provided tag.

Parameters

Name

Located In

Description

Required

TagId

Path

The id of the tag to write a value.

Yes

Value

Query String

Value to write.  This must match the defined tag type.  So if the tag is a discrete type, the value must be true or false, otherwise, numeric.  NOTE:  If there’s a configured range for the tag, the value must be within the range or an error will be returned.

Yes

Supported Types: application/json

Sample Request: POST ../api/v1/tags/{tagid}?value={value}

Responses:  A successful request will return a HTTP status code of 200.  See the Error Codes and Responses section for a full list of HTTP status codes and error codes.

Post /v1/tags/Historical

Description:  Allows insert of data to our telemetry tables for Minute, QuarterHour, Hour and Day for one or more existing tags. 

Parameters: None

Supported Types: application/json

Sample Request:  POST ../api/v1/historical

Request Body:  Accepts historical data object.

Responses:  A successful request will return a HTTP status code of 200.  See the Error Codes and Responses section for a full list of HTTP status codes and error codes.

Get /v1/alarms

Description:  Returns a list of current alarms. 

Parameters: None

Supported Types: application/json

Sample Request: GET ../api/v1/alarms

Responses:  A successful request will return a HTTP status code of 200 and a response containing an alarm data object.  See the Error Codes and Responses section for a full list of HTTP status codes and error codes.

Get /v1/alarms/{alarmid}

Description:  Returns the current state for the provided alarm.

Parameters

Name

Located In

Description

Required

Alarmid

Path

The id of the alarm to retrieve.

No.  If not supplied, all current alarms will be returned.

 

Supported Types:  application/json

Sample Request:  GET ../api/v1/alarms/{alarmid}

Responses:  A successful request will return a HTTP status code of 200 and a response containing an alarm data object.  See the Error Codes and Responses section for a full list of HTTP status codes and error codes.

 

API Error Codes and Responses

HTTP Status Codes

Code

Text

Description

200

OK

Success!

400

Bad Request

The request was invalid.  An accompanying error message will explain further.

401

Unauthorized

Missing or invalid authentication credentials.

403

Forbidden

The request is understood, but it has been refused or access is not allowed.  An accompanying error message will explain further.

406

Not Acceptable

Invalid accept type in header.  Supported types are listed per route.  All routes support application/json and historical data routes also support text/csv.

413

Request Entity Too Large

The response is too large.  If making a request through an historical data route, try using a smaller Start and End date range. 

500

Internal Server Error

An unexpected exception occurred.  Contact BluePillar support and supply the x-logging-id in the response header.

API Error Messages

All error messages are returned in json.  See error object for field description and sample.

Error Codes

Code

Text

Description

100

Authentication credentials are missing or incorrect.

Corresponds with an HTTP 401.

201

Content type not supported.

Corresponds with an HTTP 406.

202

Unexpected exception.

Corresponds with an HTTP 500.

203

Requested payload is too large. Try limiting date range or number of tags in request.

Corresponds with an HTTP 413.

205

Unauthorized resource requested.

Corresponds with an HTTP 403.

1001

Empty list of tag ids presented during live data retrieval.

Corresponds with an HTTP 400.  This will be returned if live data routes return no data. 

1100

Missing required Tag Id.

Corresponds with an HTTP 400. 

1101

Missing required start date.

Corresponds with an HTTP 400.  Returned by the historical data routes when start date parameter is missing. 

1103

Missing required end date.

Corresponds with an HTTP 400.  Returned by the historical data routes when end date parameter is missing. 

1105

Invalid end date. End date/time must be greater than start date/time.

Corresponds with an HTTP 400.  Returned by the historical data routes when specified date range is invalid. 

1106

Invalid interval. Supported values are Minute, QuarterHour, Hour or Day.

Corresponds with an HTTP 400.  Returned by the historical data routes when the interval parameter contains a non-supported value. 

1201

Missing required filter id.

Corresponds with an HTTP 400. 

 

API Object Definitions

Filters Object

Field

Type

Description

Id

string

Unique identifier for the filter.

Name

string

Name of the filter.

Tags

array of Tag objects

 

Tag:Id

string

Unique identifier for the tag.

Tag:Name

string

Name of the tag.

Tag:Entity

string

Name of the entity associated to the tag.

Tag:SiteName

string

Name of the site associated with the entity, otherwise, empty string.

Tag:SiteId

string

Unique identifier for the site associated with the entity, otherwise, empty guid. Example: 00000000-0000-0000-0000-000000000000

Tag:Building

string

Name of the building associated with the entity, otherwise, empty string.

Tag:Floor

string

Name of the floor associated with the entity, otherwise, empty string.

Tag:Room

string

Name of the room associated with the entity, otherwise, empty string.

Tag:DataType

string

Contains discrete or analog.

Json Example of Filters Object

[{

                "Id": "80936624-938D-4854-8476-8B191C07A897",

                "Name": "filter1",

                "Tags": [{

                                "Id": "E7D98DE2-5EA1-4FC7-A5C4-712DD00D5FC5",

                                "Name": "tag1",

                                "Entity": "entity1",

                                “SiteName”:”testSite1",

                                “SiteId”:”D0955B4A-E340-4C5A-8029-4B40E3620F07",

                                "Building": "building1",

                                "Floor": "floor1",

                                "Room": "room2",

                                “DataType”: “analog”

                }, {

                                "Id": "1B44BD9A-DC32-43EF-82B6-E35A63743035",

                                "Name": "tag2",

                                "Entity": "entity2",

                                “SiteName”:”testSite2",

                                “SiteId”:”7F4B1CDB-C628-445A-8213-DE9235A29967",

                                "Building": "building1",

                                "Floor": "floor2",

                                "Room": "room1",

                                “DataType”: “discrete”

                }]

}, {

                "Id": "40D96DB0-1D95-485F-874D-8A00736DFE41",

                "Name": "filter2",

                "Tags": [{

                                "Id": "97E9B219-43BC-4A8B-904C-9E1EC71877BA",

                                "Name": "tag3",

                                "Entity": "entity3",

                                “SiteName”:”testSite3",

                                “SiteId”:”4363D000-072B-42E3-B266-9E3E2B768788",

                                "Building": "building2",

                                "Floor": "floor1",

                                "Room": "room1",

                                “DataType”: “analog”

                }]

}]

Historical Data Object

Field

Type

Description

SiteId

string

Unique identifier for the site associated with the entity, otherwise, empty guid.  Example: 00000000-0000-0000-0000-000000000000

SiteName

string

Can contain one of the following:

1.       Name of the site associated with the entity or empty string

2.       “Given tag is not authorized.” when the authenticated user is not authorized to view the entity associated with the tag.

 

TagId

string

Unique identifier for the tag.

SiteDateTime

string

The date/time for the data point expressed in the site time zone.

DateTimeUTC

string

The date/time for the data point expressed in UTC.

Mean

number

The average value over the interval.  For cumulative data this will represent the delta over the interval.

Min

number

The minimum value over the interval.

Max

number

The maximum value over the interval.

Median

number

The median value over the interval.

Total

number

The sample value at the earliest time unit for the sample, rather than the sum of the values over the interval of the sample.

StDev

number

The standard deviation over the interval.

SampleSize

integer

Expected number of data points used to evaluate the interval.

ActualSampleSize

integer

Actual number of data points used to evaluate the interval.

Quality

integer

Not implemented.

MinTsUTC

string

The date/time when the Min value was captured.

MaxTsUTC

string

The date/time when the Max value was captured.

SampleTsUTC

string

The date/time when the SampleValue was captured.

Sample

Number

The earliest value within the sample interval. For an interval of Minute this is the first (00) second, for all other intervals this is the first minute.

Json Example of Historical Data Object

[{

                "SiteId": "628A126D-9CEA-4DCD-B267-0EF0CA3A03A3",

                "SiteName": "Site1",

                "TagId": "EFB83F06-C4AA-43D1-84AF-93EA66FA357E",

                "SiteDateTime": “2016-07-27T15:30:00",

                "DateTimeUTC": "2016-07-27T19:30:00",

                "Mean": 7.168,

                "Min": 0,

                "Max": 89.6,

                "Median": 0,

                "Total": 6451.2,

                "StDev": 9.253848209,

                "SampleSize": 900,

                "ActualSampleSize": 5,

                "Quality": 1

}, {

                "SiteId": "13DA3496-7E4D-4B0F-A2F6-B6A06203A4AE",

                "SiteName": "Site2",

                "TagId": "DFBAF0B0-7581-41AA-8782-5C9B760A5F27",

                "SiteDateTime": "2016-07-27T15:45:00",

                "DateTimeUTC": "2016-07-27T19:45:00",

                "Mean": 0.798134359,

                "Min": 0.794062495,

                "Max": 0.803437471,

                "Median": 0,

                "Total": 718.3209234,

                "StDev": 0.001301139,

                "SampleSize": 900,

                "ActualSampleSize": 532,

                "Quality": 1

}] 

Live Data Object

Field

Type

Description

TimeStampUTC

string

The date/time in UTC corresponding to the live value.

LiveData

array of Tag/Value pairs

 

TagId

string

Unique identifier for the tag.

Value

string

Can contain one of the following:

1.       Live tag value

2.       “Given tag is not authorized.” when the authenticated user is not authorized to view the entity associated with the tag.

3.       “Given tag is invalid.” when we are not capturing data for the tag.

Json Example of Live Data Object

{

                "TimeStampUTC": "2016-07-25 00:00:00",

                "LiveData": [{

                                "TagId": "0C92C503-DDCE-45A3-92CE-EB2A75FB2333",

                                "Value": 1

                }, {

                                "TagId": "82351CC2-21E3-4908-BE86-B991B742506D",

                                "Value": 162.391667683919

                }, {

                                "TagId": "E7D98DE2-5EA1-4FC7-A5C4-712DD00D5FC5",

                                "Value": 278.5

                }]

}

Error Object

Field

Type

Description

Status

string

HTTP status code for the response. See list of possible HTTP status codes.

Messages

array of message objects

 

Message:Message

string

Description of error.  See list of error messages and associated codes.

Message:ErrorCode

string

Code associated to the error.

Json Example of Error Object

{

"status":"406",

"messages":[{

"message":"Content type not supported.",

"errorCode":"201"

}]

}

Historical Data POST Object Definition

There are two sample types supported for a post, a single data point which contains a tagId, timestamp, value and an aggregated type which contains additional fields such as min/max/mean etc. over an interval.  When posting an aggregated sample, all aggregated fields are required as stated below.

Field

Type

Required

Description

insertType

string

yes

Only supports ‘insertNew’ which means a new record will be added.  If the record already exists, the data point will be ignored.  May support updates in the future.

interval

string

yes

This defines the type of sample being posted.  Supported values are minute, quarter-hour, hour and day. 

timeZoneSource

string

yes

The source of the time zones for the timestamps in the posted payload.  Supported values are site and utc.  When set to utc, there will be no conversion done on the posted timestamps.  When set to site, the time zone associated to the tag’s site, will be used to convert the timestamp to utc for persistence.

timeStamp

string

yes

Timestamp for the samples in the post.  Can provide multiple timestamps/data points per payload.

tagId

string

yes

Aurora internal identifier for the data point.

value

string

yes

Actual value for the data point.

mean

string

Only when part of an aggregated sample

Average value for the data point over an interval.

min

string

Only when part of an aggregated sample

Minimum value for the data point over an interval.

max

string

Only when part of an aggregated sample

Maximum value for the data point over an interval.

median

string

Only when part of an aggregated sample

Median value for the data point over an interval.

stDev

string

Only when part of an aggregated sample

Standard deviation for the data point over the interval.

sampleSize

number

Only when part of an aggregated sample

Number of actual data points used to calculate the aggregated values over the interval.

quality

number

Only when part of an aggregated sample

If there were actual data points used to calculate the aggregated values, this should be set to 0.  If only estimated data points were used, then 1.

minTimeStamp

string

Only when part of an aggregated sample

The timestamp associated with the minimum value over the interval.

maxTimeStamp

string

Only when part of an aggregated sample

The timestamp associated with the maximum value over the interval.

Historical Data Post Sample

{

  "insertType": "insertNew",

  "interval": "Day",

  "timeZoneSource": "Site",

 

  "intervalData": [{

    "timeStamp": "2017-12-05 00:00:00",

   

    "tagData": [{

      "tagId": "18D906E3-41B2-4E93-A434-75B7B8281767",

      "value": "18380",

      "mean": "18370",

      "min": "18350",

      "max": "18380",

      "median": "18350",

      "stDev": "1.5",

      "sampleSize": 59,

      "quality": 1,

      "minTimeStamp": "2017-12-05 00:00:59",

      "maxTimeStamp": "2017-12-05 00:00:00"

    }]

  }   

  ,{             

    "timeStamp": "2017-12-04 00:00:00",

   

    "tagData": [{

      "tagId": "18D906E3-41B2-4E93-A434-75B7B8281767",

      "value": "18390"

    }]

  }   

  ,{              

    "timeStamp": "2017-12-03 00:00:00",

   

    "tagData": [{

      "tagId": "18D906E3-41B2-4E93-A434-75B7B8281767",

      "value": "18400"

    }]   

  }

  ,{

                "timeStamp": "2017-12-05 00:00:00",

               

                "tagData": [{

      "tagId": "722612A6-D4CD-4C67-8C16-13EB2B102CAB",

      "value": "9987"

                }]

   

                  }]               

 

}

Alarm Data Object Definition

Field

Type

Definition

Id

string

Unique identifier for the alarm instance

AlarmType

string

Possible values:

sys,dig,hihi,hi,lolo,lo,run

 

sys – system

dig - digital

Tag

string

If the alarm is on a specific tag, this is the tag name, otherwise, empty string.

TagId

string

If the alarm is on a specific tag, this is the unique identifier for the tag.

Description

string

Description of the alarm.

Value

string

The value that triggered the alarm.

CurrentValue

string

The current value for the data point that triggered an alarm.

ValueFriendlyName

string

For alarms of type hihi, hi, lolo and lo.  Distinct friendly names can be configured for the alarms.

Status

string

Current state of the alarm.  Possible values are:

Cleared, Acknowledged, Unacknowledged

SiteId

string

If related to a site, this is the unique identifier for the site.

Site

string

If related to a site, this is the site name.

BuildingId

string

If related to an entity which is mapped to a building, this is the unique identifier for the building.

Building

string

If related to an entity which is mapped to a building, this is the name of the building.

FloorId

string

If related to an entity which is mapped to a floor, this is the unique identifier for the floor.

Floor

string

If related to an entity which is mapped to a floor, this is the name of the floor.

RoomId

string

If related to an entity which is mapped to a room, this is the unique identifier for the room.

Room

string

If related to an entity which is mapped to a room, this is the room name.

EntityId

string

If related to an entity, this is the unique identifier for the entity.

Entity

string

If related to an entity, this is the entity name.

Device

string

If related to a device, this is the device name.

DateTimeInitiatedUtc

string

DateTime the alarm was initiated in UTC.

DateTimeAcknowledgedUtc

string

If acknowleded, this is the datetime that the alarm was acknowleded in UTC.

DateTimeClearedUtc

string

If cleared, this is the datetime that the alarm cleared in UTC.

UserAcknowledged

string

If acknowledged by a user, this will contain the userid.

Url

string

url to retrieve the state of this alarm

Alarm Data Object GET Response Sample

{

    "TimeStampUtc": "2018-02-12T17:34:23.6502952Z",

    "AlarmData": [

        {

            "Id": "c7091524-54c5-43e2-b965-5de5e3317b61",

            "AlarmType": "dig",

            "Tag": "ConnectedToEmergency",

            "TagId": "2ff0b25e-b2e0-4da6-9627-05ac22146dab",

            "Description": "Connected To Emergency",

            "Value": "True",

            "CurrentValue": "False",

            "ValueFriendlyName": "Closed",

            "Status": "Cleared",

            "SiteId": "4b0cbbed-bb0d-4b9e-a2ab-f2d2f561f76c",

            "Site": "fake site",

            "BuildingId": "ebe8ca5c-1f92-4b00-a4b1-3ead85563efd",

            "Building": "Robertson Surgery Center",

            "FloorId": "011c855f-4c3a-4e54-9d2c-a84cf360cd1e",

            "Floor": "Ground",

            "RoomId": "30d977e6-4b96-42f8-8a8c-65d97bd39acd",

            "Room": "Outside",

            "EntityId": "9e86c496-c9c2-4f34-bd5c-d1c30cc0c880",

            "Entity": "Kep_ATS5",

            "Device": "GIM",

            "DateTimeInitiatedUtc": "02/06/2018 19:15:50",

            "DateTimeAcknowledgedUtc": "",

            "DateTimeClearedUtc": "02/06/2018 19:21:59",

            "UserAcknowledged": "",

            "Url": "/api/v1/alarms/c7091524-54c5-43e2-b965-5de5e3317b61"

        },

                                {

            "Id": "020f34bb-3560-4731-8005-1b9403f723ff",

            "AlarmType": "lo",

            "Tag": "FuelLevel",

            "TagId": "db73f43b-79c3-45a9-b981-74f74685e5ca",

            "Description": "",

            "Value": "500.000",

            "CurrentValue": "550",

            "ValueFriendlyName": "",

            "Status": "Unacknowledged",

            "SiteId": "",

            "Site": "",

            "BuildingId": "1afbff47-0ea8-4f14-8851-a34e5edfe7c1",

            "Building": "MSK Main Hospital",

            "FloorId": "96fc5236-52a7-4d81-96aa-c5c824dd315b",

            "Floor": "Ground",

            "RoomId": "6cb9f8a0-93be-4be1-8c95-ab1f07cc530a",

            "Room": "Outside",

            "EntityId": "a3c97491-4c7c-4375-86f3-b8345c72e7bd",

            "Entity": "Kep_Fuel1",

            "Device": "FIM",

            "DateTimeInitiatedUtc": "10/24/2017 15:40:19",

            "DateTimeAcknowledgedUtc": "",

            "DateTimeClearedUtc": "",

            "UserAcknowledged": "",

            "Url": "/api/v1/alarms/020f34bb-3560-4731-8005-1b9403f723ff"

        }

    ]

}

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk