Registering a Source Metric¶

Registering a source metric is the process of interpreting the field of the data source API. Only by registering source metrics in Common Data Service can these metrics be referenced in the expressions of unified metrics. You can register source metrics in batches by uploading a template file.

Note

Source metrics can only be used for defining unified metrics, and cannot be queried through Common Data Service APIs.

Prerequisites¶

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

Procedure¶

Select Meta Data > Source 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

Field Key

fieldKey

Required

The identifier of the field provided by the data source API, which needs to be unique under the same object type in the same data source within the same (public/private) effective scope.

Field Chinese/English/Japanese/Spanish Name

fieldNameZh/En/Ja/Es

English and Chinese names are required

The field name in different languages provided by the data source API.

API Key

srcKey

Required

The key of the data source API. You can go to Data Sources to view the API key.

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.

Data Type

dataType

Required

The data type of the metric. 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.

MDM Aggregation Methods

aggMethod

Optional

Specify how the data is aggregated when multiple objects are queried. 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.

Interval

interval

Optional

The query intervals supported by the 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.

Related Point

accumulativePoint

Optional

When querying a cumulative metric such as TD/MTD/YTD/BOL metric, Common Data Service adds the historical data of the metric to the current day data, where the current day data is obtained by querying Accumulative Points source API based on the related point.

Unit

units

Optional

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

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.

Note

The “Org ID”, “Org Name”, “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.

Results¶

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

Edit the source metric: Click Export, modify the template file as required, and import the modified file. The metrics with the same field keys will overwrite the existing metrics, and the metrics with different field keys will be added.
Delete the source metric: Click Delete of the target metric. Deleted source metrics cannot be restored.

Field Name	Identifier	Required/Optional	Description
Field Key	fieldKey	Required	The identifier of the field provided by the data source API, which needs to be unique under the same object type in the same data source within the same (public/private) effective scope.
Field Chinese/English/Japanese/Spanish Name	fieldNameZh/En/Ja/Es	English and Chinese names are required	The field name in different languages provided by the data source API.
API Key	srcKey	Required	The key of the data source API. You can go to Data Sources to view the API key.
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.
Data Type	dataType	Required	The data type of the metric. 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.
MDM Aggregation Methods	aggMethod	Optional	Specify how the data is aggregated when multiple objects are queried. 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.
Interval	interval	Optional	The query intervals supported by the 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.
Related Point	accumulativePoint	Optional	When querying a cumulative metric such as TD/MTD/YTD/BOL metric, Common Data Service adds the historical data of the metric to the current day data, where the current day data is obtained by querying Accumulative Points source API based on the related point.
Unit	units	Optional	Fill in the unit of the metric data by referring to EnOS Built-in Units.
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.