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

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 specification 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, over time, 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 current 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.

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 facility customer, they are typically given an account that is identified using an account number. Some call them customer numbers. Others say service numbers. Regardless what it is called, when used for budgeting/billing purposes, that number lets the facility and its customers keep track of transactions.

In AquaCUE, “Account Numbers,” “Customer Numbers” and “Service Numbers” are called “Account IDs.” Account IDs 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
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_City 64 Billing city.
Billing_State 2 Billing state.
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 facility directly, 0 for opted out or not using the facility 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 Account IDs in Data Exchange files can be up to 32 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).

1-account-3-locations2 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.

Account_ID Location_ID Service_Point_ID Meter_ID Endpoint_SN Endpoint_Type
1234 01 1 M1 123456789 J
1234 02 1 M2 123456780 J
1234 03 1 M3 132457687 J
Another way to use Account IDs is to assign them to locations. In fact, before Data Exchange file-based system synchronization was available, a 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.

Account_ID Billing_ Address Location_ ID Location_ Address Service_ Point_ID Meter_ID Endpoint_ SN Endpoint_ Type
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 for each entry, but do not duplicate the location addresses in the billing address fields. Instead, use the business’s billing address with each different location address.
Account_ID Billing_ Address Location_ ID Location_ Address Service_ Point_ID Meter_ID Endpoint_ SN Endpoint_ Type
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 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 facilities 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 portal user in an Data Exchange file, assign a single Person ID to the Account IDs they are responsible for.

Person_ID Account_ID Location_ID Location_Address Service_ Point_ID Meter_ID Endpoint_ SN Endpoint_ Type
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 optional field that lets facilities record the phone extension of an account holder. The value is not surfaced anywhere in AqauCUE, but can be used in a billing portal.

Account_Status is an optional field that lets facilities mark accounts as being active or inactive, regardless of Service Agreement start or end dates. After this data is passed to AquaCUE via a Data Exchange file, Monitor page filters select and count locations with Active or Inactive services.

Another optional field, Account_Portal_Status lets you hide or display an account in an online portal.

Use the Account_Billing_Cycle field to identify the cycle used for billing customers or sending them Water Focus Reports.

ZIP and Postal Codes

AquaCUE supports ZIP, ZIP+4 and international postal codes. 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 AquaCUE 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.
The Billing_Zip column was previously named Billing_Zip_Code.

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
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.
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, AquaCUE 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, AquaCUE 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, AquaCUE 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 AquaCUE 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 have been moved to streamline the Data Exchange Specification.

Tags
Column Name Max Length Description
Location_Building_Type* 64 Optional building type (e.g., ‘retail,’ ‘dining,’ ‘apartments’) label for faceting in AquaCUE Monitor.
Location_Building_Number 64 Optional building number label for filtering in AquaCUE Monitor.
Location_Site* 64 Optional site (e.g., ‘North Campus,’ ‘Uptown Village’) label for filtering in AquaCUE Monitor.
Location_Funding* 64 Optional funding label for filtering in AquaCUE Monitor.
Location_Main_Use* 64 Optional main use label for filtering in AquaCUE Monitor.
Location_Water_Type* 64 Optional water type (e.g., ‘hot,’ ‘cold,’ ‘potable,’ ‘reclaimed’) label for filtering in AquaCUE 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.
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_PopulationYear_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.

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

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 water service is provided–a “service point.”

SP vs. Service Point

For facility management organizations 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 along and the exact physical location of each meter hookup along with its timezone.

The Service Point portion of the Data Exchange Specification (shown in the table below) 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 along and the exact physical location of each meter hookup along with its timezone.

wikipedia.org/wiki/List_of_tz_database_time_zonesIf timezone is not provided, the timezone associated with the facility parent company specified via AquaCUE will be used.

Service Point
Column Name (for Oracle CC&B) Max Length Description
Service_Point_ID (SP_ID) 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.

