UNITY REST API Specification for Alarms and Data Retrieval

STATEMENT OF CONFIDENTIALITY & NON-DISCLOSURE

This document contains proprietary and confidential information. All data submitted to Customer is
provided in reliance upon its consent not to use or disclose any information contained herein except
in the context of its business dealings with Inaccess. The recipient of this document agrees to inform
present and future employees of Customer who view or have access to its content of its confidential
nature.

The recipient agrees to instruct each employee that they must not disclose any information
concerning this document to others except to the extent that such matter are generally known to,
and are available for use by, the public. The recipient also agrees not to duplicate or distribute or
permit others to duplicate or distribute any material contained herein without Inaccess express
written consent.

Inaccess retain all title, ownership and intellectual property rights to the material and trademarks
contained herein, including all supporting documentation, files, marketing material, and multimedia.

BY ACCEPTANCE OF THIS DOCUMENT, THE RECIPIENT AGREES TO BE BOUND BY THE

AFOREMENTIONED STATEMENT.

UNITY REST API Specification

for Alarms and Data Retrieval

COMMERCIAL IN CONFIDENCE 1
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS

September 2023
UNITY REST API Specification for Alarms and Data Retrieval

Document Version History

Date Document Description Author(s)
Version

2018 1.0 InAccess

2019-Mar-26 2.0 Document format update InAccess

2019-Sep-02 3.0 ApiKey method addition InAccess

2019-Oct-17 3.1 ApiKey method / Note1 addition InAccess

2020-Jan-10 3.2 “Get Segments of a Site” chapter fixes InAccess

“Fetch MeasurementSources of a Calculation Period

2020-Sep-07 4.0 InAccess
for multiple Segments” chapter addition

Added convenience endpoints for Alarms/Data

2021-Mar-21 5.0 InAccess
retrieval

ApiKey text modifications and Note2 addition /

Period key text modifications in the “Fetch
2023-Sep-08 5.1 InAccess
MeasurementSources of a Calculation Period for
multiple Segments” chapter

COMMERCIAL IN CONFIDENCE 2
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

Table of Contents
1. Prerequisites ............................................................................................................................................................. 7
1.1 Login Method / ApiKey................................................................................................................................ 7
1.1.1 Login ......................................................................................................................................................... 7
1.1.2 ApiKey ...................................................................................................................................................... 9
1.2 Get Sites operated by Agent.................................................................................................................... 10
1.3 Get Segments of a Site .............................................................................................................................. 12
2 State Variables (Alarm sources) ........................................................................................................................ 14
2.1 Get State Variables of a segment ........................................................................................................... 14
2.2 Search for State Variable Events (Alarms) ........................................................................................... 16
2.3 Search for Alarms in Sites ......................................................................................................................... 18
3 Measurement Locations (Measurement Data) ............................................................................................ 19
3.1 Get Measurement Locations of a segment ......................................................................................... 19
3.2 Retrieve Measurement Sources .............................................................................................................. 21
3.3 Search for Measurement Events per MeasurementSource .......................................................... 23
3.4 Fetch MeasurementSources of a calculation Period for multiple Segments .......................... 25
3.5 Search for Data in sites ............................................................................................................................. 33

COMMERCIAL IN CONFIDENCE 3
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

List of Tables
Table 1 – Call for login to the system ........................................................................................................ 7

Table 2 – Login method example .............................................................................................................. 7

Table 3 – Login method: cookie structure ................................................................................................ 8

Table 4 – Login method: logged in agent’s unique id ............................................................................. 8

Table 5 – Call for retrieving all the agent’s assigned sites from the Rest API ..................................... 10

Table 6 - Getting Sites operated by Agent: Curl command line example ........................................... 10

Table 7 - Getting Sites operated by Agent: Keeping the ID of each listed entry ............................... 11

Table 8 – Call for getting segments of a site .......................................................................................... 12

Table 9 – Getting segment of a site: Curl command line example ....................................................... 12

Table 10 - Getting segment of a site: keeping the id of each listed item ............................................. 13

Table 11 – Call for retrieving state variables of a segment..................................................................... 14

Table 12 - Getting State Variables of a segment: Curl command line example .................................. 14

Table 13 - Getting State Variables of a segment: keeping the StateVariable id of each listed item.. 15
Table 14 – Call to search for a state variable event (Alarms) ................................................................. 16

Table 15 - Searching for State Variable Events (Alarms): Curl request example .................................. 16
Table 16 - Searching for State Variable Events (Alarms): JSON response ............................................ 17

