A Property instance resource represents a single property entity. Since properties always belong to some owner entity (i.e. app profile or device profile), they are usually accessed through their parent's path (you can access a property resource directly by id for some operations; see operations section).

📘

Admin vs Data API

Properties resource represents different meanings when used from Admin and Data services APIs.

When used from Admin Services API, it represents the definition or metadata of a property. The user can create new properties, modify and delete existing ones through this service.

When used from Data Services API, it represents the data value stored within a property. The user can read and write data from/into properties through this service.

Please note that when we say property we refer to the property definition created within a profile entity which is uniquely identified by an id. On the other had, when we say device or app property, we refer to the instance of this property created under an object which is uniquely identified by both its parent object's id and its definition's id.

Resource Attributes

Access Types Explained

It is very important to understand the role of Api Keys when interacting with properties. Api keys convey the identity of the requesters. When a requester interacts with a device property using the device key, the requester is given full privilege - requester is considered the device itself. Otherwise it is considered an external client and has to abide by the access rules. Same rule applies to app properties as well.

Private Property

This type property can be only be only read and written by device key. This access level should be used to store device confidential data on the platform securely. It cannot be set to publish = true. All device methods can access private properties and use them.

Protected Property (read-only)

All api client and user keys with device:read-data scope are allowed to read this property. It can only be written using device key. Can be set to publish=true.

Public Property (read-write)

All api client and user keys with device:read-data scope can read this property and all client and user keys with device:write-data scope can write into this property. When written by external entities (i.e. other than the device itself) the value automatically sent to the physical device if connected to Connio MQTT broker. Can be set to publish=true.

❗️

Important

MQTT broker does not cache the commands sent to devices if the device is not online at the time of transmission. If your data is mission critical, we suggest to establish a custom feedback mechanism to make sure that your data arrived to its destination. A custom feedback mechanism can be easily built using additional properties and some edge device logic.

Supported Data Types

{
  "id": "_prp_875223872477401419",
  "accountId": "_acc_873046106083527769",
  "ownerId": "_dpf_873048732840926433",
  "name": "Temperature",
  "friendlyName": "Temperature",
  "tags": [
    "test"
  ],
  "type": "number",
  "access": "protected",
  "publish": "always",
  "measurement": {
    "type": "temperature",
    "unit": {
      "label": "Temperature",
      "symbol": "ºC"
    }
  },
  "retention": {    
    "type": "historical",
    "lifetime": "3months",
    "capacity": 100000,
    "condition": {
      "when": "always"
    }
  },
  "boundaries": {   
      "min": -25.5,
      "max": 65.5
  },
  "locked": false,
  "dateCreated": "2017-04-22T13:53:36.035Z",
  "dateModified": "2017-04-22T13:53:36.035Z"
}

Measurement

This attribute is used if and only if the property type is number. Its type attribute can be one of the following values:

Boundaries

As its name suggests, boundaries defines the limits of values each property should expect. It is mainly used for data validation and/or data visualization. Boundaries are optional. A property might have zero or one boundaries.

For example, you can use boundaries to set the limits of a temperature sensor reading. Readings that are not within the given boundary values will be discarded by the system automatically. This will prevent the property data set from being corrupted by unexpected values when device malfunctions.

Limit types per property types:

If no boundaries is set, default property boundaries takes effect. See Supported Data Types above.

Retention Policy

Retention policy governs the rules around the retention of property values. It defines when and how long incoming data should be persisted. Unlike boundaries, each property must have at least one retention i.e. default retention policy. Default retention policy cannot be deleted.

It consists of the following attributes:

Default retention policy at Property creation:

{
  "type": "historical",
  "lifetime": "3months",
  "capacity": 100000,
  "condition": {
    "when": "always"
  }
}

Another example:

{
"retention": {
	"type": "historical",
	"lifetime": "12months",
	"capacity": 3000000,
	"condition": {
	  "when": "changedx",
	  "value": 41
	}
}