Thing Definition

  • 4 minute(s) read
Prev Next

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. It is used to identify the Thing Definition (e.g., Packaging Machine), which is different from the name of the Product Model.

  • Description: The text you can use to describe the Thing Definition.

  • 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.

  • Metadata: This section allows editing additional properties.

  • Thing Definition Composition: Here, you can define 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: The properties you can use to change minor features on the thing:

    • Thing tagging allowed: The flag enabling users to tag things.

    • Default thing name: The name used by default for things.
      For more details, refer to the Default Thing Name section.

    • Default mapping asset ID: The mapping Asset Id to be assigned by default on newly created things.
      For more details, refer to the Default Thing Mapping section.

    • Default mapping path: The mapping path to be assigned by default on newly created things.
      For more details, refer to the Default Thing Mapping section.

Default Thing Name

Within the DPS, a thing could be represented by a simple string (e.g., Machine-1 [M-0001]) and this could happen in the breadcrumb, in a list of things, or in a widget.
According to the logged-in user, the information used to identify a thing may be different; for instance, a customer user is more familiar with the name of the thing (e.g., Line-1 Bending Machine), but a service or back-office user identifies the thing with the serial number or Asset Id.

For this reason, in the Thing Definition, you can specify the Thing Default Name that is assigned and kept updated for each thing.
The Thing Default Name can be based on placeholders (e.g. ${serialNumber} [${productModel.name}]).
Other than placeholders based on thing properties, you can also use include mapping information:

  • mapping.path: Includes the mapping path of the thing.

  • mapping.path[pos]: Includes the mapping path token at the given position (zero-based). The “/“ character is used to tokenize the mapping path.

  • mapping.assetId: Includes the Asset Id of the thing.

When printing the name of a thing, other than using the name (assigned by the Customer), You can also use the defaultName , which is automatically resolved according to the defined mask.

Within the breadcrumb or widgets, where a short representation of the thing must be displayed, the default name is always used for Organization and Partner users.
Instead, Customer users will always see the name that they have assigned to the thing. In case the name is empty, the defaultName is displayed instead.

Default Thing Mapping

In the Default Mapping properties (Default mapping asset ID, Default mapping path), you can use the following placeholders (e.g., ${PARENT_PATH}) that are automatically resolved:

  • RANDOM_ID_16: A random alphanumeric ID (length 16) is generated. This is helpful when registering things without an 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