Weekly OpenADE Meeting Notes

Weekly OpenADE Meeting Notes Tuesday, February 16, 2016

New Year Status • GBA Kicking into High Gear • Completing CMD Certification Suite • Completing Retail Customer Interface Spec – Completing Retail Customer Test Spec and Code • Performing NAESB Standard Update • Develop Third Party Certification Spec • Completing Retail Customer Test Spec and Code

Topics • Service Request 95 – Green Button Download My Data Gas Function Block [FB_10] only allows "therms" UOMType = 169 • Permit therms, joules, ft3, m3  expand acceptance of test • Optionally if you have volume, add MeterReading, ReadingType, and IntervalBlockfor convervionfactor history Service Request 96 – Green Button Download My Data Water Function Block [FB_11] only allows UOMType = 128 (US gl (US Gallons) • Permit US Gallons, ft3, and m3  expand acceptance of test  Service Request 97 – Update UsagePoint for 61968-9 2nd edition elements Service Request 83 – including Function Block for optional customer info (service point address, etc.) – retailcustomer.xsd •  Updated schema – espiderived.xsd •  LSE, MDMA, MSP identification • Sub-LAP and LCA • planning bus and a market operations bus? – Accept API and FBs – Generate Test Requirements espiderived.xsd –  Updated UsagePoint Populating UsageSummary bill elements Query Parameter Testing for FB_37 • • • • • • • Tariff Model Resource

Pnode/AggregationPoints from CIM Model class AggregateNode class AggregateNode +RTO MktOrganisation RTO 1 RTO +RTO 0..1 RUCZone RUCZone +RTO 1 +AggregateNode 0..* IdentifiedObject LoadAggregationPoint LoadAggregationPoint AggregateNode AggregateNode + anodeType: AnodeType [0..1] + endEffectiveDate: DateTime [0..1] + qualifASOrder: Integer [0..1] + startEffectiveDate: DateTime [0..1] MarketRegion MarketRegion 0..1 +AggregateNode +AggregateNode 0..* 0..* +AggregateNode 0..* +CnodeDistributionFactor IdentifiedObject +RegisteredResources +RegisteredResource 0..* CnodeDistributionFactor CnodeDistributionFactor 0..* +Pnode PowerSystemResource MarketCommon:: RegisteredResource +RegisteredResource + factor: Float [0..1] + podLossFactor: Float [0..1] IdentifiedObject Pnode +Pnode MarketCommon:: RegisteredResource Pnode 0..* 0..* 0..1 +Pnodes 0..* 0..* +CnodeDistributionFactor +MktConnectivityNode RegisteredGenerator RegisteredGenerator RegisteredLoad RegisteredLoad AggregatedPnode AggregatedPnode +MktConnectivityNode 1 0..* ConnectivityNode MarketOpCommon:: MktConnectivityNode +MktConnectivityNode MarketOpCommon:: MktConnectivityNode IndividualPnode IndividualPnode RegisteredInterTie RegisteredInterTie 0..1 1 +IndividualPnode +MktConnectivityNode 0..1

UsagePoint Associations that will add the needed elements class CustomersOverview class CustomersOverview IdentifiedObject Metering::UsagePoint Metering::UsagePoint + isSdp: Boolean [0..1] + isVirtual: Boolean [0..1] + phaseCode: PhaseCode [0..1] + grounded: Boolean [0..1] + servicePriority: String [0..1] + serviceDeliveryRemark: String [0..1] + estimatedLoad: CurrentFlow [0..1] + checkBilling: Boolean [0..1] + ratedCurrent: CurrentFlow [0..1] + nominalServiceVoltage: Voltage [0..1] + ratedPower: ActivePower [0..1] + outageRegion: String [0..1] + readCycle: String [0..1] + readRoute: String [0..1] + amiBillingReady: AmiBillingReadyKind [0..1] + connectionState: UsagePointConnectedKind [0..1] + minimalUsageExpected: Boolean [0..1] «enumeration» MktDomain:: AnodeType MktDomain:: AnodeType SYS RUC LFZ REG AGR POD ALR LTAC ACA ASR ECA 0..* 0..* +UsagePoints +UsagePoints +AggregateNodes 0..* +Pnode 0..1 IdentifiedObject IdentifiedObject ReferenceData::AggregateNode ReferenceData::AggregateNode ReferenceData::Pnode ReferenceData::Pnode +Pnode +AggregateNode + anodeType: AnodeType [0..1] + endEffectiveDate: DateTime [0..1] + qualifASOrder: Integer [0..1] + startEffectiveDate: DateTime [0..1] + endEffectiveDate: DateTime [0..1] + isPublic: Boolean [0..1] + startEffectiveDate: DateTime [0..1] 0..* 0..*

AnodeTypes for Aggregate Nodes • • - SYS - System Zone/Region; - RUC - Reliability Unit Commitment Zone; – A specialized class of type AggregatedNode type. Defines RUC Zones. A forecast region represents a collection of Nodes for which the Market operator has developed sufficient historical demand and relevant weather data to perform a demand forecast for such area. The Market Operator may further adjust this forecast to ensure that the Reliability Unit Commitment produces adequate local capacity procurement. - LFZ - Load Forecast Zone; - REG - Market Energy/Ancillary Service Region; - AGR - Aggregate Generation Resource; - POD - Point of Delivery; - ALR - Aggregate Load Resource; - LTAC - Load Transmission Access Charge (TAC) Group; - ACA - Adjacent Control Area - ASR - Aggregated System Resource - ECA - Embedded Control Area • • • • • • • • • • LoadAggregatinPoint(ALR?), SubLoadAggregationPoint (ECA?), ICAP or LocalCapacityArea (SYS?) are in this list or need to be explicitly added.

Resulting XML Schema For UsagePoint Enhancements XML XMLSchema (at end of UsagePoint)

Older or other slides Will build deck with new content over time.

RetailCustomer Model Identities for Rule 24 class RetailCustomer class RetailCustomer class RetailCustomer class RetailCustomer «Enumeration» PaymentMetering: :SupplierKind PaymentMetering: :SupplierKind PaymentMetering::ServiceSupplier PaymentMetering::ServiceSupplier + kind: SupplierKind [0..1] + issuerIdentificationNumber: String [0..1] utility retailer other lse mdma msp Meter Multipliers class RetailCustomer class RetailCustomer class RetailCustomer class RetailCustomer «Enumeration» Metering:: MeterMultiplierKind Metering:: MeterMultiplierKind +Meter Metering::Meter Metering::Meter kH kR kE ctRatio ptRatio transformerRatio + formNumber: String [0..1] Metering::MeterMultiplier Metering::MeterMultiplier 0..1 0..* + kind: MeterMultiplierKind [0..1] + value: Float [0..1] +MeterMultipliers

Retail Customer class RetailCustomer class RetailCustomer IdentifiedObject Common:: OrganisationRole IdentifiedObject IdentifiedObject Common:: OrganisationRole +Roles Common::Document Common::Document Common::Organisation Common::Organisation +Organisation 0..* + type: String [0..1] + authorName: String [0..1] + createdDateTime: DateTime [0..1] + lastModifiedDateTime: DateTime [0..1] + revisionNumber: String [0..1] + electronicAddress: ElectronicAddress [0..1] + subject: String [0..1] + title: String [0..1] + docStatus: Status [0..1] + status: Status [0..1] + comment: String [0..1] + streetAddress: StreetAddress [0..1] + postalAddress: StreetAddress [0..1] + phone1: TelephoneNumber [0..1] + phone2: TelephoneNumber [0..1] + electronicAddress: ElectronicAddress [0..1] 0..1 Common::Agreement Common::Agreement PaymentMetering::ServiceSupplier PaymentMetering::ServiceSupplier + signDate: Date [0..1] + validityInterval: DateTimeInterval [0..1] + kind: SupplierKind [0..1] + issuerIdentificationNumber: String [0..1] Customers:: CustomerAccount Customers:: CustomerAccount Customers::Customer Customers::Customer Customers:: CustomerAgreement Customers:: CustomerAgreement + kind: CustomerKind [0..1] + specialNeed: String [0..1] + pucNumber: String [0..1] + status: Status [0..1] + priority: Priority [0..1] + locale: String [0..1] «deprecated» + vip: Boolean [0..1] + billingCycle: String [0..1] + budgetBill: String [0..1] + lastBillAmount: Money [0..1] + loadMgmt: String [0..1] + isPrePay: Boolean [0..1] + shutOffDateTime: DateTime [0..1] +CustomerAgreements 0..* +CustomerAgreements 0..* +PricingStructures0..* +DemandResponsePrograms 0..* Customers:: PricingStructure Customers:: PricingStructure Metering::DemandResponseProgram Metering::DemandResponseProgram IdentifiedObject Common::Location Common::Location + type: String [0..1] + mainAddress: StreetAddress [0..1] + secondaryAddress: StreetAddress [0..1] + phone1: TelephoneNumber [0..1] + phone2: TelephoneNumber [0..1] + electronicAddress: ElectronicAddress [0..1] + geoInfoReference: String [0..1] + direction: String [0..1] + status: Status [0..1] IdentifiedObject Assets::Asset Assets::Asset + type: String [0..1] + utcNumber: String [0..1] + serialNumber: String [0..1] + lotNumber: String [0..1] + purchasePrice: Money [0..1] + critical: Boolean [0..1] + electronicAddress: ElectronicAddress [0..1] + lifecycle: LifecycleDate [0..1] + acceptanceTest: AcceptanceTest [0..1] + initialCondition: String [0..1] + initialLossOfLife: PerCent [0..1] + status: Status [0..1] Work:: Work:: WorkLocation WorkLocation Assets:: AssetContainer Assets:: AssetContainer Customers::ServiceLocation Customers::ServiceLocation + accessMethod: String [0..1] + siteAccessProblem: String [0..1] + needsInspection: Boolean [0..1] +ServiceLocation 0..1 +UsagePoints Metering:: UsagePoint Metering:: UsagePoint 0..* Metering::EndDevice Metering::EndDevice + isVirtual: Boolean [0..1] + isPan: Boolean [0..1] + installCode: String [0..1] + amrSystem: String [0..1] Metering::Meter Metering::Meter +Meter +MeterMultipliers + formNumber: String [0..1] Metering::MeterMultiplier Metering::MeterMultiplier 0..1 0..* + kind: MeterMultiplierKind [0..1] + value: Float [0..1]

class RetailCustomer class RetailCustomer Minor Classes and Enums «Compound» Common::Status «Enumeration» «Compound» Common::TownDetail Common::Status Customers::CustomerKind Customers::CustomerKind Common::TownDetail + value: String [0..1] + dateTime: DateTime [0..1] + remark: String [0..1] + reason: String [0..1] residential residentialAndCommercial residentialAndStreetlight residentialStreetlightOthers residentialFarmService commercialIndustrial pumpingLoad windMachine energyServiceSupplier energyServiceScheduler internalUse other + code: String [0..1] + section: String [0..1] + name: String [0..1] + stateOrProvince: String [0..1] + country: String [0..1] «Compound» Common::Priority «Compound» Common::Priority Common::StreetDetail Common::StreetDetail + rank: Integer [0..1] + type: String [0..1] + justification: String [0..1] + number: String [0..1] + name: String [0..1] + suffix: String [0..1] + prefix: String [0..1] + type: String [0..1] + code: String [0..1] + buildingName: String [0..1] + suiteNumber: String [0..1] + addressGeneral: String [0..1] + addressGeneral2: String [0..1] + addressGeneral3: String [0..1] + withinTownLimits: Boolean [0..1] «Enumeration» PaymentMetering: :SupplierKind PaymentMetering: :SupplierKind utility retailer other lse mdma msp «Compound» Assets::AcceptanceTest Assets::AcceptanceTest + type: String [0..1] + success: Boolean [0..1] + dateTime: DateTime [0..1] «Compound» «Enumeration» Metering:: MeterMultiplierKind Common::TelephoneNumber Common::TelephoneNumber Metering:: MeterMultiplierKind «Compound» Assets::LifecycleDate Assets::LifecycleDate + countryCode: String [0..1] + areaCode: String [0..1] + cityCode: String [0..1] + localNumber: String [0..1] + extension: String [0..1] + dialOut: String [0..1] + internationalPrefix: String [0..1] + ituPhone: String [0..1] kH kR kE ctRatio ptRatio transformerRatio + manufacturedDate: Date [0..1] + purchaseDate: Date [0..1] + receivedDate: Date [0..1] + installationDate: Date [0..1] + removalDate: Date [0..1] + retiredDate: Date [0..1] «Compound» «Compound» Common:: ElectronicAddress Common::StreetAddress Common::StreetAddress Common:: ElectronicAddress + streetDetail: StreetDetail [0..1] + townDetail: TownDetail [0..1] + status: Status [0..1] + postalCode: String [0..1] + poBox: String [0..1] + lan: String [0..1] + mac: String [0..1] + email1: String [0..1] + email2: String [0..1] + web: String [0..1] + radio: String [0..1] + userID: String [0..1] + password: String [0..1]

espiderived: UsagePoint current Extends UsagePoint based on newer CIM model: iec61970cim17v06a_iec61968cim 12v10_iec62325cim03v02 Backwards compatibility assured by adding new elements to end of list.

billLastPeriod • billLastPeriod – The total bill for the billing period – billLastPeriod = ∑ costAdditionalDetailLastPeriod.LineItem.amount costAdditionalLastPeriod – Deprecate and if present, should have the same value of billLastPeriod – if you populate the costAdditionalDetailLastPeriod, then costAdditionalLastPeriod would be expected to have the total IntervalReading.cost – Provided if FB_12 is selected and should probably be consistent with costAdditionalDetailLastPeriod.LineItem.amount records for which these costs pertain – but this is not guaranteed billLastPeriod = ∑ costAdditionalDetailLastPeriod.LineItem.amount – Should always add up to billLastPeriod. If the details provided are not complete, a record “other” should be included to make up the difference and indicate that all billing details have not been provided. – If no amounts are presented in this detail, there is no need for a compensating “other” record to add up to billLastPeriod • • •

Query Parameters • There was a significant discussion, led by Partha, about how the “depth” query parameter should work. During the call we accessed the “Implementation Agreement” and discovered the only documentation of the query parameters is a list of the query parameter keywords. The group agreed we need to document how the parameters work and the expected format they should contain. For example, the date query parameters (published-min, published-max, updated-min, and updated-max) need to indicate they are to be UTC “Z” time formats and not epoch time. • As a result of the two above items, additional test need to be added to FB_37 to: – Ensure query elements containing epoch time generate a 400 response – Ensure query elements containing ALL generate a 400 response – Ensure responses match requested max & depth values

Topics • • Value mapping for TOU and CPP and ConsumptionTier sftp for Batch/Bulk/{bulkId} – Is there a “user”? –  sftp://user@localhost/DataCustodian/espi/1_1/resource/Batch/Bulk/{bulkId} • Suggestion – fixed user= “GreenButton” so no PII in sftp startup • Alternative – let DC provide arbitrary uuid in the notification •  Conclusion: the DC chooses the “user” and includes it in the notificationUri where the TP gets it for use in the exchange. Target Firm Up end of July: Retailcustomer.xsd –  Need to define function blocks -- Potentials: •  FB_X1 Minimal that only provides actual IDs and UsagePoints •  FB_X2 Service Location Contents Name and Addresses and location, • No fb needed now End device • No fb needed now Pricing Structure •  FB_X3 Account data for DMD access – Access Tokens •  Access tokens to access? Individual with access_token, bulk with client_access_token – URI in Authorization •  customerResourceUri needed in OAuth authorization response and Authorization xml structure •  customerResourceUri in client access Authorization would be batch/BulkRetailCustomerInfo •  Test requirements – – If Scope has RetailCustomer function blocks, then » Verify Authorization has customerResourceUri » Verify Oauth response has customerResourceUri » Verify client_access_token works for esource/Batch/BulkRetailCustomerInfo » Verify access_token works for resource/RetailCustomer… – Additional attributes •  Move in move out – use CustomerAgreement.validityInterval • • Target Firm Up List end of July: UsageSummary.CostAdditionalDetail.itemKind – Tax, Other, ThirdParty energy provider fee, ThirdParty energy provider usage, Credit, Discount, Usage, Demand, TOU, incentive, informational, Customer Charge, Energy Charges, Supply Charges, Distribution Charges, Transmission Charges, Generation Charges, State Gross Receipts Tax, State Tax Adjustment, Administrative Charge, Ancillary Charge, Balancing Service Charge, Working Capital Charge, Purchased Generation Adjustment, Cost Adjustment, Service Location Distribution Charge, Other, Minimum charge, Tier Charge, Adjustment Charge, Program Charge/Credit, Amount Paid, Power Factor adjustment, DWR energy credit (calculation and credit value), UUT exemption status, State Tax, Local Tax, Transmission Charges, Distribution Charges, Nuclear Decommissioning Charges, Public Purpose Programs Charges, Franchise Fee, Generation Charge – Will finish consolidation of list and review OAuth login requirements for the testing •

ItemKind Simplified 1 2 3 Energy Generation Fee. A charge for generation of energy. Energy Delivery Fee. A charge for delivery of energy. Energy Usage Fee. A charge for electricity, natural gas, water consumption Administrative Fee. A fee for administrative services. Tax. A local, state, or federal energy tax. Energy Generation Credit. A credit, discount or rebate for generation of energy. Energy Delivery Credit. A credit, discount or rebate for delivery of energy. Administrative Credit. A credit, discount or rebate for administrative services. Payment. A payment for a previous billing. Information. An informational line item. 4 5 6 7 8 9 10

TOU, CPP, ConsumptionTier Code Descriptions • TOU, CPP, ConsumptionTier are integers in ReadingType/IntervalReading • What does “3” mean? • Draft Solution: – Provide an optional table in UsagePoint that provides the code, name, and description of the values of TOU and CPP when used underneath it.

UsagePoint.ProgramMappings <UsagePoint> </UsagePoint> <ServiceCategory> <kind>1</kind> </ServiceCategory> <programIdMappings> <programIdMapping> </programIdMapping> <programIdMapping> </programIdMapping> </programIdMappings> <tOUorCPPorConsumptionTier>tou</tOUorCPPorConsumptionTier> <code>1</code> <name>Summer Peak</name> <tOUorCPPorConsumptionTier>tou</tOUorCPPorConsumptionTier> <code>2</code> <name>Winter Peak</name>

RetailCustomer Architecture • API –GET .../resource/Batch/RetailCustomer/{id} –GET .../resource/CustomerInformation/{id} –… –GET .../resource/CustomerInformation/{id}/RetailCustomer/{id}/CustomerAccount/{id}/CustomerAgreement –GET …/resource/Customer/{id} –GET .../resource/CustomerAgreement/{id} –GET .../resource/Batch/BulkRetailCustomerInfo/{id} PG&E proposal Current Architecture

Large Organization Use Case Corporate Authorizes EMS Co Resource Example EMS Co Web Account Safeway Company Customer SF Regional Mgr, Oakland RM Customer Account Individual Stores Service Agreement Gas service, Electrical service Service Point Usage Points • There is sometimes an authority that can authorize a large number of individual accounts, e.g. gsa/McDonalds, … where the individual accounts may be franchised or otherwise owned/managed – yet the individual accounts have the responsibility to maintain the utility account and pay the bills.

Query Parameters • There was a significant discussion, led by Partha, about how the “depth” query parameter should work. During the call we accessed the “Implementation Agreement” and discovered the only documentation of the query parameters is a list of the query parameter keywords. The group agreed we need to document how the parameters work and the expected format they should contain. For example, the date query parameters (published-min, published-max, updated-min, and updated-max) need to indicate they are to be UTC “Z” time formats and not epoch time. As a result of the two above items, additional test need to be added to FB_37 to: – Ensure query elements containing epoch time generate a 400 response – Ensure query elements containing ALL generate a 400 response – Ensure responses match requested max & depth values Jerry Yip has some additional itemKind elements he wants to discuss during next week’s OpenADE Task Force call, which he will provide in a follow up e-mail. Jerald Pinnecker wants to discuss “subscriptions” during next week’s OpenADE Task Force call. Presently they send subscription data to a Third Party when they register and he wants to know how that data is then tied to the access token when the Third Party completes the authorization request. Additionally, he wants to know who the Third Party is supposed to use the access token. • • •

OAuth Authorization Failure Mode Usage Scenario: 1. TP redirect user to DC scope selection. 2. User approves TP and scope. 3. DC redirects user to TP with scope parameter. 4. TP redirects users to DC's OAuth /authorize endpoint with scope and client_id parameters. 5. DC redirects back to TP redirect_uri with OAuth code parameter. 6. TP makes a request to DC's OAuth /token endpoint with the code. 7. DC responds with an access_token and refresh_token. 8. TP's server crashes and doesn't save either token. • How is the TP supposed to get new tokens? In normal OAuth, you simply redirect the user back to the OAuth /authorize endpoint, the user approves access again and gets redirected back with a new code. • However, at least in one current implementation, the TP has to redirect the user to the scope selection screen, where the user will be told that they have already authorized the TP with no option to re-authorize. In order to get new tokens, the use manually has to cancel authorization, which causes them to get redirected to the main website. Then the user manually has to go back to the scope selection screen and authorize the TP again. • This re-authorization process is not ideal because it requires us training the user to cancel-then-manually-go-back- and-reauthorize, which is a very confusing and complex process and doesn't redirect the user back to the TP after cancellation. • Two possible solutions: – 1. On the DC's scope selection interface, have a re-authorize button if the user has already authorized the TP. – 2. Allow TP's to redirect the user to OAuth's /authorize endpoint with the same scope, and have the DC ask for re-authorization at that point. – Option 1 is better for GBCMD, in my opinion, because it also allows for the scenario where the TP loses the scope parameter, too. Option 2 is the more technically correct OAuth procedure. All other OAuth services I can think of do Option 2, but they also don't require a pre-defined scope parameter for the /authorize endpoint (so there's nothing to lose).

GET Subscription w/wo query parameters – Default required behaviors Problem: The amount of data that is in a: GET /Batch/Subscription/{subscriptionId} can potentially be very large. What is the obligation of a DC when that message is received without query parameters? What about the desire of some DC’s to provide only a fixed size response of say “X” months? What about when a subscription contains 1/10/1000 UsagePoints? • Alternatives – 1) Requires date range in GET /Batch/Subscription/{subscriptionId} • DC responds with 202 if data is too large to return right away – Returns with notification when data is ready and can provide query distinguished URIs – 2) DC decides maximum depth to return when no query parameters • TP may get whole history (from scope parameter HistoryLength) or may get less. – 3) Term in Scope for default GET Subscription depth • The scope can indicate for the specific subscription what the default length is. The DC decides during scope selection what to include in the offered scopes. • Solution: – Publish min/max required on resource/Batch/XXXXX APIs

Discussion of responses to requests for large data sets Given: • • • • • It's possible for a subscription to have small or enormous at data sets There GB CMD applications on the market that don't require query parameters Query parameters are specified and the Min and Max public support required for our minimum set If you have or don't have query parameters the third party is likely always to ask the first time for everything We agreed in a face-to-face that we were going to support a response of 202 when large off-line data sets are requested In a response asking for everything it should be the discretion of the data custodian to determine what the largest response it's willing to give Some data custodians want to define a fixed maximum size for any request An empty response (feed with no resources) implies no more data Therefore: •  Query parameters should remain optional in any given request •  Absence of query parameters means “everything” – this means all available data that DC is willing to provide •  202 is a valid response for …./Batch/… followed by a notification when data is ready •  The DC decides how much a maximum data response to an API request will be •  A TP that receives less than anticipated can ask for older data. •  If he gets back an empty feed, he has it all. Note: that if there is a gap in the data and he asks for the gap, he may get empty feed but there may be more data behind it. • • •

