Key Concepts¶

The user and permission system of Common Data Service is inherited from EnOS Application Portal. Before you start, you need to learn about the key concepts of EnOS Application Portal.

Below are the key concepts of Common Data Service.

Business Object Type¶

A business object type (object type or mdm type) can be referenced by a metric, a measurement point, or an attribute to define the asset type it belongs to. Object types include multiple levels, for example, site types (such as wind farm and building), device types (such as meter and energy storage system), and component types (such as battery bank and battery rack).

Object types can be divided into the following types according to their effective scope.

Public object types take effect for all OUs in the current environment.
Private object types take effect for the current OU only.

After you map the business object type with an EnOS model, by default all assets that are onboarded under the model and its child models will be mapped with the business object type. If a child model is mapped to another business object type, the assets onboarded under the child model will be mapped with the business object type mapped with the child model.

For more information, see Registering a Business Object Type.

Business Object Element¶

Business object element is a general term for business-related data objects. The business object elements that can be registered in Common Data Service include virtual attributes, virtual measurement points, business metrics, record types, and dimension types.

Data Source¶

Data sources are the basis for querying data using Common Data Service. Data providers need to standardize the data source APIs according to specifications and register the APIs in Common Data Service, so that data consumers can query the relevant data using Common Data Service.

Data sources can be divided into the following types according to their effective scope.

Public data sources take effect for all OUs.
Private data sources take effect for the current OU only.

For more information, see Registering a Data Source.

(Virtual) Attribute¶

An attribute describes the static information of an asset and is defined on the EnOS model. For example, the name and model of an inverter, the latitude and longitude of a solar site. For more information, see Device Modeling.

A virtual attribute is not the attribute defined on the EnOS model, but a non-model attribute defined by an expression calculated based on one or more parameters. The parameters can be attributes from the EnOS model, attributes provided by the registered data source APIs, and constants. For example, Common Data Service can define a virtual attribute Number of Running Inverters which is calculated by number of normally running inverters + number of running inverters in low performance + number of running inverters with limited power. For more information, see Registering a Virtual Attribute.

Virtual attributes can be divided into the following types according to their effective scope.

Public attributes take effect for all OUs in the current environment.
Private attributes take effect for the current OU only.

Common Data Service can be used to query both EnOS model attributes and virtual attributes.

(Virtual) Measurement Point¶

A measurement point describes the runtime state of an asset and is defined on the EnOS model. For example, temperature, pressure, current, and voltage. For more information, see Device Modeling.

A virtual measurement point is not the point defined on the EnOS model, but a non-model point defined by an expression calculated based on one or more parameters. The parameters can be model points, constants, and attributes. For example, Common Data Service can define a virtual point Power Ratio which is calculated by ActivePower/Capacity. For more information, see Registering a Virtual Measurement Point.

Virtual measurement points can be divided into the following types according to their effective scope.

Public measurement points take effect for all OUs in the current environment.
Private measurement points take effect for the current OU only.

Common Data Service can be used to query both EnOS model points and virtual points.

Metric¶

Metrics are statistical values that measure the overall characteristics of a target, and are numerical indicators to reflect the business status of a certain business activity. For example, production, production loss, and failure rate.

Metrics in Common Data Service can be divided into public and private metrics according to the effective scope and source and business metrics according to the usage.

Public/Private Metric¶

Metrics can be divided into the following types according to their effective scope.

Public metrics take effect for all OUs in the current environment.
Private metrics take effect for the current OU only.

If the metric keys of a private metric and a public metric are duplicated, Common Data Service returns the private metric when the metric key is used for data query.

Business/Source Metric¶

Metrics can be divided into the following types according to their usage.

Source metrics: the metrics provided by the data source APIs. Source metrics can be used for defining business metrics, and can also be queried through Common Data Service APIs when they are open queried. For more information, see Registering a Source Metric.
Business metrics: the metrics exposed externally by Common Data Service APIs. Business metrics are the query objects of Common Data Service APIs directly facing data consumers. For more information, see Registering a Business Metric.

