Registering a Business Metric¶

Registering business metrics is the process of interpreting the metrics exposed externally by Common Data Service APIs. Only by registering business metrics in Common Data Service can these metrics be queried through Common Data Service APIs.

Business metrics are the query objects of Common Data Service APIs that are directly exposed to data consumers. The metric expression defines the related source metrics and the runtime calculation logic applied during the metric query.

Common Data Service is oriented to different usage scenarios and provides the following methods to register business metrics:

For creating new or updating the existing business metrics, including public and private business metrics, you can complete the registration by Importing Files.
If you have registered raw metrics and defined derived metrics and compound metrics, you can Synchronize Metrics from Metric Management to Common Data Service to reduce the workload of mapping, debugging, and importing.

Prerequisites¶

You have been assigned the required asset permission and operation permission, and a menu group containing the Metrics menu. If not assigned, contact the application administrator.
If you need to synchronize metrics from Metric Management, ensure that you have been assigned the required operation permission of metric synchronization. If not assigned, contact the application administrator.

Importing Files ¶

Select Business Object Elements > Biz Metrics from the left navigation pane.
Select the Public Metrics or Private Metrics tab according to the effective scope of the target metric, and click Import. For more information about the difference between public and private metrics, see Public/Private Metrics.
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
Metric Key	metricKey	Required	The identifier of the metric, which needs to be unique under the same object type within the same (public/private) effective scope. Use this format: `<OrganizationPrefix>.<MetricName><ComparisonIdentifier>:<TimeDimensionSuffix>`. For more information, see Naming Rules of Business Metric Keys.
Standard Key	standardKey	Optional	The standard identifier of the metric, which needs to be unique among all metric keys and standard keys within the same (public/private) effective scope. Standard keys and standard names are used to define metrics that are not named according to rules, ensuring that all metrics can be queried by Common Data Service.
Metric Chinese/English/Japanese/Spanish Name	metricNameZh/En/Ja/Es	English and Chinese names are required	The metric name in different languages.
Standard Name	standardName	Optional	The standard metric name in different languages. Standard keys and standard names are used to define metrics that are not named according to rules, ensuring that all metrics can be queried by Common Data Service.
Object Type Identifier	mdmType	Required	The identifier of the object type that the metric 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 metric belongs to. You can go to Business Object Types to view the object type name.
Interval	interval	Optional	The query intervals supported by the metric, which needs to be consistent with the interval of the corresponding source metric. Use these intervals: L (latest data), 15m (15 minutes), 30m (30 minutes), H (hour), D (day), W (week), M (month), Q (quarter), Y (year), T (total). Separate multiple intervals by commas, for example, D,W,M,Y,T.
MDM Aggregation Methods	mdmAggMethods	Optional	Specify how the data is aggregated when multiple objects are queried. If this field is blank, Common Data Service aggregates the source metrics first and then calculate the data based on the expression. For example, when you pass a group of solar site IDs to query the aggregated Production metric, Common Data Service returns the sum of the production data of all solar sites in the group. Use these aggregation methods: sum, avg, max, min.
Is Calculated	isCalculated	Optional	Fill in `N` if the metric is a passthrough metric and fill in `Y` if the metric is a virtual metric (you can define metric expression in the Expression column). For more information about the difference between passthrough and virtual metrics, see Passthrough/Virtual Metrics.
Expression	expression	Required	For a passthrough metric, use this format `SourceMetricAPIKey@@SourceMetricFieldKey`, for example, `WindAPI@@SENL_METER_REPORT.APREVERSE_DELTA`. For a virtual metric, fill in an expression based on Spring Expression Language. For more information, see Virtual Metric Configuration Rules.
Enumerate	enumerate	Optional	If the metric is enumerated, describe the supported enumeration values.
Unit	units	Optional	Fill in the unit of the metric data by referring to EnOS Built-in Units.
Data Type	dataType	Required	The data type of the metric. Use these data types: Int, Double, String.
Is Sorted	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.
Standard Type	standardType	Optional	Fill in `standard` or `illegal` to indicate if the metric is compliance. A non-compliant (illegal) metric means its identifier has not been standardized, and it is recommended to use a compliant (standard) metric for data consumption.
Primary Metric	passMetric	Optional	If the metric is a cumulative metric, fill in the identifier of the corresponding primary metric. Leave this field blank if the metric is a primary metric.
Cumulative Metric Dimension	period	Optional	For a cumulative metric, fill in its time dimension identifier such as L, TD, and MTD. For more information about time dimension identifiers, see Registering a Cumulative Metric.
Metric Description in Chinese/English/Japanese/Spanish	metricDescriptionZh/En/Ja/Es	Optional	The metric description in different languages.
Aggregation Dimension	dimensions	Optional	The identifier of the supported dimension to aggregate the metric data. Separate multiple dimensions by commas. For example, if the `Yield` metric of solar sites supports aggregation by site type or inverter model, Common Data Service returns query results by site type or inverter model. You can go to Business Object Elements > Dimension Types to view the dimension type identifier.
Application Dependency	applicationDependency	Optional	The application that the metric depends on. Separate multiple applications by commas.
Application Version Dependency	applicationVersionDependency	Optional	The application version that the metric 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. “Related Source API” is filled based on the data source associated with the source metric referenced in the “Expression” column, and multiple data sources are separated by commas.

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

Synchronizing from Metric Management¶

Note

Supports synchronizing derived metrics and compound metrics from Metric Management. Before synchronizing, ensure that:

The metrics have been created and the required attributes have been added to the metrics. For more information, see Synchronizing Derived Metrics to Common Data Service and Synchronizing Compound Metrics to Common Data Service.

The data source of OLAP 2.3 protocol has been registered. For more information, see Registering a Data Source.

You have been assigned the required operation permission of metric synchronization. If not assigned, contact the application administrator.

Select Biz Object Element > Biz Metrics from the left navigation pane.
In Private Metrics tab, select Import > From Metric Management.
Select the business object type(s) associated with the metrics. Up to 10 business object types at a time.
Select Synchronize to synchronize the derived metrics or the compound metrics to the source metrics in Common Data Service.
You can proceed to synchronize the metrics to the business metrics in Common Data Service.

The metrics synchronized from Metric Management are all private metrics, and the identifiers of private metrics cannot be duplicated with the existing private source and business metric identifiers in the current OU.

The table below shows the results of duplicate identifier checks between the newly added metrics from Metric Management and the existing metrics within the current OU:

New Metric Type	New Metric Source	Existing Metric Type	Existing Metric Source	Result of Duplicate Identifier
Public	Common Data Service	Private	Metric Management	No impact
Private	Common Data Service	Private	Metric Management	All information of the existing metric with the same identifier will be overwritten.
Private	Metric Management	Public	Common Data Service	No impact
Private	Metric Management	Public	Metric Management	No impact
Private	Metric Management	Private	Common Data Service	The synchronization of the new metric with the same identifier will fail.
Private	Metric Management	Private	Metric Management	All information of the existing metric with the same identifier will be overwritten.

Results¶

Once registered, the metric appears in the metric list. You can perform the following actions on it.

View the business metric: Search or filter the business metrics. You can see the source of metrics in Source column. Common Data Service means the metric is synchronized from Common Data Service. Metric Management means the metric is synchronized from Metric Management.
Edit the business metric: Click Export, modify the template file as required, and import the modified file. The metrics with the same keys will overwrite the existing metrics, and the metrics with different keys will be added.
Delete the business metric: Click Delete of the target metric. Deleted metrics cannot be restored.

Note

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