CIM Tariff Model class TariffProfile class TariffProfile Document Customers:: PricingStructure Customers:: PricingStructure +PricingStructures 0..* +Tariffs 0..* Document Customers:: Tariff IdentifiedObject Metering:: ReadingType Customers:: Tariff Metering:: ReadingType Charges associated with time threshholds Charges associated with value threshholds +Tariffs 0..* +ReadingType 0..1 +TariffProfiles 0..* Document +TariffProfiles +TariffProfiles TariffProfile TariffProfile 0..* 0..* + tariffCycle: String [0..1] +ConsumptionTariffIntervals +TimeTariffIntervals +ConsumptionTariffIntervals 0..* 0..* 0..* TimeTariffInterval TimeTariffInterval ConsumptionTariffInterval ConsumptionTariffInterval +TouTariffIntervals +ConsumptionTariffIntervals + sequenceNumber: Integer [0..1] + startTime: Time [0..1] + sequenceNumber: Integer [0..1] + startValue: Float [0..1] 0..* 0..* 0..* 0..* +TimeTariffIntervals +ConsumptionTariffIntervals «Compound» AccountingUnit IdentifiedObject Charge AccountingUnit Charge +Charges +Charges + value: Float [0..1] + energyUnit: RealEnergy [0..1] + monetaryUnit: Currency [0..1] + multiplier: UnitMultiplier [0..1] + kind: ChargeKind [0..1] + fixedPortion: AccountingUnit [0..1] + variablePortion: PerCent [0..1] 0..* 0..* +ParentCharge 0..1 +ChildCharges 0..*

