Referencing Properties

  • 2 minute(s) read

Properties can be used in different ways, for instance:

  • You can display the value in a page template

  • You can include the value in a text template (e.g. Mail Body)

  • You can use the property as filtering condition or sorting criteria in an API request.

Properties values are saved in the object, directly at the first level in case of predefined properties, else into a sublevel named "properties".

{
 "id": "123",
 "name": "Boiler",
 "properties": {
    "prop1" : "foo",
    "prop2" : "bar"
 }
}
JSON

Properties do not have historical values, so at any time only the last updated value can be accessed.

The access to a property is made by using the dot notation, so you can access properties belonging to the related objects (e.g. thing → location → customer).

Custom properties require including also the "properties." sub-path, this is because custom properties values are stored under the parent object sub-node named "properties".

For instance, this is a JSON describing a thing.

{
	"id": "5aeae841005da10006e6be35",
	"name": "Hall",
	"serialNumber": "OVENx200014",
	"customer": {
		"id": "5aeae80405c5940006f7befe",
		"name": "Ristorante Fornaroli",
		"country": "Italy",
		"properties": {
			"vatNumber": "1234567890"
		},
		"type": "BUSINESS",
		"code": "C000012"
	},
	"location": {
		"id": "5aeae8054e22a20006f61476",
		"country": "Italy",
		"name": "Cisliano",
		"gpsPosition": "45.444669,8.990243",
		"properties": {
			"address": "Via Montefeltro 140, 20080 Cisliano, MI",
			"city": "Cisliano"
		},
		"partner": {
			"id": "5cf5270f2d4d4a0008f5a27c",
			"name": "Oven Service"
		},
		"metrics": {
			"performance": {
				"value": 0.5256877229073239,
				"lastUpdateTimestamp": 1632961832517
			}
		}
	},
	"gpsPosition": "45.47072521359533,8.889312744140627",
	"properties": {
		"serviceDueDate": 1633108201324,
		"status": "STANDBY"
	},
	"activationDate": 1525344321757,
	"thingDefinition": {
		"id": "5c795c602074420008bcd6ef",
		"name": "Oven-1200w",
		"description": "Oven 1200w with fan and steam.",
		"properties": {
			"fooBar2": "baz"
		}
	},
	"serviceLevel": {
		"id": "5aeae7a7d554780006bc0fed",
		"name": "Free",
		"level": 300,
		"alertingFeature": false,
		"notificationsFeature": false,
		"_default": true,
		"features": {
			"OEE": false,
			"Cookings": true,
			"System_Status": true,
			"Energy": false
		}
	},
	"connectionStatus": 1,
	"connectionStatusLastUpdateTimestamp": 1620735199626,
	"partner": {
		"id": "5cf5270f2d4d4a0008f5a27c",
		"name": "Oven Service"
	}
}
JSON

When displaying a property within the page, the system uses the Label of the property, which can be localized according to the defined translations, see the Labels article.

Depending on the property name, the widget retrieves the value from the context object (e.g. thing, location, customer, partner).

Here are reported some details-widgets for the various objects.

<thing-details-widget title="Thing Details">
   <property name="name"></property>
   <property name="properties.fooBar"></property>
   <property name="thingDefinition.name"></property>
   <property name="thingDefinition.properties.fooBar2"></property>
   <property name="location.name"></property>
   <property name="location.properties.address"></property>
   <property name="customer.name"></property>
   <property name="customer.properties.vatNumber"></property>
</thing-details-widget>
XML
<location-details-widget title="Location Details">
   <property name="name"></property>
   <property name="properties.address"></property>
   <property name="customer.name"></property>
   <property name="customer.properties.vatNumber"></property>
</location-details-widget>
XML
<customer-details-widget title="Customer Details">
   <property name="name"></property>
   <property name="properties.vatNumber"></property>
</customer-details-widget>
XML

You can use properties also into other widgets, for instance: