GridX Data Integration Specification

The GridX Data Integration Specification defines how all client source data should be mapped to the GridX Data Model. Each file type serves a distinct purpose and must abide by certain rules to achieve the greatest business value. All files should be provided as .csv, .psv or .tsv

Daily Digest 

Filename: GRIDX_{CLIENT}_DAILYDIGEST_yyyyMMddHHmmss

Suggested File Frequency: Daily. Blank files with no data are welcome when applicable

Overview: The Daily Digest file that contains a list of file names, file line counts, and the number of files that are sent by the client to GridX daily. The Daily Digest ensure all files and records are loaded.

File Specification

Customer Data

Customer  

Filename: GRIDX_{CLIENT}_CUSTOMER_yyyyMMddHHmmss

Suggested File Frequency: Daily. Blank files with no data are welcome when applicable

Overview: The Customer file provides the unique IDs that define utility customers their services. In order for the Rate Engine to accurately and reliably recreate billing calculations in the source CIS/CSS, GridX needs to map the customer data model in the source system to the GridX data model.

The GridX data model is based on two important concepts:

1. The Contract ID, which is the unit of tariff calculation and typically represents the service agreement with the customer

2. The MeterAccount ID, which represents the point of usage aggregation (i.e., all usage relevant for billing tied to the specific Contract ID

Everything above the Contract is for reporting/aggregation purposes, and everything below the Meter Account relates to meter and usage channel mapping.

Checklist:

• The Contract ID is unique for the tenant for all time
• The Contract ID is 1:1 with MeterAccount ID always (for all time)
• The MeterAccount ID is the entity that contains the “billable usage” for a given bill cycle
• The MeterAccount ID must be 1:many with Meter ID to support Meter Totalization use cases

File Specification

*DateTime fields can also be Date. In those cases, we interpret start dates to be the start of the 0th hour of the date and end dates to be the end of the 24th hour of the day. We interpret all date/time to be in the LOCAL time zone (unless data is explicitly provided in UTC time).

For the Contract_end_date, null is acceptable if the contract is active (has no end date).

MeterAccount Meter 

Filename: GRIDX_{CLIENT}_METERACCOUNTMETER_yyyyMMddHHmmss

Suggested File Frequency: Daily. Blank files with no data are welcome when applicable

Overview: The meter is the measurement device in the field that records energy delivered to customers (consumption) and received from customers (exported generation). The utility headend collects this measurement data and stores and validates (VEE) the data in the Meter Data Management System (MDMS).

At GridX, the Meter_ID represents the unique identifier for the device. GridX also has the concept of Meteraccount_ID which is the usage aggregation pointidentifier.

When the physical meter is exchanged (aka "meter swap"), the Meter_ID changes but the Meteraccount_ID does not.

When the Meter_ID is the primary key for the usage data extract, this file is required. If the Meteraccount_ID is the primary key for the usage data extract, this file is optional. If this file is not provided, GridX will be "blind" to meter swaps and will be unable to report out information regarding the Meter_ID.

Checklist:

• The MeterAccount ID is a 1:1 relationship with the Contract_ID for all time and represents the billable usage
• The MeterAccount ID must be 1:many with Meter ID to support Meter Totalization use cases

File Specification

*For the Meter_removal_date, null is acceptable if the meter is active (has no removal date).

Customer Attribute Data 

Filename: GRIDX_{CLIENT}_CUSTOMERATTRIBUTE_yyyyMMddHHmmss

Suggested File Frequency: Daily. Blank files with no data are welcome when applicable

Overview: An attribute is any fact about a customer or their service. These attributes provide basic customer information such as first name, last name, and address information. Attributes also describe the customer’s rate plan (rate code attribute) as well as any other facts that impact how the bill is framed and calculated (low income discount, special programs/riders, bill cycle).

In the GridX data model, the attribute can be attached at any level in the account hierarchy (for example, attributes can exist at the contract ID level, person level, servicepoint level, etc.). How these attributes are “attached”, as well as the time slices during which the attributes are effective, need to be provided in the extract.

Checklist:

• The ID_type matches the ID Type of the client source system
• Each attribute should be “time slice” data. If accurate start/end dates are not available in the source data, a discussion is required to agree on the best proxy

File Specification

Common Attributes

• Rate Code

• Bill Cycle (aka Read Cycle)

• Opt-in Rider/Program flag (e.g. NEM)

• Opt-in Rider/Program details (e.g. NEM Type)

• Voltage

• Phase

• Multipliers

• Premise Location (address, zip code, city, state, etc.)

• Customer Details (name, contact details, etc.)

• Industry type (SIC, NAICS)

• Low income designations (LIHEAP, CARE, FERA, deed-restricted affordable housing)

• Third party supply (boolean)

• Third party supplier (supplier name)

Example File

Bill Summary 

Filename: GRIDX_{CLIENT}_BILLING_yyyyMMddHHmmss

Suggested File Frequency: Daily. Blank files with no data are welcome when applicable

Overview: This file contains the billing summary data for customers such as the billed usage and billed amounts.

Checklist

• The bill_id represents the unique set of charges for a contract for a given bill cycle. This is different from a “pdf bill” or “invoice”
• For example, a typical Residential Customer may receive a single pdf bill (aka “invoice”) with their electric and gas charges. This represents 2 GridX bill_ids (1 gas, 1 electric). For Oracle CCB/C2M, the GridX bill_id maps to the bseg_id.
• The bill_id is unique for the tenant except for cancel/rebill
• The bill_year and bill_month should match the client source system. This is especially important for clients with SAP and CIS’s that use bill month to define seasons and price changes. Note the bill month may not align with the bill start/end dates depending on the CIS.
• For a given contract_id, all bill_id’s must be continuous. This means the start date of each bill should be exactly 1 day after the end date of the previous bill
• The GridX bill_start_date starts at the beginning of the day (00:00)
• The GridX bill_end_date ends at the end of the day (23:59:59; “inclusive”)

File Specification

Cancel / Rebill

GridX Standard Cancel/Rebill process is as follows:

1. A bill is provided according to the ICD above. At this time, it is not known that the bill will later be cancelled

2. A record for the same bill_id is provided with Is_cancellation = 1. The bill is now cancelled.

3. The rebill is provided with a different bill_id from the cancelled bill

Additional detail here: https://gridxissues.atlassian.net/wiki/spaces/PROD/pages/8905755352/Billing+Cancel+Rebill

Bill Details 

Filename: GRIDX_{CLIENT}_BILLINGDETAIL_yyyyMMddHHmmss

Overview: The Billing Details interface allows GridX to compare its rate model calculations at bill line item level (“Level 2 Calibration”). If a GridX-calculated bill does not match the Total Bill Amount in the Billing Data Extract, GridX uses the Billing Details data to determine which part of the GridX-calculated bill does not match. Once the issue is identified, it is categorized and assigned to modeling for further analysis.

-for each row that has Bill ID, the sum of all those rows should equal to total of Bill amount in 'Bill Header'

Suggested File Frequency: Daily. Blank files with no data are welcome when applicable.

Checklist

• The bill_id represents the unique set of charges for a contract for a given bill cycle. This is different from a “pdf bill” or “invoice”
• For example, a typical Residential Customer may receive a single pdf bill (“invoice”) with their electric and gas charges. This represents 2 GridX bill_ids (1 gas, 1 electric). For Oracle CCB/C2M, the GridX bill_id maps to the bseg_id.
• The bill_id is unique for the tenant except for cancel/rebill
• The bill_year and bill_month should match the client source system. This is especially important for clients with SAP and CIS’s that use bill month to define seasons and price changes. Note the bill month may not align with the bill start/end dates depending on the CIS.
• For a given contract_id, all bill_id’s must be continuous. This means the start date of each bill should be exactly 1 day after the end date of the previous bill
• The GridX bill_start_date starts at the beginning of the day (00:00)
• The GridX bill_end_date ends at the end of the day (23:59:59; “inclusive”)
• The charge_code must map to one charge type per tariff. For example, if charge_code = 123 maps to “on-peak energy”, charge_code = 123 cannot be used for any other charges
• (Line_item_quantity * Line_item_price) = Bill_line_item_amount
• For each bill_id, the sum of all Bill_line_item_amount should equal the Total_bill_amount in the 'Bill Summary' interface

Interval, Register and Usage Data 

Interval & Register 

Filename:
GRIDX_{CLIENT}_INTERVAL_yyyyMMddHHmmss

GRIDX_{CLIENT}_REGISTER_yyyyMMddHHmmss

Overview: The interval file consists of meter data collected at defined intervals, typically every 15 or 60 minutes. The interval file contains energy delivered, received and other meter reads such as kVA and kVARh.

This interface can also be used for Register reads that provide cumulative meter reads (similar to a car odometer) typically at a frequency of once per day or once per bill cycle. The sum of the interval data should match the register usage for the same channel and time period.

Suggested File Frequency: Daily. Blank files with no data are welcome when applicable. This file can be divided into multiple files and delivered in one day if size is an issue.

Checklist

• The MeterAccount ID must be 1:many with Meter ID to support Meter Totalization use cases
• GridX interprets interval timestamps as “start of interval” whereas most utilities interpret as as “end of interval”. The client must confirm the nature of their interval data in writing.

*The interval data can be stored using the ID for the physical device (i.e. meter) or the usage point. Only one ID is required.

Billing Determinant Usage (Optional)

Filename: GRIDX_{CLIENT}_BILLDETERMINANTS_yyyyMMddHHmmss

Overview: The billing determinants file consists of billed usage values framed by bill cycle periods. The Billing Determinants file contains energy consumption as well as energy generation/exports per season and time-of-use period.

Rate Modeling Data

Billing Cycle 

Filename: GRIDX_{CLIENT}_BILLINGCYCLE_yyyyMMddHHmmss

Overview: This file provides the SYSTEM billing cycle for the customers that determines the billing period being billed for that customer. Useful for Bill forecasting and reframing customer bills for rate analysis.

Suggested File Frequency: Annual. Blank files with no data are welcome when applicable.

Checklist

• The bill cycles are continuous for a given Read_Cycle, meaning there are no gaps between the Billing_Cycle_End_Date and the next Billing_Cycle_Start_Date
• The corresponding attribute is provided to map customers to their Read Cycle
• The bill_year and bill_month should match the client source system. This is especially important for clients with SAP and CIS’s that us bill month to define seasons and price changes. Note the bill month may not align with the bill start/end dates depending on the CIS.
• This file is required when billForecast is in-scope.

Rate Values 

Filename: GRIDX_{CLIENT}_RATEVALUES_yyyyMMddHHmmss

Overview: Rate Values provides all the specific values used in the billing system to bill customers.

This file can be provided daily or each time a rate value changes.

Suggested File Frequency: This file can be provided daily or each time a rate value changes.

Event Data (Optional)

Filename: GRIDX_{CLIENT}_EVENT_yyyyMMddHHmmss

Overview: Utilities may or may not have demand response events that affect rate calculations. This file contains details of any specific events that occur such as the Critical Peak Pricing (CPP).

Suggested File Frequency: Daily. Blank files with no data are welcome when applicable.

*If the event start time and end time are always the same, this field is optional

Network Details (Optional)

Filename: GRIDX_{CLIENT}_NETWORK_yyyyMMddHHmmss

Overview: A Network is a relationship between customers (technically, a many-to-many mapping) that defines how certain usage and/or billing determinants are to be allocated from one set of customers to another. The most common use case for this is Community Solar - where one Host installation allocates its generation to a set of Subscribers, each of whom receives a percentage of the total generation. This could also be used for complex or virtual net metering (VNEM) where one or more installations can be the "generator" and one or more installations can be the "recipient".

Suggested File Frequency: Daily. Blank files with no data are welcome when applicable.