# Data mapping

Source: https://cumulocity.com/docs/historian-integration/data-mapping/
Release: Latest

Cumulocity maps historian data to its [domain model](https://cumulocity.com/docs/concepts/domain-model/) of devices, measurements, events, and alarms. The following table shows how the main historian concepts are represented with each integration method.

| Historian concept | OPC UA device gateway | AVEVA PI connector |
|---|---|---|
| Historian | A server child device of the gateway device. | The thin-edge.io device on which the connector runs. |
| Asset or tag group | A child device of the server, created for each root node that matches a device protocol. | Not mapped. All tags are reported on the thin-edge.io device. |
| Tag value | A measurement series, with the type, series, and unit defined in the device protocol. Alternatively an event, alarm, or custom action. | A measurement series. You can define an optional display name and unit per tag in the datapoints configuration. |
| Collection mode | Subscription, cyclic read, or manual read, as defined in the data reporting of the device protocol. | Polling of the PI Web API at the configured poll interval. |
| Timestamps | Source and server timestamps are kept in the `c8y_ua_DataValue` fragment of events. | The timestamp of the value in the PI Web API response is used as the measurement time. |
| Quality | Values with a `Bad` or `Uncertain` status code raise a WARNING alarm on the server device. The alarm is cleared when the status returns to `Good`. | Not evaluated. Values are sent to Cumulocity regardless of their PI quality status. |


## OPC UA device gateway

With the OPC UA device gateway, the structure of the historian's address space determines the device structure in Cumulocity. The browse paths of a device protocol are relative to a starting node. If no constraints are set, the gateway applies the protocol to every node, at any depth of the tree, whose subtree contains the configured browse paths. For each matching node, the gateway creates a child device of the server device and reports the mapped variables on it.

To reproduce an asset hierarchy of the historian, for example one device per pump or production line, define the browse paths relative to the nodes that represent the assets. Use the constraints of the device protocol to limit it to specific servers or starting node IDs. For details, see [Applying constraints](https://cumulocity.com/docs/device-integration/opcua/#applying-constraints).

The gateway converts numeric values outside the range of a Java long to double values in scientific notation. This can result in a less precise, rounded value.

## AVEVA PI connector

The AVEVA PI connector reads the current value of each configured PI tag at every poll interval and sends it as a measurement to thin-edge.io. You list the tags by their PI tag name in the `datapoints.json` configuration file. Optionally, each entry can define a display name and a unit:

```json
[
  {
    "tag": "78FIQ301.A",
    "name": "Flow Rate - Inlet 301",
    "unit": "m³/h"
  }
]
```


> **Info:**
> The poll interval determines the time resolution of the data in Cumulocity. Values that change between two polls are not transferred.
