Asset hierarchy

Overview

In the DTM application, assets are the digital representation of physical assets. An asset in the DTM application can contain subassets and devices. You also have the opportunity to define properties or parameters of an asset through asset properties.

In addition to its hierarchical structure, an asset can have associated or linked data points. This means that each asset not only represents a physical entity but also serves as a dynamic interface to its operational data.

To work with assets in the DTM application, navigate to the Assets page using the navigator menu on the left. When you first start using the DTM application, no assets are displayed in the Assets page by default.

If you have already created assets, you can find them listed in a hierarchical view on this page.

Asset hierarchy

An asset hierarchy is a structure that organizes multiple assets and devices into a hierarchy, allowing for the visualization and management of complex systems.

The asset hierarchy is displayed in the Assets page. An asset hierarchy consists of a root asset and all its subsequent subassets. Click Add asset to create the entire hierarchy of an asset in the New asset page. For details, see To create an asset.

Example:

If you create the root asset “Wind turbine” with the subasset “Rotor”, which has a subasset “Blade” then the hierarchy would be as follows:

Wind turbine > Rotor > Blade

Initially, all the asset hierarchies are collapsed and it lists only the root assets. The list also shows certain asset details, for example, asset model and description. Click the expand icon to the left of each asset to view the next level of subassets. Note that the devices assigned to an asset are not shown in the asset hierarchy.

Click the asset name to view the asset details and the devices assigned to it.

To edit or delete an asset from the Assets page, click the menu icon at the right of the row and click either Edit or Delete. To delete multiple assets at once, select one or more assets and click Delete in the top banner.

Select one or more assets of same type to relocate from its current hierarchy to another. For more information on how to move assets between hierarchies, see To move assets.

Assets

Once the asset hierarchy has been created by adding assets, they can be viewed in the Assets page.

To view an asset

In the Assets page, select an asset to view its details, such as subassets, child devices, and asset properties.

The Subassets page shows all asset details:

• At the top, the asset name and description is provided, along with the Created and Last updated time.
• In the Subassets section, all subassets and devices are listed.
• All asset properties are displayed on the right.

Optionally, add subassets or assign devices from the top bar.

In the Asset tree tab, the assets hierarchy is shown.

Optionally, add subassets using the options on the top right.

If a location is specified for the asset, it is shown in the map under the properties section below its values. To see the map, provide a value for latitude and longitude. Click the full screen icon at the top right corner of the map to view it in full screen. You cannot modify the marker when viewing the asset. Edit the property to change the position of the marker.

To view the asset hierarchy

Select an asset in the Assets page to view the asset details in Subassets tab. It shows all the subassets, child devices and asset properties.

In the top right corner of the Subassets tab, you can assign devices.

You can view the hierarchy of the asset in the Asset tree tab. Initially the asset hierarchy is collapsed. Click the expand icon to view the next level of subassets.

Click Add asset to add more subassets.

To create an asset

There are two options for creating assets in the DTM application, that is, via the UI and via REST API.

The following section describes how to create an asset via the UI. See the DTM API documentation for using the DTM REST API.

To add an asset via the UI:

1. Click Add asset in the top bar of the Assets page.

2. In the New asset page, select the desired asset model from the Choose asset model dropdown menu.

   Info

   The asset models provided here are root asset models. Root asset models are asset models which are at the top of a hierarchy and don’t have any parent asset model. They are labeled “START NODE” in the hierarchy.

3. At the left, the asset hierarchy is shown. At the right, provide a name for the new asset and optionally add a description.

4. Optionally, assign devices to your root asset.

5. To add more than one root asset, click Add.

6. Under Asset properties, fill in the required information. Here you find all asset properties assigned to the asset model that you create.

For an asset with a Location property, click Choose on Map to set the values for latitude and longitude. Click the full screen icon at the top right corner of the map to view it in full screen.

The marker is positioned at the default value set in the Location property. Click or drag the marker to the preferred position to set the value for both latitude and longitude. If you do not enter a latitude or longitude value, you will not see a marker on the map.

7. Click Next to reach the next hierarchy level of your asset hierarchy and fill in the required fields. Repeat this step for all asset hierarchy levels.

8. The Confirmation step displays an overview of your asset and asset hierarchy levels. Click Create to create your asset.

The asset will be listed in the Assets page.

As you define each hierarchy level of your new asset, you see a green check mark on each asset hierarchy level in the section on the left.

Example:

1. If you want to create an asset hierarchy for the asset model “Wind turbine AZ-43Y”, select “Wind turbine AZ-43Y” from the Choose asset model dropdown. Starting with the root asset level, you see the dialog window “Wind turbine AZ-43Y” on the right.
2. Enter the Name of the wind turbine, for example, “SE-TURBINE-101”. Optionally, enter a brief description, for example, “Wind turbine with rated power of 3.6MW”.
3. To add more assets to this hierarchy level, click Add at the bottom.
4. Click Next to see the next asset level, for example, “Rotor”.
5. Fill out all required fields. Again, you have the option to add more assets on this level.
6. Click Next to continue until all assets are created.

