Cumulocity Digital Twin Manager

Overview
Installation
Features

Overview

The Digital Twin Manager enables you to create and manage assets around your physical connected devices in Cumulocity IoT. Assets can be used to structure and describe devices in logical hierarchies as encountered in the real world environment. In addition, assets in Cumulocity IoT can be extended and enriched with addtional information using the Properties Library.

Sub assets screen displaying the details of an asset selected in Asset Navigator on the left.

Note: Digital Twin Manager is supported on Cumulocity UI and microservice version of 10.14 and above

Installation

The Digital Twin Manager is shipped as a standalone application for now. This means it will be installed as a separate application, which provides all the features of the Digital Twin Manager as described in the features section. The standalone application is available in the release section and can be downloaded.

For installation of web application:

Download dtm-ui-10xx.x.x.zip from the release section
Open the Administration application in your Cumulocity tenant
Navigate to Ecosystem --> Applications
Click on Add application
Select Upload web application in the modal dialog
Select the zip archive, which you downloaded from the release section, to upload it to the tenant

After following these instructions, the application will be deployed on the tenant and is ready for use. In the application switcher on the top right you can now select the Digital Twin Manager application.

If you want to use Import assets functionality, then the microservice needs to be installed.

For installation of microservice:

Download dtm-ms-10xx.x.x.zip from the release section
Open the Administration application in your Cumulocity tenant
Navigate to Ecosystem --> Microservice
Click on Add microservice
Select Upload microservice in the modal dialog
Select the zip archive of microservice, which you downloaded from the release section, to upload it to the tenant
When prompted Subscribe to microservice select Subscribe

After following these instructions, the microservice will be deployed on the tenant. Once the microservice is deployed you can use Import Assets feature.

Note: If the microservice is deployed but not subscribed, then the Import Assets button will not visible in assets page.

Configure a role to use the bulk import feature

Navigate to the Administration application via the application switcher in the top right corner.
Under Quick links click Roles.
In the Global roles tab, select a role to which the permission has to be provided.
Set Admin permission level for Digital Twin type in the "Permissions" section.
Click Save.

Once the permission is assigned, the bulk import feature can be used.

Note: If the permission is not assigned, then the CSV template will not be downloaded correctly.

Subscribing for Feature branding

To use Localization feature, you must have public-options web application installed on the tenant. One of the ways you can get the public-options web application is by subscribing to Feature Branding. The following are the steps:

Navigate to Tenants > Subtenants
Select the subtenant for which you want to add this feature.
Under Applications subscribe for Feature branding.

Complete the setup by following the below steps on the tenant where you want to use Localization feature

Log in as an administrator of the tenant.
Navigate to Administration > Ecosystem > Applications. Under Features, make sure Feature Branding is subscribed.
Navigate to Settings > Branding, and click on Apply. Once done, make sure you can see public-options web application under Ecosystem > Applications.

Note: If you don't have the access for the tenants, please contact your administrator.

Features

Overview of features

The Digital Twin Manager consists of the following features, which support you to create your assets and asset hierarchies:

Property library - Create your own custom properties (simple or complex) to define how data should be stored on an asset
Asset types - Define asset types to describe the blueprint of your assets
Localization - Dynamically translate asset type and custom property descriptions to multiple languages
Assets navigator - Manage your asset hierarchies
Bulk import - To import the entire asset hierarchy with all the assets at once.

Property Library

The Property Library can be used to create your own custom properties to define how data should be stored on an asset. These custom properties can be either complex (nested object) or simple (key-value pair). Furthermore, you can choose a specific data type for each property you define. As of now, the Property Library supports following data types: Text, Number, Date Picker, Enumeration, Boolean.

Property Library screen displaying the list of properties and an option to add or edit the property.

Asset Types

Asset Types serve as a blueprint for your assets and define how they are structured. An Asset Type defines what custom properties an asset should have. Additionally, you can specify relationships between multiple Asset Types, which will be respected when you create your actual asset hierarchies. Once the Asset Type is created, it can be used to create various assets.

Edit Asset Type screen displaying the details of the selected asset type.

Localization

You can use the Localization component to define translations for your asset types and custom properties. These translations can be provided for all supported languages in Cumulocity IoT. This component requires to have the feature-branding feature subscribed for your Cumulocity tenant.

Subscribing for Feature-branding

Localization screen displaying the list of translated terms for your asset types and custom properties.

Assets Navigator

The Assets Navigator is the starting point to create your asset hierarchies based on the asset types and custom properties, you have defined previously. Once you have created your asset hierarchies you can use the Assets Navigator to view and manage them.

Asset Navigator screen displaying the asset hierarchy of the selected asset type.

Bulk import

To import all the assets of a particular asset hierarchy at once, use the bulk import feature. Microservice is being used to download the template and import the assets. To use the Bulk import feature, user must be part of a role that has Admin permission level for Digital twin type. Configure a role for Bulk Import

Import Assets screen displaying the modal box where you can upload and download the template.

You can find more information about how to download the template, import the assets here

Any comments, suggestions or ideas?

Let us know, if the current way for setting up and maintaining an asset hierarchy meets your needs and expectations. For any suggestions, please navigate to Issues and open a new issue with all the relevant details. Once you have created your issue, we will make sure to assign the correct label to it, which will help us to categorize your issue:

🐞 use "bug" for something that is not working
📖 use "documentation" for any feedback about the documentation
💡 use "idea" for every new idea, feature request or suggestion
❓ use "support" for questions or anything that needs further assistance

Thanks for your contribution!

These tools are provided as-is and without warranty or support. They do not constitute part of the Software AG product suite. Users are free to use, fork and modify them, subject to the license agreement. While Software AG welcomes contributions, we cannot guarantee to include every contribution in the master project.

iaananth/cumulocity-digital-twin-manager