How can we help?

Searching:

0 results found

Products/Post

POST /odata/Products/

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 –

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 –

  • Undefined
  • String
  • Json
commands/commandKind String/Enum Enables you to define if the command is a predefined direct method, as follows –

  • Undefined
  • IoTHubMethod
commandsProtocol String/Enum The command protocol, as follows –

  • Undefined
  • HTTP
  • AMQP
  • Modbus
  • SNMP
  • OPCUA
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 –

  • MultiDimensional
  • Double
  • Integer
  • GPS
  • String
events/displayType String Specifies which user interface controller is used in the Axonize Portal for presenting this event.

Use one of the values below –

  • boolean
  • range
  • allowedValues
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 –

  • Number
  • CountByValue (used for events that have a state)
  • Instantaneous (used for events that are instantaneous, such as pressing a button)
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 –

  • Text
  • Integer
  • Decimal
  • Date
  • Boolean
  • Gps
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 –

  • None
  • RTMP
String/Enum The media type, as follows –

  • Unknown
  • Video
  • Audio
  • Image
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

  • event – Is a tooltip showing the device reading value.
  • property – Is a tooltip showing the device property value.
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: typeCodename. 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 –

  • Button
  • Radio Button
  • Slider
  • Select
  • TextOneLine
  • TextMultiLine
  • IpV4
  • Number
  • OID
  • Toggle
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 –

  • INT
  • Decimal
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 –

  • Number
  • Text
  • Boolean
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 ‒

  • Key A unique key is associated with each Value.
  • Value The value of a Key.
  • iconName For each value, you can specify the name of the icon to represent this value.

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”:”http://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”:[]}