Primary/Cumulative Metric¶

Common Data Service can quickly query some metrics for a fixed time period, such as the current day, the current month, and the current year. For example, based on the Yield metric, Common Data Service can register the Yield:TD metric, which returns the yield hours between 0:00 and the current time point.

Business metrics can be divided into the following types according to whether they support fixed query period:

Primary metrics: general metrics which require users to specify the time range when querying data in a certain period.
Cumulative metrics: sub-metrics of general metrics whose metric keys include time dimension identifiers such as TD (current day), MTD (current month), and YTD (current year). Users do not need to specify the time range when querying cumulative metrics. For more information, see Registering a Cumulative Metric.

In the Business Object Elements > Biz Metrics menu, all cumulative metrics are automatically mounted under the associated primary metrics. Click the plus icon in front of a primary metric to view all cumulative metrics associated with it.

Passthrough/Virtual Metric¶

In simple scenarios, there is a one-to-one correspondence between source metrics and business metrics. But in complex scenarios, business metrics are the extension of source metrics.

Business metrics are divided into the following types according to their relationship with source metrics:

Passthrough metrics: the business metrics that correspond one-to-one with source metrics.
Virtual metrics: also known as calculated metrics, the business metrics calculated based on source metrics and expressions. There is not a one-to-one correspondence between virtual metrics and source metrics. The expressions of virtual metrics can contain such logic as four basic arithmetic operations and conditional statements, and the expression results are not directly provided by data sources, but returned by Common Data Service calculating the expressions in real time for each query. Such metrics are not stored in Common Data Service and therefore called “virtual metrics”. For more information, see Registering a Virtual Metric.

Comparative Metric¶

As a special type of virtual metric, a comparative metric is a new metric obtained by Common Data Service converting the time domain based on the comparison identifier in the metric expression.

A period-over-period metric refers to the last statistical period connected with the original statistical period. For example, for the Production(Last Period) metric, if the query period is April 1 ~ April 5, Common Data Service returns the production from March 27 to March 31.
A year-over-year metric refers to the same period last year, and a month-over-year metric refers to the same period last month. For example, for the Production(Same Period Last Year) metric and the Production(Same Period Last Month) metric, if the query period is April 1 to April 5, 2022, Common Data Service respectively returns the production from April 1 to April 5, 2021 and the production from March 1 to March 5, 2022.

For more information, see Registering a Comparative Metric.

Record Type¶

A record type is the type of non-time-series fact data such as alarm, warning, service request, and work order. Different from time-series data such as metrics and measurement points, record types have no query interval, and do not support aggregation calculation and virtual data configuration.

Record types can be divided into the following types according to their effective scope.

Public record types take effect for all OUs in the current environment.
Private record types take effect for the current OU only.

For more information, see Registering a Record Type.

Dimension Type¶

A dimension type can be referenced by a business metric to define its supported aggregation dimension such as asset type, province, and manufacturer.

Dimension types can be divided into the following types according to their effective scope.

Public dimension types take effect for all OUs in the current environment.
Private dimension types take effect for the current OU only.

For more information, see Registering a Dimension Type.

Basic Information¶

Basic information is the shared data related to business entities. The basic information in Common Data Service is mainly used to predefine the standard business information used in metric templates such as metric type and subject.

Basic information can be divided into the following types according to their effective scope.

Public basic information take effect for all OUs in the current environment.
Private basic information take effect for the current OU only.

For more information, see Managing Basic Information.

Metric Template¶

A metric template summarizes the basic information and the extended information (such as metric identifier, name, query interval, aggregation method, and unit) of a metric associated with a specific object type. Metric templates can be applied to typical scenarios like synchronizing and sharing metric data. For example, you can use metric templates to periodically synchronize metrics in Common Data Service to other data management services to ensure data standardization and consistency.

Metric templates can be divided into the following types according to their effective scope.

Public metric templates take effect for all OUs in the current environment.
Private metric templates take effect for the current OU only.

For more information, see Managing Metric Templates.