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 business metrics. You can register source metrics in batches by uploading a template file.

Source metrics can be used for defining business metrics, and be queried through Common Data Service APIs when they are open for queried.


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

  • For creating new or updating the existing source metrics, including public and private source 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 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.

  • 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


  1. Select Source Data > Source 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

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

    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 Business Object Elements > Dimension Types to view the dimension type identifier.

    Open for inquiry

    openForQuery

    Optional

    Metrics that are open for query can be queried using Common Data Service APIs. Y: the metric is open for query. N: the metric is not open for query. Default is N.

    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.

  5. Click Upload in the pop-up window. Select the filled template file and click OK. When you register a private source metric, if the metric key in the file is the same as a registered public metric key, the system will use the private source metric when the duplicate key is referenced.

Synchronizing from Metric Management


Note

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


  1. Select Source Data > Source Metrics from the left navigation pane.

  2. In Private Metrics tab, select Import > From Metric Management.

  3. Select the business object type(s) associated with the metrics. Up to 10 business object types at a time.

  4. Select Synchronize to complete synchronization.

You can proceed to synchronize the metrics to business metrics. For more information, see Synchronizing Business Metrics from Metric Management.


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 source metric appears in the metric list. You can perform the following actions on it.

  • View the source metric: Search or filter the source 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.

    ../../_images/CDS-source-metrics-source.png
  • 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 Delete of the target metric. Deleted source metrics cannot be restored.