Asset models

Asset properties

Asset properties are the parameters that define an asset model. One or more asset properties are used to define an asset model. Asset properties are created in the Asset properties page.

When you open the DTM application, default properties are readily available for use. See Default properties to view the list of properties available.

To create an asset property

When you navigate to the Asset properties page following Configuration > Asset properties for the first time, there will be no asset properties present in the system except the default properties. See Default properties to view the list of properties available.

If you use a tenant which already has asset properties defined, you find the list of defined asset properties on the left. You see the selected asset property definition on the right.

To create an asset property, click Add asset property on the bottom left. Enter the required data in the form (see description below) and click Save.

Use the Export asset properties and Import asset properties feature to transfer asset properties between tenants. This is useful for replicating the asset properties in multiple tenants. By exporting and importing properties, you can ensure consistency and reduce the time and effort required for manual configuration. See To export asset properties and To import asset properties on how to export or import asset properties.

Asset properties have the following parameters:

Once you have defined all necessary asset properties for your project, you must define the asset models.

Asset property types

To further define the asset property you can select one of the six following options listed under Type:

Text

Select Text if the asset property value is a string, for example, a wind turbine manufacturer name. Enter a valid text.

If you select Text, the following fields appear:

• Min Length:

Enter the minimum length of the text that must be provided for this asset property during the asset creation. Any text below the minimum length is not accepted.

• Max Length:

Enter the maximum length of the text that must be provided for this asset property during the asset creation. Any text above the maximum length is not accepted.

• RegExp:

Enter a valid regular expression. During the asset creation, you must provide the asset property value, which adheres to the regular expression.

Example:

If the asset property is “Generator code” with the regular expression “^MCGEN[a-zA-Z0-9]*$”, all generator codes must start with the prefix “MCGEN”.

If you do not select any of the restrictions above, it is not applicable for the asset property during asset creation.

Default value

Assigns a default value to the asset property. If this field is left empty in the asset property and marked as required in the asset model, you must enter a value during the asset creation.

Example:

If the asset property is “Generator code” with a Min length of 8, a Max length of 20 and the RegExp defined as “^MCGEN[a-zA-Z0-9]*$”, the default value must fulfill all of these three criteria. If it does not, this results in a validation error. The respective field will be highlighted to modify its content to fit the criteria.

Number

For this type you must provide a numeric value for the asset creation, for example, the height of a wind turbine tower.

The type Number contains the following fields for additional information:

• Minimum:

If selected, enter a number in the field Minimum on the right. When you create the asset, the asset property value cannot be lower or less than provided in the field.

• Maximum:

If selected, enter a number in the field on the right. When you create the asset, the asset property value cannot exceed the Maximum provided.

• Default value: Assigns a default value to the asset property. If this field is left empty in the asset property and marked as required in the asset model, you must enter a value during the asset creation.

Example:

If the asset property is “Tower height” with a Minimum of 80 and a Maximum of 110, the Default value must be between 80 and 110.

Date Picker

If selected, you must select a date from the calendar displayed in the dialog window during the asset creation.

Example:

If “Installation date” is a property of the “Wind turbine” asset, then you must select the installation date of the wind turbine when creating the asset.

Enumeration

Select Enumeration to list several values that apply to this asset property.

If selected, a second field appears below. Here, enter all desired information separated by a comma.

During asset creation, these values appear as options in the dropdown menu. Select one of the options to initialize the asset property with that option.

Example:

If you create an asset property for a wind turbine “drivetrain type” and the type must be either Gearbox or Direct-drive, you must provide these options separated by a comma when creating the asset property.

Boolean

If selected, the presence of the asset property can either be true or false during the asset creation.

An asset with this asset property shows a checkbox. Selecting this checkbox sets the asset property value to true.

Example:

If you create an asset property called “Yaw system” to identify wind turbines that rotate towards the wind direction during upwind conditions, the asset property must be created with the type “Boolean”. When you create an asset for a wind turbine with a yaw system present, it is then initialized to “true”. If there is no yaw system present, the asset is initialized to “false”.

File upload

This option allows you to upload a file during the asset creation.

If selected, enter the allowed file types separated by a comma in the Allowed file types field. Provide the maximum file size for uploads in the Max file size in MB field. When you create an asset with this asset property, you can only upload files that adhere to the allowed file types with their file size not exceeding the set limit.

Example:

To upload the schematic diagram for a wind turbine, you name the asset property “Wind turbine schematic” and specify the file type of the schematic file. Then upload the respective file. Once the asset is created, you can view this file for future reference.

