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.

Requirements

ROLES & PERMISSIONS

  • To add/update/delete/import asset properties: CREATE/ADMIN permission for permission type “Inventory”

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.

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.

Create a new asset property

Asset properties have the following parameters:

Field Description Mandatory / Optional
Label Refers to the name of the asset property. The asset property is further addressed using the information provided here. Mandatory
Key Used to uniquely identify and store the asset property in the DTM application.

Note that the key is automatically generated based on the label. You can modify the automatically generated key to suit to your needs only during asset property creation. You cannot edit the key after the asset property is created.
Mandatory
Description Provides a brief description of the asset property. Optional
Complex property toggle Used to create a complex asset property, that contains one or multiple key-value pairs. By default, the toggle is switched off. Optional
Type Defines the type of the asset property. It can be any of the following categories – Text, Number, File upload, Date picker, Enumeration, or Boolean. Mandatory
Default value Defines the default value for the parameter. You can modify the content when creating an asset using this asset property. Optional
Info
The Default value field is only shown if the selected Type is either “Text” or “Number”.

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:

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.

If not selected, no minimum length criteria is set for this asset property during the asset creation.

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.

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 have to start with the prefix “MCGEN”.

Default value

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

Info
The default value has to adhere to all validations provided beforehand. If you selected a property of the type “Text”, you can set the Min length, Max length and/or RegExp and the default value must fulfill all set validations.

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:

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

Info
If you entered a default value beforehand, it needs to be greater than or equal to the minimum provided. By default, this box is not selected.

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.

Info
If you entered a default value beforehand, it needs to be lesser than or equal to the Maximum entered here. By default, this box is not checked.
Info
If the Minimum and/or Maximum is checked, the given Default value is validated against one or both of these values.

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 have to provide these options separated by a comma when creating the asset property.

Asset property enumeration

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.

Requirements

ROLES & PERMISSIONS

  • To add/update file: CREATE/ADMIN permission for permission type “Inventory”.

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.

Info
If there is a file size limit set for the tenant, you see the limit along with the field name for Max file size in MB.
During the bulk import, the file size validation is skipped as the file is already uploaded to the tenant.

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.

Info
If the asset property you want to delete is part of an existing asset or an asset model, you see an error notification and the asset property is not deleted.

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).

Simple asset property

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.

Complex asset property

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

Asset models overview

In the overview you see the following four categories:

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.

Requirements

ROLES & PERMISSIONS

  • To add/update/delete/import asset models: CREATE/ADMIN permission for permission type “Inventory”

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:

Field Description Mandatory / Optional
Label Refers to the name of the asset model.
This name is used for the asset model throughout the application.
Mandatory
Key Used to uniquely identify and store the asset model in the DTM application.

Note that the key is automatically generated based on the label. You can modify the automatically generated key to suit to your needs only during the asset model creation. You cannot edit the key after the asset model is created.
Mandatory
Description Provides a brief description of the asset model. Optional
Icon Displayed next to the label for each asset model.
By default, no icon is selected.
Optional
Child asset models Restricts the asset assignment to the defined models.
By default, no subassets are allowed if this field is not set.
Optional
Asset properties Parameters that define an asset model.
By default, no asset properties are selected.
Optional

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 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.
Info
If you do not select and check a child asset model, then the asset cannot have any subassets.

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.
Info
If there are any validation errors for a field, it is highlighted in red with a validation error message asking you to fill in the required information. Enter the necessary information and click Save.

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 Asset property > 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 OEE or the Cumulocity IoT Machine Portal.

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.