Terminology

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:

• Accounts
• Locations
• Tags
• Service Points
• Meters
• Gas Meters
• Dates, Timezones & Daylight Savings Time
• District Metering Areas (DMA)
• Service Agreements
• Endpoints
• Mobile Reading Technology
• Miscellaneous Information

Specification Changes

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.

Accounts

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.

Account IDs

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.

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.

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.

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.

State Codes

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:

• MOR

Enter the code for Auvergne-Rhône-Alpes, France as:

• ARA

The code for Sjælland, Denmark can be entered as:

• 85

Or with the 2-character country code:

• DK-85

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.

Country Codes

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.

Location

“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.

Location IDs

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.

Tags

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.

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 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:

US/Pacific
US/Mountain
US/Central
US/Eastern
US/Alaska
US/Hawaii
US/Arizona
America/Halifax
America/St_Johns
Asia/Riyadh
Asia/Tokyo
Europe/London

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.

Meter

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.

Gas Meter

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.

Key Explanations: Meter Section

Meter ID

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:

• • 1. Do the Meter ID and Meter SN have to be the same? No. But they can be and often are.
    2. 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:

• • • Test Circle Codes HR-E Encoders (ENC-AS-00300-EN)
    • Test Circle Codes HR-E LCD Encoder (LCD-AS-00462-EN)
    • Test Circle Codes RTR (RDC-A-01)
    • To obtain the read resolution of encoders made by third parties, consult with their manufacturers.

Register_Resolution Changes
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.

Date Formats

BEACON supports the following date formats:

North American
YYYY-MM-DD
YYYYMMDD
MM/DD/YYYY
MM-DD-YYYY
M/D/YYYY
M-D-YYYY

European
YYYY-DD-MM
YYYYDDMM
DD/MM/YYYY
DD-MM-YYYY
D/M/YYYY
D-M-YYYY

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.

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.

Some examples:
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.

Endpoint Configuration

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.

Endpoint SN

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.

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 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:

Previous Behavior
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.

Manual/Mobile Reading

The fields in this portion of the Data Exchange Specification support manual and mobile meter reading.

Manual/Mobile Reading

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.

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.

Miscellaneous Information

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.

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:
  
  ID fields
  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_Or_Measure, Register_Resolution, Endpoint_Type
  
  Date fields
  SA_Start_Date, SA_End_Date, Meter_Install_Date, Meter_Install_Start_Read, Meter_Removal_End_Read, Endpoint_Install_Date, Endpoint_Removal_Date
  
  Miscellaneous
  Account_Email, Account_Autopay, Account_BillerAutoPay, Service_Point_Timezone

Remember that updating IDs requires a special Data Exchange file, described here.

Troubleshooting

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.