In this release

This release is mainly devoted to a new preview feature Application Specific Properties, an extended properties bag for each twin, that is defined by a schema and associated with an specific Application.

New functionality

(In the Preview API)

Application Specific Schema

Every agent that has access to an application, has permission to manage schemas which specify the application’s specific properties.

  • POST /json/application/{applicationId}/schema – Create a new application related schema
  • GET /json/application/{applicationId}/schema/{schemaId} – Get application-related schema by application id and schema id
  • DELETE /json/application/{applicationId}/schema/{schemaId} – Delete application-related schema by application id and schema id
  • GET /json/application/{applicationId}/schemas – Get all application-related schema ids for an application

Application Specific Schemas are simplified Json Schemas description of Application Specific Properties. All properties should be mentioned in the schema, also there can be added additional properties for validation. The schema itself is an array of potential properties. All properties can contain:

  • name – (required) value can contain only alphanumeric characters and underscores.
  • type – (required) predefined const value.
  • required – (the field itself is required) boolean that defines if property is required.
  • description – (non-required) open text field.
  • metadata – (non-required) object field that can contain simple types, such as number, string, and boolean.

Only some “type” values are supported:

Type Description Additional properties Example
integer Type for representation only integer values.
  • minimum
  • maximum
  • examples
 {
“name”: “integer_field”,
“description”: “Integer Test Field”,
“required”: true,
“type”: “integer”,
“maximum”: 100,
“minimum”: 0,
“metadata”: {
“metadata_integer_field_1”: “metadata value”,
“metadata_integer_field_2”: 100.0,
“metadata_integer_field_3”: true
},
“examples”: [
10, 20, 30
] }
number Type for representation of all number values.
  • minimum
  • maximum
  • examples
 {
“name”: “number_field”,
“description”: “Number Test Field”,
“required”: true,
“type”: “number”,
“maximum”: 100.0,
“minimum”: 0.0,
“metadata”: {
“metadata_number_field_1”: “metadata value”
},
“examples”: [
10.10, 20.20, 30.30
] }
string Type for representation of all possible string fields.
  • minLength
  • maxLength
  • examples
  • enum
 {
“name”: “string_field”,
“description”: “String Test Field”,
“type”: “string”,
“maxLength”: 100,
“minLength”: 0,
“metadata”: {
“metadata_string_field_1”: “metadata value”
},
“examples”: [
“string”
] },
{
“name”: “string_field_with_enum”,
“description”: “String Test Field With Enum”,
“type”: “string”,
“enum”: [
“value_1”,
“value_2”
],
“metadata”: {
“metadata_string_field_1”: 100
},
“examples”: [
“value_1”
] }
boolean Type for all true/false values – {
“name”: “boolean_field”,
“description”: “Boolean Test Field”,
“type”: “boolean”,
“metadata”: {
“metadata_boolean_field_1”: “metadata value”
}
}
object Type for simple objects. Can contain only simple types, like string, boolean, and number. It is not possible to validate inner values and add nested objects. – {
“name”: “object_field”,
“description”: “Object Test Field”,
“type”: “object”,
“metadata”: {
“metadata_object_field_1”: true
}
}

 

Application Specific Properties

(In the Preview API)

Access

All endpoints for App Specific properties are authorized by application ID. Persons do not have permission to access App Specific Properties, only application agents. Future versions will support more access scenarios:

  • Applications accessing other Applications’ properties
  • Person accessing Applications’ properties
  • etc.

Application ID is retrieved out of the authentication context and therefore does not need to be stated. In order to have access to the App Specific Properties application should have access to the associated twin.

Create And Update Application Specific Properties

Single:

  • POST /preview/json/twin/appspecificproperties
  • PUT /preview/json/twin/appspecificproperties

Requests Example:

{
  “schemaId”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
  “twinId”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
  “field_a”: “field_a_value”,
  “field_b”: “field_b_value”,
  “filed_c”: “field_c_value”,
  “field_d”: “field_d_value”,
  “field_e”: “field_e_value”,
  “field_f”: “field_f_value”,
  “field_g”: “field_g_value”,
  “field_h”: {
    “nested_prop_1”: “nested value 1”,
    “nested_prop_2”: “nested value 2”
  }
}

Batch:

  • POST /preview/json/twins/appspecificproperties
  • PUT /preview/json/twins/appspecificproperties

Requests Example:

[
  {
    “schemaId”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
    “twinId”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,
    “field_a”: “field_a_value”,
    “field_b”: “field_b_value”,
    “filed_c”: “field_c_value”,
    “field_d”: “field_d_value”,
    “field_e”: “field_e_value”,
    “field_f”: “field_f_value”,
    “field_g”: “field_g_value”,
    “field_h”: {
      “nested_prop_1”: “nested value 1“,
      “nested_prop_2”: “nested value 2”
    }
  }
]

Each App Specific Properties bag json should contain two mandatory fields:

  • twinId;
  • schemaId;

Fetch App Specific Properties

Single:

  • GET /preview/json/twin/{twinId} /appspecificproperties/schema/{schemaId}?requested_properties=property_1,property_2,property_3

Where:

  • ‘requestedProperties’ – an optional query parameters: array of comma-separated property keys that will be included in App specific properties bag object response. Nested property keys should be requested by the format ‘parent_property_key.nested_property_key’. If this parameter is not included in the request, the full properties bag object will be returned.

Paged request:

  • POST /preview/json/twin/appspecificproperties/ schema/{schemaId}

Request example:

Your Content Goes Here

{
    “page”: ,
    “size”: ,
    “requestedProperties”: [“<property_1>”,“<property_2>”,“<property_3>”]
}

Where ‘requestedProperties’ – array of property keys that will be included in App specific properties bag object response. Nested property keys should be requested by the format ‘parent_property_key.nested_property_key’.

Remove Application Specific Properties

Single:

  • DELETE /preview/json/twin/{twinId}/ appspecificproperties/schema/{schemaId}

Batch:

  • POST /preview/json/twins/appspecificproperties/delete

Batch delete request example:

{
    “schemaId”: “”,
    “twinIds”: [“twin_uuid_1”,“twin_uuid_2”,“twin_uuid_3”]
}

Breaking changes

None.

Fixes and minor updates

Minor improvements

  • Added ‘me’ endpoint for application:
    • GET /json/application/me
  • Added endpoint to fetch full list of Asset classes:
    • GET /json/assetclass
  • Added Preview endpoint to fetch twin statistics for BuildingComponent:
    • POST /preview/json/buildingcomponent/ {id}/statistic
  • Added a new “in_range” filter to GET twins endpoint, that contains the “hasGeoReferenceOrigo” field.
    • GET /json/realestate?in_range=10;10;10&page=0&size=50
    • GET /json/realestatecomponent?in_range=10;10;10&page=0&size=50
    • GET /json/buildingcomponent?in_range=10;10;10&page=0&size=50
    • GET /json/asset?in_range=10;10;10&page=0&size=50
    • GET /json/device?in_range=10;10;10&page=0&size=50
    • GET /json/sensor?in_range=10;10;10&page=0&size=50
    • GET /json/actuator?in_range=10;10;10&page=0&size=50
    • GET /json/room?in_range=10;10;10&page=0&size=50
    • GET /json/storey?in_range=10;10;10&page=0&size=50
  • New field “hasGeoReferenceOrigo” was added to all BuildingComponent twins.

Fixed Defects:

  • Newly onboarded devices are not included in systems (issue PLAT-3865)
  • 403 Error when registering Application (issue PLAT-3906)
  • Sensors were created with same aliases (with different cases) (issue PLAT-3897)