Thing Definition

  • 2 minute(s) read

Each connected product registered within the DPS application must be associated with a Thing Definition.

A Thing Definition defines the main product information, the exchanged data (metric, command, parameters), events, UI dashboards, and more.

The catalog supports multiple Thing Definitions, allowing the manufacturer to connect any kind of product.

Optionally, a Thing Definition can be enriched with more domain-specific properties (e.g. image, size, power).

In the case of complex products that are composed of several parts (e.g. smart grids for lighting, large industrial machines), a Thing Definition can be a child of another Thing Definition.

To simplify the abstraction process, a Thing Definition can extend another Thing Definition, inheriting all the elements of the parent levels recursively.

Creating a new Thing Definition

Here you will find how to configure a Thing Definition from scratch.

To create a new Thing Definition, you should:

  1. Enter the Catalog / Thing Definitions page.

  2. Click on the top right Add Thing Definition button.

  3. Edit the available fields.

  4. Press the Save button.

Editing a Thing Definition

Within a Thing Definition, you can configure the following properties:

  • Name: the name of the Thing Definition, generally, it represents the model name or product code.

  • Description: a text used to describe the thing within pages.

  • Thing Definition Inheritance: this section allows you to select the super Thing Definition from which to inherit elements. For more details refer to the Thing Definition Inheritance article.

  • Meta Data: this section allows editing additional properties used to describe the associated things.

  • Thing Definition Composition: the section allows defining whether the Thing Definition is part of another Thing Definition (e.g. Controller → Sub-Thing). In this way, when a thing associated with this Thing Definition is created, the thing must be associated also with the parent thing as defined by the composition. When a parent Thing Definition is selected, you can also define:

    • Inherited connection status: whether the connection status is inherited by the parent thing.

    • On update, perform a broadcast notification: whether the updates are sent to the parent thing only.

    • Cascade delete on sub things: in case the parent thing is deleted, delete also the sub things.

  • Thing Settings: properties you can use to change minor features on the thing

    • Thing tagging allowed: the flag enabling the users to tag things of this type.

    • Default thing name: the name used by default for things.

    • Default mapping asset ID: the mapping asset-id to be assigned by default on newly created things.

    • Default mapping path: the mapping path to be assigned by default on newly created things.

Default thing mapping placeholders

In the Default Mapping properties (Default mapping asset ID, Default mapping path) you can use the following placeholders that are automatically resolved:

  • RANDOM_ID_16: a random alphanumeric ID (length 16) is generated. This is helpful when registering things without asset ID.

  • ROOT_ASSET_ID: in case the thing is a sub-thing, this placeholder is resolved with the asset ID of the root thing.

  • PARENT_PATH: in case the thing is a sub-thing, this placeholder is resolved with the path of the parent thing.
    With this placeholder all the sub-things (recursively) can use the same asset ID (e.g. the one of the root thing) and a structured path with nesting levels.

Example 1

ROOT THING
  AssetId: ROOT-A

SUB THING (child of ROOT THING)
  AssetId: ${ROOT_ASSET_ID}_SUB-1 -> ROOT-A_SUB-1    

Example 2

ROOT THING
  AssetId: ROOT-A
  Path: XYZ

SUB THING 1 (child of ROOT THING)
  AssetId: ${ROOT_ASSET_ID} -> ROOT-A
  Path: ${PARENT_PATH}/SUB-1 -> XYZ/SUB-1 

SUB THING 2 (child of SUB THING 2)
  AssetId: ${ROOT_ASSET_ID} -> ROOT-A
  Path: ${PARENT_PATH}/SUB-2 -> XYZ/SUB-1/SUB-2