Universal consumption reading meter connector specification

Edit online

The universal consumption reading meter connector specification is used when interval consumption values are supplied directly.

File name and tab name

For the connector to process and load a file, the file must match the following criteria:
  • File name has the format EnviziConsum_XXXX:
    • XXXX can include any characters, including spaces.
    • File type is CSV or XLSX.
    • For example, a typical valid file name might be EnviziConsum_DemoCorpUS_20251222_140655835.csv or EnviziConsum_DemoCorpUS_20251222_140655835.xlsx.
  • XLSX files must contain a sheet that has the name Data.

Each file name should contain a unique organization and location identifier, and a date timestamp that indicates when the file was created. The information is not used for file processing, but it is useful to troubleshoot data loading issues.

Connector information

  • The connector loads data into meters.
  • The connector reads a maximum of seven columns from A to G in the CSV or XLSX file template.
  • The connector loads data by matching fields in the source file with a specific IBM® ESG Suite serial number, as indicated in the Data field mappings section:
    • No two meters in Envizi ESG Suite can ever have the same serial number.
    • If a matching serial number cannot be found, data is not loaded for the given rows.

Column headings

The connector searches in the file to match on the column headings that are identified in the following table:
Table 1. Source file columns and headings
Column Heading
A Organization
B Meter ID
C Timestamp
D Data Type
E Value
F Units
G Quality
Note: If the column headings are not matched exactly as indicated in the previous table, the file is not loaded.

Data rows

After incoming files have passed all the previous file validation criteria, each row of data is checked to see whether it is valid for loading into Envizi ESG Suite. The connector identifies valid data rows if they meet all the following criteria:

  • An Envizi ESG Suite meter serial number is found that matches the following format: Organization_Meter ID
  • The data type and units are a recognized combination
  • The timestamp is in a valid format
Any blank rows are automatically skipped, and the connector continues to process rows until it reaches the end of the file. Data row validation is case insensitive.
Note: If a row is not identified as a data or skip row, then it is not read or loaded.

Data field mappings

After a data row is identified, data row handlers determine what happens with the data and where it is stored in Envizi ESG Suite.

Table 2. Data values retrieved from the source file
Envizi ESG Suite column Source file column Source file name Data format Notes and assumptions
Serial No 1-A

2-B

 Organization

Meter ID

 Text

Text

 The connector searches for an Envizi meter serial number that matches the following format:
  • Organization_Meter ID
where Organization is the organization abbreviation in column 1-A, and Meter ID is the meter ID in column 2-B.
Example:
  • 1-A Organization = Envizi
  • 2-B Meter ID = MAIN.SWBD_1
  • Envizi Serial No. = Envizi_MAIN.SWBD_1
Note: The Organization code is used to ensure that the meter serial number is unique in the Envizi ESG Suite. It is recommended to use a short form of your organization's name as the Organization code. Contact IBM Support if you are unsure what value to use for the Organization code.
Interval Consumption Timestamp 3-C Timestamp DateTime Format is yyyy-mm-dd hh:mm:ss (24-hour format)

The timestamp is rounded to the nearest 15-minute interval (00, 15, 30, 45)

Supported interval periods for the file are 15 minutes, 30 minutes and hourly. The time that is provided must reflect the local site time without any adjustments for daylight savings.

24 hour Date time format dd/mm/yyyy hh:mm:ss or mm/dd/yyyy hh:mm:ss is supported on specific regional servers. Contact IBM Support and check whether this format can be used for your region.
Meter Data Type 4-D Data Type Text See the following Supported data types and units section for details.
Interval Consumption 5-E Value Decimal Value to be stored against the appropriate unit field in the meter.
Units 6-F Units Text See the following Supported data types and units section for details.
Estimated 7-G Quality "A" or "E" Used to identify if the data point is an actual reading or an estimated reading.

Supported data types and units

The connector supports the following data types and units.
Note: By default, Envizi ESG Suite displays mass and volumetric data types as raw values without converting to equivalent energy consumption. You can use the meter scaling factor to convert between units of measure.
Table 3. Supported data types and units
Source file data type Source file units Envizi ESG Suite component Envizi ESG Suite utility group Notes and assumptions
Electricity kWh Consumption Meter – Electricity (kWh) Electricity If both kWh and kVARh exist for an interval (multiple rows in the data file for same interval and meter), the following measures are calculated:
  • kVAh
  • Power Factor (pF)

Demand UOMs = kW and kVA
Electricity kVARh Consumption Meter - Electricity (kWh) Electricity Demand UOM = kVAR
Natural Gas cf Consumption Meter - Natural Gas (cf) Natural Gas Demand UOM = cf/h
Natural Gas ccf Consumption Meter - Natural Gas (ccf) Natural Gas Demand UOM = ccf/h
Natural Gas GJ Consumption Meter - Natural Gas (GJ) Natural Gas Demand UOM = GJ/h
Natural Gas MJ Consumption Meter - Natural Gas (MJ) Natural Gas Demand UOM = MJ/h
Natural Gas m3 Consumption Meter - Natural Gas (m3) Natural Gas Demand UOM = m3/h
Natural Gas kWh Consumption Meter - Natural Gas (m3) Natural Gas Demand UOM = kW
Water L Consumption Meter - Water (L) Water Demand UOM = L/h
Water kL Consumption Meter - Water (kL) Water Demand UOM = kL/h
Water m3 Consumption Meter - Water (m3) Water Demand UOM = m3/h
Domestic Water gal Consumption Meter - Domestic Water (gal) Water Demand UOM = gal/h
Domestic Water cf Consumption Meter - Domestic Water (cf) Water Demand UOM = cf/h
Blowdown Water gal Consumption Meter - Blowdown Water (gal) Water Demand UOM = gal/h
Makeup Water gal Consumption Meter - Makeup Water (gal) Water Demand UOM = gal/h
Cooling Tower Water gal Consumption Meter – Cooling Tower Water (gal) Water Demand UOM = gal/h
Irrigation Water gal Consumption Meter - Irrigation Water (gal) Water Demand UOM = gal/h
Fuel Oil gal Consumption Meter - Fuel Oil (gal) Fuel Demand UOM = gal/h
Liquid Propane cf Consumption Meter - Liquid Propane (cf) Fuel Demand UOM = cf/h
Steam lbs Consumption Meter - Steam (lbs) Thermal Demand UOM = lbs/h
Chilled Water Btu Consumption Meter - Chilled Water (Btu) Thermal Demand UOM = Btu/h
Chilled Water kBtu Consumption Meter - Chilled Water (kBtu) Thermal Demand UOM = kBtu/h, where kBtu = 1,000x Btu
Chilled Water ton hours Consumption Meter - Chilled Water (ton hours) Thermal Demand UOM = tons
Hot Water Btu Consumption Meter - Hot Water (Btu) Thermal Demand UOM = Btu/h
Hot Water kBtu Consumption Meter - Hot Water (kBtu) Thermal Demand UOM = kBtu/h
Hot Water ton hours Consumption Meter - Hot Water (ton hours) Thermal Demand UOM = tons
Thermal kWh Consumption Meter - Thermal (kWh) Thermal Demand UOM = kW

Data validation

In the following section, last good value refers to the last valid interval consumption and demand for the meter. The last good value might be used as an estimate to replace the consumption and demand for an interval if the following data validation checks fail.

When the connector loads each data row, it performs the data validation checks that are shown in the following table:
Table 4. Data loading validation checks
Data validation check Description and action
Null value Null values are considered invalid data. The connector logs an error and skips the row. Subsequently, values are estimated when a valid meter reading is received.
Non-numeric value Non-numeric values are considered invalid data. The connector logs an error and skips the row. Subsequently, values are estimated when a valid meter reading is received.
Negative value Negative values, for example, negative consumption values, are considered invalid data except for Electricity meters (with negative consumption enabled at organization level or meter level). Organization setting in Admin > Interval meter settings > Negative consumption correction enabled or individual meter setting Meter data negative consumption correction is enabled. If skipped, the connector logs an error and skips the row.
Data spike A data spike is a large increase in value that is more likely to represent a data anomaly or meter fault, rather than an actual increase in consumption or demand.

Envizi ESG Suite detects data spikes by comparing the calculated demand for the current interval with the maximum historical demand over a look-back period, where the default is the previous 30 days. If the demand for the current interval is greater than the maximum historical demand by a specified margin, where the default multiplier is 10, the calculated consumption and demand for the interval is replaced with the last good value and the data is flagged as estimated.

Envizi ESG Suite suppresses issues and alerts from being generated when data is flagged as estimated.

Note: The data spike validation logic provides good results for meters with regular load profiles but can be triggered unintentionally for meters with irregular load profiles. You can configure the following options at the organization level to suit your organization's preferences:
  • Spike detection threshold (maximum historical demand multiplier) [10x, 100x (default), 1000x]
  • Spike detection look-back period [1 month, 3 months, 6 months, 12 months, lifetime].
For individual meters that still experience false positive data spike detection, you can disable the data spike validation check in the meter settings page.

Gap filling within a file

Based on the organization settings (Interval meter settings > Gap filling and Gap filling estimation method) or meter settings (Gap filling), the connector can fill the gap with 0 or last good value from a previous interval.

The connector can apply last good value estimation method (last consumption value for the meter) to backfill data gaps that are less than or equal to [24 hours (default), 48 hours, 72 hours]. Data gaps that are longer than the selected period are not filled but can be covered by configuring meter data accruals.

Overwriting of data

If data is loaded for a specific interval and then reissued in a subsequent file, the most recent data, if valid, overwrites the existing data.

Example file format

The following screenshot shows an example file for loading meter data:

Figure 1. Meter data source file example
Example spreadsheet with meter data columns: Organization, Meter ID, Timestamp, Data Type, Value, Units, and Quality.