Programmatically Adding Properties to Things
The AddPropertyDefinition service can be used to create a new local or remote-bound property on a Thing, Thing Template, or Thing Shape. The service has the following parameters:
|
Parameter
|
Base Type
|
Description
|
|---|---|---|
|
name
|
STRING
|
Required. The name of the property to create.
|
|
type
|
BASETYPENAME
|
Required. The ThingWorx base type of the property. For a list of ThingWorx base types, see the table, "Base Types", in Thing Properties.
|
|
description
|
STRING
|
Description of the property.
|
|
category
|
STRING
|
Category name to classify the property.
|
|
dataShape
|
DATASHAPENAME
|
When the property's base type is INFOTABLE, defines the Data Shape used by the property.
• The Data Shape entity specified for this parameter must exist before the service is run.
• This parameter is not required. However, the INFOTABLE cannot be set through Composer (using the Set button) without a Data Shape specified.
|
|
defaultValue
|
STRING
|
Specifies the default value for the property.
|
|
readOnly
|
BOOLEAN
|
True if the property is read-only otherwise, false.
|
|
persistent
|
BOOLEAN
|
True if values will persist over a restart of the ThingWorx service (values are stored in the persistence provider), false if the value is cleared on restart of the ThingWorx service.
|
|
logged
|
BOOLEAN
|
If true, the property is stored in a configured value stream.
|
|
dataChangeType
|
STRING
|
Defines what constitutes a change in the value of the property for logging/alert purposes. One of Always, Never, On, Off, or Value.
• Always —Fire a change event for any property value change.
• Never — Never fire a change event on a property value change.
• On — For most values, any change to the property fires a data changed event.
• Off — Fires a data changed event if the new value evaluates to a boolean false.
• Value — For number types (NUMBER, INTEGER, LONG, etc), a change event is fired if the difference between the old and new property value exceeds the threshold specified in the dataChangeThreshold parameter.
|
|
dataChangeThreshold
|
NUMBER
|
The minimum number by which the numeric property should change before firing a data change event.
|
Remote Properties
There are additional parameters for remote-bound properties. They are specified as an array of remoteBindingAspects.
 |
These properties do not need to be specified unless the property being defined is being bound to a remote property.
|
|
Parameter
|
Base Type
|
Description
|
||
|---|---|---|---|---|
|
remote
|
BOOLEAN
|
True if the property is bound to a remote property, false if not. (Default false)
|
||
|
remotePropertyName
|
STRING
|
The name of the property on the Remote Thing to bind to.
|
||
|
cacheMethod
|
STRING
|
A way to read bound edge property values:
• Read from server cache prohibits server requests to the Edge for the value of the property. The value is always retrieved from the server cache. Any updates to the cached value depend on the property's dataChangeType and the Scan Rate. Without the property settings at the Edge for the property, it is possible for the server to never have the value from the Edge and to return only the default value stored on the server. If the dataChangeType of the property is ALWAYS or VALUE, the cacheMethod defaults to this setting.
• Fetch from remote every read retrieves the value from the Edge for every request. There is no caching involved with this option. If the dataChangeType of the property is NEVER, the cache type defaults to this setting.
• Cached for specific time allows you to control how often requests are made to the Edge. After the first request, the server accesses the property on the edge device for its value. Another request to the Edge is not made until the defined cacheInterval expires. Note that the Edge device may update the value on the server (via push) during that period.
|
||
|
cacheInterval
|
NUMBER
|
When the cacheMethod is Cached for specific time, the number of seconds that the server caches the property value before a request is sent to the Edge for the property value. The value is always retrieved from the Edge upon the first request.
|
||
|
timeout
|
INTEGER
|
Time in seconds to wait for a response from the Remote Thing.
|
||
|
pushType
|
STRING
|
Defines how are values are pushed from the remote device. Set to ALWAYS, NEVER, ON, OFF, or VALUE, with definitions similar to dataChangeType above.
|
||
|
pushThreshold
|
NUMBER
|
Defines the threshold that a numeric type property must exceed before a data change is pushed to the remote device.
|