To add subassets

You can add subassets to an asset from the Subassets or Asset tree tab.

1. Click Add asset to load the Asset hierarchy for the selected asset.

2. The root asset is displayed with the label “parent node”. The asset hierarchy displayed below it is a subset of the root asset hierarchy.

   

Example:

If “Wind turbine” is a root level asset, then “Rotor” is a subasset of “Wind turbine” and “Blade” is a subasset of “Rotor”. If you navigate to the Subassets or Asset tree page of “Wind turbine” and click Add asset, the asset hierarchy loads for “Rotor” and “Blade”.

If you navigate to the “Rotor” asset and and click Add asset, you can only add subassets for “Blade”.

For details on how to add assets in the asset hierarchy, see To create an asset.

To create multiple instances of an asset

At each hierarchy level, you can create multiple assets from a single asset model.

For a wind turbine rotor with three blades, for example, you first create the asset hierarchy level for “Rotor”. Then use the asset model “Blade” to add the blades.

Click Add at the bottom to add more blade assets.

To delete an asset template, click the delete icon at the top right.

Modify the assets by navigating to the asset pages using the Previous and Next buttons. You can track your progress via the green check marks in the asset hierarchy on the left.

When all assets in the asset hierarchy show green check marks, a Confirmation page shows a preview of the asset hierarchy. Click Create to create the asset hierarchy.

If the asset hierarchy has been successfully created, you see a pop-up notification at the top right. The new asset hierarchy in displayed the Assets page. Also see viewing assets.

To assign devices to an asset

On creating a new asset you can assign one or more devices to it.

1. Click Assign devices in the New asset page.
2. The resulting dialog window lists all devices registered for the tenant. Select one or multiple devices and click Assign.

To add new devices, switch to the Device Management application. For details, refer to Registering devices.

To filter and select devices

You can view, search, or filter devices easily with the following options.

• The columns shown in the grid specify the device details for each device. Click Configure columns at the top right to show or hide columns.

• Click Reload to reload the page and display the latest list of devices present in the Cumulocity tenant.

• Click Sort on the applicable columns to view the device data in either ascending or descending order. The sort icon shows up when hovering over the column.

• To filter devices based on text, use the Filter option in the applicable columns. The filter icon shows up when hovering over the column. When a filter is applied, a notification will be shown at the top.

• To clear the filters, click Clear all filters.

To modify an asset

To modify any of the asset details, click the edit icon next to it, enter the new information, and save it.

For an asset with a location, click or drag the marker to the preferred position to select the value for latitude and longitude on the map. Click the full screen icon at the top right corner of the map to enter full screen mode. To see the map, provide a value for latitude and longitude.

To delete an asset

To delete a subasset or device in the hierarchy, click the delete icon next to it and confirm. The delete icon shows up when hovering over a row.

In the confirmation dialog, you can select if you only want to delete the asset with all associated subassets or if you additionally want to delete all associated devices.

To search for an asset

You can search for assets using the Search button at the right of the top bar. Enter a search term into the textbox at the top of the Search window to see all assets matching the search criteria in the Search results section.

The Search page only shows a limited number of matches. To see more details, click Go to the asset data table at the bottom. This will show the entire search results in a table format.

To move assets

To move one or more assets, follow the steps below:

1. Select one or more assets of the same type in the Assets page.
2. Click Move selected at the top.
3. In the resulting dialog, a list of assets is shown which allow the selected assets as its children. Click the radio button to the left of an asset to select it.
4. Click Move to complete the relocation.

Data points

Data points represent the numerical measurements collected from connected devices and sensors. These are the fundamental real-time data streams that offer insights into the operational status, performance, and environmental conditions of your physical assets. These data streams are key to monitoring asset health, identifying trends, and making informed decisions over time.

To effectively organize and interpret the vast amount of data collected from IoT devices, Cumulocity structures measurements using two key concepts: fragments and series. These concepts are crucial for understanding how measurement data is categorized and stored within the platform and how to use data points in the Digital Twin Manager (DTM) application.

A fragment serves as a logical container or category that groups related measurements or characteristics of an asset (or any managed object). It identifies a specific capability or a set of related data points. Within a fragment, a series represents a specific, individual measurement stream. It is the named property that holds the actual numerical value and its corresponding unit. A data point, and with this the measurement series it represents, is uniquely identified by the combination of its fragment and series.