Table 17 - Call for retrieving Alarms for Sites.......................................................................................... 18

Table 18 – Call for getting Measurement Locations of a segment ....................................................... 19

Table 19 - Getting Measurement Locations of a segment: Curl command line example ................... 19

Table 20 - Getting Measurement Locations of a segment: Keeping the ID of each entity from the
JSON response........................................................................................................................................... 20

Table 21 - Call for retrieving Measurement Sources .............................................................................. 21

Table 22 - Retrieving Measurement Sources: Curl command line example ........................................ 21

Table 23 - Retrieving Measurement Sources: JSON response .............................................................. 22

Table 24 - Call to Search for Measurement Events per MeasurementSource ..................................... 23

Table 25 - Call to Search for Measurement Events per MeasurementSource: Curl command line
example ...................................................................................................................................................... 23

COMMERCIAL IN CONFIDENCE 4
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

Table 26 - Call to Search for Measurement Events per MeasurementSource: JSON response ......... 24

Table 27 - Call to Segment Query ........................................................................................................... 25

Table 28 – Segment Query example request for MeasurementSources.............................................. 26

Table 29 – Segment Query example response for MeasurementSources ........................................... 32

Table 30 - Call for retrieving Data for Sites ............................................................................................. 33

COMMERCIAL IN CONFIDENCE 5
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

SCOPE
The purpose of this document is to provide the reader with the means for fetching alarms and
measurements from the UNITY-BE, using HTTP REST calls.

To achieve this, some boilerplate REST calls are required, to authenticate and collect the necessary
data to finally fetch the actual content.

Please read through this document, as we provide detailed examples per request along with the
data required to keep per step for the next steps, until you fetch the data.

COMMERCIAL IN CONFIDENCE 6
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

1. Prerequisites
In this section, we describe the boilerplate calls required to fetch either measurements or
alarms. Also, you can find useful information about your asset portfolio.

1.1 Login Method / ApiKey

POST /ifms/login Login to the system

Table 1 – Call for login to the system

1.1.1 Login
The login method is the first method to be called by the agent, to gain access to further system
calls.
The HTTP body must contain the username, password and lang (language code, eg. “en”).

Example:
curl -X POST -k -i 'https://server/ifms/login' --data '{

"username" : "user",

"password" : "password",

"lang" : "en"

}'

Table 2 – Login method example

In the event of a successful login, the service will respond with 200 OK, which means that it is
logged in the UNITY System. In the Response Headers of this request there will be a Cookie
(IFMSCK), which should be saved. The agent must include this cookie in every subsequent request,
in order to communicate with our Rest API. You should reuse this cookie for all requests. Do not try
to re-login multiple times, as the system limits this action.

COMMERCIAL IN CONFIDENCE 7
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

The cookie has the following structure:

IFMSCK=data={uuid}&lang=en&session={sessionid}&type=null&digest=ee1KgfPFRsxhXjWtj1yZTw==

Table 3 – Login method: cookie structure

Also, from the response body, keep the logged in agent’s unique id (“id” field), in order to use it in
other services and get data that refers to the agent.

Example:

{"id":"UUID",

"name":"username",

"uri":"URL"}

Table 4 – Login method: logged in agent’s unique id

Otherwise, an error response code will be returned. The available error codes are:

• 401 Unauthorized: if the provided credentials were invalid.

• 404 Not Found: if the requested language is not available

COMMERCIAL IN CONFIDENCE 8
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

1.1.2 ApiKey
Due to the cookie required for the login methos, it is recommended that ApiKey is used.
ApiKey should be used in every API call as an HTTP Header with name “Api-Key.”

For Example:

Note 1:
As a convenience, use the https://server/ifms/agents/whoami to obtain the same response as in a
successful “login”, to obtain your agent’s data.

Note 2:
In API calls
server=URL of the UNITY Web portal
example_portal.solarpark-online.com
If you are not aware of the URL, contact [email protected]

COMMERCIAL IN CONFIDENCE 9
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

1.2 Get Sites operated by Agent

GET /ifms/agents/{id}/sites Retrieve all sites (plants)

Table 5 – Call for retrieving all the agent’s assigned sites from the Rest API

This call allows you to retrieve all the agent’s assigned sites (plants) from the Rest API.

Use the ID saved from the previous step. Also remember to include the IFMSCK in the cookie
header.

Here is a curl command line example:

