Home › Data Exchange

Data Exchange

How the Data Exchange Process Relates of Your Business Processes 

BEACON digitally models water services by creating database entries that link or provision an account, a location, and a service point with the metering technology installed there–typically a meter and, if applicable, an AMI or AMR endpoint for capturing and transmitting usage and operational data.

To accomplish this modelling, we use comma-separated-values (CSV) files to pass information from your billing and other information systems to BEACON. These CSV files are text-only spreadsheets in which each column identifies the information type, and each row contains the corresponding data for an individual record or service.

This structure lets you set up, update, and revise information at scale. Whether you need to update a single service or tens of thousands of services, the data exchange process supports your daily business processes, from customer billing to residential and commercial move-ins and move-outs, meter and endpoint changeouts, and usage monitoring.

Data Exchange Specification 

The term “Data Exchange Specification” refers to a family of specifications that define precise column names, character limits, and formatting rules for importing, synchronizing, and updating utility data in BEACON. A downloadable version of the Data Exchange Specification is available here.

The Data Exchange Specification includes fields for gathering and maintaining information related to the following:

Accounts – ID, account holder name and contact information, billing address and so on.

Locations – ID, service point address, geolocation data for the meter/service point and other details about the location such as number of occupants, evapotranspiration values, whether the location has a swimming pool and so on.

Service Points – ID used to distinguish multiple hookups at a single location (for example, someplace with a meter for potable water and a different meter for irrigation), geolocation data (used for greater accuracy when there is more than one service point at a single location), route number and so on.

Meters – Serial number, manufacturer, model, size, continuous flow/intermittent flow expected tag, unit of measure, resolution, installation date, removal date and so on.

Service Agreements – ID, service start and end dates.

Endpoint Configurations – Serial number, type, installation date and removal date.

AMR and Manual Reads – Read sequence, alert codes and high/low read limits for meters.

BEACON uses distinct Data Exchange file types, each with its own defined structure, and automatically detects the file type based on the columns present in a given file.

Accounts and Assets files – the file type you’ll be using most often, these files are used to set up new accounts, provision and swap meters and endpoints, pass tags and other essential data from your billing and information systems to BEACON. See Terminology for a complete breakdown of the fields available in this Data Exchange file type.

ID Update files – use this file type when you change billing vendors and want to update or change your account, location, service point, and meter IDs. ID Update files perform a global search and replace for key fields, avoiding so-called orphaned services that result from incorrectly passing new IDs to BEACON while not changing the old IDs. See Update IDs for details. 

Interval Meter Reads – these files give you the ability to import interval reads collected with AMR an AMI solutions from Badger Meter and third parties. For details, see Import Interval Meter Reads. 

Billing Meter Reads – use this file type to import current and historic billing reads. For a better understanding, see Import Billing Meter Reads. 

Billing Read Exports – these files define the billing read output of BEACON. Consult Billing Read Export Specification for more information. NOTE: We highly recommend working with our Software Services team when setting up your billing read export files.

Configured Export files – used for billing systems that cannot handle CSV-format billing files, our Software Services team will assist in configuring your Format C or Format D export files, so they align with your billing software.


Warnings and Exceptions

Regardless of the file type, BEACON returns errors and warnings when it encounters issues with file imports. To ensure accurate data exchange, review the Exceptions Report created during the import process to troubleshoot and correct files before proceeding with the import. See Data Exchange Errors FAQ and Data Exchange Warnings FAQ for vital information on handling exceptions. Keep in mind that errors prevent a file or a specific record in a file from being processed.

Think of warnings as notifications that tell you of an impending action. If that action is what you intended, it is safe to proceed with the import. If the action wasn’t what you intended, you can make the appropriate changes before proceeding. 


Handle With Care 

Before handling your first CSV file, please read CSV Files and Excel and follow the instructions to preserve the fidelity of your data. 

Essential Information

Minimum Import File Size – Import files can be as small as two rows–one for the column names (also referred to as column headers), and a second row for data associated with each column in the file.

Maximum Import File Size – 70MB. 

Maximum Export File Size – A maximum of 1,048,576 records (1,024*1,024) can be returned in a single export operation.

Delimiters – BEACON supports the following delimiters in order of precedence: commas, tabs, semicolons, colons, pipes, tildes. 

Supported File Extensions – .csv, .txt, .dat, and .a. Other formats that do not pass text formatting information in the file should also work.

 

Minimum Fields
The minimum fields required to perform various operations in BEACON depend on whether you are setting up – also called provisioning – a service for the first time or updating an existing service.  

To provision a service, that is, associate an account and location and its service point(s) with a meter and if appropriate an AMI or AMR endpoint, for the first time you need to import at a minimum these fields:

Account_ID, Location_ID, Meter_ID, Endpoint_SN, and Endpoint_Point_Type, along with Meter_Size, Register_Unit_of_Measure, and Register_Resolution. See Terminology for detailed descriptions of these and every other field in the Accounts and Assets Data Exchange Specification.

If the service already exists or you previously provisioned a particular AMI or AMR endpoint, BEACON will remember its Endpoint_Type. Similarly, BEACON remembers Meter_Size, Register_Unit_of_Measure, and Register_Resolution when the meter has been previously provisioned. 

If possible, please provide the dates in your files. That is, Service_Agreement_Start_Date, Meter_Install_Date, Endpoint_Install_Date, and if appropriate Service_Agreement_End_Date, Meter_Removal_Date, and Endpoint_Removal_Date. If your billing system does not support the ability to provide dates, BEACON will use default dates. For details, see Terminology.

The minimum required fields differs based on the data your upload. For example,  billing reads, interval meter reads, and other operations. You will find the requirements for each operation on the Help pages that correspond to those Data Exchange Specifications. 

Import Best Practices
Utilities with <10,000 services should feel confident uploading records for all of their services in a single Data Exchange file.

Uploading deltas – Data Exchange files that contain only the records for services that have recent changes (deltas), such as meter and endpoint swaps, account status changes, and so on – is recommended for utilities of all sizes.

Some utilities upload deltas throughout the week and upload records for all of their services periodically, for example, once per month or once per week. This helps ensure that new or modified accounts and services that were accidentally left out of your update process will be updated. 

When changing billing vendors, always use ID Update files to update Account IDs, Location IDs, Service Point IDs, and Meter IDs. Making such changes without using an ID Update file can and does break the link between customer emails and the account ID that lets your customers access the EyeOnWater web portal and smartphone apps. 

Data Exchange In-Depth
The following sections of the BEACON Integration Hub will help you synchronize your CIS and billing systems with BEACON using Data Exchange files. 

 

 

Knowledge Base

 

 

Knowledge Base Archive

User Guide
Follow via Email

Enter your email address to get new content notifications by email.