Best Practices
Best Practices Approved by the IWG
The IWG has approved Best Practices, which are guidelines supported by research and experience, leading to optimal outcomes when followed. They represent the most efficient or prudent course of action in a given business situation.
In Ontario, the initial iteration of Green Button standards draws from past experiences with similar systems or lessons learned from other jurisdictions. The IWG recommends implementing these best practices where Distributors can do so without undue burden or interfering with their other regulatory responsibilities, and where it does not contradict other Utility best practices.
The IWG or its sub-working groups have publicly decided on these Best Practices at the IWG meetings. For other considerations discussed, please refer to Appendix A: Non-Consensus Best Practices Item.
The below Best Practices are publicly available on the OEB’s Industry-led Work Group pages at the Ontario Energy Board. We have made it easier to find and search them. This page will be updated as required. The OEB website is considered the source of the content, and if there is any discrepancy, please consider the OEB as the source of truth. If you find any missing Best Practices or differences in material from the OEB website, please contact us, and we will consider your input and make the change as required.
Unanimously Approved Best Practices
Best Practices approved by all participants in the OEB IWG meetings.
- Simple KPIs
LDCs shall provide key performance indicators (KPIs) to OEB on a quarterly basis similar to the following:
• Number of third parties in the onboarding process
• Number of third parties that have completed all onboarding and are available to any customer
• Number of one-time customer authorizations via GBCMD (by usage / billing / account info)
• Number of ongoing customer authorizations via GBCMD (by usage / billing / account info)
• Number of account holders with one authorized Third Party vs. two or more
This is a best practice, not a requirement at this time. The expectation is that these should not be mandated
by the regulatory deadline due to the time and effort involved to implement.Why?
o OEB and the Ministry will want information to judge the utilization levels of GBCMD across the province - Best available billing data
LDCs shall provide electric and gas billing data that (1) is consistent with the bills delivered thorough portals
including e-billing (historically and into the future); (2) include all bill corrections & changes; and (3) are updated to the Third Party as soon as possible when updates occur. This recommendation does NOT impose new billing or metering requirements on LDCs, but rather ensures symmetry in the quality of bill information available from LDCs to Third Parties and account holders.Why?
• Must be compliant with the Regulation and OEB guidance
• There is a need for high accuracy of billing information for decision-making
• Bills are required in normal business practices and are used as official receipt. Thus, the billing data provided via Green Button should be consistent with the “energy data” (as defined by Regulation) on the bills.
• Bill data is already used by 3rd parties and account holders and it is always assumed that the bill is the
official receipt which is used for payment, auditing and informational / operations purposes. - Data, Functionality or Interface Changes
Utilities should provide advanced notice to registered third parties about substantial changes to Green Button CMD implementation involving energy data, functionality or interface changes.
Changes include, but are not limited to:
• New bill types or billing plans
• New data types added to CMD that are not captured or capturable in v3.3 of the standard
• Changes in certification, including changes to pass/fail status of individual certification tests
• Customer user interface modifications such as new web pages in the authorization flow or
interstitials; the addition of multi-factor authentication requirements; or substantial deviation
from UX best practices established by the IWG
Why?
• Un-noticed significant changes will drive costs and uncertainty, triggering support requests.
• Customer education materials about the consent process will need to be modified. - Additional Scope ParameterRecommendation: The Utility should provide an alternative digital process wherein a customer visiting the website will have the ability to identify themselves without requiring creation of an online account in the Utility’s customer portal. The personal information required to establish identity should be consistent with the Utility’s standard practices.
Why?
• Some customers who wish to share their data in Green Button format with a Third Party will not have an online account (My Account portal), nor a desire to register for one. • Digital processes can be designed to accommodate an accountholder sharing their data via a “one-time login” or something similar. • Establishing identity in this manner should not be more onerous than establishing identity in creating a “My Account,” i.e., the personal information required should be consistent between these two methods. - Customer Experience Begins at the Third Party’s WebsiteRecommendation: In Green Button Connect My Data, the customer experience begins at the Third Party’s website. Then the user is redirected to the Utility. If the customer is not already logged in to the Utility, the customer must first authenticate, using the Utility’s standard procedure(s). Once authentication is successful, then the authorization screen should be one web page. Finally, the user is redirected to the Third Party’s website to complete the transaction.
Why?
• In other jurisdictions, Utilities designed very different user journeys without standardization. • Failing to be specific at the outset about the customer “flow” can result in customer confusion and wasted effort. - Customer Notifications
Recommendation: Customer Notifications. Where the account holder has provided a valid email
address, Utilities should send an initial authorization confirmation by email, but thereafter are not
required to send periodic reminders to customers about the Third Parties they have authorized.
Why?• The authorization form should advise the customer that Third Parties will have access to their
data until such time as the customer revokes the authorization and advise the customer that they
can revoke the authorization at any time.
• Customers should receive a confirmation by email after a successful authentication and
authorization. This communication will allow the customer to review and validate their actions.
• Customers should be able to see which Third Parties they have authorized via the existing
online customer portal, with links to documentation on how to amend or rescind an
authorization.
• Notifications should align with Utility current best practices to avoid customer confusion. - Customer Take it or Leave itRecommendation: General description: Distributors should support the concept of “take it or leave it” scopes of authorization that are presented to customers. Data types should be selectable or unselect able by the customer depending upon the Third Party’s dynamic selection. (Note: This would not apply to meter/service selection, which must always be chosen by the customer.) See examples in previous Best Practice recommendation. Technical description: Distributors should support “noedit” as a parameter in “AdditionalScope.” The Third Party may or may not include “AdditionalScope” in its authorization request, but if included, Distributors should honour it, making the data types fixed and unchangeable by the customer.
Option #1
Option #2– Take it or Leave it
Why?
• If a Third Party requires, for example, 24 months of usage history to deliver their product, it doesn’t make sense for the customer to unknowingly reduce the history to 3 months, rendering the product non-functional. (Note: if the customer moved in only 2 weeks ago, then only 2 weeks of history will be provided regardless.) • A frustrating user experience would result in a back-and-forth between Distributor and Third Party if the authorized scope is not sufficient for a particular product being offered. • Other jurisdictions (California, New York) have adopted “noedit” as a best practice for this reason. - Customer Without
Internet AccessRecommendation: For customers without internet access, the Utility should establish both telephone
and/or paper form-based processes whereby a customer can grant a data-sharing authorization (or
revocation). For technical implementation of this recommendation, OAuth2.0 standards shall be
followed, consistent with ITWG guidance.* In the case of telephone authorizations, Utility staff should
assist the customer to meet the authentication and authorization requirements. (The intent of this
recommendations is not to resolve or address the mechanism of bulk authorizations).
* Telephone or paper methods will be available based on customer type following standard Utility
practices. For example, Utilities may prescribe paper forms for large commercial customers but support
telephone authorizations for residential customers.
Why?
• Green Button implementations are digital tools; however, we anticipate a small number of
customers who do not have Internet access, will want to share their data with Third Parties. To
ensure confidentiality and accountability in a telephone call, this is best handled by the Utility
staff, who have access to the customer’s information.
• Business customers may want to use paper forms to ensure that internal approvals are correctly
obtained. - Data-Request Performance
Recommendation: With respect to data-request performance, the consensus is that “Historical
Requests” would be processed by Utilities as soon as possible based on current processing load. This
means that it is expected that requests would be fulfilled near real-time or within a few hours if the
request came at a peak time (precluding outage windows).
Why?
• There is a mechanism to alert Third Parties to new data being available from a Utility;
therefore, it is expected that large data requests are not needed on a regular basis.
• Most Utility systems utilize a batch cycle process, which means that data does not change, or is
not made available on a continuous basis and therefore, does not require real-time response.
• Data integration methods for some Utilities may be predicated on other Third Parties (e.g.,
IESO MDM/R). - Detailed Handling of Account Information Selection During Authorization ProcessRecommendation: If the Customer removes Account Information from the Authorization screen before Authorizing access to the Third Party, the response from the Authorization Server Token Endpoint should not contain any Retail Customer Function Block values (FB_51, FB_53 – FB_70) in the returned scope parameter, nor include a customerResourceURI element. See diagram example below.
Why?
• The presence of a customerResourceURI element in the access token response provides the Third-Party application greater authorization than indicated by the Customer.
• The presence of Retail Customer Function Block values in the returned scope parameter provides the Third-Party application greater authorization than indicated by the Customer. - Detailed Handling of Appearance of Account Information on Authorization Consent FormRecommendation: If the OAuth 2.0 Authorization Server Authorize Endpoint request contains a scope parameter without a Retail Customer Function Block (e.g., FB_51, FB_53 – FB_70) element, the customer’s Authorization screen should not allow them to access the Account Information checkbox. See diagram example below.
Why?
• The lack of Retail Customer Function Block elements in the scope parameter indicates the Third Party is not interested in Account Information.
• Addition of Account Information by the customer violates the OAuth 2.0 access token standard by granting the Third Party more authorization than they have requested.
• Addition of Account Information by the customer provides additional data the Third-Party application will not use and may cause software issues. - Detailed Handling of Appearance of Billing Information on OAuth Authorization FormRecommendation: If the OAuth 2.0 Authorization Server Authorize Endpoint request does not contain a scope parameter with a Billing Information Function Blocks (e.g., FB_15, FB_16, FB_27, FB_28 element present, the customer’s Authorization screen should not allow them to access the Billing Information checkbox. See the diagram example below.
Why?
• The lack of any billing information function blocks in the scope parameter indicates the Third Party is not interested in Billing Information. • Addition of Billing Information by the customer violates the OAuth 2.0 access token standard by granting the Third Party more authorization than they have requested. • Addition of Billing Information by the customer provides additional data the Third-Party application will not use and may cause software issues. - Detailed Handling of Appearance of Energy Usage
on Authorization OAuth Authorization FormRecommendation: If the OAuth 2.0 Authorization Server Authorize Endpoint request contains a scope parameter without an Energy Usage Function Block (e.g., 1, 3-12, 29, 34-40) element, the customer’s Authorization screen should not allow them to access the Energy Usage checkbox. See diagram example below.
Why?
• The lack of Energy Usage Function Block elements in the scope parameter indicates the Third Party is not interested in Energy Usage information.
• Addition of Energy Usage by the customer violates the OAuth 2.0 access token standard by granting the Third Party more authorization than they have requested.
• Addition of Energy Usage Information by the customer provides additional data the Third-Party application will not use and may cause software issues. - Detailed Handling of Authorization Consent Form Rendering with Use
of no Edit AdditionalScope ParameterRecommendation: If the OAuth 2.0 Authorization Server Authorize Endpoint request contains a scope parameter ‘additionalScope=noEdit’ element the customer should only be allowed to Deny or Authorize the request. They should not be able to make any modifications to the request on the Authorization screen. See diagram example below.
Why?
• The use of the ‘additionalScope=noEdit’ element in the scope parameter indicates the data being requested is required by the Third-Party application to function properly.
• Any additional data the customer Authorizes violates the OAuth 2.0 access token standard by granting the Third Party more authorization than they have requested.
• Any additional data the customer Authorizes the Third Party beyond what they are requesting will not be used by the Third-Party application and may cause software issues.
• Any reduction of the requested data by the customer likely will limit or prevent the Third-Party application from properly functioning. - Detailed Handling of “Energy Usage” Selection During Authorization ProcessRecommendation: If the Customer removes Energy Usage from the Authorization screen before Authorizing access to the Third Party, the response from the Authorization Server Token Endpoint should not contain any Energy Usage Function Block values (FB_1, FB_3 – FB_12, FB_29, FB_34 – FB40) in the returned scope parameter, nor include a resourceURI element. See diagram example below.
Why?
• The presence of a resourceURI element in the access token response provides the Third-Party application greater authorization than indicated by the Customer.
• The presence of Energy Usage Function Block values in the returned scope parameter provides the Third-Party application greater authorization than indicated by the Customer. - Detailed Handling of Billing Information Selection During Authorization ProcessRecommendation: If the Customer removes Utility Billing from the Authorization screen before Authorizing access to the Third Party, the response from the Authorization Server Token Endpoint should not contain Function Block 15, 16, 27 and 28 (i.e., billing information function blocks) values in the returned scope. See diagram example below.
Why?
• The presence of billing information function block values in the returned scope parameter provides the Third Party application greater authorization than indicated by the Customer. - Electric Consumption in Interval Blocks
Recommendation: Electric consumption in IntervalBlocks should be reported as per the definition in the Retail Settlement Code, section 11.3.
Why?
• This will provide consistency for all users of the data and ensure they do not have to adjust different periods of time or between data sets.
• It will ensure consistency in how data is supplied by Green Button solutions as compared to EBT purposes. - Maintenance Windows
Recommendation: Maintenance windows. Utilities should make best efforts to notify external parties
of regularly scheduled maintenance windows, that would impact the ability of apps to retrieve data.
Unscheduled emergency maintenance is not included in the notification process.Why?
• Will allow Third Parties to schedule routine maintenance to coincide with Utility maintenance windows, minimizing impact to consumers.
• Third party vendors can communicate with consumers if the schedule is known in advance.
• The priority during emergency outages or outages outside of the Utility’s control is on returning
systems to normal operations. - Pre-printed/Pre-formatted Information
Recommendation: Pre-printed/pre-formatted information that is supplied as part of the utility bill but
is static or mandatory in nature (e.g., HST registrant number, bill terminology definitions, E&OE
terms, etc.) does not have to be supplied within the Green Button data loads.Why?
• This information is standard for all the customers in a given Utility and may not be in electronic
form (e.g., may be on pre-printed paper stock or pre-formatted design templates for e-bills).
• The information is not specific to each customer’s account or energy usage.
• The information is not relevant to Third Parties consuming energy or account data for analytics
purposes.
• The information is available publicly through other means (e.g., “What does my bill mean”
examples on Utility websites) or to the customer directly through their regular bill. - Providing TOU to Tiered Comparison in Green Button Format
Recommendation: Providing TOU to Tiered comparison in Green Button format is not within scope
of the Ontario Green Button implementation.Why?
• Bill comparison between Tiered and TOU rates is a complex data analysis process. The
algorithm calculates the cost differential based on a customer’s historical usage at the current
Tiered and TOU rates.
• Green Button data being provided will allow a Third Party to develop the same features in their
application if this were something that would add value to their product.
• Consumers have existing tools to see a bill comparison, through the OEB rate comparison tool,
or via existing Utility customer portals. - Providing Weather Data in Green Button format
for Electric or Gas UtilitiesRecommendation: Providing Weather Data in Green Button format for Electric or Gas Utilities is not
within scope of the Ontario Green Button implementation.Why?
• Weather data is provided on some customer portals, but the Utility is not the source of this data,
and it is not stored in the Utility systems. It is generally a real time API interface with
Pelmorex (The Weather Network).
• Providing weather data would add complexity and cost to the Green Button solution. - Real Time Account Balance
Recommendation: Real-time account balance information is not within scope of the Ontario Green
Button Implementation.Why?
• Utility CIS systems do not store a running account balance. The customer’s current balance is
calculated ‘on the fly’.
• It is sufficient to provide the information that shows on the last published bill, i.e., Amount
Owing. - Regulation Requirement
for Energy and Account Holder InformationRecommendation: Under the Green Button Regulation, Distributors are required to make energy
usage and account holder information available in Green Button format. As a general principle, the
information to be made available is information identified in the NAESB ESPI standard, and where the
Utility is the authoritative source of the data that is collected and made available to its customers in the
normal course of its operations.Why?
• Data requirements that are outside of the scope of Green Button standards could necessitate a
Utility having to make changes to their operational practices, with limited or no cost recovery.
• Data that is not identified in the NAESB ESPI standard, cannot be provided within the context
of the NAESB standard XML schemas.
• Aside from commodity costs that Distributors bill and collect from consumers on behalf of
Electricity Retailers, providing any Third-Party charges that appear on the bill but do not
originate from the Utility should not be considered within scope of the Ontario Green Button
implementation. - Utility Grid Work /
Service Outage InformationRecommendation: Utility Grid work / Service Outage information Requirements is not within scope
of the Ontario Green Button implementation.Why?
• Outage information varies from one Utility to the next, and not all Utilities have software
systems dedicated to the automated management of outage notifications.
• Outage information is provided to customers via existing channels, for example My Account
customer portals and through social media.
• Outage information is not identified within the NAESB ESPI standard. - Vocabulary of Scope SelectionRecommendation: The presentation of data elements included in the customer authorization screen should be consolidated and standardized into the following categories:
- “Electric usage”
- “Gas usage”
- “Billing”
- “Account information, which contains personally identifiable information”
Note: Only the categories requested by the third party will appear. E.g., if “Billing” is not requested, it will not appear.
Why?- Reflects identified best practices in other jurisdictions.
- This will allow standardization in terminology between different utilities across the province.
- Provides clear, concise, consistent verbiage for customer authorization process in defining the data being shared.
Non-Consensus Best Practices
Best Practices where at least one party in the OEB IWG working group meeting did not approve the Best Practice and reason why
- Bad Actors & Notifications
Submitted by: IUXWG
Non-Consensus – IWG
Background on Issue: This issue focuses not on the enforcement procedures involving Third Parties
that have breached Utility terms and conditions and become “bad actors.” Rather, this issue is focused
on the question of what notifications to various parties should be triggered in various cases:- What is the notification mechanism when a Third Party is deemed a bad actor?
- What is the notification mechanism when a bad actor has been “reformed”?
Below is a helpful escalation model from other jurisdictions:
Recommendation: For this recommendation, the following terms apply:
(A) “Suspicion” means a utility gains a reasonable suspicion that a third party has violated the terms between utility and third party.
(B) “Suspension” means a utility temporarily halts some or all data transmission to a third party due to verified term violations or an imminent potential violation.
(C) “Termination” means a utility halts all ongoing data transmission to a third party due to a final determination of a terms violation.
A- Suspicion should not result in customer notifications.
B- Suspension should trigger prompt notification to third party.
C- Termination triggers notifications to affected customers and the Third Party.• A “redeemed” Third Party should trigger notifications to the Third Party and customers who had active authorizations at the time of suspension or termination.
• Utilities can contact OEB about any of the above as needed.
• Utilities should provide an optional mechanism for non-residential customers to receive notifications if their Third Party is suspended.The processes of “suspension,” “termination” and “redeeming” a Third Party are not prescribed by this recommendation.
Why?
• Uniform expectations for notification procedures across Utilities are helpful to everyone.
• Third party business reputations could be unfairly damaged by notifying customers of suspected, but not verified, wrongdoing.Non-Consensus Reason:
• Per the Green Button Implementation – Draft OEB Staff Guidance letter sent on October 12, 2021, OEB staff notes it would generally not be a Distributor’s role to monitor the behaviour of a Third Party once the customer agrees to share their data with the Third Party. Rather, it is the Third Party’s responsibility to manage the data under its own privacy policies and legal or regulatory requirements.• While not required to monitor the behaviour of Third Parties, Utilities understand the importance of protecting their internal systems, their customers and the Green Button data, and may terminate the authorization for a given Third Party if there has been a significant violation of the terms and conditions under which access to the energy data was provided.
• The proposed steps (suspicion, suspension, termination) seem logical, but Utilities need flexibility to establish their own process based on their legal advice and operating procedures, for actions they would take in cases where a Third Party is in violation of the Utility Terms and Conditions.
• Utilities feel strongly that the business relationship is between the customer and the Third Party. Third party organizations have a responsibility to communicate with their customers on all matters related to their business.
• Some form of notification to the OEB makes sense. As the Regulator, they should be aware of potential risks to Ontario consumers, and the steps being taken to protect them. Notification of other Utilities would not be appropriate. The OEB has stated that Utilities can accept or reject a Third Party based on their individual terms and conditions. If a Third Party violates one Utility’s Terms and Conditions, that doesn’t mean they would be in violation of another
Utility’s Terms and Conditions. A concern is that communicating your actions to other Utilities could lead to legal action by the Third Party.• We do not agree that Utilities should be required to notify customers about the suspension or termination of a Third Party. The Third Party is responsible for doing this. This would be a significant increase in in scope from what is documented in the Regulation and OEB guidance. Green Button solutions and/or CIS systems would require customization to support this, which adds complexity, time and cost to the Utility’s Green Button implementation. Utilities are committed to meeting the implementation timeline, but we need to move forward with implementation to do so.
- Best Available Meter Data
LDCs shall provide electric and gas usage readings that (1) are up to date to the best of their knowledge at
the time of transmission; (2) correctly use the QualityofReading attribute to denote reading quality; and (3) are
updated to the Third Party as soon as possible when updates occur. This recommendation does NOT impose
new metering, meter reading or validation, editing and estimation (VEE) requirements on LDCs, but rather
ensures symmetry in the quality of usage information available to both LDCs and Third Parties.
Why?
o Third Parties need to know the level of accuracy of the usage data they received for decision-making and
settlement.
o There is a need to strike a balance between 100% accuracy (which is impossible) and 0% accuracy (which
is unworkable), recognizing the complexities of VEE
o This is not a prohibition on estimated readings. Estimated reads should be properly marked using
QualityOfReading.
Reason(s) for Non-Consensus: Already assumed to be part of the implementation. No need for Best Practice - Data Errors & Updates
1. Billing data updates shall be handled via Rec #2023-02.
2. Electric and gas usage data updates shall be handled via Rec #2023-01.
3. Notifications:
1. LDCs should handle all updates and errors as soon as possible via established Green Button processes (e.g., pub/sub notification,
bulk transmission via REST, etc.)
2. Should any errors or updates require LDCs to take manual corrective action, then the LDC shall timely notify the affected Third
Party and explain the circumstances (e.g., complex account number changes that result in re-issuance of bills).
Why?
• Regulation 633/21 defines “energy data” as available to the account holder. This process helps resolve discrepancies with
Green Button data, if they surface.
• OEB asked for clarity.
• Manual fixes will trigger a notification to the Third Party, whereas updates in the normal course of business (such as to billing or usage
data) will occur automatically using established Green Button procedures.
Reason(s) for Non-Consensus:
Utilities would like further review of this information, including a review of the Regulation, and are not prepared to pass this Best Practice at this
time.
Utility Vendors and Green Button Providers would like further review and are not prepared to pass this Best Practice at this time - Distributors to Prevent Inadvertent
Termination of Data FlowsSubmitted by: IUXWG
Non-Consensus – IWG
Recommendation: A best practice is for Distributors to prevent inadvertent termination of data flows
due to meter changeouts and "legitimate" account number changes (e.g., CIS upgrades).
Why?
• In the past, some commercial customers with hundreds/thousands of meters have experienced revocations of data-sharing without their knowledge.
• Several Distributors are planning imminent upgrades to their CIS, and customers want to ensure their data-sharing is as seamless as possible.
Non-Consensus Reason:
• Green Button data users also want the best practice to apply to Utility mergers. Their rationale
is that the administrative burden of ensuring continuity of consumption data should be the Distributor’s responsibility, not the customers’.
• Distributors disagreed, saying it is not always technically possible.
• IUXWG requests OEB guidance with additional input from all interested Parties. - Standardized
Letter of AuthorizationSubmitted by: IUXWG
Non-Consensus – IWG
Recommendation: In order to support large, multi-site customers, Distributors should accept a standardized letter of authorization (LOA) so that customers can fill out a single form and send it to multiple Utilities for processing.Why?
A standardized form provides (i) significant administrative efficiencies to larger customers spanning
multiple Utilities and (ii) consistency across Ontario’s electricity providers.Non-Consensus Reason:
• Utilities believe manual authorization forms should only be supported for customers without internet access, and a large volume of LOAs will become unmanageable and distracting from the core web-based Green Button solution.
• Utilities believe it is impractical to standardize the form given that each Utility may have unique authentication requirements and legal terms and conditions. - Source of Truth for Smart Electric Meter Usage Data
1. For customers with less than 50kW peak demand, electric usage data provided via CMD shall match with the Smart Metering
Entity (SME) after a bill has been generated. Electric usage data sent *before* a bill has been generated is considered not final.
Why?
• Regulation 393/07 grants the SME exclusive authority on electric meter usage data validation. Ratepayers already pay for this
function.
• Market-wide consistency is more important than accuracy. To have trust in the market, Green Button data must match the
bills and the SME.
• Mismatches drive significant costs and uncertainty for both third parties and utilities.Notes: Green Button data won’t be officially correct until it’s billed. SME has “valid” or “estimated” status. Third Party will know it’s
“final” by checking if data were received AFTER bill is generated.Reason(s) for non-consensus: Needs regulatory review Utilities would like further review of this information and are not prepared to pass this Best Practice at this time.
Utility Vendors and Green Button Provider would like further review and are not prepared to pass this Best Practice at this time.