Additional Information for UsageSummary.CostAdditionalDetail • Add an enumeration tag to lineitem to indicate what kind of charge it is • itemKind – Tax – TOU – Demand – ThirdParty energy provider fee – ThirdParty energy provider usage

Solutions to Add Customer Account Numbers Make non- obfuscatedId  Add link  Extend each Class with IdentifiedObject.name Add Atom Extension

Account/Agreement Topology

Separation of PII containing Resource RetailCustomer from Subscription* PII Containing information Anononymous EUI Subscription Customer CustomerAccount UsagePoint Customer Agreement Normal ESPI Resources ServiceLocation PostionPoint Key Authorization ServiceSupplier New Resource EndDeviceAsset PricingStructure Existing Resource *This data structure is to be developed on an aggressive schedule based on HelpDesk issue #83 and PAP10 NAESB Std REQ.18. No single API request can retrieve both PII and Anonymous data Non-Resource Class

class CustomerProfile class CustomerProfile OrganisationRole Customers::Customer Need to determine which are IdentifiedObjects -> resources {root} Model + kind: CustomerKind [0..1] + specialNeed: String [0..1] + pucNumber: String [0..1] + status: Status [0..1] + priority: Priority [0..1] + locale: String [0..1] ::IdentifiedObject + description: String [0..1] + mRID: String [0..1] + name: String [0..1] Document Customers::CustomerAccount + billingCycle: String [0..1] + budgetBill: String [0..1] ::Document + createdDateTime: DateTime [0..1] + lastModifiedDateTime: DateTime [0..1] + revisionNumber: String [0..1] + status: Status [0..1] ::IdentifiedObject + description: String [0..1] + mRID: String [0..1] + name: String [0..1] +CustomerAgreements +Customer Agreement +CustomerAccounts Customers::CustomerAgreement 1 0..* + loadMgmt: String [0..1] ::Agreement + signDate: Date [0..1] + validityInterval: DateTimeInterval [0..1] ::Document + createdDateTime: DateTime [0..1] + lastModifiedDateTime: DateTime [0..1] + revisionNumber: String [0..1] + status: Status [0..1] ::IdentifiedObject + description: String [0..1] + mRID: String [0..1] + name: String [0..1] • • • • UsagePoints of RetailCustomer Location of premise Account ID Sub Account (SA) ID—Service Agreement / Account is name depending on utility Customer name, nickname (or short name) Address and info SDG&E provides only email address and UPID correspondence csv email and UsagePoint ID (Customer Obfuscated Key) MeterID ServicePointId Pnode LoadAggregationPoint, SubloadAggregationPoint Climate zone Account open date Account close date SA Open and Close date MDM Agent Id (who does meter read) ServiceSupplierId EnergyServiceProviderId (may be same as service supplier) Demand Response Provider May need list of Ids for service providers rather than explicit?? (0..* relationship{role, href}) Related assets ???? For example pool pump and pool pump participation in a program. Related programs ???? «deprecated» + vip: Boolean [0..1] +CustomerAccount 1 0..* • • • +CustomerAgreements +CustomerAgreements +CustomerAgreements 0..* +CustomerAgreements 0..* 0..* 0..* WorkLocation Customers::ServiceLocation Customers::ServiceLocation Common:: PositionPoint Common:: PositionPoint + accessMethod: String [0..1] + siteAccessProblem: String [0..1] + needsInspection: Boolean [0..1] ::Location + type: String [0..1] + mainAddress: StreetAddress [0..1] + secondaryAddress: StreetAddress [0..1] + phone1: TelephoneNumber [0..1] + phone2: TelephoneNumber [0..1] + electronicAddress: ElectronicAddress [0..1] + geoInfoReference: String [0..1] + direction: String [0..1] + status: Status [0..1] ::IdentifiedObject + description: String [0..1] + mRID: String [0..1] + name: String [0..1] • • • • • • • • • • • +PositionPoint + xPosition: String [0..1] + yPosition: String [0..1] + zPosition: String [0..1] 0..1 +ServiceLocation +ServiceLocations 0..1 0..* +ServiceLocation 0..1 Metering:: UsagePoint Metering:: UsagePoint +UsagePoints 0..* +ServiceLocation 0..1 AssetContainer Metering::EndDevice Metering::EndDevice +EndDevices PaymentMetering::ServiceSupplier +ServiceSupplier + isVirtual: Boolean [0..1] + isPan: Boolean [0..1] + installCode: String [0..1] + amrSystem: String [0..1] ::Asset + type: String [0..1] + utcNumber: String [0..1] + serialNumber: String [0..1] + lotNumber: String [0..1] + purchasePrice: Money [0..1] + critical: Boolean [0..1] + electronicAddress: ElectronicAddress [0..1] + lifecycle: LifecycleDate [0..1] + initialCondition: String [0..1] + initialLossOfLife: PerCent [0..1] + status: Status [0..1] ::IdentifiedObject + description: String [0..1] + mRID: String [0..1] + name: String [0..1] + kind: SupplierKind [0..1] + issuerIdentificationNumber: String [0..1] 0..* 1 • • Metering::DemandResponseProgram Metering::DemandResponseProgram +DemandResponsePrograms + type: String [0..1] + validityInterval: DateTimeInterval [0..1] 0..* • Customers:: PricingStructure Customers:: PricingStructure +PricingStructures • 0..* + code: String [0..1]