Service_Point_Type (SP_Type) 1 Type of service being read. Water ( W ), Sewer (S), Gas (G), Electric (E), Fire (F), Irrigation (I) and Reclaimed/Recycled (R). If not specified, the default is Water (W).
Service_Point_Cycle (SP_Cycle) 12 An identifier used to denote the billing cycle name.
Service_Point_Route (SP_Route) 12 Identifier of the route or book the metered service belongs to. It is used by AquaCUE to group accounts for loading into collection devices or running reports.
Service_Point_Class_Code (SP_Class_Code) 12 Identifier for this service point’s billing classification/category in the billing system, e.g., residential, commercial, irrigation, etc.
Service_Point_Class_Code_Normalized (SP_Class_Code_Normalized) 24 The standard AquaCUE class code that the billing system class code corresponds to. Must be one of ‘Commercial,’ ‘FireService,’ ‘Industrial,’ ‘Irrigation,’ ‘Sewer,’ ‘SingleFamilyResidential,’  ‘MultiFamilyResidential’ or ‘Vacant.’
Service_Point_Latitude (SP_Latitude) 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.
Service_Point_Longitude (SP_Longitude) 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.
Service_Point_Timezone (SP_Timezone) 64 Name of the timezone where the service/meter is located, e.g. US/Pacific. For a list of timezone names see:
Service Point IDs In AquaCUE, 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. 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

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 the following 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 an Data Exchange file, Service_Point_Latitude and Service_Point_Longitude coordinates take priority over Location_Latitude and Location_Longitude coordinates and are displayed on the Location tab of each meter Card on the Monitor page.

Use the Service_Point_Timezone field to identify the timezone where the meter is located. If no timezone is given, the facility parent company timezone will be used in its place. For companies that deliver water service to locations that span different timezones, providing a Service_Point_Timezone gives AquaCUE and therefore your facility a more complete and accurate picture.

The Service_Point_Timezone field supports entries of up to 64 characters. AquaCUE 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.

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.

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.

Meter
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.)
Meter_Size_Unit 6

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

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.

Gas Meter
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 AquaCUE to handheld reading devices and determines the index read value displayed.
Meter ID Another unique identifier, Meter IDs can be up to 40 characters long and can include letters, numbers and symbols. Some facilities 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 AquaCUE Express customer outreach program • Enable filtering data based on Meter SN on the Monitor page. Meter IDs should change when the meter is changed out.

Key Explanations: Meter Section

The Meter_SN field is for recording the serial number engraved on the meter itself. Some facilities prefer to put the serial number of the encoder register attached to the meter in the Meter_SN field. Others use is 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.

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, describing its obscure location or recording 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.

Meter_Continuous_Flow is a boolean field. Entering a 1 tells AquaCUE that continuous flow is expected at the location. Leaving the field blank or entering a 0 tells AquaCUE 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.

