Asset hierarchy

Introduction

Assets

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.

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 already created assets, you 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 is 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.

Creating assets via the UI

You have two options for creating assets in the DTM application. The following section describes how to create an asset via the UI. Alternatively, see Creating assets via bulk import on how to import assets in bulk into the DTM application.

To create an asset

To add an asset via the UI:

1. Click Add asset in the top right corner of the Assets page.

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

   Info

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

3. The asset hierarchy is shown in the left section and the respective dialog window is shown on the right. Fill out the fields labeled “required”.

4. Optionally, add a description or 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 in the section to set the values for the latitude and longitude using map view. 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 out the fields as necessary for your asset. Repeat 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 is now 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:

If you are creating an asset hierarchy for the asset model “Wind turbine AZ-43Y”, select the root asset model “Wind turbine AZ-43Y” in the Choose asset model dropdown menu. Starting with the root asset level, you see the dialog window “Wind turbine AZ-43Y” on the right. Enter the name of the wind turbine in the field Name, for example, “SE-TURBINE-101”. In the field Description you can enter a brief description of this asset, for example, “Wind turbine with rated power of 3.6MW”. However, this field is optional and can be left empty. To add more assets to this level, click Add new at the bottom. Repeat until all desired assets on this level have been filled out.

Click Next to see the next asset level, for example, “Rotor”. Fill out all required fields. You have the option to add more assets on this level. Click Next to continue until all assets are created.

To assign devices to an asset

When you create a new asset you have the option of assigning one or more devices to this asset.

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.
3. The dialog closes and you can continue creating the asset.

To add a new device, add it through the Device management application. Refer to Registering devices for further information.

To filter and select devices

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

1. Columns in the grid specify the device details for each device. Click Configure columns at the top right to show or hide columns.

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

3. Click Sort on the applicable columns to view the device data in either ascending or descending order.

4. To filter devices based on text, use the Filter option in the applicable columns. If you apply a filter, you see a notification at the top.

5. To clear the filters, click Clear all filters. To see the sort icon and the filter icon hover over each column.

To add multiple instances of an asset

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

Example:

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

1. Click Add at the bottom to add more blade assets.

   

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

3. Modify the assets by navigating 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.

4. When done, the Confirmation page shows the asset hierarchy. Click Create to create the asset hierarchy.

On successful asset hierarchy creation, you see a pop-up notification in the top right corner. You can view the newly created asset hierarchy in the Assets page. Also see viewing assets.

In case of a bulk operation failure, the entire operation is rolled back and the user will be navigated to main assets page to cleanup the entities created and to try the operation again.

To view asset details

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 or click Import assets to add assets in bulk.

To add subassets

To add subassets to an asset open the 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, 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 Asset tree page of “Wind turbine” and click Add asset, the asset hierarchy loads for “Rotor” and “Blade”.

If you navigate to the existing “Rotor” asset and want to add a subasset, you can only add subassets for “Blade”.

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

Creating assets via bulk import

To import the entire asset hierarchy with all assets at once, use the bulk import feature. For each asset model, a CSV template is provided. Fill in the required details in this template and upload the file to create the assets in bulk for the selected asset model.

To use the bulk import feature

To use the Bulk import feature, you must enable the Digital Twin permission for the user’s role, following these steps:

1. Navigate to the Administration application via the application switcher in the top right corner.

2. Under Quick links click Roles.

3. In the Global roles tab, select the role to which permissions are to be provided.

4. Select the “Admin” permission for “Digital Twin” in the “Permissions” section.

5. Enable access to the DTM application by selecting the following checkboxes:

   • Under Application access, select “Dtm-ms”.

   • Under Custom applications, select “Digital twin Manager”.

6. Click Save.

Once the permissions are assigned, the bulk import feature can be used.

To download a CSV template for bulk import

Follow the steps below:

1. Navigate to the Assets page and click Import assets.

2. The Import assets dialog has a dropdown Select asset model. If you have added the asset models, all the root asset models are listed in the dropdown.

3. Select the asset model for which you want to create the asset hierarchy.

   

