Code Monkey home page Code Monkey logo

cumulocity-digital-twin-manager's Introduction

Cumulocity Digital Twin Manager

${\color{red}The \ open-source \ release \ of \ DTM \ has \ been \ discontinued \ after \ version \ 1019.1.2.\ This \ decision \ was \ made \ because}$ ${\color{red}our \ customers \ now \ benefit \ from \ continuous \ deployment, \ which \ enables \ them \ to \ access \ changes \ much \ faster.}$

Table of Contents

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 Asset properties.

The home screen of the DTM application gives an overview of the application. You can see the number of asset models, asset properties and assets available at a glance. You can add asset properties, asset models and assets using the quick links.

You cannot create asset models, properties and assets if you dont have inventory admin permission.

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:

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

DTM installation gif

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:

  1. Download dtm-ms.zip from the release section
  2. Open the Administration application in your Cumulocity tenant
  3. Navigate to Ecosystem --> Microservice
  4. Click on Add microservice
  5. Select Upload microservice in the modal dialog
  6. Select the zip archive of microservice, which you downloaded from the release section, to upload it to the tenant
  7. 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

  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 a role to which the permission has to be provided.

  4. Set Admin permission level for Digital Twin type in the "Permissions" section.

  5. 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:

Log in to the corresponding management tenant as an administrator

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

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

  1. Log in as an administrator of the tenant.
  2. Navigate to Administration > Ecosystem > Applications. Under Features, make sure Feature Branding is subscribed.
  3. 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:

  • Assets - Lists all the available assets and its hierarchy which are created using asset models and properties.
  • Asset properties - Create your own asset properties (simple or complex) to define how data should be stored on an asset
  • Asset models - Define asset models to describe the blueprint of your assets
  • Localization - Dynamically translate asset model and asset property descriptions to multiple languages.

Assets

Assets are the digital representation of physical assets. An asset in DTM application can contain subassets and devices. Initially, no assets are displayed in the Assets page by default. If you have already created assets, you find them listed with its hierarchy.

image

Assets screen displaying the list of assets and an option to add asset or import assets.

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.

image

Asset hierarchy screen displaying the subassets of the root asset.

Creating assets via 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.

You can create assets based on the asset models and properties you have defined previously.

image

Asset creation screen displaying the asset hierarchy of the selected asset model.

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

Note: Import assets button is disbaled if user doesn't have permission to create a group.

image

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

View assets

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.

image

Sub assets tab displaying the details of the selected asset.

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 child assets in bulk.

image

Asset tree tab displaying the child asset hierarchy of the selected asset.

Asset search

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.

image

Asset search screen displaying the results based on the text entered.

Asset properties

The Asset properties can be used to create your own properties to define how data should be stored on an asset. These asset 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 Asset properties supports following data types: Text, Number,File Upload Date Picker, Enumeration, Boolean.

image

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

Asset models

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

image

Edit Asset model screen displaying the details of the selected asset model.

Localization

You can use the Localization component to define translations for your asset models and asset 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

image

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

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.

cumulocity-digital-twin-manager's People

Contributors

beabehnisch avatar cguether avatar dchc01 avatar dimpuprasad avatar nneuerburg avatar spau6 avatar srinath0707 avatar techcommunity avatar vagdevi1998 avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

cumulocity-digital-twin-manager's Issues

Suggestion: Custom properties - Blacklist certain Keys

If a user defines a custom property he is free to decide how to name it and what key should be used. The key is used as property name in the data model of the asset, which is created based on this custom property. As there aren't any limitations to what keys the user can define, he could use keys, which are already used as built-in properties. This can result in strange side effects.

For example if the user defines a custom property, which has the key type, he could by accident override the built-in property type, which is used to identify the asset type. There should be a blacklist, which contains keys, which must not be used by users and are marked as built-in.

Unable to edit and save existing Asset Property type-complex

Steps to reproduce

  1. Create asset property with type complex property and add 3 key-value pairs
  2. Save the asset property
  3. Assign the property to an asset
  4. Navigate to asset page and submit details for the respective asset and save
  5. Now Edit the property and add 4 the key to same asset property, and it will not provide option to save it

Video displaying the occurrence of the issue

Video.2022-08-25.at.10.46.17.AM.mp4

Unable to use localization despite feature branding is already subscribed

While I was able to use localization till now, but once I upgraded to 1015.0.0.312 i started getting error to "Configure the feature branding to use the translation memory."

I am already subscribed to feature branding but still getting error.

UI version: 1015.0.0.312
Microservice version: 1015.0.0.312

image

DTM: Property library: Issues observed in Add new property screen.

Issues are mentioned below,

  1. When user is creating a custom property, and default value is already filled, then the moment user clicks on Max length check box, empty validation error is displayed for default value. It should be displayed only if the default value does not conform to the max length of characters.

  2. When creating a custom property of type text, in minimum length field, user is able to reduce the value to lesser than 0 using the decrement icon. This should not be allowed.

  3. If user selects type as a text and configures min & max length, it is observed that if they don’t provide value as per the condition then error message is being displayed only for min length not for max. Though user can’t provide text beyond max length.

  4. Validation issue when creating custom property of type number. In case user provides a 2 digit number as maximum limit and enters a default value greater than that, then in validation message only the first digit is seen.

  5. Validation for Key field is missing in the complex custom property. It accepts space/special characters as valid input.