RetailCustomer  API – – – – – – • GET .../resource/Batch/RetailCustomer/{id} GET .../resource/RetailCustomer/{id} … GET .../resource/RetailCustomer/{id}/CustomerAccount/{id}/CustomerAgreement/{id} GET .../resource/CustomerAgreement/{id} GET .../resource/Batch/BulkRetailCustomerInfo/{id}  Authorization – • Scope string addition? • X RCInfo=AC where – A=Address included , C=AccountInfo included • X RCBulkId=123 for access to account info in bulk  Access tokens to access? Individual with access_token, bulk with client_access_token Thoughts: •  Simpler to use the one authorization and the one bulkID for this data which would be used with …/Bulk/{bulkId} and with …/BulkRetailCustomer/{bulkId} • X Desire to select which APIs query parameters are valid for – but, currently we only test for the specific query paramters needed for IntervalBlock date ranges. Other parameters and which resources they apply to are optional. •  Leave generic query parameters as is for all resources but no requirements to support any specific set by resource. – – • FB – – – – X Has RetailCustomer – Just one FB_4X with RCInfo X Has Additional Detail indicated by content of RCInfo  Alternative – just like EUI data have separate function blocks for groupings of data (along resource lines) and they are part of scope=FB_xxxxxxxxxx Need to work out FBs that make sense for RetailCustomer  Document as a separate document to maintain isolation of the PII and related discussions (CustomerResourceModelHelpdesk83.docx) •  customerResourceUri needed in authorization and Authorization xml structure •