To edit an asset property

1. Select the desired asset property in the Asset properties to see all the details on the right of the screen.
2. Edit any content of the asset property.
3. Click Save to save your changes.
4. If this property is used by any asset model, in the resulting confirmation dialog, select Confirm to continue to save your changes.

To search and filter asset properties

1. Navigate to the Asset properties page.
2. Enter the desired name in the search field on the top left.
3. Click the search icon .

All asset properties matching the search values are displayed on the screen on the left. If the search entry does not match with any asset properties, you see a notification.

To delete an asset property

Select the respective asset property in the Asset properties and click Delete on the bottom right.

In the resulting confirmation dialog, click Confirm to continue.

Types of asset properties

There are two types of asset properties, both fulfill different requirements:

Simple asset property

A simple asset property consists of a single key value pair. This option is set by default when creating new asset properties.

In the Asset properties simple asset properties are listed with their type.

Example:

If the asset property is called “Tower height”, you use the key “tower_height” with the Default value of “70” (see image below).

Complex asset property

A complex asset property consists of multiple key value pairs, meaning, it contains a root object followed by one or more key value pairs. You can select the complex asset property option by switching on the toggle. If you switch on the toggle, you must define each key value pair as well as providing a Type for each pair.

In the Asset properties complex asset properties are listed with the label “Object”.

You see the preview of data model on the right side of properties section.

Example:

If the asset property is called “Gearbox specifications” with the key “gearbox_specifications”, then power, speed increasing ratio and weight are the multiple key value pairs defining the property “Gearbox specifications”. Switch on the Complex property toggle (see image below). Enter the required information for all key value pairs and click Save.

To export asset properties

Follow the steps below:

1. On the Asset properties page, click Export asset properties. In the resulting dialog box, you see the list of asset properties along with their description and type.
2. Select one or more desired asset properties and click Export.
3. The dialog closes and a JSON file named ‘Export-asset-properties.json’ downloads.

Use the downloaded file to import the asset properties into a DTM application on another tenant.

To import asset properties

To import asset properties into the DTM application, follow the steps below:

1. On the Asset properties page, click Import asset properties.
2. Upload the JSON file in the drop file area of the resulting dialog. The JSON file is the file containing exported asset properties from a DTM application on another tenant.
3. Click Next to preview the asset properties before importing them.
4. Click Import to import the asset properties.
5. Alternatively, click Back to go to previous step. Hover over the file name and click the Delete icon to remove the current file and upload a different one.
6. View newly imported asset properties in the Asset properties page.

Default properties

Characteristics

• Default properties are readily available when you open the application.
• Default properties cannot be deleted.
• Only selected fields within a default property are editable and the editable fields vary depending on the specific property.
• Default properties cannot be exported.

Location

The Location property enables you to assign location (latitude and longitude) to an asset. You can set the default values of the latitude and longitude by entering the corresponding values or alternatively using the map view.

To set the default values for the latitude and longitude using the map view, click Choose on Map at the end of the section. Click the full screen icon at the top right corner of the map to view it in full screen. Without values for latitude and longitude, the marker is hidden. To see the marker, click anywhere on the map. Click or drag the marker to the preferred position to select the default value for latitude and longitude.

Asset models

The asset model is a blueprint or template to create one or multiple assets. It defines how the asset will look like after it is created. An asset model consists of one or more asset properties and/or child asset models.

To get a quick start to use the DTM application, import pre-defined asset models from Asset model samples page. These asset models and associated properties are defined based on best practices. For details about how to import asset models from samples, see To import asset model samples.

To reach the Asset models page, navigate to Configuration > Asset models.

When you create an asset model, you see the details of this asset model in the overview.

In the overview you see the following four categories:

• Model name: Name of the asset model
• Key: Unique identifier for the asset model
• Description: Brief description of the asset model
• Child asset models: List of child asset models
• Asset properties: List of asset properties

Click Configure columns to configure the displayed columns.

Click Reload to reload the screen. The total number of asset models is displayed on the bottom left of the page.

Use the Export asset models and Import asset models feature to transfer asset models between tenants. This is useful for replicating the asset models in multiple tenants. By exporting and importing asset models, you can ensure consistency and reduce the time and effort required for manual configuration. See To export asset models and To import asset models on how to export or import asset models.

To create an asset model

Click Add asset model on the top right to create a new asset model. This opens the New Asset model page. Here, provide the following six parameters:

Once all required asset models are created, you can start creating assets using these asset models.

To select an icon

