Composite Thing Management

  • 4 minute(s) read

The concept of Thing Definition allows to abstract a physical machine and reuse its definition as model for things that will be registered in the DPS.

This works fine as long as all products are identical and off-the-shelf, but in some cases, in the DPS a product or a machine cannot be described by a single Thing, and you need something more complex in order to accommodate all the elements composing the product, in this case Sub-things must be created.

Sub-things approach is recommended when you have to deal with products having the same part replicated multiple time, and their number may differ thing by thing. For instance two customers bought the same product model, but with different set-ups. The first customer's product has two operational modules, while the second has only one module.

By using sub-things in the DPS you will have a root thing which is visible in the main lists as a normal thing, and by entering its details, you can access the sub-things recursively.
Each level will have its set of metrics, command and parameters, events and views.

Here’s a step-by-step guide about how to configure a generic machine having a first-level of sub-things of type Unit, and a second-level of sub-things of type Module.  

Understand the machine architecture

  • Begin by defining the main parts composing the machine. Machines with several units and modules typically have a core unit (or controller) and peripheral modules, each performing distinct functions.

  • Identify each module, including the data that belongs to it, the presence of specific command or parameters the number of occurrences of such a module. Knowing each module's purpose will help in configuring them correctly.

Create thing definitions

  • Create a Thing Definition for the root thing, this is the one that will be assigned to the main product model.

  • For each identified module define a new thing definition.

    • In the composition select the parent thing definition.


    • Select the Inherited connection status flag, this will update the connection status globally on the root thing.
      If not selected, each sub-thing will have its connection status updated separately.


    • In the Default mapping asset ID field, set to ${ROOT_ASSET_ID}, so when you go to create sub-things in the DPS, you will not need to specify the Asset ID on each of sub-thing.
      In the Default mapping path field, ${PARENT_PATH}/${THING_SERIAL_NUMBER}, so each sub thing will use the parent level path plus the thing serial number.
      In this way all the IoT messages and data will be addressed in a structured way under the Asset ID of the root thing.


      For more details about default mapping placeholder refer to this guide.
      It is not mandatory to specify default mappings or to use placeholders; if you do not do so when registering or creating things, you will need to provide the correct mapping for each one.
      By using placeholders, the mapping is automatically calculated based on the position of the sub-thing in relation to the root thing.

  • By proceeding, recursively among all modules you will recreate the entire machine structure.

Thing Inheritance

To simplify the elements to be configured (e.g. metrics, templates), all thing definitions used in a composite thing could inherit from a base thing definition.

In this way, it is possible to define all common elements in the base thing definition that will be reused in all underlying thing definitions.

Product models association

  • Create a Product Model that will be associated to the things registered in the DPS.

  • Associate the Product Model to the root thing definition.

  • Into the product model, create a model part for each identified machine module recursively.


  • Associate each Model Part to the right Thing Definition.

Templates configuration

When defining templates for the various thing definitions, you can place a Thing List which allows navigating sub-things of the current level.
For example, the image below shows a list of things with expandable rows for lower-level things.

In the template editor, within the property panel of the Thing List widget you can find these advanced properties:

Here is the template code:

<thing-list-widget-v2 [title]="'Machine Parts'" [controlsEnabled]="false" [expandableCompositeThings]="true">
	<property name="name"></property>
	<property name="serialNumber"></property>
	<property name="productModelPart.name" label="Model Part"></property>
</thing-list-widget-v2>

How to publish IoT data

The mapping will affect the way you will publish data to the cloud. The thing and sub-things (recursively) will share the same root asset ID and connection information. Note that, even if in the DPS there will be a thing with sub-things, data publishing will always be made by the single connected product to the root thing. Data of sub-things will be addressed through structured paths.

For instance, considering the STC mapping, these are some example topics.

<USERNAME>/M0001/data  -> publish a metric for the root thing
<USERNAME>/M0001/unit_1/data -> publish a metric for the sub-thing Unit-1 
<USERNAME>/M0001/unit_2/mod_c/data -> publish a metric for the sub-thing Module-C under Unit-2

  • <USERNAME>: is the Username specified in the root thing connection mapping.

  • M0001 is the Asset ID specified in the root thing connection mapping.

In the alternative you can use a flatten approach, where each sub-thing uses a path uniquely defined under the root thing. 

<USERNAME>/M0001/data  -> publish a metric for the root thing
<USERNAME>/M0001/unit_1/data -> publish a metric for the sub-thing Unit-1 
<USERNAME>/M0001/mod_c/data -> publish a metric for the sub-thing Module-C