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 set up a filter:

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

Trending Modal                                                                                                                                                     

2. 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.

 

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

 

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

Note:  API Filters must be set up 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 set up 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 the list of possible HTTP status codes.
Messages	array of message objects
Message:Message	string	Description of error.  See the 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 that contains a tagId, timestamp, value and an aggregated type that 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 that is mapped to a building, this is the unique identifier for the building.
Building	string	If related to an entity that is mapped to a building, this is the name of the building.
FloorId	string	If related to an entity that is mapped to a floor, this is the unique identifier for the floor.
Floor	string	If related to an entity that is mapped to a floor, this is the name of the floor.
RoomId	string	If related to an entity that 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"

        }

    ]

}