Skip to content

Metadata

A Metadata is a key-value pair that can be used by the platform users to add extra information or description on a Device, a Folder or a Tenant. It includes the following elements:

  • Key: the identifier of the metadata. Mandatory and unique for the target.
  • 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 target.

Note

When used on a device, metadata are not sent to the device. To that, use device configurations instead

Metadata types

Custom

Custom metadata can be set by the users, 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 often 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_descriptor a JSON complex object that contains {"agent_id":1, "position":"UP"}
Key Value
my_number 42
address 14 rue Rhin et Danube
custom_descriptor {"agent_id":1, "position":"UP"}

Device Metadata Features

Read metadata

Permission

  • read.[device|folder|tenant]

Feature

  • Users can read Metadata associated with a target. It is possible to filter only on a specific key or get all metadata
  • If requested key or target ID does not exist, a dedicated error is returned

Create metadata

Permission

  • update.[device|folder|tenant]

Feature

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

Update metadata value

Permission

  • update.[device|folder|tenant]

Feature

  • Users can update existing Metadata
  • 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

  • update.[device|folder|tenant]

Feature

  • Users can remove existing Metadata
  • 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 target event in the system
  • Only metadata keys are logged in the event payload (no value)