In this release

The main focus of this release is a full update of the ProptechOS authorization model with improved configuration and added roles to enable user self-management. Users with admin roles will be able to create and modify policies, and also to grant and revoke resource access and role policies to other users.

New functionality

1. Resource Permission Policy

ResourcePermissionPolicy (RPP) – represents resource access policy in ProptechOS platform. RPP is a set of rules that controls read and modify access to the twins. RPP itself consists of different properties that are responsible for different access levels. ResourcePermissionPolicy model:

  • propertyOwner – what PropertyOwner this RPP belongs to;
  • includesAll – flag that is responsible for providing READ access to all twins in PropertyOwner dataset;
  • excludesAll – list of twins types where each separate type will exclude all twins of this type from READ access (allowed values: Collection, RealEstate, RealEstateComponent, BuildingComponent, Asset, Device, Sensor, Actuator);
  • included – is responsible for providing READ access to specified twins. It is represented by a key/value map where:
    • key – type of the twin (allowed values: Collection, RealEstate, RealEstateComponent, BuildingComponent, Asset, Device, Sensor, Actuator),
    • value – list of specified twin ids and ‘propagatable’ flag;
  • excluded – is responsible for avoiding READ access to specified twins. It is represented by a key/value map where:
    • key – type of the twin (allowed values: Collection, RealEstate, RealEstateComponent, BuildingComponent, Asset, Device, Sensor, Actuator),
    • value – list of specified twin ids;
  • allowWriteTwinClasses – list of twins types where each separate type will provide WRITE permission to all twins of this type that are allowed by READ related access policies like: includesAll, included (allowed values: Collection, RealEstate, RealEstateComponent, BuildingComponent, Asset, Device, Sensor, Actuator). Also this rule will allow user to create new twins of specified types and subtypes;
  • filters – additional tool that will help to filter out included sensors and actuators by QuantityKind and PlacementContext;
  • capabilities – special tool to control specific actions in ProptechOS:
    • DeviceGateway – will allow user to access device security key;
    • Actuation – will allow user to perform actuation over included set of actuators;
    • Streaming – will allow streaming recipient receive online telemetry from included set of sensors;

Usage Details

  • Access result is calculated according to the following schema:
    • INCLUDED (‘icludesAll’ OR ‘included’) AND NOT EXCLUDED (‘excludesAll’ OR ‘excluded’);
  • Propagatable Access (‘propagatable’ flag) – each twin has its own hierarchy that is taken into account during access evaluation. Hierarchy is fetched according to the following approaches with From-Bottom-To-Top rule:
    • Sensor/Actuator – hasSuperDevice -> Device – isMountedInBuildingComponent -> BuildingComponent – isPartOfBuilding -> Building – isPartOfRealEstate -> RealEstate;
    • Asset – locatedIn -> BuildingComponent – isPartOfBuilding -> Building – isPartOfRealEstate -> RealEstate;
    • Collection;

So according to the hierarchy schema top twins may work with either propagated access (like ‘open umbrella’) or not propagated access (like ‘closed umbrella’). What does it mean in practice:

  • Example 1 demonstrates included single RealEstate with propagatable access, that will allow user to have READ access to the full orphan tree (all buildings, rooms, assets, devices, sensors and actuators):

“included”: {
      “RealEstate”: {
        “ids”: [
          “3fa85f64-5717-4562-b3fc-2c963f66afa6”
        ],
        “propagatable”: true
      }
    }

  • Example 2 demonstrates included single RealEstate with non-propagatable access, that will allow users to have READ access only to this specific RealEstate:

“included”: {
      “RealEstate”: {
        “ids”: [
           “3fa85f64-5717-4562-b3fc-2c963f66afa6”
        ],
        “propagatable”: false
      }
    }

If users should  have READ access to some orphan twins, those twins should be additionally specified in the ‘included’ section:

“included”: {
      “RealEstate”: {
        “ids”: [
          “3fa85f64-5717-4562-b3fc-2c963f66afa6”
        ],
       “propagatable”: false
    },
    “RealEstateComponent”: {
    “ids”: [
       “3fa85f64-5717-4562-b3fc-2c963f66afa6”
    ],
    “propagatable”: false
  },
  “BuildingComponent”: {
    “ids”: [
      “3fa85f64-5717-4562-b3fc-2c963f66afa6”
    ],
    “propagatable”: true
  }
}

  • Admin users may specify only orphan twin types ids as included in RPP (e.x. only Room id without specified it’s RealEstate id), in this case the full twin hierarchy will be populated as included twins in the RPP according to the From-Bottom-To-Top rule with propagatable false.
  • Propagatable flag is ignored for the following types: Collection, Asset, Sensor, Actuator as these twin types don’t have orphan twins according to hierarchy schema.

