Release notes – version 5.1.0

Java

{
  “deviceId”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
  “buildingComponentId”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
  “migrateSubDevices”: true
}

where,

deviceId – id of the device that will be migrated

buildingComponentId – id of the building component where the device will be installed.

migrateSubDevices – boolean parameter that indicates if sub devices of the device should be migrated to a new building component.

• POST /json/sensor/migrate – migrate Sensor to a new building component.

Request body:

Java

{
  “sensorId”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
  “buildingComponentId”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”
}

where,

sensorId – id of the sensor that will be migrated

buildingComponentId – id of the building component where the sensor will be installed.

• POST /json/actuator/migrate – migrate Actuator to a new building component.

Request body:

Java

{
  “actuatorId”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
  “buildingComponentId”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”
}

where,

actuatorId – id of the sensor that will be migrated

buildingComponentId – id of the building component where the sensor will be installed.

When a Device is migrated:

• New device, that is a full copy of the pre-migration device is created with twin status ‘Archived’, edge status ‘Decommissioned’ and ‘isMountedInBuildingComponent’ pointing to the pre-migration location. ‘isMountedInBuildingComponent’
• the Device that was migrated changes its ‘isMountedInBuildingComponent’ value to the one that was in migration request
• A ‘replaced’ relationship between the device and its pre-migration copy is created. (myDevice replaced preMigrationCopyOfMyDevice)
• If migrateSubDevices is true, all the subdevices will be migrated with the device, see what is happening with subdevices in sections When Sensor is migrated and When Actuator is migrated.

When Sensor is migrated:

• First three bullets of the device migration are applicable also to sensor migration
• All the pre-migration telemetry is copied to the archived mirror sensor (that remains in the pre-migration location).

When Actuator is migrated:

• First three bullets of the device migration are applicable also to actuator migration
• All the actuation commands and responses associated with the migrated actuator are copied to the mirror actuator that was created as its replacement.

Building Component Geometry

Geometry data is added to the API. Be aware that this feature is released in the preview API and it may undergo changes. Initially, the geometries that will be created and updated via the API will not be visible or have effect on ProptechOS UI.

Endpoints

• GET /preview/json/geometry – endpoint to get the list of geometries for specific building components filter.

Filter:

• buildingcomponent_ids – building component id’s, separated by a comma;
• building_ids – building id’s, separated by a comma;
• buildingcomponent_classes – building component classes, separated by a comma;
• feature_types – feature types, separated by a comma. Possible feature types: Level, Openings, Structure, all related to storey building component;
• size – page size, minimum 500 features, maximum 1000 features for the page;
• next_page_token – next page token, for query filter;

At least one of buildingcomponent_ids or building_ids should be provided in the filter.

Request response includes:

• content – list of GeometryWrapper objects, sorted by created date
• nextPageToken
• previousPageToken
• size

URL Example:

/preview/json/geometry?buildingcomponent_ids=bf66ad3f-b36d-4a70-a731-4a69b2f5ebe9&building_ids=bf66ad3f-b36d-4a70-a731-4a69b2f5ebe9&buildingcomponent_classes= Room%2CStorey%2CZone&size=1000

• GET /preview/json/geometry/{buildingComponentId} – get Geometry for the specific building component.

URL Example:

/preview/json/geometry/bf66ad3f-b36d-4a70-a731-4a69b2f5ebe9

• PUT /preview/json/geometry – endpoint to update Geometry for the specific building component.
• POST /preview/json/geometry – create Geometry for the specific building component.
• PUT /preview/json/geometries – update Geometries for specific building components.
• POST /preview/json/geometries – create Geometries for specific building components.
• DELETE /preview/json/geometry/{buildingComponentId} – delete Geometry for the specific building component

URL Example:

/preview/json/geometry/bf66ad3f-b36d-4a70-a731-4a69b2f5ebe9

Geometry Object

• uuid – building component ID, required field
• createdTime – automatically filled by API, geometry created datetime
• updatedTime – automatically provided by API, geometry updated datetime
• createdByAgent – automatically provided by API, geometry created agent
• updatedByAgent – automatically provided by API, geometry updated agent
• featureCollection – GeoJson format, required field
  • type – constant “FeatureCollection”, required field
  • features – an array with all building component geometries. By default, one geometry is expected for all building component types, except Storey. Required field.
    • type – constant “Feature”, required field.
    • geometry – GeoJson geometry object, required field.
      • type – geometry type, supported types are “LineString”, “Polygon”, “MultiPolygon”
      • coordinates – double multi-level array, depends on type
    • properties – free map for auxiliary fields.

For all geometries, the API is expecting two fields in “properties” area:

1. area – if it is not provided it can be calculated from coordinates for Polygon and MultiPolygon.
2. height – if empty, the API provides by default a 3.5m value.

For multi features, storey geometry should be set properties.featureType, should contain one of the following values: Level, Structure, Openings.

Example of Geometry object

One feature, LineString example. It can be used as a body for building components with the class “Room” and “Zone”.

Java

{
“uuid”: “bf66ad3f-b36d-4a70-a731-4a69b2f5ebe9”,
“createdTime”: “2023-09-01T12:04:00.497Z”,
“updatedTime”: null,
“createdByAgent”: “elon.must@proptechos.com“,
“updatedByAgent”: null,
“featureCollection”: {
“type”: “FeatureCollection”,
“features”: [
{
“type”: “Feature”,
“geometry”: {
“type”: “LineString”,
“coordinates”:[[0,0],[1,1],[2,2] ] }
}
] }
}

AppRoles Improvements

In order to improve AppRoles functionality usability new management endpoints are added.

Endpoint to update App Roles

• PUT /json/application/{applicationId}/approle

Endpoints for viewing granted AppRoles per application

• GET /json/application/{id}/approles/assignees – endpoint to view all AppRoles with assigned persons;
• GET /json/application/{id}/approle/{appRoleId}/assignees – endpoint view assigned persons with specific AppRole;

System edge status

• GET /json/system/{id}/edgestatus

System edge status is derived by analyzing the edge status of all devices included in the system:

• Ok
  • more than 90% of the devices are in this status
• Error
  • 10% or more of the devices are in Error status
• Not Started
  • 0 of the devices are in Warmup status
  • 10% or more of the devices are in Not Started status
  • less than 10% are in Warning status
  • less than 10% are in Error status.
• Warmup
  • some devices are in Warmup status
  • less than 10% are in NotStarted status
  • less than 10% are in Warning status
  • less than 10% are in Error status.
• Warning
  • 10% or more of the devices are in Warning status
  • less than 10% are in Error status

Breaking changes

None

Fixes and minor updated (internal links are added only for reference)

Improvements:

1. PLAT-3674 – Organization is required to have at least one assigned ResourcePermissionPolicy;
2. PLAT-3978 – Added opportunity to import manually devices into non alias based system;
3. PLAT-4048 – Added general Agent endpoint to get any agent by id;
4. PLAT-4023 – Added “metadata” field for App Specific Properties Schema;
5. PLAT-4029 – Support the dry_run flag for schema/property creation/update;
6. PLAT-4051 – Return 404 when there is no latest observation for sensor
7. PLAT-4058 – Added Asset sub-class “OfficePod”.

Defects fixed:

1. PLAT-3986 – Source field was not saved on Application create;
2. PLAT-4099 – System could be member of non existing AliasNamespace;
3. PLAT-4064 – Enum property cannot be removed;

PLAT-4031 – Change the allowed symbols list to the blocklist for App Specific Properties.