[Legacy] Universal interval consumption meter connector specification

Edit online

The legacy universal consumption reading meter connector specification is retained for backward compatibility with older SBS‑based integrations.

Important: Use the new Universal consumption reading meter connector specification. This meter connector is only for legacy users.

Filename and tab name

For the connector to process and load a file, the filename must have the format CLIENT_EnviziSBS_XXXX, and the file must match the following criteria:
  • CLIENT_ is the identifier for the client, and is preferably an acronym of up to four characters, for example, Envizi - ENV. Contact IBM® Support if you are unsure what to use as the client identifier.
  • XXXX can include any characters, including spaces.
  • File type is CSV or XLSX.
  • For example, a typical valid filename might be ENV_EnviziSBS_20160103.csv or ENV_EnviziSBS_20160103.xlsx.

Each filename 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 Envizi 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
Note: The Organization code is used to ensure that the meter serial number is unique in Envizi ESG Suite. Contact IBM Support if you are unsure what value to use for the Organization code.
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 = ENV-LOC1
  • 2-B Meter ID = MAIN.SWBD_1
  • Envizi Serial No. = ENV-LOC1_MAIN.SWBD_1
Interval Consumption Timestamp 3-C Timestamp DateTime Format is one of the following
  • yyyy-mm-dd hh:mm:ss (24-hour format) (recommended).
  • dd/mm/yyyy hh:mm:ss AM/PM (12-hour format). Contact IBM Support and check whether this format can be used for your region.

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.

Note: Envizi ESG Suite interprets the timestamp as the start of the interval time. For example, for hourly data, values that are stored against a timestamp of 01:00 are interpreted as the utility consumption between 01:00 and 02:00.
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 SBS Electricity Electricity If both kWh and kVARh exist for an interval, the following measures are calculated:
  • kVAh
  • Power Factor (pF)

Demand UOMs = kW and kVA
Electricity kVArh SBS Electricity Electricity Demand UOM = kVAr
Electricity Phase A A SBS Electricity Electricity N/a
Electricity Phase B A SBS Electricity Electricity N/a
Electricity Phase C A SBS Electricity Electricity N/a
Electricity Phase A V SBS Electricity Electricity N/a
Electricity Phase B V SBS Electricity Electricity N/a
Electricity Phase C V SBS Electricity Electricity N/a
Gas GJ SBS Gas Meter - GJ Natural Gas Demand UOM = GJ/h
Gas MJ SBS Gas Meter - MJ Natural Gas Demand UOM = MJ/h
Gas kWh SBS Gas Meter - kWh Natural Gas Demand UOM = kW
Gas m3 SBS Gas Meter - m3 Natural Gas Demand UOM = m3/h
Gas ccf SBS Gas Meter - CCF Natural Gas Demand UOM = ccf/h
Gas Pulses SBS Gas Meter - GJ Natural Gas Demand UOM = GJ/h

Envizi ESG Suite accepts Pulses as a unit of measure for natural gas, but displays the unit as GJ in the platform. If the actual number in the Data Value column is not Gigajoules (GJ), then a scaling factor needs to be applied to the gas meter so that Envizi ESG Suite can calculate and report a value in GJ.

For example, if a file for a gas meter contains 10 Pulses, and each Pulse is 0.2GJ, then a scaling factor of 0.2 needs be set for the meter so that it displays 2GJ consumption for that interval.
Water L SBS Water Meter - L Water Demand UOM = L/h
Water kL SBS Water Meter - KL Water Demand UOM = kL/h
Water m3 SBS Water Meter - M3 Water Demand UOM = m3/h
Water Pulses SBS Water Meter - KL Water Demand UOM = kL/h

Envizi accepts Pulses as a unit of measure for water, but displays the unit as kilolitres (kL) in the platform. If the actual number in the Data Value column is not kL, then a scaling factor needs to be applied to the water meter so that Envizi ESG Suitecan calculate and report a value in kL.

For example, if a file for a water meter contains 10 Pulses, and each Pulse is 0.2kL, then a scaling factor of 0.2 needs to be set for the meter so that it displays 2kL consumption for that interval.
Thermal kWh SBS Thermal Meter - kWh Thermal Demand UOM = kW

Data validation

When the connector loads each data row, it performs the data validation checks that are shown in the following table.
Note: In the following table, last good value refers to the last valid interval consumption and demand for any meter. The last good value might be used as an estimate to replace the consumption and demand for an interval if the data validation checks fail.
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 interval consumption value 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 interval consumption value is received.
Negative value Negative values are considered invalid data. The connector logs an error and skips the row. Subsequently, values are estimated when a valid interval consumption value is received.
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 zero and the data is flagged as estimated.

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 (default previous 30 days). If the demand for the current interval is greater than the maximum historical demand by 10x, the calculated consumption and demand for the interval is replaced with 0 and the data 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 look-back period [0 days, 30 days (default), 60 days, 90 days, 120 days].
For individual meters that still experience false positive data spike detection, you can disable the data spike validation check by setting the spike detection look-back period to 0 days.

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
Spreadsheet showing electricity meter readings for 'MainElec' from September 1, 2023, at hourly intervals. Columns include Organization, Meter ID, Timestamp, Data Type, Value in kWh, Units, and Quality. Values range from about 51.64 kWh at midnight to 115.48 kWh by 1:00 PM.