In this release

We provide functionality that allows Property Owner Admin to manage Organization administrator roles. Also in this release, we add a new endpoint for fetching observations, with pagination implemented using tokens.

New functionality


1. Role management for Property Owner Admin

This release provides full Role management for Property Owner Admins, giving access to Organization Admin roles.

  • PUT /json/role – update existing full Role, but it is not possible to update such fields as class, canManageOrganization, canManageResourcePermissionPolicies, propertyOwner.
  • POST /json/role – create a new Organization Admin role, only if it is missing for specified organization
  • DELETE /json/role/{id} – delete Organization Admin role by ID, if the organization no longer exists.

2. New Improved endpoint to fetch sensor observations

A new endpoints for fetching sensors telemetry for a requested period of time:

  • GET /json/sensor/{id}/observations
  • GET /sensor/{id}/observations

The response will be paginated, and a unique token (“next page token”) is generated and returned to let the client make subsequent requests for the next page – until the final page (and all observations) have been returned.

Request parameters are:

  • id – sensor unique identifier from where to get the observations
  • startTime – ISO 8601 dateTime in UTC (Zulu)
    • “now” if empty
  • endTime – ISO 8601 dateTime in UTC (Zulu)
    • “now” – 24 hours if empty
  • size – the size of the page to be returned. 15 000 observations on one page are max.
    • 1000 – if empty
  • nextPageToken – token for fetching a particular page. If specified a particular page will be returned, and if omitted, the first page will be returned. If there are subsequent pages, the response will include a token for fetching the next page.
    • initial page – if empty

For example:

Request:

GET /json/sensor/{id}/observations?size=5

Response:

{
    “last”: false,
    “size”: 5,
    “nextPageToken”: “g58x-Mc_6snrXRFRCJ8JOAd60-5OENR-RIh_ukuL_rvzDcwOFgVx9koseaR7bjzTj6NsTZpxdjPSQ3ZfsBjWrg==”,
    “previousPageToken”: null,
    “content”: [
      {
        “observationTime”: “2023-04-02T15:25:43.686447Z”,
        “value”: 24,
      },
      {
        “observationTime”: “2023-04-02T15:30:43.890864Z”,
        “value”: 18,
      },
      {
        “observationTime”: “2023-04-02T15:35:43.987534Z”,
        “value”: 19,
      },
      {
        “observationTime”: “2023-04-02T15:40:43.954453Z”,
        “value”: 23,
      },
      {
        “observationTime”: “2023-04-02T15:45:43.954613Z”,
        “value”: 22,
      },
    ]
}

Next request (with included in parameters nextPageToken from the response above) will retrieve the next portion of observations:

GET/json/sensor/{id}/observations?size=5&nextPageToken=g58x-Mc_6snrXRFRCJ8JOAd60-5OENR-RIh_ukuL_rvzDcwOFgVx9koseaR7bjzTj6NsTZpxdjPSQ3ZfsBjWrg==

Response:

{
    “last”: false,
    “size”: 5,
    “nextPageToken”: “P6st3rOCNZH9H_DJVevaI1ru-Ll7u2EmUdWPkr8JakhTU5zfvgnhV3Bxf5GF1mEG-C8FeGgr6hrMTzqrKK3YOA==”,
    “previousPageToken”: “yPfYQLRIz0SdcM9qS3iJbUmz9Oa2ded2SBcEANaSUrnzDcwOFgVx9koseaR7bjzTj6NsTZpxdjPSQ3ZfsBjWrg==”,
    “content”: [
      {
        “observationTime”: “2023-04-02T15:50:43.856476Z”,
        “value”: 24,
      },
      {
        “observationTime”: “2023-04-02T15:55:43.897783Z”,
        “value”: 20,
      },
      {
        “observationTime”: “2023-04-02T16:00:43.988574Z”,
        “value”: 20,
      },
      {
        “observationTime”: “2023-04-02T16:05:43.875643Z”,
        “value”: 23,
      },
      {
        “observationTime”: “2023-04-02T16:15:43.453277Z”,
        “value”: 22,
      },
    ]
}

This endpoint will replace the old (unpaginated) sensor observation endpoint

GET /json/sensor/{id}/observation

The old, unpaginated endpoint is less performant, and will be omitted from our API docs, but will continue to be in service.

Preview API

2. Twin Statistics

Statistics returns the e.g. the total amount of devices in a specified real estate.

  • POST /preview/json/realestatecomponent/{id}/statistic – Get statistic for specific real estate component.
  • POST /preview/json/realestate/ {id}/statistic – Get statistics for specific real estate.

Statistic Request contains an array of Statistic Request Items. Each item should contain “baseTwinType”.

The list of possible base twin types:

  1. RealEstateComponent
  2. BuildingComponent
  3. Device
  4. Asset

All twin types can be splitted by subclasses and by twin statuses.

Statistic Request example:

“requestItems”: [
    {
      “baseTwinType”: “Device”,
      “splitBy”: {
        “twinClasses”: [
            “Sensor”
        ],
        “twinStatuses”: [
          “Valid”,
          “Archived”
        ]
    }
 }
]

Statistic Response example:

{
  “statisticBricks”: [
    {
      “twinType”: “Sensor”,
      “totalCount”: 3,
      “splitByTwinStatus”: {
        “Valid”: 3,
        “Archived”: 0
      }
    }
  ]
}

Breaking changes

None

Fixes and minor updates

1. Filter Roles by Property Owner for Agent

This release limits Agent roles representations to only roles that belong to the same Property Owner.

2. Filter RPPs by Property Owner for Agent

This release limits Agent roles representations for only resource permission policies that belong to the same Property Owner.

3. Batch Operations Improvement

Building components and devices batch create/update operations accept twins of multiple classes. In order to simultaneously create twins of multiple classes, twins should have predefined uuids.

Building components endpoints may accept Storeys, Zones, Rooms etc. in the same batch:

  • POST /json/buildingcomponents;
  • PUT /json/buildingcomponents;

Devices endpoints may accept Devices, Sensors, Actuators. in the same batch:

  • POST /json/devices;
  • PUT /json/devices;

4. Global System Improvement

Global Systems are fetched with populated property ‘locatedInBuildings’ and can be filtered by building ids as other collection types.

5. Twin Endpoint Improvement

New query filter ‘twin_classes’ was added to the general twin endpoint. The filter accepts comma separated list of all valid twin classes. Affected endpoints:

  • GET /json/twin
  • GET /twin