Asset hierarchy

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.

Assets

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

To work with assets in the DTM application, navigate to the Assets page using the navigator on the left. When you first start using the DTM application, no assets are displayed in the Assets page by default, instead you see a message is displayed prompting to create the assets.

If you already created assets, you find them listed on this page (see image below).

Asset hierarchy

The asset hierarchy is displayed on the right in the New asset page. An asset hierarchy consists of the root asset type and all its subsequent child asset types. Each hierarchy level comprises of numerous custom properties for the asset as well as its subassets and devices.

Example:

If you create the root asset level “Building” with the child asset “Floor”, which has the child asset “Room”, then the hierarchy would be displayed as follows:

Building > Floor > Room

To create an asset

To add an asset via the UI:

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

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

   Info

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

3. The asset hierarchy is shown in the left tab and the respective dialog window is shown in the right tab. 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 the Add button.

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

   Info

   The custom properties are defined when creating the asset type. When creating an asset you must provide the values for all custom properties.

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 in the assets requirements.

8. The Confirmation dialog displays an overview of your asset and asset hierarchy levels. Click Create and 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 overview on the left.

Example:

If you are creating an asset hierarchy for the asset “Building”, select the root asset level “Building” in the Choose asset type dropdown menu. Starting with the root asset level, you see the dialog window “Building” on the right. Enter the name of the building in the field Name, for example, “Administration building”. In the field Description you can enter a brief description of this asset, for example, “Office building for administration department”. However, this field is optional and can be left empty. To add numerous 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, “Floor”. Fill out all required fields. You have the option to add numerous assets on this level. Click Next.

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 Device Management > Connecting devices > Device registration in the User guide.

To filter and select devices

Various columns specify the device details for each device. To configure the columns:

1. Click Configure columns at the top right.

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.

   Info

   The sort icon and the filter icons appear on hover over each column.

6. You can select devices through the checkbox. To cancel your selection, click Cancel on the top bar, which removes all selected devices.

7. Click the Assign button at the bottom. The window closes and you can continue creating the asset.

To add multiple instances in an asset

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

Example:

For one building with two floors, you first create the asset hierarchy level for “Building”. Then use the asset type “Floor” to add the floors.

1. Click Add at the bottom to add the asset to the floor asset type.

   

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

   Info

   The delete icon appears on hover.

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 Confirm 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 by clicking the root asset and following the navigation. Also see viewing assets.

Subassets

Click the root asset in the Assets page to load the Subassets page. It shows the details of the root asset, all subassets, child devices and custom properties.

In the top right corner in the Subassets page, you can add child assets, assign devices and import assets in bulk.

To add child assets

1. Click Add child asset in the Subassets page to load the Asset hierarchy for a root asset or asset.

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

   

Example:

If “Building” is a root level asset, then “Floor” is a child asset of “Building” and “Room” is a child asset of “Floor”. If you navigate to the “Building” asset and click Add child asset, then the asset hierarchy loads for “Floor” and “Room”.

If you navigate to the existing “Floor” asset and want to add a child asset, then you can only add child assets for “Room”.

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

Creating assets via bulk import

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

To create a role to use the bulk import feature

To use the Bulk import feature, you must provide permission for Digital Twin 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 which is already assigned for your username.

4. Set all available permissions for Digital Twin in the “Permissions” section by selecting the following checkboxes:

   • Under Application access, select “Digital Twin”.

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

5. 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 Choose asset type.

   • If no asset types are created yet, only the asset type “Group” is listed in the dropdown.

   • If you have added the asset types, all the root asset types are listed in the dropdown.

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

   

4. On selection, two additional options appear:

   • Drop file here - upload the CSV template as a file, for importing assets in bulk.
   • Download Template - download the CSV template for the selected asset type.
   
   

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 a custom 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 custom 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 custom property. If the type is “text” or “number” and custom criteria were provided during custom property creation, then the input value in CSV template must fulfill all the custom property criteria.

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 type. Then enter the asset details for child asset types under the root asset. Next, enter the details for the next level in the hierarchy of child assets 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 type in the Import assets dialog.

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

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 child assets or the child asset hierarchy:

1. Navigate to the child asset page and download the template using Import assets.

2. Fill in the details for the child asset 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.

If all details are mentioned correctly in the CSV template, the child asset 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 by clicking the parent asset.

To view an asset

1. Select an asset.

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

3. Optionally add child assets, assign devices or import assets 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 custom properties for this asset will be displayed on the right.

To view an asset hierarchy

To view an asset hierarchy:

1. Click the asset and scrolling down.

2. When you click the subassets, their child asset hierarchy is displayed. This way, you can view the entire hierarchy.

3. You can also view the hierarchy and navigate to the particular asset using the navigator on the left. Expand the hierarchy in the navigation and select the desired asset to view the asset details.

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.

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.

2. In the resulting confirmation dialogue, click Confirm to continue or Cancel to cancel the deletion.

3. Optionally select the checkbox in the confirmation dialogue to delete all the subassets and devices for the selected asset.