1. Click the Select icon button on the left.
2. In the following dialog window, search or filter icons by type or select an icon from the predefined list.
3. Select the desired icon.
4. Click Save.

To add a child asset model

1. Click Add child asset model to add a new child asset model.
2. In the dropdown select one or multiple allowed child asset models.
3. The selected child asset models are then displayed under Allowed child asset models with the checkbox Required on the right. If the asset model requires this child asset model, select the checkbox. By default, it is clear.
4. Click the remove icon next to the checkbox to remove the child asset model from the selected asset model.

If one or more child asset models are checked as required, an asset created with this asset model can have only subassets belonging to the selected child asset models.

Example:

If the asset model is “Rotor” and you select “Blade” as an allowed child asset model, then the newly created asset “AZ-43Y Rotor” can only have “Blade” assets as subassets.

To add an asset property to an asset model

1. Click Add asset property to add a new asset property to the asset model.
2. In the resulting dialog box, select one or multiple asset properties from the dropdown field. To search for specific asset properties, type the respective name in the dropdown field.
3. The selected asset properties are then displayed on the Asset properties segment with the checkbox Required on the right. If the asset model requires this asset property, select the checkbox. By default, it remains clear.
4. Reorder the asset properties via drag and drop.
5. To remove the asset property from the asset model, click the remove icon next to the checkbox.
6. Click Save to save your settings.

If there is no asset property meeting your requirements when you search, click New asset property. For more details on how to create a new asset property see To create an asset property.

Root asset model

To create a root asset model follow a bottom-up approach by defining all child asset models and asset properties in the provided templates first.

This root asset model can then be used to create an asset hierarchy, which then defines all the assets, subassets, asset properties and devices in the DTM application.

As a result you can use the asset hierarchy in other Cumulocity IoT applications, such as the Cumulocity IoT Cockpit.

To create an asset model for the entire hierarchy

1. Create all required asset properties.
2. Then create the asset models in a bottom-up approach, that is, all the child asset models are created first, followed by the root asset model at the end.
3. Create assets for the new asset hierarchy.

This approach, allows you to create the desired hierarchy including all asset models, child asset models and asset properties in one process.

To modify an asset model

1. Click the edit icon on the right side of each asset model.
2. Make your changes in the editor.
3. Click Save.
4. If this asset model is used by any asset, select Confirm in the resulting confirmation dialog to continue saving your changes.

To delete an asset model

There are two ways to delete an asset model:

Delete each asset model individually

On the Asset models page, hover over the desired asset model and click the delete icon on the right.

Delete the asset models in bulk

On the Asset models page, select the checkboxes next to the desired asset models. Click Delete to delete the selected asset models.

To sort asset models

To sort columns, hover over the respective column header and click the sort icon for an ascending or descending order.

To filter asset models

1. Use the filter option to filter asset models based on text in the respective asset group.
2. Hover over a column title for the filter icon to appear on the right.
3. Click the icon to filter the asset models in this column.
4. To clear all applied filters click Clear filters at the top.

To export asset models

To export asset models to add in another tenant, follow the steps below:

1. On the Asset models page, click Export asset models.
2. In the resulting dialog, you see the list of asset models. Initially, all the asset models are collapsed. Click the expand icon to the left of each asset model to view the next level of child asset models.
3. Select one or more desired asset models.
4. Click Export to export the selection.
5. The dialog window closes and a JSON file named ‘Export-asset-models.json’ downloads.

Use the downloaded file to import the asset models into the DTM application on another tenant.

To import asset models

To import asset models, follow the steps below:

1. On the Asset models page, click Import asset models.
2. Upload the JSON file in the drop file area of the resulting dialog. The JSON file is the file containing exported asset models from a DTM application on another tenant.
3. Click Next to preview the asset models. Initially, all the asset models are collapsed. Click the expand icon to the left of each asset model to view the next level of child asset models.
4. Click Import to import the asset models.
5. Alternatively, click Back to go to previous step. Hover over the file name and click the remove icon to remove the current file and upload a different one.
6. The newly imported asset models are listed on the Asset models page.

To import asset model samples

When you navigate to the Asset model samples page following Configuration > Asset models > Asset model samples, you see a list of samples with name, description and tags associated with it.

To view the sample, click the menu icon at the top right of sample name and click View. In the resulting dialog, you see a list of asset models. Initially, the asset models in the list are collapsed. Click the expand icon to the left of each asset model to view the complete hierarchy. Click Import to import the asset models in the sample.

Alternatively, to import the asset models in the sample without a preview, click the menu icon at the top right of sample name and then click Convert to asset model.