Opinum Standard Data File

One way to upload data on Opinum Data Hub, is to create a CSV File containing your data and upload it on your storage page or through the Opinum FTP server.

With the correct trigger configured, the system will process your file and send your data on the related Source you have created in Opinumb.

In this section, we are going to describe how to create such a file. An overview of Opinum data structure is also presented to clarify the way the StandardDataFile.csv works.

Download

Download the template file: Standard Data File

Opinum data structure

Data in Opinum are stored as timeseries in a database. A data point is defined by three parameters:

  • Datetime: ISO 8601
  • Value: Float
  • VariableId : Int

VariableId is an internal ID referring to a variable. A variable represents a type of measurement from a specific meter called “Source” in the Opinum structure.

Variables are defined by a name, technical parameters such as data ingestion frequency and data aggregation type and a MappingConfig field, used to link the data to the right variable. Each Variable is linked to one Source.

Sources represent the meters and are defined by an internal Id (SourceId), a name, an energy type and sets of technical parameters used to identify a meter such as SerialNumber, MeterNumber, EanNumber or SourceName. The choice of values for these parameters may differ from one case to another but it is critical that at least one of these parameters should uniquely apply to a specific meter, for data mapping purposes. This is explained in the next section.

Data mapping

The data mapping in Opinum works following these steps:

  1. Identify the source

The unique meter is found in your Opinum account by querying on one of these parameters:

  • SourceId [automatically generated by Opinum at the creation of the source – can’t be edited]
  • SerialNumber
  • MeterNumber
  • EanNumber

Where to find these parameters? Go on the Sources Page, click on the name of the source for which you want to display these parameters. A pop-up window opens and displays the general information of your source:

Source_Identifiers

There is a priority order between those parameters. So, even if several of those parameters are set in the upload file, the system will only base its query on the prior identifier. The order applied is the following :

  • SourceId
  • EanNumber
  • SerialNumber
  • SourceName
  • MeterNumber

For example, if the EanNumber and the serialNumber are set in the upload file, only the Ean will be taken in consideration.

Please, note that if several sources match the identifiers, the system will select the first one found and will upload the data on the first variable matching the variable identifiers given (Id or mappingConfig) related to this source.

2.Identify the variable

The system inspects the variable linked to the previously found meter and selects the one with the specified MappingConfig parameter.

Where to find the variableId and the MappingConfig? Go on the Sources Page, click on the name of the source for which you want to display the variables. A pop-up window opens and display the general information of your source. Click on the tab ‘Variables’.

For each variable, you can click on the icon ‘settings’ which allows you to see the variable Id [automatically generated by Opinum at the creation of the variable – can’t be edited] and enter a MappingConfig.

Variable_Identifiers

Standard Data File

File name

The file name must start with « Opisense StandardDataFile ». The file is identified as being a standard upload file by finding this key string in the file name. It can be followed by specific information such as date or client reference.

Content

The StandardDataFile.csv must contain the following information:

  • At least one Source identification parameter:

    • SourceId
    • SerialNumber
    • MeterNumber
    • EanNumber
    • SourceName

  • MappingConfig parameter

  • Timestamp

  • Value

Tip

Note that the VariableId can be used in replacement of 1. and 2, in which case the variable is automatically identified from this unique technical identifier.

Format

The StandardDataFile.csv must respect the following requirements.

File format

CSV coma separated.

Headers

Headers must be specified respecting the following syntax:

  • date
  • value
  • meternumber
  • source_id
  • source_serialNumber
  • source_ean
  • source_name
  • mapping_config
  • variable_id
Warning

Every header must be entered between double quotes (“) The column order is not important. Only the columns corresponding with used parameters are mandatory.

Body

Each line of the file corresponds to one variable, one timestamp and one value. Values linked to different variables or timestamps can be filled in the same file, on different lines.

Column Format
date ISO 8601 (yyyy-mm-ddTHH:mm:ssZ)
value Decimal (separator: period)
meternumber String
source_id Integer
source_serialnumber String
source_ean String
source_name String
mapping_config String
variable_id Integer
Warning

Every value must be entered between double quotes (“)

Example

Context

One electricity meter with two measurements:

  • Day Index
  • Night Index

Opinum structure

  • Source EanNumber: 54141234567891011
  • Two Variables with MappingConfig: *IndexDay
    • IndexNight

Opinum StandardDataFile content

Headers

  • date
  • value
  • source_ean
  • mapping_config

Headers

Body

Body

Create the Standard Data File in Excel

In case you use Excel to create your Standard Data File, we highly suggest you to read this section where you will find some tips and advices : Standard Data File with Excel

Send data to Opinum

Once your own Opisense Standard Data file is ready, you can upload it in the Storage or automatically send it to Opinum FTP.

In both cases, you need first to define a trigger.

Tip

Learn more about Triggers.