Example: Within the c8y_Temperature fragment, T (for Temperature) could be a series. Each series provides a distinct stream of data for a particular metric. If a device has two temperature sensors, one for ambient temperature and one for internal temperature, both might fall under the c8y_Temperature fragment but would have distinct series names, such as for example T_Ambient and T_Internal.

The DTM application allows managing data points for assets.

Types of data points

In Cumulocity, data points are inherently associated with managed objects in the platform’s inventory. As assets are a type of managed object, measurements can be associated with assets as any other managed object. However, there are two distinct ways in which data points can be associated with assets in the Digital Twin Manager.  

Direct association: Any managed object in Cumulocity, including an asset, can directly receive measurements and have measurements directly associated. This means that an asset itself can be the source of a measurement. For example, if a building asset has its own sensors directly integrated with Cumulocity, the measurements from these sensors will directly be associated with that building asset.

Linked association: The Digital Twin Manager allows linking of data points from one managed object (typically a device) to an asset. This means the asset itself does not generate the measurement and does not have the measurement directly associated, but it points to a measurement originating from another source, usually a connected device that is part of or related to the asset’s hierarchy.  

To view data points

To view the data points for a specific asset, select an asset from the hierarchy on the Assets page. In the asset details view, select the Data points tab.

Understanding the columns in the data points list

The Data points tab presents all relevant information about the data points associated with the selected asset in a table format. Each row in the table represents a unique data point with the following columns:

For linked data points, the Source column shows the name (or ID) of the source device and the fragment and series on the source device. Fragment and series are only shown for the source if they are different to fragment and series of the data point itself. Via the source context menu of linked data points, you get access to actions such as changing the source device or unlinking the data point.

Understanding states

The Status column provides immediate feedback on the state of a data point. Understanding these states is key to ensuring assets are receiving the expected data. States currently supported in the DTM application are:

In case of an error or warning status for a data point the, Source shows the warning or error indicators and provides options to troubleshoot and resolve the issue via the context menu. For example, in the case of a Missing source status, you can select a new source device to link the data point to.

To create linked data points

All data points associated with an asset can be created in the Data points tab of the Assets page.

1. Select an asset from the hierarchy on the Assets page and switch to the Data points tab in the asset details.
2. The Data points tab contains a comprehensive list of all data points associated with the selected asset.
3. Click the Link data points button at the top right of the Data points tab. This opens the data point selector dialog.
4. Select the source device from which you want to link data points. This is done by navigating through the asset hierarchy in the left panel of the dialog.
5. In the center panel, you can either select from existing data points associated with the source device or define custom data points by specifying the fragment and series.
6. The right panel displays the data points you have selected for linking. Review your selections here.
7. Once you have made your selections, click the Add data points button at the bottom of the dialog to finalize the linking process.

For each selected data point, a new data point will be created for the asset, pointing to the source device and its specific measurement series.

When choosing from available data points, you have two primary options:

Associated data points: Select from the list of measurement series already known or received by the platform from the currently selected source device in the Data point selector. These are measurements that the platform has already processed and recognized. You can click the plus button next to any of these listed data points to add them to your selection.

Custom data points: If the desired measurement has not yet been received by the platform from the source device, you can define it as a custom data point. To do this, you must manually provide the fragment (for example, c8y_Temperature) and series (for example, T) in the respective input fields. You might also need to provide a measurement type.

To modify linked data points

1. Navigate to the Assets page and select the asset for which you want to manage linked data points.
2. In the Data points tab of the asset details, find the linked data point you wish to update.
3. Click the Change source option in the context menu of the linked data point.
4. In the Change source dialog, you can select a new source device or modify the fragment and series of the linked data point.
5. After making your changes, click Save to apply the changes.

To delete linked data points

1. Navigate to the Assets page and select the asset for which you want to delete linked data points.
2. In the Data points tab of the asset details, find the linked data point you wish to delete.
3. Hover over the linked data point and click the delete icon that appears at the right.
4. In the confirmation dialog, select Delete to delete the linked data point.

To unlink linked data points

1. Navigate to the Assets page and select the asset for which you want to unlink data points.
2. In the Data points tab of the asset details, find the linked data point you wish to unlink.
3. Click the Unlink source option in the context menu of the linked data point.
4. In the confirmation dialog, select Unlink to remove the link between the asset and the source device for that data point.

Source warnings and errors

Sources of linked data points can have warnings or errors that indicate issues with the data point. Warnings are highlighted using the warning icon, while errors are highlighted using the error icon .

Possible issues include:

• Error: The source device cannot be found.
• Warning: The measurement type is required but is not configured for the data point.
• Warning: The measurement type, if configured for the data point, is not matching the measurement type of the latest measurement received from the source device.

By hovering over the warning or error icon, you can see more details about the issue. This helps in troubleshooting and resolving any problems with the linked data points. To resolve the issues, use the context menu actions available for the source.