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


  1. Select Meta Data > Unified Metrics from the left navigation pane.

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

  3. Click Download in the pop-up window and choose to download an Excel and a JSON template file.

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

  5. 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 Delete of the target metric. Deleted metrics cannot be restored.