curl -X GET -k --cookie 'IFMSCK:

data={uuid}&lang=en&session={sessionid}&type=null&digest=ee1KgfPFRsxhXjWtj1yZTw==' -i
'https://server/ifms/agents/{id}/sites'

Table 6 - Getting Sites operated by Agent: Curl command line example

COMMERCIAL IN CONFIDENCE 10
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

From the JSON response, keep the ID of each listed entry (site).

Example (along with other useful fields):

"id":"224",

...

},

"id":"335",

...

},

...

"id":"446",

...

Table 7 - Getting Sites operated by Agent: Keeping the ID of each listed entry

To this point, you should have a list of Site IDs available to your account. The next step is to
retrieve the actual data.
If you are interested in Alarms ( StateVariable Events) and a list of related Segment Apcodes and/or
StateVariable Apcodes is provided to you, it is better to jump to section “Search Alarms in Sites,”
else continue reading.
If you are interested in MeasurementEvents and a list of related Segment Apcodes and/or
MeasurementSource Apcodes and/or CalculationPeriod names is provided to you, it is better to
jump to section “Search Data in Sites,“ else continue reading.

COMMERCIAL IN CONFIDENCE 11
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

1.3 Get Segments of a Site

GET /ifms/sites/{site_id}/segments?recursive=true Retrieve all segments of a site

Table 8 – Call for getting segments of a site

This call retrieves the segments of a site.

Segments are nodes of the tree representation of the plant, they can be virtual or physical. The
physical segments of a plant are linked to physical “assets”. Virtual segments are used as tree
nodes, for the tree structure.

Make one call per site ID collected from the previous step.

Example curl command:

curl -X GET -k --cookie 'IFMSCK:

data={uuid}&lang=en&session={sessionid}&type=null&digest=ee1KgfPFRsxhXjWtj1yZTw==' -i
'https://server/ifms/sites/{site_id}/segments'

Table 9 – Getting segment of a site: Curl command line example

COMMERCIAL IN CONFIDENCE 12
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

From the response JSON body, keep the id of each listed item.

Example response (along with other fields):

"id":"224",

...

},

"id":"335",

...

},

...

"id":"446",

...

Table 10 - Getting segment of a site: keeping the id of each listed item

COMMERCIAL IN CONFIDENCE 13
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

2 State Variables (Alarm sources)

In this section we describe the call an agent should use to get the state variable he wants.

Consider the StateVariable entities to be the source that generates alarm events.
StateVariables are related to segments.

2.1 Get State Variables of a segment

GET /ifms/segments/{segment_id}/sv Retrieve state variables of a

ars segment

Table 11 – Call for retrieving state variables of a segment

Use the ID from the previous step to retrieve the available StateVariables for a Segment.

Example curl command:

curl -X GET -k --cookie 'IFMSCK:

data={uuid}&lang=en&session={sessionid}&type=null&digest=ee1KgfPFRsxhXjWtj1yZTw==' -i
'https://server/ifms/segmnets/{segment_id}/svars'

Table 12 - Getting State Variables of a segment: Curl command line example

COMMERCIAL IN CONFIDENCE 14
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

From the JSON body response keep the StateVariable id of each listed item.

Example (along with other fields):

"id":"224",

...

},

"id":"335",

...

},

...

"id":"446",

...

Table 13 - Getting State Variables of a segment: keeping the StateVariable id of each listed item

COMMERCIAL IN CONFIDENCE 15
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

2.2 Search for State Variable Events (Alarms)

GET /svars/{svar_id}/events Search for a state URL Parameters:

variable event occ_start_date,
occ_end_date

Table 14 – Call to search for a state variable event (Alarms)

With this call you may retrieve the actual alarm events per StateVariable. Use with the IDs from the
previous step.

You can define a time range to search events within, with the following parameters:

• occ_start_date: is the date of occurrence of event after which the search should apply in,
the date is in type YYYYMMDDTHHMMSSZ and is in UTC.
• occ_end_date: is the date of occurrence of event before which the search should apply in,
the date is in type YYYYMMDDTHHMMSSZ and is in UTC.

The parameters can be used in combination or none of them. If there are no parameters, then the
agent will get all the events of an svar_id. You should use this method with a valid time range.

Example curl request:

curl -X GET -k --cookie 'IFMSCK:

data={uuid}&lang=en&session={sessionid}&type=null&digest=ee1KgfPFRsxhXjWtj1yZTw==' -i
'https://server/ifms/svars/{svars_id}/events?occ_start_date={start_date}&occ_end_date={end_date}'

