Thing Properties
Thing properties are used to describe the data points that are related to a Thing. For example, a customer may have a name property and address property. A truck may have the following properties: driver, capacity, and location.
Properties are a simple and convenient way to know the current conditions of a Thing. Properties can be static (for example, manufacturer and model number) or dynamic (for example, temperature). You set up properties based on your asset structure, business processes, and the solutions you want to deliver.
When you create a property, you can select one of the following kinds of bindings:
• None
A property for a local Thing. This is the default setting.
• Locally Bound
Links the property to a property defined on a different Thing on the ThingWorx server. You can set this property to be read-only, and it can still receive a value from another property on the server. This is not used for remote devices, unless you are creating a local binding to a remotely-bound property.
• Remotely Bound
When a remote device first connects to a ThingWorx server, the server binds the remote device to its corresponding Thing. Once the remote device is bound, you need to create a remote binding between each property defined on that remote device and the Remote Thing that represents the device in ThingWorx. ThingWorx uses this binding to send and receive updates for each property value from a remote device over an active WebSocket connection.
 |
If a local Thing and a Remote Thing have a property with the same name, and another property is bound to the remote property setting, the remote property also sets the local property value.
|
|
|
After changing the value of remote property on remote Thing through the Composer, it is not saved in ThingWorx, and the DataChange event does not get triggered. Only the property update is sent to the edge.
|
 |