OpenADE Task Force Topics • Green Button Connect My Data Testing and Certification (target fall 2014) –  Complete function block descriptions –  Complete test case requirements – Amend CMD test requirements if gaps are discovered in dry run or other process Issues Raised and Implementation Questions –  How to use BR=bulkID with application to account and account groupings, as well as, large ThirdParty collections of Authorizations. –  Service Request 83 – including Function Block for optional customer info (service point address, etc.) –  Service Request 84 – having scope selection screen on Data Custodian Site vs 3rdParty site (need to write up description) –  Service Request 85 – Duplicating TOU and CPP from ReadingType to IntervalReading as in SEP 2.0 – Service Request 86 – Desire to add digital signature to Green Button data to protect against tamper. –  Service Request 90 – Error in GB TestPlan: FB_07,08 AccumulcationBehavior should be 4 –  Service Request 91 – Error in Test Plan: FB_04 –  Mega Third Party –  Service Request 92 – Certificate reference – Service Request 93 -- Customers have requested access to the Green Button CMD API interface to access their own account information –  Enhancement of UsageSummary.CostAdditionalDetail to indicate kind of billing determininant New Resources for OpenADE Exchange requested – Tariff Model Resource –  Customer Information Resource • •

Mega Third Party • Host Third Party for smaller third parties – Small solar companies that don’t want to implement ESPI technical requirements – Have simple web site – Want customer data • Why does small third party interface to mega third party have to be standardized? – Have consulting company they are hosting GB on behalf of – Retail Customer authorizes little third party and mega third party to access the data • How does mega third party track the authorization which occurs from the little third party – Wants ability to tag a OAuth sequence to associate with the little third party – perhaps a state parameter???