Table 15 - Searching for State Variable Events (Alarms): Curl request example

COMMERCIAL IN CONFIDENCE 16
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

The JSON response will contain the alerts, ordered by occurrence time:

"id":"45",

"name":"shelter temperature",

"type":"Temperature,HiHi"

"ack":false,

"severity":5,

"occured":"20090603T131809Z"

...

Table 16 - Searching for State Variable Events (Alarms): JSON response

COMMERCIAL IN CONFIDENCE 17
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

2.3 Search for Alarms in Sites

This section describes a convenience endpoint to retrieve Alarms for several Sites, based on
filtering parameters.

POST ./ifms/sites/svars/events Retrieve Alarms for Sites

Table 17 - Call for retrieving Alarms for Sites

The body of the request is a JSON object acting as a filter, with the following fields:

• siteIds: A JSON array of Site UUIDs. Will retrieve Alarms for these Sites.

• startDate: A String ISO8601 date, acting as starting point to Alarms retrieval.

• endDate: A String ISO8601 date, acting as the end date to Alarms retrieval.

• segmentApcodes: (Optional) A JSON array of Segment Apcode Strings. Filters result to

contain Alarms from specific Segments types.

• stateVatiableApcodes: (Optional) A JSON array of StateVariable Apcode Strings. Filters

result to contain Alarms from specific StateVariable types.

• severity: (Optional) An integer [0-100]. Result will contain alarms of the specific severity.

• severityLte: (Optional) An integer [0-100]. Result will contain alarms of with less than or
equal to this severity.

• severityGte: (Optional) An integer [0-100]. Result will contain alarms of with greater than or
equal to this severity.

• withNamePath: (Optional) Boolean. If set to true, the result will contain a name path of each
alarm for the Browser tree.

COMMERCIAL IN CONFIDENCE 18
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

3 Measurement Locations (Measurement Data)

In this section we will describe the way the agent will get the metrics from a segment.

3.1 Get Measurement Locations of a segment

GET /ifms/segments/{segme Retrieve all measurements for a segment

nt_id}/mlocs

Table 18 – Call for getting Measurement Locations of a segment

This call will retrive the MeasurementLocations os a Segment. Use the segment_id from paragraph
1.3, in order to get ids from measurement locations.

Consider a MeasurementLocation, as the entity placeholder of metrics. Example, a Temperature

metric.

Example curl command:

curl -X GET -k --cookie 'IFMSCK:

data={uuid}&lang=en&session={sessionid}&type=null&digest=ee1KgfPFRsxhXjWtj1yZTw==' -i
'https://server/ifms/segments/{segment_id}/mlocs

Table 19 - Getting Measurement Locations of a segment: Curl command line example

COMMERCIAL IN CONFIDENCE 19
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

Keep the ID of each entity from the JSON response:

"id":"3456",

...

},

"id":"3568",

...

},

...

"id":"3467",

...

Table 20 - Getting Measurement Locations of a segment: Keeping the ID of each entity from the JSON
response

COMMERCIAL IN CONFIDENCE 20
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

3.2 Retrieve Measurement Sources

GET /ifms/mlocs/{mlocs_i Retrieve all measurement sources per

d} Calculation Period for every Measurement
Location

Table 21 - Call for retrieving Measurement Sources

This call will retrieve the MeasurementSources of a MeasurementLocaion. A MeasurementSource, is

the actual source that generates metric events, (usually) at regular intervals, called Calculation
Periods. For the Temperature MeasurementLocation example, a MeasurementSource could be the
average 30min temperature.

Use the Ids from the previous step, in order to retrieve the ids for measurement sources per
MeasurementLocation.

Example curl command:

curl -X GET -k --cookie 'IFMSCK:

data={uuid}&lang=en&session={sessionid}&type=null&digest=ee1KgfPFRsxhXjWtj1yZTw==' -i
'https://server/ifms/mlocs/{mlocs_id}

Table 22 - Retrieving Measurement Sources: Curl command line example

COMMERCIAL IN CONFIDENCE 21
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

The JSON response will contain the following object among others:

{
...
"sources" : [
{
"id":"1234",
"calcPeriod":"20m"
...
},
{
"id":"1235",
"calcPeriod":"1d"
},
{
"id":"1236",
"calcPeriod":"1mo"
},

{
"id":"1237",
"calcPeriod":"1y"
}
],
...
}

Table 23 - Retrieving Measurement Sources: JSON response

Each listed MeasurementLocation has an array of “sources”. Keep the Ids of the
MeasurementSources, for the required period you want to retrieve data for in the next step.

COMMERCIAL IN CONFIDENCE 22
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

3.3 Search for Measurement Events per MeasurementSource

GET /sources/{source_id}/ Search for Parameters:

events measurement events start_date,

end_date

Table 24 - Call to Search for Measurement Events per MeasurementSource

This call retrieves actual metrics for a MeasurementSource. Use the Ids from the previous step. The
search of the events can be based on the following criteria:

• start_date : is the date of occurrence of event after which the search should apply in,
the date is in type YYYYMMDDTHHMMSSZ and is in UTC.
• end_date: is the date of occurrence of event before which the search should apply in,
the date is in type YYYYMMDDTHHMMSSZ and is in UTC.

The parameters can be used in combination or none of them. If there are no parameters, then the
agent will get all the events of a source_id. You should always use a valid time range.

Example curl command:

curl -X GET -k --cookie 'IFMSCK:

data={uuid}&lang=en&session={sessionid}&type=null&digest=ee1KgfPFRsxhXjWtj1yZTw==' -i
'https://server/ifms/sources/{source_id}/events?start_date={start_date}&end_date={end_date}'

Table 25 - Call to Search for Measurement Events per MeasurementSource: Curl command line example

COMMERCIAL IN CONFIDENCE 23
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

The JSON response will contain the event data, ordered by event time:

{ "val":"23",

"date":"20090501T0005Z",

"uri":"http://server/sources/345/events/20090501T0005Z"

},

{ "val":"24",

"date":"20090501T0010Z",

"uri":"http://server/sources/345/events/20090501T0010Z"

},

...

{ "val":"32",

"date":"20090531T02355Z",

"uri":"http://server/sources/345/events/20090531T2355Z"

Table 26 - Call to Search for Measurement Events per MeasurementSource: JSON response

COMMERCIAL IN CONFIDENCE 24
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

3.4 Fetch MeasurementSources of a calculation Period for multiple Segments

This is a more advanced REST API call, that may be used to fetch multiple MeasurementSources
along with their latest event, for a number of Segments for a particular Calculation Period in one
HTTP call. Also, information about the containing Segment and MeasurementLocation are included
in the result.

POST /segments/query Segment Query for JSON request body

MeasurementSources

Table 27 - Call to Segment Query

The request body of the HTTP POST, is a JSON text object with the keys:

• ids: A JSON array of Segment Id strings. Only Segments matching these Ids are queried.
Note that the Ids may not be limited to one Site only.

• mlocs: String, comma separated list of MeasurementLocation Apcodes to filter the result.
MeasurementSources only from MeasurementLocations with such Apcodes will be included
in the result. If omitted, no filtering takes place and all available MeasurementLocations are
included.

• period: String. It can take the values TR, 1d, 1mo, 1y. TR is the standard Calculation Period
(e.g. 10minutes, 15 minutes). If period is omitted in the JSON text, then TR Calculation period
will be used.

• stngs: String. Set this to empty string “”.

• svars: String. Set this to empty string “”.

Note:
This REST API call may be also used for fetching StateVariables and Settings, by respectively setting
their Apcodes in “stngs” and “svars” keys as done with “mlocs”. By setting any of these to empty
String “”, no results are fetched for this type.

COMMERCIAL IN CONFIDENCE 25
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

Example :
curl -X POST -k -i 'https://server/ifms/segments/query' --data '{

"ids" : ["id1", "id2"],

"mlocs" : "apcode1,apcode2,apcode3",

"stngs" : "",

"svars" : "",

"period" : "15m"

}'

Table 28 – Segment Query example request for MeasurementSources

A successful example JSON response would be:

[

"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",

"name": "string",

"apcode": "string",

"desc": "string",

"basetype": "string",

"properties":

"propApcodeName": "string",

"propApcodeName2": "string"

},

"type": {

"apcode": "string",

"id": "string",

COMMERCIAL IN CONFIDENCE 26
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

"name": "string",

"uri": "string"

},

