Registering a Virtual Attribute¶

A virtual attribute is calculated based on one or more parameters, including model attributes, attributes provided by data sources, and constants.

Virtual attributes can be flexibly applied to scenarios where existing attributes cannot meet the requirements. For example, when you need to query the installed capacity of distributed sites in a region, you can configure a virtual attribute Installed Capacity of Distributed Sites with the expression denoting the attribute value is the installed capacity if the site is distributed, otherwise it is 0. Based on this virtual attribute, Common Data Service can query the installed capacity of distributed sites in the region by aggregating the site data to the region data.

Only by registering virtual attributes in Common Data Service can these attributes be queried through Common Data Service APIs. You can register virtual attributes in batches by uploading a template file.

Note

A virtual attribute is not saved in the model, nor does it require storage. It is calculated in real time by Common Data Service during query. Therefore, virtual attributes can only be used in lightweight calculation scenarios.
Common Data Service supports querying virtual attributes, as well as the attributes on the models mapped with registered object types.

Prerequisites¶

You need to be assigned the required asset permission and operation permission, and a menu group containing the Virtual Attributes menu. If not assigned, contact the application administrator.

Procedure¶

Select Business Object Elements > Virtual Attributes from the left navigation pane.
Select the Public Attributes or Private Attributes tab according to the effective scope of the target attribute, and click Import. For more information about the difference between public and private attributes, see Public/Private Attributes.
Click Download in the pop-up window and choose to download an Excel and a JSON template file.

Enter the following information in the template file.

Field Name

Identifier

Required/Optional

Description

Attribute

attribute

Required

The identifier of the attribute, which needs to be unique under the same object type within the same (public/private) effective scope.

Attribute Chinese/English/Japanese/Spanish Name

zh_CN/en_US/ja_JP/es_ES

English and Chinese names are required

The attribute name in different languages.

Object Type Identifier

mdmType

Required

The identifier of the object type that the attribute belongs to. You can go to Business Object Types to view the object type identifier.

Object Type Name

mdmTypeName

Optional

The name of the object type that the attribute belongs to. You can go to Business Object Types to view the object type name.

MDM Aggregation Methods

mdmAggMethods

Optional

Specify how the data is aggregated when multiple objects are queried. Use these aggregation methods: sum, avg, max, min.

Expression

expression

Required

The format of the expression differs depending on how the attribute is generated. See Virtual Attribute Expression Examples.

foreignKey

foreignKey

Optional

If the attribute data is returned based on a dimension table, fill in the identifier of the model attribute used to query the dimension table.

Is I18n Supported

extract18n

Optional

Fill in Y if internationalization is supported in the query results and fill in N if not.

Enumerate

enumerate

Optional

If the attribute is enumerated, describe the supported enumeration values.

Unit

units

Optional

Fill in the unit of the attribute data by referring to EnOS Built-in Units.

Data Type

dataType

Required

The data type of the attribute. Use these data types: Int, Double, String.

Is Sortable

sortable

Optional

Fill in Y if the query results can be sorted in ascending/descending order and fill in N if not.

Filters

filters

Optional

Specify how the data in the query results is filtered. Use these filters: in, ==, !=, >, >=, <, <=. Separate multiple filters by commas, for example, ==,in.

Application Dependency

applicationDependency

Optional

The application that the attribute depends on. Separate multiple applications by commas.

Application Version Dependency

applicationVersionDependency

Optional

The application version that the attribute depends on. Separate multiple versions by commas.

Note

The “Org ID”, “Org Name”, “Related Source API”, “Updated On”, and “Updated By” fields in the template file can be left blank and will be filled by the system after upload.

Click Upload in the pop-up window. Select the filled template file and click OK. When you register a private attribute, if the identifier in the file is the same as a registered public attribute identifier, the system will return the private attribute when the duplicate identifier is passed in to query the attribute.

Virtual Attribute Expression Examples ¶

A virtual attribute can be generated in the following methods.

Configure an expression based on model attributes.
Associate the attribute with a dimension table.

Both of the above methods require configuring expressions. The table below lists the typical examples of attribute expressions.

Attribute Generation Method	Expression Syntax	Attribute Example	Expression Example	Expression Description
Configuring an expression based on model attributes	Use this format to reference a model attribute: Attribute[‘ModelAttributeIdentifier’]	Safe Operation Days	#{(T(System).currentTimeMillis() - new java.text.SimpleDateFormat(‘yyyy-MM-dd’).parse(Attribute[‘safeOpStartDay’]).getTime()) / (24 * 60 * 60 * 1000)}	Subtract the safe operation start time from the current system time and convert the result into days
Associating with a dimension table	Use this format to associate a dimension table: #{Dimension[‘DataSourceAPIKey@@DimensionTableIdentifier@@AttributeField’]}	Province	#{Dimension[‘SolarAPI@@siteAttributes@@province_name_i18n’]}	Use the province_name_i18n field in the siteAttributes dimension table provided by the Solar API as the Province attribute

Results¶

Once registered, the attribute appears in the attribute list. You can view its details and perform the following actions on it.

Edit the virtual attribute: Click Export, modify the template file as required, and import the modified file. The attributes with the same identifiers will overwrite the existing attributes, and the attributes with different identifiers will be added.
Delete the virtual attribute: Click Delete of the target attribute. Deleted attributes cannot be restored.

Note

If the business object type that the attribute belongs to has been deleted, you need to contact the system administrator to delete this attribute.

Field Name	Identifier	Required/Optional	Description
Attribute	attribute	Required	The identifier of the attribute, which needs to be unique under the same object type within the same (public/private) effective scope.
Attribute Chinese/English/Japanese/Spanish Name	zh_CN/en_US/ja_JP/es_ES	English and Chinese names are required	The attribute name in different languages.
Object Type Identifier	mdmType	Required	The identifier of the object type that the attribute belongs to. You can go to Business Object Types to view the object type identifier.
Object Type Name	mdmTypeName	Optional	The name of the object type that the attribute belongs to. You can go to Business Object Types to view the object type name.
MDM Aggregation Methods	mdmAggMethods	Optional	Specify how the data is aggregated when multiple objects are queried. Use these aggregation methods: sum, avg, max, min.
Expression	expression	Required	The format of the expression differs depending on how the attribute is generated. See Virtual Attribute Expression Examples.
foreignKey	foreignKey	Optional	If the attribute data is returned based on a dimension table, fill in the identifier of the model attribute used to query the dimension table.
Is I18n Supported	extract18n	Optional	Fill in `Y` if internationalization is supported in the query results and fill in `N` if not.
Enumerate	enumerate	Optional	If the attribute is enumerated, describe the supported enumeration values.
Unit	units	Optional	Fill in the unit of the attribute data by referring to EnOS Built-in Units.
Data Type	dataType	Required	The data type of the attribute. Use these data types: Int, Double, String.
Is Sortable	sortable	Optional	Fill in `Y` if the query results can be sorted in ascending/descending order and fill in `N` if not.
Filters	filters	Optional	Specify how the data in the query results is filtered. Use these filters: in, ==, !=, >, >=, <, <=. Separate multiple filters by commas, for example, ==,in.
Application Dependency	applicationDependency	Optional	The application that the attribute depends on. Separate multiple applications by commas.
Application Version Dependency	applicationVersionDependency	Optional	The application version that the attribute depends on. Separate multiple versions by commas.