Issues • What if one customer authorizes for two different provider using mega-third party – PG&E only permits one authorization for actual customer/third party pair. – Same customer goes to Solar1 and Solar2 who are using the services of MegaTP – How can DC know one authorization from the next –  Consensus: let this be private matter between MegaThirdParty and customer. No additional protocol required. • What if wordpress directs to DC and not TP?

GBCMD Test Harness • Using Stunnel Proxy to isolate https from http on test harness – Three message types: • 1) DataCustodian to Mock Server – https  http – Use stunnel server config (tpserver.conf) • 2) SOAPUI to DataCustodian using groovy script and httpbuilder – http https – Use stunnel client config (tpclient.conf) – host must be what is in ApplicationInformation remapped to port 8080. • 3) SOAPUI to DataCustodian via Selenium – https web browser integration – Use Selenium browser with what is in ApplicationInformation bypassing stunnel for these messages

 Certified Link <link rel="related" href="https://cert.greenbuttonalliance.org/92348981231"/> • Added to feed (or if only entry, added to entry) • Assigned by GBA at test request submission • Until certified, may return “in progress” or some useful status • Optional request of return type for GET (returned by GBA site): 1. GET https://cert.greenbuttonalliance.org/92348981231 2. GET https://cert.greenbuttonalliance.org/92348981231?format=JSON 3. GET https://cert.greenbuttonalliance.org/92348981231, Header parameter Accept: application/json 4. Return (XML Version) – exact form tbd.

Chunking – When the DataCustodian needs to provide data in “chunks” • Have huge data set that DC wants to provide in “chunks” over HTTPS • Use common URI – Subscription or Bulk / id – Chunked by index and date? – Use ESPI query parameters (FB_37) to distinguish chunks <?xml version="1.0" encoding="UTF-8"?> <BatchList xmlns="http://naesb.org/espi" xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:schemaLocation="http://naesb.org/espi espiDerived.xsd"> <resources>../espi/1_1/resource/Batch/Bulk/1?start-index=1&max-results=1000&published-max=2012-04-02T04:00:00Z &published-min=2012-04-02T04:00:00Z</resources> <resources>../espi/1_1/resource/Batch/Bulk/1?start-index=1&max-results=1000&published-max=2012-04-02T04:00:00Z  &published-min=2012-04-02T04:00:00Z</resources> </BatchList>