Full RPP Example:

{
      “propertyOwner”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
      “filters”: [
        {
          “deviceQuantityKind”: “https://w3id.org/rec/core/Temperature”,
          “devicePlacementContext”: “https://w3id.org/rec/device/OutdoorAir”
      },
      {
        “deviceQuantityKind”: “http://proptechos.com/ontology/extension/PM10”,
        “devicePlacementContext”: “https://w3id.org/rec/device/OutdoorAir”
      },
      {
        “deviceQuantityKind”: “https://w3id.org/rec/core/CO”,
         “devicePlacementContext”: “https://w3id.org/rec/device/IndoorAir”
      }
    ],
    “capabilities”: [
      “DeviceGateway”,
      “Streaming”,
      “Actuation”
    ],
    “allowWriteTwinClasses”: [“RealEstate”,”RealEstateComponent”,”BuildingComponent”,
“Device”],
    “includesAll”: false,
    “excludesAll”: [“Sensor”],
    “included”: {
    “RealEstate”: {
      “ids”: [
        “3fa85f64-5717-4562-b3fc-2c963f66afa6”

    ],
    “propagatable”: false
  },
  “RealEstateComponent”: {
    “ids”: [
      “3fa85f64-5717-4562-b3fc-2c963f66afa6”
    ],
    “propagatable”: false
  },
  “BuildingComponent”: {
    “ids”: [
      “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
      “3fa85f64-5717-4562-b3fc-2c963f66afa6”
    ],
    “propagatable”: false 
  },
  “Device”: {
    “ids”: [
      “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
      “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
      “3fa85f64-5717-4562-b3fc-2c963f66afa6”
    ],
    “propagatable”: false
   }
 },
 “excluded”: {
 “Actuator”: {
   “ids”: [
      “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
       “3fa85f64-5717-4562-b3fc-2c963f66afa6”
    ]
  }
 },
  “id”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
  “class”: “ResourcePermissionPolicy”,
  “status”: “Valid”,
  “popularName”: “Example RPP”,
  “createdByAgent”: “[email protected]”,
  “updatedByAgent”: null,
  “createdTime”: “2023-02-21T12:29:49.238Z”,
  “updatedTime”: null,
  “comment”: {},
  “source”: {}
 }

Resource Permission Policy Management

ResourcePermissionPolicy management is now allowed for users with the PropertyOwnerAdmin role. RPP management includes full control over the policies that belong to the Property Owner. RPP management is represented by new endpoints:

  • GET /json/rpp
  • GET /json/rpp/{id}
  • POST /json/rpp
  • PUT /json/rpp
  • DELETE /json/rpp/{id}

2. Role

Role – represents an entity that is responsible for security management access. Each role provides a different level of security management access. Currently ProptechOS includes 3 different role types:

  • Property Owner Admin – has full control over ProptechOS resource and security management in scope of single Property Owner. PropertyOwnerAdmin is limited to the single instance;
  • Organization Admin – has full control over Organization security twin and has limited control over specified security and resource twins (e.x Application). OrganizationAdmin is limited to the single instance per each organization;
  • User – default role that does not have dedicated representation on the API

Role management

In this release PropertyOwnerAdmin will be able to list all roles that belong to the PropertyOwner. And full control over the roles will be available for PropertyOwnerAdmin in future releases. Role management is represented by new endpoints:

  • GET /json/role
  • GET /json/role/{id}
  • POST /json/role
  • PUT /json/role
  • DELETE /json/role/{id}

3. Twins Multiple Restore

In the scope of this release a new feature to restore multiple twins of the same type was introduced. This feature is only available for agents with batch operations allowed.

The list of endpoints:

  • PUT /json/realestates/restore
  • PUT /json/realestatecomponents/restore
  • PUT /json/buildingcomponents/restore
  • PUT /json/rooms/restore
  • PUT /json/storeys/restore
  • PUT /json/assets/restore
  • PUT /json/devices/restore
  • PUT /json/sensors/restore
  • PUT /json/actuators/restore
  • PUT /json/aliasnamespaces/restore
  • PUT /json/collections/restore
  • PUT /json/apartments/restore
  • PUT /json/tenantunits/restore
  • PUT /json/regions/restore
  • PUT /json/spacecollections/restore
  • PUT /json/systems/restore
  • PUT /json/addresses/restore