DTM: Assets: Issues observed in custom properties section under subassets page.

  1. Create an asset type with the simple custom property. Navigate to Assets page and create an asset hierarchy. Now navigate to subassets page, the custom properties of an asset is being displayed on right side of the screen.

Behavior observed: Only the properties value has been shown, which is not very clear for the user.
Expected behavior: Properties value should be shown along with the name.

  1. Follow the steps mentioned in the above issue. Instead of simple custom property, create complex property.

Behavior observed: The property key is being shown as a property header under custom properties which is incorrect.
Expected behavior: The property label should be shown as a header.

  1. If user deletes a property from the asset type which is used in an existing asset hierarchy and add another then the property which is added newly is not getting loaded under custom properties section in subassets screen.

Digital Twin Manager : Validations missing in Assets section.

In the Digital Twin Manager application, under Assets section, validations are missing for the below scenarios :

  1. User is able to create 2 hierarchies with same asset name, this should not be allowed.

  2. In Assets page, able to create Asset with blank name. This should not be allowed.

  3. Asset names donot have any upper limit on the maximum number of characters.

DTM: Issues observed in edit property window in subassets page.

  1. Once the asset is created, later if user try to modify the custom property value, and if there is validation error, then the message is not displayed. It displays an empty validation.

  2. The cancel option for properties is not working as expected. Edit the custom property and change the custom value and click cancel. Value does not get saved but when clicked on edit again, it shows the modified unsaved value which is incorrect.

DTM : Same device can be used in multiple hierarchies, which should not be allowed.

Currently in DTM application the below issues are observed with respect to hierarchy creation and hierarchy structure :

  1. Adding same device for different assets should be restricted. User is able to assign the same device to multiple Assets, which is not logical. This should be restricted.

  2. Moving an asset outside it's parent should be restricted. Currently user can move an asset outside the parent and place it in a totally different asset hierarchy, which should be restricted.
    Eg : User can move the printer asset from under a Building and place it in Production line which is not relevant/ logical.

    1. When user tries to move an asset, it is observed that alert popup is getting displayed. Currently the following message is getting displayed on the popup "Do you want to move the group?", this has to be changed like "Do you want to move the asset?".

    2. A generic isseue observed throughou the application is that, user can create duplicate labels / names or names with whitespaces only. Both should be restricted.

DTM : Select all devices link does not work as expected.

In DTM application, in any of the pages where a check box is displayed against the rows, user has an option to select all the rows using Select-all at top.

On click on this "Select all" icon, another link gets displayed asking if user wants to select all the rows in all the page. But on click of the option, the rows of other pages are not selected.

Either this option needs to be removed or the functionality has to work so that all rows gets selected.

Another issue observed is that in "Assign devices" page, (lazy loading is implemented here) on click of Select all option, only 20 devices or the number of devices loaded currently gets selected, which is not the expected behavior. Ideally on Select all, all the rows will have to get selected.

UI not loading after deployment

After I deployed the webapplication zip file and selected Digital Twin Manager in the app switcher the App is not loading. I only see the turning wheel.

I'm on eu-latest.cumulocity.com

JS console says:

[Error] SyntaxError: Invalid regular expression: invalid group specifier name
(anonymous function) (3119.42aad4d6562079f548eb.js:1)
[Error] Unhandled Promise Rejection: ChunkLoadError: Loading chunk 3119 failed.
(missing: https://mstoffel.eu-latest.cumulocity.com/apps/digital-twin-manager/3119.42aad4d6562079f548eb.js)
generatorResume (bootstrap.53ce2fb8f940af0e7d0a.js:2:109177)
a (bootstrap.53ce2fb8f940af0e7d0a.js:2:4834)
promiseReactionJob

Recent Version

Hello Digital Twin Team,

Is there any more recent version of the Digitial Twin Manager that you can upload?

Digital Twin Manager : Deletion of Asset type and Custom property, which is being used in Asset is allowed.

In the Asset configuration section below scenarios are allowed, which should not be allowed or user has to be notified regarding the same :

  1. Since the same assets and devices can be assigned to different hierarchies/ assets, deletion of these asset or devices from one asset/ hierarchy will affect the other assets/ hierarchy. And the user is not notified about the same.

  2. Deletion of an asset type, used in an existing asset is allowed, which is wrong. No user notification received.

  3. Deletion of an asset property, being used in an asset type is allowed, which is wrong.

User is not notified about the same.

DTM: Localization: CSS issues in Localization page.

In DTM application, navigate to Localization page.

  1. On hover over , edit icon is not getting displayed for translation field. Scenarios are mentioned below.

    a) If user configures all the columns.

    b) If translation text is too long.

