Skip to content

Device Metadata

A Device Metadata is a Key-Value that can be used by the platform users to add extra information or description on a Device. It includes the following elements:

  • Key: the identifier of the metadata. Mandatory and unique for the Device.
  • Value: a free field indicating the value of the metadata. It is JSON data type (boolean, number, string and complex object).
  • Type: a metadata can either be a custom one, or a system one. See this section.

These metadata are associated with one specific Device.

Metadata types

Custom

Custom metadata can be set by the customer, as long as they have the required permissions. Interpretation of the value is done by the business application and the user.

Note

Custom metadata have no impact on the internal behavior, they are strictly dedicated to the customer usage.

System

System metadata are used by the system to convey technical information that will have an impact on some features. They cannot be edited by the user, and are ofter created as a side effect of a configuration. In most use cases, they can be ignored, since their value will be retrievable through the API, in the endpoint that controls the feature they parameterize.

Example

A Device has 3 metadata

  • address a string that contains 14 rue Rhin et Danube
  • my_number a number that contains 42
  • custom_decriptor a JSON complex object that contains {"agent_id":1, "position":"UP"}
Key Value
my_number 42
address 14 rue Rhin et Danube
custom_decriptor {"agent_id":1, "position":"UP"}

Device Metadata Features

Synthesis table

Feature State
Read device metadata Available
Create metadata Available
Update metadata value Available
Delete metadata Available
Event generation Available

Read device metadata

Permission

  • read.device metadata

Feature

  • Users can read Metadata associated with a Device. It is possible to filter only on a specific key or get all metadata
  • if requested key or device id does not exists, a dedicated error is returned

Create metadata

Permission

  • write.device metadata

Feature

  • Users can create new Metadata associated with a Device specifying the desired key and value
  • If key already exists the targeted metadata is updated (see update metadata value)

Update metadata value

Permission

  • write.device metadata

Feature

  • Users can update existing Metadata associated with a Device
  • The key cannot be changed, only the value can be changed. You can create new Metadata if a new key is needed
  • Multiple Metadata can be edited at the same time

Delete metadata

Permission

  • write.device metadata

Feature

  • Users can remove existing Metadata associated with a Device
  • It removes the key and value of the Metadata
  • No archive, removed Metadata cannot be restored

Event generation

Permission

  • not applicable

Feature

  • Metadata updates by users are logged as a Device event in the system
  • Only metadata keys are logged in the event payload (no value)