Every endpoint has a list of twin ids as the input parameter, the same list is returned in response in case if all twins are successfully restored. Number of twins that can be restored in one request is limited to 1000. The same set of endpoints is implemented for JSON-LD as well.

For example:

Request:

  • PUT /json/rooms/restore

{
  “twinIds”: [
    “8a772d09-57af-481c-857c-e83d57a3fb51”,
    “20d72545-fdbc-4773-80fe-1db9f57fd242”,
    “9ca4e2b5-e74c-4443-8ec8-02fba95be5a3”
  ]
}

Response:

[
  “8a772d09-57af-481c-857c-e83d57a3fb51”,
  “20d72545-fdbc-4773-80fe-1db9f57fd242”,
  “9ca4e2b5-e74c-4443-8ec8-02fba95be5a3″
]

4. Address Twin Belongs to Property Owner

An Address twin belongs to Property Owner, which is represented as “propertyOwner” in the object.  Here is an example of Address JSON.

{
    “type”: “type”,
    “propertyOwner”: “00dcbcb3-64cf-4710-96a9-fb49bce3e010”,
    “id”: “00dcbcb3-64cf-4710-96a9-fb49bce3e010”,
    “status”: “Valid”,
    “createdTime”: “2023-01-01T00:00:00.000Z”,
    “updatedTime”: “2023-01-01T00:00:00.000Z”,
    “popularName”: “popularName”,
    “createdByAgent”: “createdByAgent”,
    “updatedByAgent”: “updatedByAgent”,
    “comment”: {},
    “source”: {},
    “class”: “Address”,
    “streetAddress”: “streetAddress”,
    “postalCode”: “postalCode”,
    “countryName”: “countryName”,
    “locality”: “locality”,
    “region”: “region”
}

5. GraphQL API (Preview)

GraphQL is a query language for APIs and a runtime for fulfilling API queries. GraphQL provides a complete and understandable description of the data in your graph, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools. For more information please visit GraphQL Page.

Since this release of ProptechOS you can fetch data via GraphQL API. GraphQL API is available in our Preview API via the new endpoint:

  • POST /preview/graphql

GraphQL API Try Out

To try out the new GraphQL API graphiql page can be used. This test page is available via <BASE_PROPTECHOS_URL>/preview/graphiql . In order to start, the Authorization header with Bearer token in JSON format should be provided in “Header” section (Bearer token can be copied from the Swagger page). Authorization header example:

{“Authorization”: “Bearer eyJ0eXAiOiJKV1QiLCJhbGci…”

Examples of some possible requests to start:

  1. Get paged Devices

{
  getDevicesPaged {
    totalElements
    content {
      id
      isMountedInBuildingComponent {
        id
        isPartOfBuilding {
          id
          isPartOfRealEstate {
            id
            ownedBy {
              id
            }
          } 
        }
      }
    }
  }
}

2. Get paged Devices with specified page and page size:

{
  getDevicesPaged(filter: {pageFilter: {page: 5 size: 50}}) {
    totalElements
    content {
      id
      isMountedInBuildingComponent {
        id
       isPartOfBuilding {
          id
          isPartOfRealEstate {
            id
            ownedBy {
              id
            }
          }
        }
      }
    }
  }
}

3. Get Device by id

{
  getDevice (id: “3fa85f64-5717-4562-b3fc-2c963f66afa6”) {
    id
    popularName
    class
    littera
    createdTime
    createdByAgent
    isMountedInBuildingComponent {
      id
      popularName
      class
      littera
      createdTime
      createdByAgent
      isPartOfBuilding {
        id
        popularName
        class
        littera
        createdTime
        createdByAgent
        isPartOfRealEstate {
          id
          popularName
          class
          littera
          createdTime
          createdByAgent
          ownedBy {
            id
            popularName
            class
            createdTime
            createdByAgent
          }
        }
      }
    }
  }
}

Breaking changes

None

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

  1. PLAT-3692 – User with PO Admin role cannot Create/Update/Delete roles available in thier PO;
  2. PLAT-3693 – Twin restore endpoint randomly fails with 404;
  3. OSUI-1524 – Cannot add rooms to TenantUnit after it was archived and restored;
  4. PLAT-3703 – 500 when user tries authenticate in wrong API;
  5. PLAT-3717 – Redirect URIs for Applications are not saved in app’s json;
  6. PLAT-3722 – Cannot modify/clear “included” field of RPP;
  7. PLAT-3725 – Cannot create Device when RPP has “allowWriteTwinClasses” set only to [“Device”];