Making Sense of the Terminology in Data Exchange Files
The Data Exchange Specification uses terms such as Account ID, Location ID, Service Point and Unique Identifier that may be confusing to some as the terms – and the way they are used – may be new. For example, what exactly is an “Account ID”? Does it need to be unique? If so, why and in what way? What happens when the person responsible for the account moves? Does the Account ID move with them or stay “glued” to the location? What is a Service Point and where is it? Why does it need to have an ID? When should these IDs change and why?
For those who are used to thinking of “billing interface” files instead of Data Exchange files, think of “data exchange” as another way of saying “billing interface.”
If you haven’t already, take a moment to review the information about Data Exchange and utility business processes here. Then use the information in this document to better understand:
- Terms used in the Data Exchange Specification
- Information called for in the Specification
- Different ways Data Exchange files can be used to integrate utility data with BEACON.
Click the following links to jump directly to information about how Data Exchange Specification relates to:
- Service Points
- Gas Meters
- Dates, Timezones & Daylight Savings Time
- District Metering Areas (DMA)
- Service Agreements
- Mobile Reading Technology
- Miscellaneous Information
Badger Meter may modify attributes of the Data Exchange Specification from time to time without prior notification. Revision history is listed on the Data Exchange download page.
In response to evolving customer needs, new columns are sometimes added to the Data Exchange Specification. These additional columns will not affect existing Data Exchange files. Similarly, some columns have been renamed and other column attributes have been modified. All previous column names are backwardly compatible, so that if your Data Exchange files use old column names, the importer will still recognize them. While it is not required, we recommend renaming old column headers to keep your Data Exchange files aligned with the Data Exchange Specification.
In cases where column names have changed from previous versions of the Data Exchange Specification, the old and new column names are described in the corresponding explanation below.
Previously, the Data Exchange Specification was called the BEACON Data Exchange Specification, and Data Exchange files were referred to as BDE files. Both the spec and the files have changed in name only. Both still function as before.
IDs and Case Tolerance
While fields such as Register_Unit_Of_Measure are case sensitive (entries must be in capital letters, for example GAL, CUBIC FEET, etc.) if you use letters in Account_IDs, Meter_IDs, Location_IDs or Service_Point_IDs, BEACON treats lower-case and upper-case letters as identical. In other words, BEACON thinks of Location_ID 1234A as being identical to Location_ID 1234a.
The concept of holding an “account” will be familiar to anyone that gets billed on a regular basis for ongoing services. When a person or business becomes a utility customer, they are typically given an account that is identified using an account number. Some utilities call them customer numbers. Others say service numbers. Regardless what it is called, when used for billing purposes, that number lets the utility and its customers keep track of transactions.
In BEACON, “Account Numbers,” “Customer Numbers” and “Service Numbers” are called “Account IDs,” because they can use any combination of letters, numbers and symbols such as hyphens. For example, JBD123A4567, JBD-123-A-4567 and 12345678 are typical Account IDs.
The Account Information section of the Data Exchange Specification (shown below) starts with a field for Account IDs followed by fields for collecting the contact information of the person or business responsible for paying for water services.
|Column Name||Max Length||Description|
|Account_ID||64||Unique identifier of the Account used for billing purposes.|
|Account_First_Name||64||First name of the account owner.|
|Account_Last_Name||64||Last name of the account owner.|
|Account_Full_Name||128||Full name of the account owner.|
|Account_Email||254||Email address of the account owner.|
|Account_Phone||32||Phone number of the account owner.|
|Account_Phone_Extension||255||Phone number extension of the account owner used for billing portal purposes.|
|Billing_Address_Line1||64||Billing address line 1.|
|Billing_Address_Line2||64||Billing address line 2.|
|Billing_Address_Line3||64||Billing address line 3.|
|Billing_ZIP||10||Billing ZIP+4 or postal code.|
|Billing_Country||3||ISO 3166-1 country code of the billing address (e.g. ‘US’, ‘USA’, ‘CA’, ‘MX’).|
|Person_ID||32||Identifier used for grouping together Accounts that belong to a single person or individual.|
|Account_Status||1||A (active) or I (inactive).|
|Account_Portal_Status||1||S (show) or H (hide).|
|Account_Billing_Cycle||12||An identifier used to denote the cycle name used when sending bills.|
|Account_Paperless||1||Enter 1 if the account has opted in for paperless billing, 0 for opted out or not enrolled in paperless billing.|
|Account_AutoPay||1||Enter 1 if the account has opted in for auto pay through the utility directly, 0 for opted out or not using the utility for auto pay.|
|Account_BillerAutoPay||1||Enter 1 if the account has opted in for third party auto pay such as through a billing vender, 0 for opted out or not using a 3rd party for auto pay.|
Account IDs in Data Exchange files can be up to 64 characters long. The combination of letters, numbers and symbols must also be unique. Hence the term unique identifier. Unique how? Unique within your billing system. This lets you tell one customer from another, even if they have the same name or live at the same location. If a person or business has more than one account, Account IDs help distinguish one set of transaction records from another.
Note: If your Account IDs use hyphens, spaces and other symbols, they are included in the character count.
Using Account IDs in Data Exchange Files
Account IDs can be used in different ways. For example, you can use them as unique identifiers for individuals or businesses. When that person or business moves from one place to another within your water district, their Account ID does not need to change. It can move with the customer. Alternately, if you prefer to change the Account ID when someone moves out of a location, you can. The Data Exchange Specification provides the flexibility to adapt to your preferred business practices.
If a person or business pays for water service at multiple locations, creating a Data Exchange file that lists the account owner’s Account ID and billing details on each of the location entries they pay for lets you aggregate usage at multiple locations in one bill.
In the example below, a single account holder, for example a landlord or property rental firm, is associated with three different locations where water service is provided. Each location has a service point and metering technology (a meter, an encoder and an endpoint).
Modelling this example in a Data Exchange file requires three separate rows in the spreadsheet. All three rows use the same Account ID and different Location IDs, Service Point IDs, Meter IDs and endpoint serial numbers along with all of the details that go with each of them.
Another way to use Account IDs is to assign them to locations. In fact, before Data Exchange file-based system synchronization was available, the manual provisioning process let you create an Account ID by duplicating an existing Location ID.
Using matching Account and Location IDs in Data Exchange-file-based system sync works for customers that pay for water at one location (typically their home). It also works for customers that pay for water service at multiple locations.
For customers that pay for using water at one location, create an entry in the Data Exchange file that uses identical Account and Location IDs and duplicate the address details in the billing address and location address fields.
|1234||3 ½ Main St.||1234||3 ½ Main St.||1||M1||123456789||J|
For customers that pay for water service at multiple locations, use duplicate Account IDs and billing address for each entry, but use different location IDs and location addresses.
|1234||3 ½ Main St.||1234||75 Park Ave.||1||M1||112345678||J|
|1234||3 ½ Main St.||4321||10 W. 1st St.||1||M2||111234567||J|
|1234||3 ½ Main St.||2341||7 W. Olive Lane||1||M3||111123456||J|
First Name, Last Name, Full Name—Why All Three?
Data Exchange files include separate fields for Account First Name and Account Last Name. Data Exchange files also have a field for Account Full Name. If this confused you, you are not alone. The option to enter a first name and a last name or a full name was created to accommodate requests from BEACON users. Either method is acceptable, but we recommend entering first and last names separately. It gives the most flexibility in customer outreach where you have the option of saying “Hello Jane” instead of “Hello Jane Doe” or “Hello Doe, Jane.” The Account Full Name field is ideal for business names.
Person_ID is an optional unique identifier. It can be up to 32 characters long. For utilities that offer services through an online billing portal, Person IDs can be used to associate multiple accounts with a single portal user.
When modeling configurations that associate multiple accounts with a single billing portal user in a Data Exchange file, assign a single Person ID to the Account IDs they are responsible for.
|1||1234||1234||75 Park Ave.||1||M1||112345678||J|
|1||4321||4321||10 W. 1st St.||1||M2||111234567||J|
|1||2431||3241||7 W. Olive Lane||1||M3||111123456||J|
Account_Phone_Extension is an option field that lets utilities record the phone extension of an account holder. The value is not surfaced anywhere in BEACON, but can be used in a billing portal.
Account_Status is an optional field that lets utilities mark accounts as being active or inactive, regardless of Service Agreement start or end dates. After this data is passed to BEACON via a Data Exchange file, Monitor page filters select and count locations with Active or Inactive services.
Another optional field, Account_Portal_Status lets utilities hide or display an account in a billing portal.
Use the Account_Billing_Cycle field to identify the cycle used for billing customers.
Use the Account_Paperless, Account_AutoPay and Account_BillerAutoPay fields to indicate customer payment method preferences.
Another optional field, Account_Portal_Status lets utilities hide or display an account in a billing portal.
BEACON supports standard ISO 3166-2 codes for names of states, provinces and other principal subdivisions of all countries defined by ISO 3166-1. Both 3-character alpha and 2-digit numeric (when applicable) codes are supported.
For example, enter the code for Morelos, Mexico as:
Enter the code for Auvergne-Rhône-Alpes, France as:
The code for Sjælland, Denmark can be entered as:
Or with the 2-character country code:
Principal subdivision codes are exported in ISO 3166-2 format. For example:
- Veracruz, Mexico = VER
- Sjælland, Denmark = 85.
ZIP and Postal Codes
BEACON supports ZIP, ZIP+4 and international postal codes. Be sure to include the hyphen when entering ZIP+4 codes: for example, 12345-6789. The Data Exchange importer validates U.S., Canadian, U.K. and German postal codes. Other international postal codes are considered valid if they fall within the 10-character limit.
The Billing_ZIP column was previously named Billing_Zip_Code.
BEACON supports two or three-character codes for names of countries, dependent territories and special areas of geographical interest as defined by ISO 3166-1. Both alpha and numeric codes are supported. For example, the country code for the Unites States of America can be entered any one of three ways:
- two-letter: US
- three-letter: USA
- three-digit: 840
Country codes are exported in ISO 3166-1 alpha-2 format. For example, the United States = US. Canada = CA.
“Locations” are places where utilities deliver water service. A location could be a house, a shopping mall, a skyscraper, a hydroelectric dam, a multi-thousand acre agribusiness and anything in between.
The Location section of the Data Exchange Spec includes fields for capturing a location’s name, address and Geo-coordinates.
Remember that Location IDs are required for all Data Exchange entries.
|Column Name||Max Length||Description|
|Location_ID||40||Unique identifier for the location where the service is being provided.|
|Location_Name||64||Label for this location in cards and maps.|
|Location_Address_Parity||1||Use ‘O’ for addresses that should be treated as the odd-numbered side of the street and ‘E’ for addresses that should be treated as the even-numbered side of the street.|
|Location_Address_Line1||64||Address line 1 for the service location.|
|Location_Address_Line2||64||Address line 2 for the service location.|
|Location_Address_Line3||64||Address line 3 for the service location.|
|Location_City||64||City of the service location.|
|Location_State||2||State or Province of the service location.|
|Location_ZIP||10||ZIP+4 or postal code of the service location.|
|Location_County_Name||64||County name of the service location.|
|Location_Country||3||ISO 3166-1 country code of the billing address (e.g. ‘US’, ‘USA’, ‘CA’, ‘MX’).|
|Location_Latitude||15||Latitude position of the service location in decimal degrees.|
|Location_Longitude||15||Longitude position of the service location in decimal degrees.|
Like Account IDs, Location IDs must be unique within your billing system. Location IDs can be any combination of letters, numbers and symbols that add up to no more than 40 characters. As mentioned previously, Location IDs can be duplicated to create Account IDs. The Location address should be the physical address of the place where water service is being provided.
The Location ID should not change, even when a new tenant moves in or a meter is changed out. In addition, the Location ID should be a number that is already being used in your billing system.
Key Explanations: Location Section
The Location_Name field lets you identify places by giving them a name, for example, Golf Course Irrigation, Town Hall, Joe’s Pizza and Fast Oil Change, etc. This name is displayed as a filter on the Monitor page and as location marker names in the Consumption Graph map view. The field supports free-form text entries, which means you can enter any string of up to 64 characters.
The Location_Address_Line(1,2,3) fields are used to identify where water service is being provided and are displayed under card Location tabs as the Service Address.
Location_Address_Parity lets utilities identify premises as being on the odd-numbered or even-numbered side of the street. Enter ‘O’ for odd-numbered locations, ‘E’ for even numbered locations. The Location_Address_Parity field also lets utilities decide whether addresses such as 3 1/2 Main Street or 123-A Main Street are odd or even. Leave the field blank if street parity is not considered for your utility operations.
The Location_Longitude and Location_Latitude fields let you enter the precise Geo-location of a particular place. If you do not know them, BEACON uses the Location address to get the coordinates from Google maps. Location Geo-coordinates are displayed on Monitor page card Location tabs. Enter a Location_Longitude that is no more than 15 digits long and between -180 and 180 degrees. Enter a Location_Latitude that is no more than 15 digits long and between -90 and 90 degrees. Do not include symbols for degrees (º), hours (‘) or minutes (“).
Note: The first time you provision an account and provide Location Geo-coordinates but do not provide Service Point Geo-coordinates, BEACON uses the Location Longitude and Latitude values as the Service_Point_Latitude and Service_Point_Longitude used to derive Monitor page map locations. If you provide both Location and Service Point longitude and latitude values, BEACON will use the Service Point values for both Location and Service Point.
About Longitude and Latitude Precision
While the Location and Service Point Longitude and Latitude fields in BEACON let you enter as many as 15 characters, the practical limit of accuracy for a meter is five or six decimal places. Five-decimal precision translates to ~1 meter precision or ~3-feet precision. Six-decimal precision is accurate to within a few inches.
When displayed on Monitor page cards, longitude and latitude values are rounded to six-decimal-place precision.
Fields in the Tags section of the Data Exchange Specification let you capture data related to all meters at a given location. Tag fields labeled with an asterisk (*) in the table below can appear as Monitor page filters when enabled via the Assets>Utility Settings page.
Tags are optional and start at the Location_Building_Type field and end at the Location_Parcel_Number field. If you do not have this information, leave the fields blank in your Data Exchange files. Tags for recording monthly evapotranspiration values for a given location are available, but have been moved to streamline the Data Exchange Specification.
|Column Name||Max Length||Description|
|Location_Building_Type*||64||Optional building type (e.g., ‘retail,’ ‘dining,’ ‘apartments’) label for faceting in BEACON Monitor.|
|Location_Building_Number||64||Optional building number label for filtering in BEACON Monitor.|
|Location_Site*||64||Optional site (e.g., ‘North Campus,’ ‘Uptown Village’) label for filtering in BEACON Monitor.|
|Location_Funding*||64||Optional funding label for filtering in BEACON Monitor.|
|Location_Main_Use*||64||Optional main use label for filtering in BEACON Monitor.|
|Location_Water_Type*||64||Optional water type (e.g., ‘hot,’ ‘cold,’ ‘potable,’ ‘reclaimed’) label for filtering in BEACON Monitor.|
|Location_Area||6||Lot area in square feet.|
|Location_Irrigated_Area||6||Area of lot that may be watered, in square feet.|
|Location_Population||3||Number of occupants at location.|
|Location_Irrigation||1||1 if location is known to be irrigate, 0 if not.|
|Location_Year_Built||4||Year of construction for the current structure on the location.|
|Location_Pool||1||1 if location is known to have a swimming pool.|
|Location_Bathrooms||3||Number of bathrooms at location.|
|Location_District*||32||Label for district.|
|Location_DHS_Code*||64||Optional Department of Health Services code.|
|Location_Parcel_Number||32||County assessor parcel number or APN.|
|Meter_Text_1, Meter_Text_2, Meter_Text_3 … Meter_Text_10*||64||10 optional custom tags that can be used for filtering on the Monitor page. Meter Text tags are meter-centric.|
The Location_Building_Type field lets you note whether a building is a retail store, a gym, a parking structure, etc. The field supports free-form text entries, which means you can enter any string of up to 64 characters. When the Building Type tag is enabled by Badger Meter personnel, the text strings create custom filters on the Monitor page.
Location_Main_Use lets you note how water is being consumed. The field supports free-form text entries of up to 64 characters. Housing, domestic, sprinkler, sewer district, well and landscape are some examples. When the Location Main Use tag is enabled by Badger Meter personnel, the text strings create custom filters on the Monitor page.
Location_Population, Year_Built, Location_Bathrooms, as their names imply, let you note how many people live or work in a particular place, when a structure was built and how many bathrooms are in a particular place, respectively. All of these things are helpful when comparing water use between “similar” locations. When entering the number of bathrooms, use integers and floating numbers, not fractions. For example, use 3, 3.0 or 3.5. Do not use 3 1/2.
Location_Irrigation is a boolean field, which means that entering a 1 means “yes, this location uses water for irrigation.” Entering a 0 means “no, this location is not a place where irrigation happens.”
Location_DHS_Code is a code used by some utilities to identify the water source or watershed a premise is served from.
Location_Parcel_Number is used for similar homes comparisons in customer outreach programs. Use a combination of up to 32 alphanumeric characters to enter the county assessor parcel number or APN for a given property.
Use the Meter_Text_1, Meter_Text_2, Meter_Text_3 … Meter_Text_10 fields to create custom tags for selecting and counting meters on the Monitor page. When these Meter Text tags are enabled by Badger Meter personnel, the text strings create custom filters that appear under Meter_Text_x on the Monitor page.
TIP: When naming Meter_Text_x tags, be consistent. BEACON treats each value as a separate tag. In other words, entering “potable water,” “Potable water” and “POTABLE” (notice the difference in capitalization) in the same Meter_Text_x column results in three different tags.
Previous Location and Tag Column Names
Location columns were previously called Premises and Services. For example, the Location_Address_Line1 column was at one time named Premise_Address_Line1 and at another time Service_Address_Line1. Location_City was Premise_City and Service_City. Location_Water_Type was previously called Service_Type. Location_State has been called Premise_State and Service_State. Location_ID has been called Premise_ID and Service_ID.
In addition, Location_District was previously named Location_Outreach_District.
Location_WFR has been deprecated.
Previously, Location_Parcel_Number required a combination of up to 32 numbers and dashes to enter the county assessor parcel number or APN for a given property. The entry needed to begin and end with an integer, and double dashes were not supported.
Service Point (SP)
Physically, a service point is where a water pipe connects to a meter and if applicable an encoder register and an endpoint. In other words, it is a place where a utility delivers water service–a “service point.”
SP vs. Service Point
For utilities that use the Oracle® Customer Care and Billing (CC&B) system, which limits column names to a maximum length of 30 characters, any of the Data Exchange Specification Service Point-related column names can be shortened to SP_xxx, as shown in parenthesis in the table below.
The Service Point (SP) portion of the Data Exchange Specification starts with a Service_Point_ID field followed by fields for capturing the type of service being delivered, where the service falls in your billing cycle, collection routes and the exact physical location of each meter hookup along with its timezone.
|Service Point (SP)|
(for Oracle CC&B)
|32||An identifier used to distinguish between multiple service hookups at the same Location. The combination of Location ID and Service Point ID represents a single point to which a meter is to be attached. This value MUST be provided if multiple services are present at a single Location. If this value is omitted, a default Service Point ID of ‘1’ is used.|
|1||Type of service being read. Water ( W ), Sewer (S), Gas (G), Fire (F), Irrigation (I) and Reclaimed/Recycled (R). If not specified, the default is Water (W).|
|12||An identifier used to denote the billing cycle name.|
|12||Identifier of the route or book the metered service belongs to. It is used by BEACON to group accounts for loading into collection devices or running reports.|
|12||Identifier for this service point’s billing classification/category in the billing system, e.g., residential, commercial, irrigation, etc.|
|24||The standard BEACON class code that the billing system class code corresponds to. Must be one of ‘Commercial,’ ‘FireService,’ ‘Industrial,’ ‘Irrigation,’ ‘Sewer,’ ‘SingleFamilyResidential,’ ‘MultiFamilyResidential’ or ‘Vacant.’|
|15||Latitude position of the Service Point in decimal degrees; provided separately from Location Latitude in case a more specific location for the service’s meter hookup is available.|
|15||Longitude position of the Service Point in decimal degrees; provided separately from Location Latitude in case a more specific location for the service’s meter hookup is available.|
|64||Name of the timezone where the service/meter is located, e.g. US/Pacific. See this list of timezone names. If you do not provide a timezone, the timezone associated with the utility specified via BEACON will be used.|
Service Point IDs
In BEACON, Service Point IDs distinguish between two or more meters at the same location (for example, one for potable water and another for irrigation). If no Service Point ID is provided, the Service Point ID will be assigned a default value of 1 by the importer. For any Location where multiple services are present, Service Point IDs are required. Service Point IDs can be any combination of letters, numbers and symbols that add up to no more than 32 characters. In a Data Exchange file, every Location ID (and therefore every row in the spreadsheet) must also have a Service Point ID. When combined, each pair of Location ID and Service Point IDs must be unique within your billing system. Remember that each meter (and each side of a compound meter) needs its own row in a Data Exchange spreadsheet.
Because it is the combination of a Location ID and Service Point ID that has to be unique, you can have a Location ID be something like 20010 and name its Service Points 01-20010, 02-20010 and so on. You could also name all of your Service Point IDs in this manner, so that any Location with a single meter would have a Service Point ID that was the Location ID preceded (or followed) by 01. For example, 01-20010 or 20010-01.
Location IDs and Service Point IDs do not need to change with a move-in or move-out, nor do they need to be changed when there is a meter or endpoint change out. An example of when these identifiers would change is if a water service line is abandoned.
Key Explanations: Service Point Section
Service_Point_Type lets you classify the type of service being read by the meters at a location.
The Service_Point_Class_Code field supports free-form text entries that can be up to 12 characters long. A “class code” describes the category or classification used in your billing system for that service. For example, residential, commercial, industrial, etc.
How is the Service_Point_Class_Code field different from the Service_Point_Class_Code_Normalized field? Instead of free-form text entry, the Normalized field only recognizes six service types/categories. As a result, entries in the Service_Point_Class_Code_Normalized field must be one of the following: Commercial, FireService, Industrial, Irrigation, Sewer, SingleFamilyResidential, MultiFamilyResidential or Vacant.
Providing Service_Point_Latitude and Service_Point_Longitude coordinates helps pin-point the exact location of the service hookup. When included in a Data Exchange file, Service_Point_Latitude and Service_Point_Longitude coordinates are displayed on the Meter tab of each meter card. Service Point Geo-coordinates are also used to map the service point location on the Monitor page. Previously, entering Location and Service Point Geo-coordinate values separately in your Data Exchange files was recommended. This is no longer necessary.
Use the Service_Point_Timezone field to identify the timezone where the meter is located. If no timezone is given, the utility timezone will be used in its place. For utilities that deliver water service to locations that span different timezones, providing a Service_Point_Timezone gives BEACON and therefore your utility a more complete and accurate picture. Monitor page cards display the Service_Point_Timezone on the Meter tab as Timezone.
The Service_Point_Timezone field supports entries of up to 64 characters. BEACON supports an extensive list of timezones, defined in this wikipedia entry.
For quick reference, use this list of common timezones:
For more granularity, consult the wikipedia list and enter the timezone name exactly as it appears in the TZ* column.
Daylight Savings Time
BEACON automatically adjusts to Daylight Savings Time.
Previous Service Point Column Names
Earlier versions of the Data Exchange Specification called the Service_Point_Route column Route and Route_ID.
The Meter section of the Data Exchange Specification captures vital details required to accurately measure and bill customers for their water use along with information that can be used to keep track of when or if a meter has been changed out, its first and last read, etc.
|Column Name||Max Length||Description|
|Meter_ID||40||Identifier of the meter. It must be unique and is required.|
|Meter_SN||64||Serial number of the meter or meter register. Used for information purposes.|
|Meter_Manufacturer||32||Manufacturer of the meter. (Badger, Sensus, Neptune, etc.)|
|Meter_Model||64||Model of the meter. (M25, M55, T160, etc.)|
|Meter_Size||10||Numeric size of the meter. (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.)|
Unit of measure for meter size: NPS, inches, DN or mm. If left blank, the unit defaults to inches.
|Meter_Note||128||Additional information for meter, e.g., precise location on property.|
|Meter_Continuous_Flow||1||1 if meter is expected to have continuous flow. Leaving the field blank or entering 0, tells BEACON to expect intermittent flow.|
|Register_Number||1||Use the Register_Number field to identify whether a meter is a single or compound meter. Leave the field blank or enter 0 for single-register meters. For compound meters, enter 0 or L for the low-flow register. Enter 2 or H for the high-flow register. For compound meters, the Location_ID, Service_Point_ID, and Meter_ID are expected to be the same for all registers.|
|Register_Unit_Of_Measure||12||Unit that the meter measures in. (GAL, CUBIC_FEET, CUBIC_METER, IMP, LITER, AF, OIL_BARRELS, FLUID_BARRELS.)|
|Register_Resolution||6||Factor of the rightmost movable digit (0.01, 0.1, 1, 10, 100, 1000, etc). Taken together with the Register_Unit_Of_Measure this represents the smallest unit of change that the register can report.|
|Register_Note||128||Additional information for each register of a compound meter. Data entered in this field can be exported via the EDS Reads API and is not viewable on cards.|
|Dials||1||Enter a number between 0 and 9 that represents the number of dials on registers connected to ORION fixed network endpoints. Note: For meters connected to ORION Cellular endpoints, BEACON ignores values entered in this column.|
|Pit_Type||20||To describe the meter pit, enter one of: OUTDOOR, INDOOR, METAL_COVERED_PIT, CONCRETE_COVERED_PIT, PLASTIC_COVERED_PIT, CONCRETE_METAL_DOOR, UNSPECIFIED.|
|Meter_Install_Date||10||The date the current meter was installed if a meter change out occurred, otherwise leave blank.|
|Meter_Install_Start_Read||9||Initial read of meter when it is installed.|
|Meter_Removal_Date||10||The date the meter is removed from the associated Service Point; provide only if meter is being removed.|
|Meter_Removal_End_Read||9||Final read of meter when it is removed; if present this is interpreted as a meter removal/swap.|
Use these columns to provision gas meters and endpoints. Gas meter billing reads, called index reads, are displayed on Monitor page cards. Gas flow will not be not displayed in the consumption graph. To change a Monitor page card meter icon type to Gas you must include the Fluid_Type column and enter GAS.
|Column Name||Max Length||Description|
|Fluid_Type||5||Enter one of GAS or WATER.|
|Gas_Pressure_Compensation||7||Denotes the lower or higher pressure of the gas lines in a particular neighborhood (higher than normal pressure implies more gas used). Typical entries range from 0.8 to 1.8. Entries support five-decimal precision in this format: x.xxxxx.|
|Gas_Sub_Count||1||Enter one of 0, 1, 2 or 3. A sub count is the fractional portion of a gas index read (odometer value). The sub count entry is passed from BEACON to handheld reading devices and determines the index read value displayed.|
Key Explanations: Meter Section
Another unique identifier, Meter IDs can be up to 40 characters long and can include letters, numbers and symbols. Some utilities use the meter serial number (SN) as the Meter ID. That raises two questions:
- Do the Meter ID and Meter SN have to be the same? No. But they can be and often are.
- If the Meter SN is used as the Meter ID, do you still need to enter the serial number in the Meter SN field? While the Meter SN is not required for basic services, we recommend that you enter the serial number in the Meter SN field to:
• Take advantage of the EyeOnWater customer outreach program
• Enable filtering data based on Meter SN on the Monitor page. Meter IDs should change when the meter is changed out.
Tip: For super-compound or hybrid meters with a low-flow side, a high-flow side and one or more sides for fire and other services, differentiate between each by adding a meaningful abbreviation to the meter ID. For example, you could use -FS for fire service, -IR for irrigation, etc. See Meter Configurations, IDs and Data Exchange for more information.
The Meter_SN field is for recording the serial number engraved on the meter itself. Some utilities prefer to put the serial number of the encoder register attached to the meter in the Meter_SN field. Others use this field to differentiate between usages – for example, adding the letter M to serial numbers to indicate “main” meter and adding the letter D to serial numbers to indicate that they are “deduct” meters.
Use the Meter_Model field to further identify the type of meter installed at a given location. We recommend entering the actual meter model if it is known, but you can use up to 64 characters and enter any combination of letters, numbers and symbols to describe the meter.
Like Meter_Model, Meter_Manufacturer lets you further identify the meter at a given location by providing the name of its manufacturer. This information is displayed as Make under the Meter tab on Monitor page cards.
Use the Meter_Size field to pass the numeric size of the meter to BEACON. Be sure to enter decimal equivalents, not fractions. For example, enter 0.5 instead of 1/2. Meter_Size is displayed on Monitor page cards under the Meter tab as Size and Register Size.
Use the Meter_Size_Unit field to designate whether your meter sizes are in inches or millimeters by entering NPS, inches, DN or mm. If no entry is provided, unit defaults to inches.
Use the Meter_Note field to capture additional details about the meter. For example, describe its obscure location or record when it was provisioned. Meter_Notes are displayed under the Meter tab on Monitor page cards. Once recorded, Meter Notes cannot be revised or removed.
The Register_Number field identifies whether a meter is a single or compound meter. Leave the field blank or enter 0 for single-register meters. For compound meters, enter 0 or L for the low-flow side of the meter. Enter 2 or H for the high-flow side of the meter.
NOTE: For configured, Format C, Accounts and Assets data exchange files, you must enter a value for both registers of a compound meter. In other words, do not leave the low-flow side value blank if you enter an H or 2 to designate the high-flow side of a compound meter.
Meter_Continuous_Flow is a boolean field. Entering a 1 tells BEACON that continuous flow is expected at the location. Leaving the field blank or entering a 0 tells BEACON that intermittent flow is expected.
The Register_Unit_Of_Measure field is required. Be sure to use all capital letters when entering either GAL, CUBIC_FEET, CUBIC_METER, IMP, LITER or AF. On Monitor page cards, this field is displayed under the Meter tab as Unit. If Fluid_Type is GAS, this unit must be CUBIC_FEET.
Register_Resolution is another required field. It tells BEACON where the decimal goes in a raw encoder read. Getting the correct resolution–and recording it in BEACON–is essential for accurate customer billing. Register Resolution is based on a combination of factors: meter model and size, encoder type, unit of measure (gallon, cubic feet or cubic meter) and the type of endpoint that is attached to the encoder.
For more information on determining the resolution of ORION® and GALAXY® endpoints connected to Badger Meter Recordall® Series meters, Badger Meter ADE® encoders and Badger Meter E-Series® with High-Resolution Protocol encoders, see the following application briefs, which are available for download at http://www.BadgerMeter.com:
BEACON treats Register_Resolution changes as corrective actions that result in recalculation of all the consumption recorded by the particular meter. In other words, if a meter was provisioned on January 1, 2022 with an install date of 2022-01-01 and a resolution of 0.01 and on February 28, 2023 you pass a file that changes that meter’s register_resolution to 1.0, BEACON will recalculate the flow going back to January 1, 2022 using the new resolution as the multiplier. Flow recorded after February 28, 2023 will also use the new resolution as the multiplier.
If you are installing a new meter while reusing the existing Meter_ID and passing a new Register_Resolution value that you do not want to affect previously recorded consumption, you must pass a new Meter_ID along with the new Register_Resolution. Doing so tells BEACON to apply the new Register_Resolution moving forward, not backward. For example, if a meter was provisioned on January 1, 2022 with an install date of 2022-01-01 and a resolution of 0.01 and on February 28, 2023 you pass a file provisioned a new meter at the same location with a meter register_resolution to 1.0, BEACON will continue to display consumption recorded up to January 1, 2022 using 0.01 as the Register_Resolution and will calculate consumption recorded after January 1, 2022 at 23:59:59 (midnight) using 1.0 as the Register_Resolution.
Tip: If your usual practice is to reuse Meter_IDs, you can add a suffix to the original Meter_ID to indicate that a new meter was installed with a different Register_Resolution. For example Meter_ID 1234 could be Meter_ID 1234-1.0.
The Dials field lets you enter the number of dials on registers that are connected to ORION fixed network endpoints. For registers connected to ORION Cellular endpoints, any value entered in this field will be ignored.
Use the Pit_Type field to describe the meter pit. The information will be helpful when troubleshooting endpoint communication issues possibily related to installation.
The Meter_Install_Date and Meter_Removal_Date fields help track meter change outs. BEACON uses this data to determine what gets displayed on meter cards. For example, when viewing a single meter card in the Monitor page Consumption Graph for a service where a meter has been replaced, you will see uninterrupted flow data as measured by both meters.
The Consumption Graph above shows that a meter change out took place on August 31. Flow measured by the previous meter is displayed in light blue, while flow from the new meter is shown in dark blue. To see uninterrupted flow graphs where a meter change out has occurred, select the meter card and use the More drop-down menu to Hide Other Meters.
The Meter_Install_Start_Read and Meter_Removal_End_Read fields let you record the first read of a new meter and last read of the old meter when there is a meter change out. Enter the value as a billing read.
Whenever possible, provide the Meter_Install_Date and if appropriate Meter_Removal_Date. If the importer detects a Meter_Install_Date that was previously recorded and a new Meter_Install_Date is not included in a successive Data Exchange file, the system uses the existing date. If, however, no date was previously given or the file is provisioning the meter for the first time, when the file is imported, for meters connected to ORION Cellular endpoints, the Meter_Install_Date defaults to the latest date that the endpoint was activated. For meters connected to any other supported endpoint type, missing Meter_Install_Dates default to midnight (23:59:59) “today” in the service point timezone. If no service point timezone is given, the timezone defaults to the utility timezone.
If you provide a new Meter_Install_Date but do not give a corresponding Meter_Removal_Date, BEACON uses the new meter install date as the removal date of the old meter.
Previously, if you did not give a Meter_Install_Date or a Meter_Removal_Date in your Data Exchange files, when the file was imported, it did not matter which type of endpoint was involved. Missing dates defaulted to noon “today” in the service point timezone. If no service point timezone was given, the timezone defaulted to the utility timezone.
Daylight Savings Time
BEACON automatically adjusts to Daylight Savings Time.
Fluid_Type tells BEACON whether a given meter measures water (the default) or gas. When this field is provided and GAS is entered:
- Gas_Sub_Count becomes a required field.
- Register_Unit_Of_Measure must be CUBIC_FEET.
Gas_Pressure_Compensation defaults to 1 if no value is provided.
Gas_Sub_Count is passed from BEACON to handheld meter reading devices and determines the index read (odometer value) displayed.
BEACON supports the following date formats:
Whether BEACON processes a given date as month/day/year or day/month/year depends on the Country and Language drop-down menu selections on the Assets>Utility Settings>Settings page.
For more on working with CSV files in Excel, click here.
Also note that BEACON dates come from the Unix world, which means that the world began on 1970-01-01. As a result, when imported, service agreements or meter histories that pre-date January 1, 1970 are rounded to 1970-01-01.
Previous Meter Column Names
Register_Resolution was previously named Read_Resolution.
Register_Unit_Of_Measure was previously named Register_Unit.
Meter_Install_Date was previously named New_Meter_Install_Date.
Meter_Install_Start_Read was previously named New_Meter_Start_Read.
Meter_Removal_End_Read was previously named Previous_Meter_End_Read.
Utilities that have been manually provisioning endpoints and using the drop-down menu to select a timezone might wonder how timezones are set using Data Exchange files. When using Data Exchange files, you can enter a timezone in the Service_Point_Timezone field or let BEACON automatically determine the timezone based on the Location address if the address is in North America. For utilities outside of North America and for locations that do not have ZIP or postal codes, the timezone defaults to a setting specific to the utility (typically, the timezone of the utility headquarters).
If you accidentally enter the wrong timezone, correct it by simply changing the value in the Service_Point_Timezone field and reimporting the Data Exchange file. Be sure your Data Exchange file includes at a minimum the following fields: Location_ID,
Service_Point_ID, Account_ID, Meter_ID and Service_Point_Timezone.
Daylight Savings Time
BEACON automatically adjusts to Daylight Savings Time.
District Metering Areas
Two fields in the Data Exchange specification let you designate Supply and Demand meters in District Metering Areas. DMAs let utilities monitor consumption across a water distribution network. In BEACON, such networks are defined by zones. A zone is a collection of Supply meters and Demand meters. Supply meters measure water flowing into a zone. Demand meters measure water being consumed within a zone. For more information, see DMA.
|District Metering Areas|
|Supply_Zone_ID||40||Identifier that designates a meter as a Supply meter in a DMA Zone.|
|Demand_Meter_ID||40||Identifier that designates a meter as a Demand meter in a DMA Zone.|
Key explanations: District Metering Areas Section
As their names imply, the Supply_Zone_ID and Demand_Zone_ID fields let you designate whether a meter is a Supply meter or a Demand meter in a given DMA Zone.
When modeling DMA zones, any given meter can:
- Belong to zero (0), one (1) or two (2) zones.
- Be either a Supply meter or a Demand meter in a given zone.
- Be a Supply meter in one zone and a Demand meter in another zone.
- Not belong to more than two zones.
- Supply meters cannot supply other Supply meters within a given zone.
- Demand meters cannot supply other Demand meters within a given zone.
If your DMA water distribution network uses daisy-chained zones, configure them as multiple zones in BEACON.
Typically, utilities use service agreements to track when people become customers or move in and out of locations. BEACON uses service agreement data to track what account is financially responsible for the service at a particular service point. BEACON uses the unique combination of an Account ID, Service Point ID and the start and end dates of a service agreement to know whether an account is active and when it has been terminated. The start and end dates affect the Account fields on Monitor page cards. In addition, service agreement start and end dates ensure that EyeOnWater users see only usage that belongs to them, not previous or future occupants of the same location.
Account_ID + start date + no end date = The account took over as of the start date.
Account_ID + start date + end date = This account was responsible for this service point from the start date through end date.
Account_ID + no start date + no end date = This account is responsible for this service point. When no dates are present, BEACON assumes the account is active as of midnight (23:59:59) on the day of the Data Exchange file was imported. “Midnight” is defined by the local time of the service point or utility.
Whenever possible, provide the SA_Start_Date and if appropriate SA_End_Date. If the importer detects an SA_Start_Date that was previously recorded and a new SA_Start_Date is not included in a successive Data Exchange file, the system uses the existing date. If, however, no date was previously given or the file is provisioning the account for the first time, when the file is imported, an the account is associated with a meter connected to an ORION Cellular endpoint, the SA_Start_Date defaults to the latest date that the endpoint was activated. For accounts associated with meters connected to any other supported endpoint type, missing SA_Start_Dates default to midnight (23:59:59) “today” in the service point timezone. If no service point timezone is given, the timezone defaults to the utility timezone.
If you provide a new SA_Start_Date, but do not give a corresponding SA_End_Date, BEACON uses the new service agreement start date as the end date of the old service agreement.
Providing an SA_End_Date that is in the future lets you anticipate a known customer move-out. If that customer has an EyeOnWater account, their access will be removed at the time the Data Exchange file containing the SA_End_Date is imported and processed, not on the SA_End_Date itself.
Previously, if you did not give SA_Start_Dates or SA_End_Dates in your Data Exchange files, when the file was imported, it did not matter which type of endpoint was involved. Missing dates defaulted to noon “today” in the service point timezone. If no service point timezone was given, the timezone defaulted to the utility timezone.
|Column Name||Max Length||Description|
|SA_Start_Date||10||Date service began. The combination of Account_ID, Service_Point_ID, and SA_Start_Date is a distinct, unique Service Agreement.|
|SA_End_Date||10||Date service ends. If present, this record is interpreted as a termination of the service agreement for the specified Account_ID, Service_Point_ID, and SA_Start_Date.|
This section of the Data Exchange Specification is for capturing details about the endpoints connected to the meters in your system. Some of these details are essential for obtaining accurate billing reads. For manually read meters that do not have an endpoint, leave these fields blank. When no endpoint serial number is provided, a service record is created for the account and location, and no provisioning takes place.
|Column Name||Max Length||Description|
|Endpoint_SN||20||Serial number of the endpoint paired with the specified meter.|
|Endpoint_Type||1||A letter or number indicating the type of endpoint used to read the meter. ORION Cellular (J or 4), ORION ME (N, M or 5), ORION SE (N or 5), ORION CE (Z or 6), GALAXY TR3 (G or 8), GALAXY TR2 (g or 7), Magnetic Barnacle (L or 3), Pulse Barnacle (K or 3) and Manually Read Meter (C).|
|Endpoint_Install_Date||10||Date the endpoint was connected to the meter specified by Meter_ID.|
|Endpoint_Removal_Date||10||Date the endpoint was removed from the meter specified by Meter_ID. When this value is present this record is interpreted as an unpairing of the endpoint from the meter.|
The Endpoint_SN (serial number) field acts as a unique identifier. For AMI systems, Endpoint_SN is a required field. For manually read meters without endpoints, leave this field blank or enter the letter C. Endpoint SNs can be any combination of letters, numbers and symbols that add up to no more than 20 characters. Typically, endpoint serial numbers are printed on the endpoints and are sometimes on a tag that a field technician can peeled off and attach to an Endpoint Installation form.
Key Explanations: Endpoint Configuration Section
For all non-manually read meters, Endpoint_Type is a required field. Enter either a single letter or a number to indicate the type of endpoint connected to the register at the particular service point and to enable data filtering on the Monitor page based on endpoint type.
This field is case-sensitive and supports the entries shown in the table below.
Enter either a letter or a number. Do not enter both.
(this field is case-sensitive)
(for billing vendors that cannot provide lower-case letters)
|ORION ME||N, M||5|
|ORION Mobile M||N, M||5|
|Manually Read Meter||C or blank||blank|
Because BEACON automatically detects the difference between ORION ME and ORION SE endpoints, ORION ME and ORION SE fixed network endpoints can both be marked as Endpoint_Type N. In addition, ORION ME and ORION Mobile M endpoints can marked as either Type N or Type M. When data is exported for an ORION ME endpoint, it will be marked as Endpoint_Type M.
When endpoints are marked as type C, the Endpoint_SN, Endpoint_Install_Date and Endpoint_Removal_Date columns are ignored.
While it is common to think of Endpoint Install Dates as the day the endpoint was put into a meter pit, Endpoint Install Dates actually refer to the day the endpoint was connected to the meter. This explains why BEACON automatically changes Endpoint Install Dates that come before the Meter Install Date to match the Meter Install Date.
In other words, if a meter change out occurs and the endpoint is not changed out, the Endpoint Install Date automatically becomes the date the endpoint was connected to the new meter.
Whenever possible, provide the Endpoint_Install_Date and if appropriate the Endpoint_Removal_Date. If no dates are given:
- If the importer detects an Endpoint_Install_Date that was previously recorded and a new Endpoint_Install_Date is not included in a successive Data Exchange file, the system uses the existing date.
If you provide an Endpoint_Install_Date but do not give a corresponding Endpoint_Removal_Date, BEACON uses the new endpoint install date as the removal date of the old endpoint
When a date is included in the Endpoint_Removal_Date field, BEACON automatically unprovisions the endpoint and uses the removal date as the cutoff.
Previously, endpoint and meter installation and removal dates could not fall outside of a given service agreement’s start/stop dates. And endpoints could not be installed on a date that came before the current meter install date. Now, endpoint and meter install/removal and service agreement start/stop dates are independent of each other.
Put another way:
If an endpoint or meter install/removal date fell outside the service agreement dates, the install/removal dates in the file were moved so they fell on the relevant service agreement date.
If an endpoint or meter swap was being performed, the old service configuration would be closed and a new service configuration would be opened as of the new endpoint/meter install date.
In addition, between September 18, 2018 and April 26 2021, for ORION Cellular and ORION Cellular LTE endpoints:
• If the file was provisioning an endpoint for the first time and no date was provided, the Endpoint_Install_Date defaulted to midnight (23:59:59) of the latest date that the endpoint was activated.
• If an ORION Cellular or an ORION Cellular LTE endpoint was previously provisioned, it behaved as all other endpoint types did. That is, the missing Endpoint_Install_Date defaulted to midnight (23:59:59) “today” in the service point timezone. If no service point timezone was given, the timezone defaulted to the utility timezone.
Behavior after September 18, 2018
Endpoint and meter install/removal dates are no longer constrained to the account/service agreement dates.
If an endpoint or meter install/removal date falls outside of the service agreement dates, the given dates are accepted by the system and have no effect on the service agreement dates.
If an endpoint or meter swap is performed, the dates in the file are accepted by the system and have no effect on the service agreement dates.
The fields in this portion of the Data Exchange Specification support manual and mobile meter reading.
|Column Name||Max Length||Description|
|Read_Sequence||10||A number that specifies the order of account records sent to collection devices. This number must be an integer (do not include decimal points). For manual meter reading, this is the walking order the meter reader will follow.|
|Alert_Code||2||A code between 01 and 99 sent to the collection device that represents a notification message to the meter reader.|
|High_Read_Limit||9||The maximum expected meter reading value. It is used to warn of a high reading. Should not be the same value as the Low_Read_Limit.|
|Low_Read_Limit||9||The minimum expected meter reading value. It is used to warn of a low reading. Should not be the same value as the High_Read_Limit.|
Use the Read_Sequence field to set the order of account records sent to collection devices and to tell meter readers the order or route to follow when manually reading meters. Read_Sequence values must be whole numbers, i.e. they must not include decimal points.
An Alert_Code is a two-digit number between 01-99 that notifies people performing meter reads of conditions at the location where the meter is located. Alert codes are defined on a per-utility basis. Once imported via Data Exchange (or Configured Import), alert codes are sent from BEACON to the mobile reading device with the work item assignment process.
|Sample Alert Codes|
|01||Beware of big dog.|
|02||Locked Gate – Contact security manager for entry.|
|03||Locked Gate – See comment for Access Code.|
|04||Meter under flower pot.|
|05||Meter in back of the house.|
High_Read_Limit and Low_Read_Limit fields in the Data Exchange Specification (or Configured Import) let you use whole numbers to designate expected high and low meter readings for any given location. The two numbers cannot be the same value. If a read falls outside one of those values, the reader will get an alert on their mobile reading device. Some billing systems use high/low reads to create exception reports. BEACON uses these values in support of mobile reading devices.
The Miscellaneous_Information fields let you pass information to BEACON that can help you link billing read records from BEACON when they are exported to your billing system.
|Column Name||Max Length||Description|
|Utility_Use_1||64||Miscellaneous information that is stored in BEACON and passed back in the billing file as received.|
|Utility_Use_2||64||Miscellaneous information that is stored in BEACON and passed back in the billing file as received.|
BEACON stores information entered in the Utility_Use_1 and Utility_Use_2 fields, but does not display it.
Rather, it passes the information in its billing read file exports. The purpose of these fields is to help link the billing read export to the utility’s billing system. Sample entries include the names of key fields or other meaningful information.
The _CLEAR_ Command
The Data Exchange process lets successive imports overwrite previous imports when their data fields overlap. That makes it easy to, for example, change or correct the name and billing address on an account by simply importing a new Data Exchange file that contains the correct information.
There are times when removing data from a particular field is desirable. For example, when one customer moves out of a location where you want to continue monitoring usage by leaving the account active (and optionally flagged as being vacant or unoccupied) while not exposing customer personally identifiable information (PII).
Removing data previously required you to enter a blank space to overwrite the data in a given field. That workflow has been replaced by the _CLEAR_ command, which lets you remove information that is already stored in the system.
- The _CLEAR_ command consists of the word CLEAR in all caps preceded and followed by an underscore exactly as shown. Do not include any spaces.
- To use _CLEAR_, simply enter the command in the field of interest.
- _CLEAR_ works on all but the following fields in the Data Exchange Specification for Accounts and Assets:
Account_ID, Location_ID, Service_Point_ID, Meter_ID, Endpoint_SN
Fields that cannot be empty
Service_Point_Type, Service_Point_Timezone, Meter_Manufacturer, Meter_Model, Meter_Size, Meter_Size_Unit, Meter_Continuous_Flow, Register_Number, Register_Unit_Of_Measure, Register_Resolution, Endpoint_Type
SA_Start_Date, SA_End_Date, Meter_Install_Date, Meter_Install_Start_Read, Meter_Removal_End_Read, Endpoint_Install_Date, Endpoint_Removal_Date
Account_Email, Account_Autopay, Account_BillerAutoPay, Service_Point_Timezone
Remember that updating IDs requires a special Data Exchange file, described here.
Because successive Data Exchange file imports overwrite previous Data Exchange file imports in fields where data overlaps, it is easy to correct mistakes. That said, when you need assistance from Badger Meter Technical Support, it is highly recommended that you do not email Data Exchange files to us, because they contain sensitive personally identifiable information (PII). Instead, let your Badger Meter Technical Support contact know the name of the file(s) you need help with and the date you imported them. The support contact will be able to securely pull the file directly from BEACON. In addition, if you have not accepted an import because you haven’t resolved an issue, do not cancel the import. Leave the file in the System Sync Import Module. Badger Meter Technical Support personnel can access the file from there.