"site": {

"properties": {

"additionalProp1": "string",

"additionalProp2": "string",

"additionalProp3": "string"

},

"name": "string",

"id": "string",

"state": "string",

"lastUpdate": "string",

"enterprise": {

"name": "string",

"id": "string",

"uri": "string",

"agentRoles": true

},

"installDate": "string",

"desc": "string",

"profile": {

"name": "string",

"id": "string",

"uri": "string"

},

COMMERCIAL IN CONFIDENCE 27
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

"type": {

"name": "string",

"id": "string",

"uri": "string",

"apcode": "string"

},

"asset": {

"model": {

"name": "string",

"id": "string",

"uri": "string"

},

"properties": {

"additionalProp1": "string",

"additionalProp2": "string",

"additionalProp3": "string"

},

"id": "string",

"site": {

"id": "string",

"name": "string",

"properties": {

"additionalProp1": "string",

"additionalProp2": "string",

"additionalProp3": "string"

COMMERCIAL IN CONFIDENCE 28
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

},

"state": "string",

"uri": "string"

},

"enterprise": {

"name": "string",

"id": "string",

"uri": "string",

"agentRoles": true

},

"assetType": {

"name": "string",

"id": "string",

"uri": "string",

"apcode": "string"

},

"serial": "string",

"installDate": "string"

},

"status": {

"children": [

"apcode": "string",

"id": "string",

"name": "string",

"uri": "string"

COMMERCIAL IN CONFIDENCE 29
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

],

"effectiveEvent": {

"ack": true,

"apcode": "string",

"date": "string",

"duration": 0,

"endDate": "string",

"id": "string",

"name": "string",

"quality": 0,

"severity": 0,

"type": "string",

"uri": "string"

},

"effectiveUnAckedEvent": {

"ack": true,

"apcode": "string",

"date": "string",

"duration": 0,

"endDate": "string",

"id": "string",

"name": "string",

"quality": 0,

"severity": 0,

"type": "string",

COMMERCIAL IN CONFIDENCE 30
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

"uri": "string"

},

"parent": {

"apcode": "string",

"id": "string",

"name": "string",

"uri": "string"

},

"svars": [],

"mlocs": [

"mloc": {

"apcode": "string",

"id": "string",

"name": "string",

"sscode": "string",

"uri": "string"

},

"msrc": {

"calcPeriod": "string",

"calcTimeSpanCount": 0,

"calcTimeSpanMode": "string",

"check": "string",

"date": "string",

"engUnit": "string",

COMMERCIAL IN CONFIDENCE 31
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

"id": "string",

"manualIngest": true,

"quality": "string",

"range": "string",

"uri": "string",

"val": "string"

},

"monitor": {

"engUnit": "string",

"monitor": true,

"status": "string",

"uri": "string"

],

"stngs": []

Table 29 – Segment Query example response for MeasurementSources

Which represents a JSON array, containing Segment information for every requested Segment Id.
Each Segment element has a “mlocs” key (among others), which is a JSON array of
MeasurementLocation objects related to the containing Segment object, each containing a “msrc”
key with details to the specific MeasurementSource with the requested Calculation Period, if found.
The “date”, “val” and “quality” fields for the “msrc” object, represent this MeasurementSource’s
latest event data, if any.

COMMERCIAL IN CONFIDENCE 32
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS
UNITY REST API Specification for Alarms and Data Retrieval

3.5 Search for Data in sites

This section describes a convenience endpoint to retrieve Data for several Sites, based on filtering
parameters.
POST ./ifms/sites/sources/events Retrieve Data for Sites

Table 30 - Call for retrieving Data for Sites

The body of the request is a JSON object acting as a filter, with the following fields:

• siteIds: A JSON array of Site UUIDs. Will retrieve Data for these Sites.

• startDate: A String ISO8601 date, acting as starting point to Data retrieval.

• endDate: A String ISO8601 date, acting as the end date to Data retrieval.

• segmentApcodes: (Optional) A JSON array of Segment Apcode Strings. Filters result to

contain Data from specific Segments types.

• measurementLocationApcodes: (Optional) A JSON array of MeasurementLocation Apcode

Strings. Filters result to contain Alarms from specific MeasurementLocation types.

• periods:(Optional) A JSON array of String CaclculationPeriod names. Filters the result to

contain Data only for specific CalculationPeriods ( e.g. 15m).

• withNamePath: (Optional) Boolean. If set to true, the result will contain a name path of each
alarm for the Browser tree.

COMMERCIAL IN CONFIDENCE 33
NOT FOR TRANSMITTAL, REPRODUCTION OR DISCLOSURE, WITHOUT WRITTEN AUTHORIZATION OF INACCESS