For information on setting up property bindings, whether local or remote, see Manage Property Bindings.
|
Each property has a name, description, and a ThingWorx data type, known as a base type in ThingWorx. Depending on the base type, additional fields may be enabled. A simple scalar type, like a number or string, adds basic fields like default value. More complex base types have more options. For example, a base type of INFOTABLE includes the ability to define a Data Shape to describe the data structure of the infotable. For more information, see Property Base Types.
A Thing property value consists of three characteristics: value, timestamp, and quality (VTQ). VTQ values can be provided or automatically set and acceptable quality statuses are located in the QualityStatus class. Whenever a property is set or updated, all of its VTQ characteristics are updated.
In general, a property can be updated in Composer by setting me.PropertyName = value, and the timestamp will reflect the current timestamp of the server. For historical updates, you can use the UpdatePropertyValues and UpdatePropertyValuesBatched services, which allow you to perform value updates of multiple properties. Property values cannot be set to null. For more information about these services, see the table below.
|
Option
|
Description
|
|---|---|
|
UpdatePropertyValues
|
Accepts a single values InfoTable parameter consisting of multiple rows. Each row contains the property name, value, and quality, accompanied by the update timestamp. Property values cannot be set to null.
By default, the value updates are performed for each property separately. To have the values sorted and grouped by timestamp rather than by property, the GroupPropertyValuesByTime setting should be set to true in theBasicSettings section of platform-settings.json.
When the above setting is set to true, the data-triggered events and alerts for all properties updated with the same timestamp are fired together. As a result, multi-event subscriptions registered for some or all these events will execute only once per timestamp, having the matched events passed in the events parameter.
|
|
UpdatePropertyValuesBatched
|
Accepts a single batches InfoTable parameter consisting of multiple rows. Each row contains a batch of properties’ values and the update timestamp.
The batch field value is an InfoTable consisting of multiple rows. Each row contains the property name, value, and quality. Property values cannot be set to null.
The properties' values are sorted and grouped by batches' timestamps, meaning that the data-triggered events and alerts for all properties updated with the same timestamp are fired together. As the result, multi-event subscriptions registered for some or all these events will execute only once per timestamp, having all matching events passed in the events parameter.
|
|
|
When writing custom services, avoid generating code which may concurrently modify the same property of a given entity. For example, do not concurrently increment or decrement a property value, as it can result in unpredictable property values. Similarly, incrementing properties to act like counters within subscriptions is a common misuse that will result in inaccuracy.
|
The HistoricalDataLogged event will fire when a historical property value is set. For example, consider that the current set timestamp of a VTQ property on an entity is 2020-02-04 20:16:20. Upon importing a new version of that entity, an older VTQ property is set, such as 2019-12-24 19:00:45. That set will cause the HistoricalDataLogged event will fire for that property, and any subscriptions to that event on the property will be exercised.
Alerts
For information about alerts, see Alerts.
Aspects of Properties
Properties can have the following aspect settings:
• Has Default Value— Sets a default value for the property when the Thing is initialized.
• Index— If selected, the property is stored and indexed to the database property persistence provider for improved searching using the QueryImplementingThingsOptimized service. See Indexed Properties for more information.
◦ Only properties that change infrequently should be indexed. Telemetry data properties should not be indexed.
◦ If Index is selected, the Persist setting will be automatically selected and editing of the Persist setting is disabled.
◦ If the Index setting is subsequently turned off, Persist will remain selected, but editing will be re-enabled to allow you to set or deselect.
◦ Only the following base types support the Index setting: STRING, NUMBER, INTEGER, LONG, BOOLEAN, DATETIME, THINGNAME, USERNAME, GROUPNAME, HYPERLINK, IMAGELINK, MASHUPNAME, MENUNAME, DASHBOARDNAME, TEXT, GUID, NOTIFICATIONCONTENTNAME, NOTIFICATIONDEFINITIONNAME, STYLETHEMENAME, and THINGGROUPNAME.
• Persist— If selected or set to true, each value change is persisted to the database. Persistent property database writes occur asynchronously to avoid deadlocks. While the property value is set immediately, the database write occurs asynchronously at a later point in time. The following validations occur before a persistent property value is written to the database:
◦ The Thing must still exist.
◦ The Thing must have an id.
◦ The Thing id and the pending write id must match.
◦ The Thing must still define the property with the same name as the pending write.
◦ The defined property must still be persistent.
Updates and restarts do not affect queue processing.
• Read Only— If selected or set to true, the data is static and cannot be written at run time. The only way to change the value is by changing the default value. This is useful for static configuration data.
• Log— If selected or set to true, the property value is automatically logged to a value stream when the data changes (based on the data change type).
|
|
If the data change event fails to fire under certain circumstances, the value stream entry may not be logged, but the property value set is retained. It is possible that properties can be set on an entity, but the corresponding value stream write may be dropped, due to the queue containing those writes becoming full and unable to empty to the database. This may occur if the volume of incoming writes is greater than how fast the queue is configured to empty. This can be tuned in platform-settings.json per persistence provider. Loss of connection from ThingWorx to the database may also cause the queue to back up and not empty in a performant manner.
|
• Scope— Select the scope of the property.
Data Change Information
Data Change Type
This setting specifies when a data change event is triggered by a property value change. You use it when other processes must be initiated based on the value of the property. Each subscriber is sent a change notice with an infotable that contains the old and new property values. For example, you can set up a subscription for changes to the DeliverySchedule property. If the schedule changes, you can notify the driver via SMS.
Data Change Type options are as follows:
• Always— Fire the event to subscribers for any property value change.
• Never —Do not fire a change event.
• On— For most values, any change will trigger an event. For more complex base types, such as infotables, event rules may be different.
• Off — Fire the event if the new value evaluates to a boolean false.
• Value— For numeric types, if the new value has changed by more than the threshold value, the change event will fire. For non-numeric types, the change event will fire upon the value changing in any way from the original value. Logging of the value to a value stream only occurs if the value was determined to have changed.
Deprecated
Selecting the Deprecated checkbox will deprecate the entity. Enter the Version from which the entity must be deprecated in the major.minor.patch format. Optionally, add a comment.
Remote Binding Information
The next table lists the options that are available if the Binding option is set to Remotely bound.
|
Option
|
Description
|
||
|---|---|---|---|
|
Remote Property Name
|
The name of the property, as it exists at the Edge.
|
||
|
Cache Method
|
Cache method provides the following ways to read bound Edge property values:
• Read from server cache prohibits server requests to the Edge property value. It only retrieves the value from the server. Any updates to the server-cached Edge property value depend on the Edge property's Data Change Type and the scan rate (Edge property value push definition). Without the proper settings at the Edge property, it is possible for the server to never have the Edge property value and to only return the server property default value. If the Data Change Type of the Edge property to which you are binding equals ALWAYS or VALUE, the cache type will default to this setting.
• Fetch from remote every read retrieves the Edge property value from the Edge for every request. There is no caching with this option. If the Data Change Type of the Edge property to which you are binding equals NEVER, the cache type defaults to this setting.
• Cached for specific time controls the frequency of requests to the Edge property. After the first request, the server accesses the Edge property for its value and does not make another request to the Edge property for the defined number of seconds. Note that the Edge property may update the server value (via push) during that time.
|
||
|
Cache Interval
|
The time period (in seconds) for which the server caches the Edge property value before a request for the property value retrieves it from the Edge. The value is always retrieved from the Edge at the first request.
|
||
|
Start Type
|
Specifies the value used to initialize a remotely-bound property when its Thing starts or restarts. This initialized value does not trigger a property change event.
• Use Default Value — sets the initial value of the property to the specified default value, despite the edge-side value. If the property is persisted, then the initial value will be set to the last value persisted to the database.
• Read Edge Value — queries the edge for its current value, so that the value on the server is always in sync with the value on the edge, even when the Thing restarts on the server.
|
||
|
Push Type
|
Push Type applies only to Edge enhanced Thing properties. These components can push their value changes to the server. You can configure this ability using the server property binding.
• Pushed based on value change: you can configure a value change threshold. When you use this setting, you can also set the Push Threshold value, a deadband that must be exceeded before a new value is pushed to the server from the edge.
• Never pushed
• Always pushed
|
||
|
Push Threshold
|
This option is available if Push Type is set to Pushed based on value change. It specifies the range (plus or minus) around the edge property value for the property value push to occur. The property value must change by more than the specified value.
|
||
|
When Disconnected
|
Specifies how the remote property value binding should be handled if the connection to the Remote Thing is temporarily lost.
• Ignore values that are changing while disconnected.
• Fold all the changes into a single last changed value — Send the last changed value when the connection is restored.
|
||
|
Timeout
|
The timeout used for calls to Remote Things during a property read or write.
• Use system default — The default is 30 seconds.
• Custom timeout. Add to Timeout Interval (sec).
|
Related Links