Searching:
0 results foundProducts/Post
Description
To create a new Product.
See the following for request and response details ‒
See Also
Request ‒ Products/Post
Properties for Products are organized hierarchically by object. The hierarchy of objects for the Products/Post request properties is as follows –
- products (general)
- serviceCommand
- serviceEvent
- serviceProperty
- mediaSettings
- tooltipElement
- commandArgument
- valueRange
- eventLoggingSettings
- aggregatedEventSettings
- commandServiceProperty
- additionalProperty
The properties for each of the objects listed above are described in the sections that follow. Each object has its own section and table of properties.
Request – Products/Post – Products (General) Properties
Property | Type | Description | Mandatory |
name | String | The free-text name of the Product. | Y |
description | String | The free text description of the Product. | |
icon | String | A link to the default icon to represent Devices of this Product type. | |
customIdDisplay | Boolean | The customID of a Device is the Device’s unique identifier in an external system. This enables the correlation of the Axonize Device ID with the external system’s Device ID.
The customIdDisplay specifies whether to show a field in the Axonize Portal that enables the entry of a customer ID when defining each Device of this Product. Note ‒ customID is a property in the Devices/Post request of the Axonize REST API. |
|
customIdRequired | Boolean | Specify True if it is mandatory to enter the customIdDisplay field when defining a Device of this Product (described above) in the Axonize Portal. | |
serialNumberDisplay | Boolean | Specifies whether to show a field in the Axonize Portal that enables the entry of a serial number when defining each device of this Product.
serialNumber is a property in the Devices/Post request of the Axonize REST API. |
|
serialNumberRequired | Boolean | Specify True if it is mandatory to enter the serialNumberDisplay field when defining a Device of this Product (described above) in the Axonize Portal. | |
active | Boolean | Not in use. | |
keepAliveThreshold | Integer | Specifies how long the system waits for a message from a Device (in minutes) of this Product before determining that the Device is disconnected. These Devices are indicated in the Axonize Portal as Disconnected. The default is 5 minutes, unless otherwise specified.
-1 ‒ Specifies that the Device should never be indicated in the Axonize Portal as Disconnected. |
|
defaultVirtualDeviceEvents | String | This property specifies the virtual device manifest for devices of this Product. This property is only relevant for virtual devices. See Defining a Virtual Device Manifest for more information. | |
disconnectChildDevicesOnDisconnect | Boolean | Specify True for all child Devices to be marked as Disconnected in Axonize when the parent Device is determined to be disconnected. This may be useful in a gateway scenario. | |
connectChildDevicesOnConnect | Boolean | Specify True for all child Devices to be marked as Connected in Axonize when the parent Device is determined to be disconnected. This may be useful in a gateway scenario. | |
disconnectGroupDeviceOnAllChildrenDisconnect | Boolean | Specifies that if all of a Group Device’s children are disconnected, the Group Device is also disconnected.
Note ‒ This is related to the Group Device feature. |
|
connectGroupDeviceOnAnyChildrenConnect | Boolean | Specifies that if even one of a Group Device’s children is Connected, the Group Device is also connected.
Note ‒ This is related to the Group Device feature. |
|
onConnectCommandIds | String | The list of command IDs to be automatically triggered when Devices of this Product connect to Axonize. | |
manufacturer | String | The free text manufacturer name of this Device type. | |
autoDiscoveryCommand | String | Specifies one or more command IDs to be automatically activated on the Device itself, when a Device is created. | |
displayCommandsTab | Boolean | Specifies that the Axonize Portal shows the Commands tab for Devices of this Product. This tab enables you to automatically activate commands on Devices of this Product. | |
onDeleteCommands | Array of Strings | Specifies one or more command IDs to be automatically activated on the Device itself, just before a Device of this Product is deleted from the Axonize system. | |
onPatchCommands | Array of Strings | Specifies one or more command IDs to be automatically activated on the Device itself, just before the data on a Device of this Product is patched by the Axonize system. | |
dispayDeviceSDKDetails | Boolean | This option is for Axonize Device SDK developers.
True ‒ Specifies that additional information for developers is shown in the Axonize Portal. |
|
enableSDKFeatures | Boolean | Enables you to activate the device twin features in Axonize. These features enable you to update a device’s firmware and settings from the Axonize platform. Such changes will be reflected on the Axonize platform. By default, this property is disabled. It must be set it to True to enable these features. | |
urn | String | Not in use. | |
schemaDefinitionsId | String | The ID of the schema definition, indicates that for this specific product, there is a schema to parse the incoming payload to the Axonize format. | |
disableInheritedConnectFromChildren | Boolean | Specify True to prevent parent device status connection to be affected by his child devices connection status. |
Request ‒ Products/Post – serviceCommand Properties
Property | Type | Description | Mandatory |
commands | Array | Defines an array of one or more commands that the Axonize REST API can use for each Device of this Product type. These commands enable you to trigger actions on the device using the sendCommand endpoint.
The Axonize Device SDK should be activated on the device and set up accordingly to listen to this command. Alternatively, Axonize can set up its command gateway that can send commands to Devices that are not using the Axonize Device SDK. After a command is created, Axonize returns a unique identifier (command ID) to be used with the Axonize REST API Command entity in order to send commands to a device. |
|
commands/name | String | The free-text name of the command. | To use the command in the UI |
commands/payload | String | The name of the method that is executed on the Device. For example, sending a payload of Reset runs the Reset command on the Device and gracefully resets the Device. | Y |
commands/commandResponseType | String/Enum | The device structure returned by the command payload (described above). The values of this property are –
|
|
commands/commandKind | String/Enum | Enables you to define if the command is a predefined direct method, as follows –
|
|
commandsProtocol | String/Enum | The command protocol, as follows –
|
|
commandsUrl | String | For internal use. This is the address of the command’s gateway. | |
commandsAddress | String | For Internal use. The remote address to where to send commands for this device type. This address is the internal address of the command’s gateway. |
Request – Products/Post – serviceEvent Properties
Property | Type | Description | Mandatory |
events | Array of Event Objects | An Event/Reading is data received by the Axonize Server from a Device.
This array property enables you to define one or more events that the Device can send to the Axonize server. Defining events here provides various customization options, even though the Axonize Dashboard can show events that are not defined here, Defining events here enables you to configure how the values of this event are shown in the Dashboard. For example, the icon or color in which a 0 value is shown in the Dashboard. The properties that appear below describe a single event. |
|
events/typeCode | Integer | The code of this event type as defined in the event manifest. See Defining a Device Event Manifest for more information.
The combination of the typeCode property and the name property (described below) represent a unique identifier for an event type. |
To use events in the UI |
events/name | String | A free-text name of this event. This name does not appear in the Event Manifest. | To use events in the UI |
events/description | String | A description of the event. | |
events/dataType | String | The actual format of the data for this event, which corresponds to what is specified in the event manifest for the data type.
Use one of the values below –
|
|
events/displayType | String | Specifies which user interface controller is used in the Axonize Portal for presenting this event.
Use one of the values below –
|
|
events/nameResourceKey | String | This is the unique identifier of this event for translating the event name property (described above). For example, this unique identifier could be used by Axonize’s localization service to translate the name property Temperature into French Température. | |
events/unit | String | The default unit of the event’s value. For example, Fahrenheit or Centigrade. This unit is used for the event when a Device does not specify the unit. | |
events/isAccumulated | Boolean | When enabled, indicates that the event contains an accumulated value. For example, an electrical meter. When this setting is enabled for an event, Axonize reads the value differences between each reading and calculates the delta from the previous reading. | |
events/logicalType | String | The logical type of this event. Valid values are –
|
|
events/fieldsCount | Integer | Not in use. | |
events/precision | Integer | The number of digits that show after the decimal point. | |
events/retention | Integer | Not in use. | |
events/iconName | String | The name of the default icon of the event. | |
events/iconColor | String | The color of the icon to represent this event in the Axonize Portal, which is represented in hex format. | |
events/subject | Not in use. | ||
events/calculationId | This feature enables you to set which custom calculation is used. It is only applicable for Group devices and can only be enabled with Axonize support.
Contact Axonize support for more information if you want to use it. |
||
events/ defaultRollupMethod | Enables you to specify the default rollup aggregation for this event. For example, when set to AVERAGE for temperature and SUM for electricity consumption, Axonize will automatically select this aggregation method when aggregation is required. For example, for analytics. | ||
AggregatedEventSettings | ChartSeriesBase | Specify custom reading |
Request – Products/Post – serviceProperty Properties
Property | Type | Description | Mandatory |
commands/arguments/serviceProperty | Array | Defines an array of one or more properties of this Command’s argument contained within the serviceproperty property (described below). | |
commands/arguments/serviceProperty/displayName | String | The free-text name to be displayed for this argument in the Axonize Portal. | To use the command in the UI |
commands/arguments/serviceProperty/name | String | The name of this property of the argument. | To use the command in the UI |
commands/arguments/serviceProperty/dataType | String | The data type of this property of the argument. Valid values are –
|
To use the command in the UI |
commands/arguments/serviceProperty/allowedValueRange | String | The values allowed to be entered for this argument. You can enter one or more sets of allowed value ranges as described below.
If the data type (dataType described above) of the argument property is Number, then you can enter a minimum and maximum value, as well as set a Step for this value. For example, if the Minimum is 10, the Maximum is 20 and this Step is 2, then the following values can be entered ‒ 10, 12, 14, 16, 18, 20. |
|
commands/arguments/serviceProperty/isUnique | Boolean | When enabled, it indicates that this property is unique for the application level. When this setting is enabled for a property, the Axonize API validats on property creation or update to ensure that they are infact unique. | |
commands/arguments/serviceProperty/required | Boolean | When enabled, it indicates that the property is required and that the product must have a value for this property. |
Request – Products/Post – mediaSettings Properties
<tdmediaSettings/
mediaProtocol<td”>mediaSettings/
mediaType<td”>The dimension ratio of the screen’s size. The format is – number, colon, number. For example, “3:4” or “6:9”.
Property | Type | Description | Mandatory |
mediaSettings | Object | Specifies the media settings for Devices that stream media. These settings describe the manner in which to show the video, such as the protocol to use, the media type to use and so on (see below).
You can provide a link for a device in the streamUrl property. |
|
String/Enum | The type of media streaming protocol, as follows –
|
||
String/Enum | The media type, as follows –
|
||
mediaSettings/ aspectRatio |
String |
Request – Products/Post – tooltipElement Properties
Property | Type | Description | Mandatory |
tooltip | Array of Tooltip Elements | A tooltip displayed in Axonize maps and diagrams when you hover over a device. It shows the device status, which can be an event or property, as described below – | |
tooltip/type | String | Can be an event or property –
|
|
tooltip/value | String | If the type (described above) is event, the value contains the Event typeCode-name. The value is connected to two properties of the service event – typeCode and name, and is represented in the following format: typeCode–name. For example, 7-temperature.
If the type is property (described above), the value should be the property name to be displayed in the tooltip. |
Request – Products/Post – commandArgument Properties
Property | Type | Description | Mandatory |
commands/arguments | Array of Strings | Defines an array of one or more arguments of a command to be sent to the Device. | To use the command in the UI |
commands/arguments/name | String | The free-text name of the argument. | To use the command in the UI |
commands/arguments/value | String | The actual value of the command. This is the value that will affect the device. | |
commands/arguments/defaultValue | String | The default value displayed in the Axonize Portal before you select/enter a value. | |
commands/arguments/unit | String | The unit of the value (described above). For example, Fahrenheit or Centigrade. | |
commands/arguments/uiType | String/Enum | The type of user interface controller for this argument, as follows –
|
To use the command in the UI |
Request – Products/Post – valueRange Properties
<td”>The severity of the event, which can be one of the following values –
- Warning
- Minor
- Major
- Critical
Property | Type | Description | Mandatory |
events/valueRange | Object | If the data type is Number, then you can enter a minimum and maximum value, as well as set a Step for this value. For example, if the Minimum is 10, the Maximum is 20 and this Step is 2, then the following values can be entered ‒ 10, 12, 14, 16, 18, 20. | |
events/valueRange/allowedValues | Array of AdditionalProperties | Describes the allowed values for incoming event data. | |
events/valueRange/allowedValues/iconName | String | The name of the icon to represent this event value in the Axonize Portal. | |
events/valueRange/allowedValues/iconColor | String | The color of the icon to represent this event in the Axonize Portal. | |
events/valueRange/allowedValues/severity | String/ Enum |
||
events/valueRange/allowedValues/key | String | Specifies the key of a property. | |
events/valueRange/allowedValues/value | String | Specifies the value of a property. | |
events/valueRange/minimum | String | Specifies the minimum value for the event. | |
events/valueRange/maximum | String | Specifies the maximum value for the event. | |
events/valueRange/precision | Integer | Specifies the number of decimal points to display. | |
events/valueRange/numericType | String/ Enum |
Specifies the numeric type of the event, which can be one of the following values –
|
|
events/valueRange/step | String | A numeric value specifying the gaps between allowed values in the same event. | |
events/valueRange/ranges | Array of Range Objects | Ranges is an array of range objects. Each ranges property represents an Axonize Product object property to be modified in order to affect its functionality.
For example, if a value is between 1–5, then it is represented by a specific iconName, iconColor and severity, and if it is between 6–10, it is represented by a different ranges object. |
|
events/valueRange/ranges/minimum | Integer | The minimum for the range. | |
events/valueRange/ranges/maximum | Integer | The maximum for the range. | |
events/valueRange/ranges/iconName | String | The name of the icon to represent this event value in the Axonize Portal. | |
events/valueRange/ranges/iconColor | String | The color of the icon to represent this event in the Axonize Portal. | |
events/valueRange/ranges/severity | String | The severity of the event. |
Request – Products/Post – eventLoggingSettings Properties
Property | Type | Description | Mandatory |
events/loggingSettings | Not in use. |
Request – Products/Post – aggregatedEventSettings Properties
Property | Type | Description | Mandatory |
events/aggregatedEventSettings | Not in use. |
Request – Products/Post – commandServiceProperty Properties
Property | Type | Description | Mandatory |
commands/arguments/serviceProperty/ currentStatus | Not in use. | ||
commands/arguments/serviceProperty/ currentStatusFromReading | String | The event type in which to update the current status of the command.
For example, 7 – temperature will update the command status every time a new reading arrives with this type. The statuses are defined in the Product/ serviceEvents/events/typeCode property. |
Request – Products/Post – additionalProperty Properties
Property | Type | Description | Mandatory |
additionalProperties | Array | The additionalProperties property enables you to extend the Axonize schema model by adding your own properties for each Device type. For example, you can add a property named Firmware Version that specifies the version of the Device’s firmware.
additionalProperties are defined per Product. Once defined, they are available in the Axonize API and Axonize Portal. These properties can also be used as keywords, as described on page 499. |
|
additionalProperties/ displayName |
String | The name to appear in the Axonize Portal for this additional property. | |
additionalProperties/name | String | The internal logical name to be used for this property. This name must match the additional property’s name on the Device itself. | Y |
additionalProperties/extra | String | A free-text description of the additional property. | |
additionalProperties/ dataType |
String | The data type of this property. Valid values are –
|
Y |
additionalProperties/ allowedValueRange |
String | If the data type (dataType described above) is Number, then you can enter a minimum and maximum value, as well as set a Step for this value. For example, if the Minimum is 10, the Maximum is 20 and this Step is 2, then the following values can be entered ‒ 10, 12, 14, 16, 18, 20. | |
additionalProperties/allowedValueRange/allowedValues | String | The unique identifier of this event value to be used for converting how this value appears in the Axonize Portal.
If the data type is String, then you can specify the following ‒
For example, this identifier could be used to convert the value 0 so that it appears as Closed in the Axonize Portal and the value 1 as Open. |
|
additionalProperties/defaultValue | String | The default value of the additional property. | |
additionalProperties/unit | String | The default unit of the additional property value. For example, Fahrenheit or Centigrade. | |
additionalProperties/uiType | String | See commands/arguments/uiType. | Y |
additionalProperties/required | Boolean | True ‒ If this additional property is mandatory. |
Example JSON Products/Post Request
curl -X POST \
https://api.stg.axonize.com/odata/products/ \
-H ‘Authorization: Token’ \
-H ‘Content-Type: application/json’ \
-H ‘appId: 801A048A-9F23-429F-BF0D-B6D35B22771E’ \
-d ‘{
{“name”:”ExampleFridge”,
“manufacturer”:”TheFridgeMakingCompany”,
“tooltip”:[],
“customIdDisplay”:false,
“serialNumberDisplay”:false,
“displayDeviceSDKDetails”:false,
“events”:[{“nameResourceKey”:””,
“name”:”HowColdIsItRightNow”,”typeCode”:7,”defaultRollupMethod”:”Avg”,”precision”:1,”displayType”:null,”valueRange”:{“allowedValues”:[],”ranges”:[]},”aggregatedEventSettings”:null}]} { }
‘
Response ‒ Products/Post
All the same properties in the request are returned in the response. In addition, the response that is returned also contains the following properties –
Status 201 – Created
Property | Type | Description |
id | String | A unique Product identifier that is automatically generated for this user by Axonize. |
commands/commandId | The unique identifier is created by Axonize for each command that you define in the Product/Post. | |
createDate, createUser, updateDate, updateUser |
See Common Response Properties. |
Example JSON Products/Post Response
{“@odata.context”:”https://dev-axonizeapi-axonize.dev-ase-axonize.p.azurewebsites.net/odata/$metadata#Products/$entity”,”urn”:null,”name”:”ExampleFridge”,”description”:null,”icon”:null,”customIdFormat”:null,”customIdDisplay”:false,”customIdRequired”:true,”serialNumberFormat”:null,”serialNumberDisplay”:false,”serialNumberRequired”:false,”active”:false,”keepAliveThreshold”:0,”defaultVirtualDeviceEvents”:null,”disconnectChildDevicesOnDisconnect”:false,”connectChildDevicesOnConnect”:false,”disconnectGroupDeviceOnAllChildrenDisconnect”:false,”connectGroupDeviceOnAnyChildrenConnect”:false,”onConnectCommandIds”:[],”manufacturer”:”TheFridgeMakingCompany”,”commandsProtocol”:”Undefined”,”commandsAddress”:null,”commandsUrl”:null,”autoDiscoveryCommand”:null,”displayCommandsTab”:false,”onDeleteCommands”:[],”onPatchCommands”:[],”displayDeviceSDKDetails”:false,”enableSDKFeatures”:false,”id”:”5bb0634719ec0c19c4596b49″,”appId”:”801A048A-9F23-429F-BF0D-B6D35B22771E”,”createDate”:”2018-09-30T05:46:47.7900808Z”,”createUser”:”1234″,”updateDate”:”0001-01-01T00:00:00Z”,”updateUser”:null,”commands”:[],”events”:[{“typeCode”:7,”description”:null,”name”:”HowColdIsItRightNow”,”nameResourceKey”:””,”datatype”:null,”logicalType”:null,”displayType”:null,”unit”:null,”retention”:0,”iconName”:null,”iconColor”:null,”isAccumulated”:false,”subject”:null,”fieldsCount”:null,”precision”:1,”calculationId”:null,”defaultRollupMethod”:”Avg”,”valueRange”:{“minimum”:null,”maximum”:null,”precision”:0,”numericType”:null,”step”:null,”allowedValues”:[],”ranges”:[]},”loggingSettings”:null,”aggregatedEventSettings”:null}],”additionalProperties”:[],”mediaSettings”:null,”tooltip”:[]}