Deferred Response when DC does not have data ready TP Request: HTTP GET https://localhost/DataCustodian/espi/1_1/Subscription/1 Content-type: application/xml DC HTTP returns 202 Request: HTTP POST https://localhost/ThirdParty/espi/1_1/Notification Content-type: application/xml Response: Request: HTTP GET https://localhost/DataCustodian/espi/1_1/Subscription/1 Content-type: application/xml HTTP returns 200 and Data • • • ThirdParty makes asynchronous request DataCustodian does not have the data ready – returns HTTP 202 Some time later (when ready no guarantees or time limit) DataCustodian sends Notification with original URL in BatchList DataCustodian provides the result •

Green Button Data File Summary • Can there be a “digest” of what is in a Green Button data set (i.e. feed) so that the whole data set returned by a GET or DMD can be judged for content without reviewing the contents – Different Usage Points in file may have different contents – Content may be dependent on when data is retrieved – Simple xpath statements can be used to understand the contents – Unsuitable data is likely to be asked for once not repeatedly • Consensus: Not needed

New XML Schema Tags • certificationNumber – Provides information about the certificate issued to the creator of the file • contentHash – Provides a checksum value of the files contents the recipient of the file may use to confirm the file has not been tampered with and all elements of the file were received – Response to OpenADE Help Desk item 86 • http://osgug.ucaiug.org/HelpDesk/Lists/servicerequests/DispForm.aspx?ID=86 &Source=http%3A%2F%2Fosgug%2Eucaiug%2Eorg%2FHelpDesk%2FLists%2Fs ervicerequests%2FGreenButton%2Easpx • Consider RFC 4287 Atom Syndication Format section 5.1 which describes Digital Signatures for Atom: https://tools.ietf.org/html/rfc4287#section-5.1

Certification Structure link type=“text/html” href=“https://cert.greenbuttonalliance.org/certificate/987654321987654321” />

Possible Options • GET https://cert.greenbuttonalliance.org/92348981231?ThisGuysScopeIs=FB_ 01040507” PGE -92348981231 – scopes=1_4_5,1_4_10,1_4_5_10 •

Variable return types • Query Parameter: – GET https://cert.greenbuttonalliance.org/9234898123 1?format=XML • Accept Header Parameter: – Accept: Application/XML • Atom link types – <link type=“XML” href=“https://foo.bar.com”/>

Certificate Solutions • Create new required resource for GB • *** Create a required feed related link • Look at other atom feed attributes to implement

[FB_14] OAD011 [NEG] Malformed Refresh Token Request • Verify Data Custodian rejects a malformed Refresh Token Access Token Request – Refresh_token field-value pair that was issued to another Third Party • The current CMD test harness can only simulate a single Third Party application and thus is not able to present a refresh_token request using another Third Party’s assigned refresh_token • Two application information structures would need to be registered at the Data Custodian under test to be able to support this requirement – Refresh_token field-value pair has expired • A short lived refresh_token would need to be available to perform this test requiring the Data Custodian under test to be able to modify the refresh_token expiration period • The authorization server’s token expiration test should not be based on the type of token issued, therefore the existing test in OAD016 [NEG] Invalid Access Token Request (Access Token contained in the Authorization Header has expired) makes this test redundant

Cell Phone API Model • How to do authorization for cell phone APP – Still need to involve App developer (DC may not accept request from any app) – API FBs – Customer and his app authentication • Get an access token – Differs in certificate management and security • Security • Privacy – Retail Customer vs Subscription

One Data Custodians Potential Design Dimensions for UsageSummary Nettable: total cost = sum of nettable components NEM: Net Metering Implementation Perspective to Billing data Meter Relationships (Additive-Conjunctive, Subtractive) Special Bill Items oNEM Statement oShadow Bill Info oLevel Pay Plan customers Rates (bill periods: pricing changes, seasons)   NEM: o Non-NEM customers: o Nettable  UDC  Taxes (DWR, City and State)  T&D  Discounts    o Non-nettable  Event days  GHG Nettable  UDC  Commodity  Taxes (DWR, City and State)  Discounts  Care  FERA  Employee discounts Non-nettable  Demands  Minimum charge  Customer charge  Event days  GHG Care FERA Employee discounts. o

Topics • Multiple ReadingTypes in file not referenced by contents –  Proposal – permit (right now excluded) • Definition of Net metering FB_07 vs. FW/REV metering FB_08

FB_03 • espiderived.xsd – thirdPartyUserPortalScreen vs. client_uri • Appears to duplicate same function • client_uri is optional by dynamic registration OAuth protocol • Solution – Make client_uri and thirdPartyUserPortalScreen optional in schema – Authorization.authorizedPeriod and publishedPeriod should be optional since not needed in authorizations for client admin and registration • Solution – Make both fields optional in the schema – Ensure they are present for access_token based authorizations – If present validate authorizedPeriod and publishedPeriod are valid date format – If either authorizedPeriod or publishedPeriod is present, both are required – Allow duration to be present with “0” values implying non-expiring authorizations grant_types for ApplicationInformation • Should it be set of grant_types that DC supports? • Spring requires separate client_id for client_credentials flow • Solution: – Nothing needs to change •

FB_03 • grant_types test assertion in FND002 re: redirect_uri – Solution: • Remove the test from FND002 and OADxxx • response_types should be “code” – Solution: • Add test to validate content of response_types is “code” • Lifetime of client_access_token – If shortlived, you need to do client_credentials each day to get a new one • This forces you to use the “secret” often which is a greater risk than client access token • What does this do the lifetime of the “Authorization”

Weekly OpenADE Meeting Notes