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:
• My Property
A property for a local Thing. This is the default setting.
• Local 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.
• Remote
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.
|
 |
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 the Base Types table below.
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 batch historical updates, you can use the UpdatePropertyValues service, which allows you to pass a specific value, timestamp, and quality. Property values cannot be set to null.
|
|
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.
|
In ThingWorx 8.3.13, 8.4.9, 8.5.5 and later, 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:
• Persistent
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.
• Logged
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.
|
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 values, if the new value has changed by more than the threshold value, fire the change event. The threshold value is specified with the dataChangeThreshold aspect (a NUMBER). For non-numeric values, this setting behaves the same as Always.
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).
|
Property Base Types
The defined base type provides context around the data stored in the property. The next table lists the base types are available for all Thing entities:
|
Base Type
|
Description
|
||
|---|---|---|---|
|
BASETYPENAME
|
A valid base type name.
|
||
|
BLOB
|
A binary large object.
|
||
|
BOOLEAN
|
A true or false value.
|
||
|
DASHBOARDNAME
|
The name of a dashboard.
|
||
|
DATASHAPENAME
|
A reference to a data shape in the model. Uses special handling.
|
||
|
DATETIME
|
A formatted date and time.
|
||
|
GUID
|
Globally unique identifier. When a GUID property is created, a GUID is automatically created if a default value or value is not set by the user. The following behaviors are followed for persistent and non-persistent GUID properties and are also applicable in a federation scenario:
• If the property is set as persistent or not persistent and a default value or value is not set by the user, a new GUID value is generated each time the Thing is initialized. If a system or Thing restarts, a new value is generated.
• If the property is persistent and a default value or value is set by the user, a new value is not generated when a Thing or system restarts.
|
||
|
GROUPNAME
|
A user group name.
|
||
|
HTML
|
HTML content.
|
||
|
HYPERLINK
|
A standard URL (such as www.ptc.com).
|
||
|
IMAGE
|
Binary data that can be rendered as an image.
|
||
|
IMAGELINK
|
A URL link to an image.
|
||
|
INFOTABLE
|
A standard representation of data in ThingWorx that is similar to a SQL result set. There are a number of built-in services for building, consuming, and parsing an infotable.
|
||
|
INTEGER
|
A number that can be written without a fractional component.
|
||
|
JSON
|
A JavaScript Object Notation (JSON) object.
|
||
|
LOCATION
|
Standard World Geodetic System (WGS) 84 coordinate, expressed as [longitude, latitude], elevation.
|
||
|
LONG
|
The LONG type should be used when a required range is longer than what the INTEGER base type provides.
|
||
|
MASHUPNAME
|
A reference to a ThingWorx mashup. Uses special handling.
|
||
|
MENUNAME
|
The name of a menu.
|
||
|
NUMBER
|
A number.
|
||
|
PASSWORD
|
A masked password value.
|
||
|
QUERY
|
A JSON object that includes an array of filters. Each filter should include value, type, and fieldname.
|
||
|
SCHEDULE
|
A cron-based schedule configured using the Schedule Editor.
|
||
|
STRING
|
Any amount of alphanumeric characters.
|
||
|
TAGS
|
ThingWorx tag values.
|
||
|
TEXT
|
Any amount of alphanumeric characters. The difference with STRING is that TEXT is indexed.
|
||
|
THINGCODE
|
A numerical representation of a Thing containing a Domain ID and Instance ID. For example, 2:1.
|
||
|
THINGNAME
|
A reference to a Thing in the model. Uses special handling.
|
||
|
THINGSHAPENAME
|
A reference to a Thing Shape in the model. Uses special handling.
|
||
|
THINGTEMPLATENAME
|
The name of a Thing Template.
|
||
|
USERNAME
|
A reference to a ThingWorx user.
|
||
|
VEC2
|
A collection of two numbers. For example, 2D coordinates x and y.
|
||
|
VEC3
|
A collection of three numbers. For example, 3D coordinates x, y, and z.
|
||
|
VEC4
|
A collection of four numbers. For example, 4D coordinates x, y, z, and w.
|
||
|
XML
|
An XML snippet or document.
|
|
|
The values entered in the Min Value and Max Value fields are for information only. Actual values less than or greater than the specified values are accepted.
|
Related Links