Register_Resolution is another required field. It tells AquaCUE where the decimal goes in an encoder read. Getting the correct resolution–and recording it in AquaCUE–is essential for accurate customer budgeting. Register Resolution is based on a combination of factors: meter model and size, encoder type, unit of measure (gallon, cubic foot 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 ADE (RDC-A-02)
  • Test Circle Codes RTR (RDC-A-01)
  • To obtain the read resolution of encoders made by third parties, consult with their manufacturers.

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.

The Meter_Install_Date and Meter_Removal_Date fields help track meter changeouts. AquaCUE  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.

consumption-graph-two-meters The Consumption Graph above shows that a meter changeout 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 changeout 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 changeout. 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 noon “today” in the service point timezone. If no service point timezone is given, the timezone defaults to the facility timezone.

If you provide a new Meter_Install_Date but do not give a corresponding Endpoint_Removal_Date, Acquaue uses the new meter install date as the removal date of the old meter.

Previously, if you did not give Meter_Install_Dates or Meter_Removal_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 facility timezone.


Fluid_Type tells AquaCUE 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 AquaCUE to handheld meter reading devices and determines the index read (odometer value) displayed.

Date Formats

AquaCUE 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 AquaCUE 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>Facility Settings>Settings page.

A common mishap occurs when entering dates into a new spreadsheet, especially when using Microsoft® Excel®: Dates get reformatted from the supported ISO date formats shown. For example, Excel might display 2014-01-06 as 1/6/14. That format is not supported by AquaCUE. To correct the problem in Excel for Mac, choose Preferences>Edit and check “Preserve display of dates entered with four-digit year.” Excel for Windows gets its date preferences from the operating system. If you are using a different spreadsheet application, consult its owners manual.

Alternately, you can quote dates in CSV files. For example, use a text editor such as Notepad++ on Windows or Sublime Text on Mac OS to add double-quotes around “2016-04-04”. Make sure, however, that they are in fact inch marks, not so-called smart quotes by turning off smart quotes and smart dashes in the text editor.

Also note that AquaCUE 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.

Timezones

Facilities 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 AquaCUE Data Exchange is enabled, timezone is automatically determined by the Location address if the address is in North America. For facilities outside of North America and for locations that do not have ZIP or postal codes, the timezone defaults to a setting specific to the facility management company (typically, the timezone of the company headquarters). The setting is controlled by Badger Meter personnel.


District Metering Areas

Two fields in the Data Exchange specification let you designate Supply and Demand meters in District Metering Areas. DMAs let you monitor consumption across a water distribution network. In AquaCUE, 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
Column Name Max Length Description
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.
In addition:
  • Supply meters cannot supply other Supply meters within a given zone.
  • Demand meters cannot supply other Demand meters.
If your DMA water distribution network uses daisy-chained zones, configure them as multiple zones.

Service Agreement

Typically, facilities use service agreements to track when businesses or people become customers or move in and out of locations. AquaCUE uses service agreement data to track what account is financially responsible for the service at a particular service point. AquaCUE 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.

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, AquaCUE assumes the account is active as of noon on the day of the Data Exchange file was imported. “Noon” is defined by local time of the service point or facility management company.

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 noon “today” in the service point timezone. If no service point timezone is given, the timezone defaults to the facility management company timezone.

If you provide a new SA_Start_Date, but do not give a corresponding SA_End_Date, AquaCUE uses the new service agreement start date as the end date of the old service agreement.

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 facility management company timezone.

Service Agreement
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.

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 Configuration
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 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 installed on 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 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. 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. ORION CellularJ4ORION MEN, M5ORION SEN5ORION CEZ6GALAXY TR2g7GALAXY TR3G8Magnetic BarnacleL3Pulse BarnacleK3Manually Read MeterC or blankblank When endpoints are marked as type C, the Endpoint_SN, Endpoint_Install_Date and Endpoint_Removal_Date columns are ignored.

Whenever possible, provide the Endpoint_Install_Date and if appropriate the Endpoint_Removal_Date. If no dates are given:

For ORION Cellular endpoints:

  • If the file is provisioning the endpoint for the first time and no date is provisioned, the Endpoint_Install_Date defaults to the latest date that the endpoint was activated.Note: When provisioning ORION Cellular endpoints, the Endpoint_Install_date cannot come before the Meter_Install_Date. If you provide an Endpoint_Install_Date that pre-dates the Meter_Install_Date, AquaCUE will use the Meter_Install_Date as the Endpoint_Install_Date.
  • If the ORION Cellular endpoint was previously provisioned, it will behave as all other endpoint types do. That is, the missing Endpoint_Install_Date defaults 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.
For all other endpoint types:
  • 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.

Activation Dates

ORION Cellular endpoints are activated by a magnet swipe. ORION Cellular LTE endpoints are activated when they are connected to a register and detect flow for the first time, when they detect a register change by being unplugged from one register and plugged into a new register or via their IR communication port.


When a date is included in an Endpoint_Removal_Date field, AquaCUE automatically unprovisions the endpoint and uses the removal date as the cutoff.

If you provide an Endpoint_Install_Date but do not give a corresponding Endpoint_Removal_Date, AquaCUE uses the new endpoint install date as the removal date of the old endpoint.

Manual/Mobile Reading

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

Manual/Mobile Reading
Column Name Max Length Description
Read_Sequence 6 A number that specifies the order of account records sent to collection devices. For manual meter reading, this is the walking order the meter reader will follow.
Alert_Code 2 A code 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.
Low_Read_Limit 9 The minimum expected meter reading value. It is used to warn of a low reading.
Use the Read_Sequence field to set the order of accord records sent to collection devices and to tell meter readers the order or route to follow when manually reading meters.

An Alert_Code is a two-digit number that notifies people performing manual meter reads of conditions at the location where the meter is located. Alert codes are defined on a per-facility basis. Once set up in AquaCUE through the Data Exchange process, alert codes are sent from AquaCUE to the mobile reading device.

Sample Alert Codes
Code Description
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 let you designate maximum and minimum expected readings for any given location. If a read falls outside one of those values, the reader will get an alert on their mobile reading device.

Miscellaneous Information

The Miscellaneous_Information fields let you pass information to AquaCUE that can help you link billing read records from AquaCUE when they are exported to your information system.

Miscellaneous Information
Column Name Max Length Description
Utility_Use_1 64 Miscellaneous information that is stored in AquaCUE and passed back in the billing file as received.
Utility_Use_2 64 Miscellaneous information that is stored in AquaCUE and passed back in the billing file as received.
AquaCUE stores information entered in the Utility_Use_1 and Utility_Use_2 fields, but does not display it. Rather, Aquacue includes the information in its billing read file exports. The purpose of these fields is to help link the billing read export to the facility’s information 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 new _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 AquaCUE. 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.  

KNOWLEDGE BASE



User Guide