Registering a Unified Metric¶

Registering unified metrics is the process of interpreting the metrics exposed externally by Common Data Service APIs. Only by registering unified metrics in Common Data Service can these metrics be queried through Common Data Service APIs. You can register unified metrics in batches by uploading a template file.

Note

Unified metrics are the query objects of Common Data Service APIs directly facing data consumers.

Prerequisites¶

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

Procedure¶

Select Meta Data > Unified 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 Unified Metric Keys.
Metric Chinese/English/Japanese/Spanish Name	metricNameZh/En/Ja/Es	English and Chinese names are required	The metric name in different languages.
Object Type Identifier	mdmType	Required	The identifier of the asset type that the metric belongs to. You can go to Meta Data > Object Types to view the object type identifier.
Object Type Name	mdmTypeName	Optional	The name of the asset type that the metric belongs to. You can go to Meta Data > 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. 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 Registering a Virtual Metric.
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 Meta Data > 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.

Results¶

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

Edit the unified 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 unified metric: Click Delete of the target metric. Deleted metrics cannot be restored.