As Green Button gets used for more than electricity -- i.e. gas and water.
As the usage summary resource gets used for billing details, a set of clarifications and extensions are needed.
As ESPI designates RESTful web services for exchange of data, the concept of “current”, “last” and “previous” is not suitable for ESPI objects. For example, if a 3rd party requests data for a 6 month date range, what is considered “last period” or “previous day”? This ambiguity does not fit with the other provided objects in ESPI.
We propose instead to make the billing period specific to the 3rd party requested and/or data custodian provided date range of data. For a 3rd party request that spans several billing periods, the UsageSummary will return data for whatever bill periods have bill information available. For example, if a request is made that spans 3 historical billing periods, for which 2 of the billing period usage summaries are available at the time of the request, then usage summaries for the 2 bill periods will be provided.
To avoid 3rd parties having to know in advance a customer’s billing period, requests only need to overlap with a day within that billing period to return the related usage summary (i.e. request does not need to cover the entire billing period to be valid).
It is at the discretion of the data custodian for how to handle authorization. For example, at the time of customer authorization, the data custodian and/or 3rd party can choose to put the responsibility on the customer in so far as understanding that authorization of bill summary information means sharing bill information for any of the authorized usage date range. For example, if a bill spanned from 1/15 to 2/15, and the customer authorized sharing of usage data only starting on 2/1, then a request for bill usage information for February could include sharing information from 1/15-1/31. Alternatively, the Data Custodian could implement additional logic to prevent such a scenario.
Batch requests (i.e. all objects underneath Usage Point, including MeterReading, IntervalBlock etc.) will return available bill amount info pertaining to the requested date range as prescribed above. Individual requests for usage summaries only, will behave similar to batch as far as date logic, however will return usage summaries only.
Daily batch subscription files, whereby only the latest day’s usage is provided, will provide UsageSummaries only as that data becomes available to the Data Custodian to publish.
To preserve backwards compatibility we agreed in OpenADE to:
1) Create new UsageSummary (which is NAESB REQ.18 name)
2) Add new tags recommended by PG&E
3) Retain all existing tags and make UsageSummary and ElectricPowerUsageSummary identical – but mark old one deprecated for backwards compatibility – new implementations will have to accept either Resource on input
4) Revise descriptions of existing tags to make clear what goes with billing period etc.
5) Provide documentation on how to interpret query parameters for GET UsageSummary