4. On selection, the following options become available:

   • Drop CSV file here or click to browse - upload the CSV template as a file, for importing assets in bulk.
   • Download Template - download the CSV template for the selected asset model.
   
   

5. Click Download Template to download the CSV template.

CSV template parameters

The CSV template has the following fields:

To provide a file input as an asset property value, the file must first be uploaded to a Cumulocity IoT tenant using the Cumulocity IoT API.

Refer to the Binaries API in the Cumulocity IoT OpenAPI Specification for details on how to upload a file to Cumulocity IoT.

The binary ID in the API response must be provided as input for the asset property field with type “file” in the CSV template.

If the type is “Boolean”, the input field must be either “true” or “false”. If the type is “enumeration”, then the input field must be in the list of values specified during creation of the asset property. If the type is “text” or “number” and custom criteria were provided during asset property creation, then the input value in CSV template must fulfill all the asset property criteria.

When creating a property, you have the option to assign a default value. If a property’s value is left empty in the CSV file during the bulk import, its value is set to default. To override this behavior, enter ’null’ as the value in the CSV file. This does not set the value and it is seen as undefined when viewing the asset.

Fill in details for all the assets which must be created as part of the asset hierarchy.

Start with the asset details for root asset model. Then enter the asset details for child a models under the root asset. Next, enter the details for the next level in the hierarchy of subassets and repeat until the details for all the assets are entered in the CSV template. Save the CSV template in your system.

To upload a CSV template

To upload the CSV template follow the steps below:

1. Click Import assets in the Assets page.

2. Select the asset model in the Import assets dialog.

3. Upload the previously filled and saved CSV template in the Drop file here section and click Import.

4. If all the inputs are provided correctly, the bulk import is successful, resulting in a success notification. The asset hierarchy and its assets are created successfully.

5. View the newly created assets in the Assets page.

If the inputs are not provided in the correct format, the bulk import fails with validation errors, resulting in a Failed asset imports notification, showing the issue types, for example, an invalid template or an incorrect asset hierarchy. No assets are created.

If the bulk import fails, review the reported issues and try again.

Partial import

If the asset hierarchy already exists, and you want to import more assets, it can be achieved by a partial import.

To import subassets or the subasset hierarchy:

1. Navigate to the Asset tree page of the subasset and download the template using Import assets.

2. Fill in the details for the subasset hierarchy in the CSV template. See CSV template parameters for more details.

   Info

   From any hierarchy level, the template will be downloaded only for its child hierarchy. Assets must only be imported for the child hierarchy.

3. Click Import assets.

4. Upload the CSV template in the Drop file here section in the Import assets dialog and click Import.

If all details are mentioned correctly in the CSV template, the subasset hierarchy is created successfully.

An unsuccessful partial import will result in a Failed asset imports notification, showing the validation issues. Review the reported issues and try again.

Viewing assets

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

To view an asset

1. Select an asset from the hierarchy on the Assets page.

2. The Subassets page contains the asset details, created and last updated time displayed at the top right.

3. Optionally assign devices from the top bar.

4. The asset name and description along with the icon are displayed at the top. All subassets and devices for this asset will get listed in the Subassets section.

5. All the asset properties for this asset will be displayed on the right.

6. In the Asset tree tab you see the asset hierarchy.

7. Optionally add subassets, or import assets using the options on the top right.

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

To modify an asset

Fields are marked editable by an edit icon . To modify any of the asset details, click the edit icon , enter new details and save.
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:

1. Click the delete icon next to it.

   Info

   The delete icon appears on hover of each row under the subassets section.

In the following dialog box, click Confirm to continue. Optionally select the checkbox in the dialog box to delete all subassets and devices for the selected asset.

To search for an asset

You can search for assets through 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 section Search results.

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.

The Search page only shows a limited number of matches. In case of more matches, switch to the asset data table to see the complete results.

The DTM application extends the full text search capability of Cumulocity IoT for searching assets. See Search and filter functionality to know more about available search options.

To move assets

Use the assets move feature to relocate assets within hierarchies. To move one or more assets, follow the steps below:

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