Bug: Create new asset using a complex property without values

Description

I have defined an asset model "building". The asset has a complex asset property field "c8y_Position" (not required), including the properties lat (Number, no default value) and lng (Number, no default value).

When defining the asset property field, the UI shows the preview of the data model as follows:

{
  "c8y_Position": {
    "lng": "",
    "lat": ""
  }
}

Why are lat and lng defined as text string?

How to reproduce the bug

Once I start to create a new building asset without defining the property c8y_Position, I observed different behaviors:

  1. Leaving the input fields for c8y_Position untouched, the created asset object has the c8y_Position property defined as noticed above with an empty string as value.
  2. When I first enter a value in the input field, remove it again, click on the create button, then the c8y_Position property of the new asset looks like this:
{
  "c8y_Position": {
  "lng": null,
  "lat": null
  }
}

Expected behavior

Because the properties lat and lng are defined as type Number, I would expect to not try to cast those as string text field, when the field is empty. I would expect to define the values lat and lng as null. So from my perspective, the correct model should look like this:

{
  "c8y_Position": {
    "lng": null,
    "lat": null
  }
}

Unable to upload Microservice dtm-ms-1016.0.0.561.zip

When I am trying to upload microservice dtm-ms-1016.0.0.561.zip (downloaded from latest release) , I am getting the following error : Microservice application name is incorrect: only lower case letters, digits and dashes allowed. Maximum length: 23.

image

Digital Twin aware widgets

I'd like a widget that uses the Digital twin asset model/hierarchy and combine that with measurement & event/alarm data.

Are there any existing widgets or sample code that support this?

Ideally I am wanting something that supports expand/collapse of the hierarchy, and filtering by asset type.

Otherwise I'm assuming I'd need to create a custom widget and use the API to query the asset model... correct?

Unable to add child device to an asset

I would like to add child devices to an asset but I'm unable to do so:

image

I would expect to see the show child button to be able to add child devices to an asset.

Information:
All my child devices are not marked as c8y_device because they don't need device management functionalities.
DTM version: 1015.0.0.318

DTM : Validation issues observed in DTM application

In DTM application, the below validation issues are observed :

  1. In Asset types page, when creating an asset type for "description" field, we can have an upper limit on the maximum characters allowed. This limit can be based on the total length of text displayed when user hovers over the description tab and the maximum text that can be displayed in the hover pop up.
  2. When creating an asset type, user has an option to create a custom property field as well. When clicked on create new custom property option, Save button is getting enabled even though required field is empty.
  3. Currently in Asset type page, the confirmation pop up and the success notification on deleting an asset type is different when we delete the asset type via check box and via delete icon. Uniformity has to be maintained.
  4. When creating a new asset type, In the notification pop up for Asset types, the key is being used instead of label.
  5. When creating an asset, the validation message displayed is blank, incase it violates the rules mentioned in Custom property. Validation messag has to be displayed.

No properties of a subasset are displayed

When adding a subasset to an asset you can navigate to the asset and see its properties (with the bug of not having the labels that is already reported) but if you click on a subasset you only see the devices assigned and no the properties of the subasset.

I think is a bug but i cannot label the issue.

DTM : Assets : In Assets page the total asset count at bottom is not getting displayed.

In DTM application the beow issues are observed :

  • The asset count displayed at the bottom is not correct. Instead of count, a variable gets displayed which is not the expected behavior.
  • In Assets page, the no filter label and the help icon for filters have to be removed as there is no filter option in this page.
  • Currently in all the screens where configure column is available, user is able to deselect all columns which should be restricted.
  • When creating an asset, for next button to be enabled, user has to click outside the form. This is the behavior for all forms.
  • If there are more than 20 Assets, then it does not get displayed on the grid. User is able to see the same in left pane though.

Improve Installation and role setup for DTM

Currently the README.md does not explain a couple of important steps for the installation of DTM:

  1. It is not explained when (if you want to use the CSV import feature) & how to install the microservice
  2. After installing the microservice, roles must be properly configured. How this can be done should also be documented (or better automated).
  3. The import feature might also fail if old asset type definitions are used. This should also be explained.
  4. For the localization feature, the Feature branding needs to be subscribed. It would be good to a) explain this in the README.md as well and b) only show the localization feature within DTM if the Feature branding is indeed subscribed.

Furthermore, it would be nice to improve the error messages within the UI so that users can resolve issues more easily. Currently, when trying to download a template you will always get the same error message: "Unable to download the template"

DTM: Icons of subasssets are not displayed

After the creation of an Asset you create some subassets and they are not displayed with their icons but with the folder normal icon.

I think that's a bug but i cannot add a label

DTM: Suggestion_Not show groups in Digital Twin

As a suggestion, when you are using Digital Twin Manager in a tenant that already has some folders, the folders are shown in the DTM and messes up the assets configured through DTM and the older assets. There should be an option to hide the folders that doesn't have an asset type defined in DTM

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    πŸ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. πŸ“ŠπŸ“ˆπŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❀️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.