Green Button CMD Workshop Overview
This content provides insights into the Green Button CMD Workshop happening on April 21-22 at SCE, covering topics like Architecture Guidelines, Function Blocks, Relationship Management, Data Transfer, Definitions, and more. The agenda includes discussions on customer information, service agreements, and data exchange among various stakeholders involved in the energy sector.
Download Presentation
Please find below an Image/Link to download the presentation.
The content on the website is provided AS IS for your information and personal use only. It may not be sold, licensed, or shared on other websites without obtaining consent from the author. Download presentation by click this link. If you encounter any issues during the download, it is possible that the publisher has removed the file from their server.
E N D
Presentation Transcript
The Green Button CMD Workshop April 21,22 at SCE SDG&E Blockowicz, Brendan BBlockowicz@Semprautilities.com Logan, Tom TLogan@semprautilities.com Bristow, Johnie JBristow@semprautilities.com Rodoni, Madeleine MRodoni@semprautilities.com Kundu, Partha PKundu@semprautilities.com Brown, Gregory GMBrown@semprautilities.com Wiffen, Stuart SWiffen@semprautilities.com NIST Marty Burns, marty@hypertek.us John Teeter, john.teeter@nist.gov Don Coffin, donald.coffin@reminetworks.com Kin Lane, kinlane@gmail.com PGE www.greenbuttondata.org Jerry Yip (IT): (jerry.yip@pge.com) Ed Denson (IT): (ed.denson@pge.com) Deepak Subramanian (IT): (deepak.subramanian@pge.com) Kruti Patel (BA) (Kruti.patel@pge.com) Jaclyn Hood (Product Mgr) (Jaclyn.hood@pge.com) SCE Andrew Eisses/SCE/EIX, Andrew.Eisses@sce.com Vidyod Mavilavalappil/SCE/EIX, Vidyod.Mavilavalappil@sce.com Natalie Martinez natalie.martinez@sce.com, Genevieve Feng/SCE/EIX, Genevieve.Feng@sce.com Dale LeFevre, dale.lefevre@austin.rr.com Gopal Bhageria, gopal.k.bhageria@in.ibm.com Zoe Hillenmeyer, Zoe.Hillenmeyer@sce.com Cannis Meng, Cannis.Meng@sce.com
Agenda 1 [~2.5 hr] Architecture Guidelines 1.1 Each IOU Present Overview of their plans and 1.2 Key Definitions SA, CISR, implementations 2 [~1.5 hr] Function Blocks 2.1 [.5 hr] Minimum FBs 2.2 [1 hr] Content of each FB 3 [~8 hr] Relationship Establishment and Management 3.1 [~2-3 hr] Scope 3.2 [~1 hr] Third Party Registration 3.3 [~3-4 hr] Authorization 4 [~5 hr] Data Transfer 4.1 [~2 hr] REST GETs 4.2 [~1 hr] SFTP 4.3 [~2 hr] Other
Definitions Customer If residential it is individual (customer of record) If commercial it is an entity Customer Account Organization of the bill A customer may multiple customer accounts Service Account/Agreement Corresponds Customer to a meter Customer Information Service Request (CISR) A legal agreement that authorizes a California utility to provide customer information to a thirdparty paper or online Service Point/Location Logical location representing the meter at the premises level ESPI RetailCustomer Owner of one or more UsagePoints (has right to authorize) Subscription Authorized access to a (sub) set of UsagePoints of a single RetailCustomer Bulk Authorized access to a collection of UsagePoints governed by individual authorizations to a third party
GBCMD ids and resources depends on authorization level Account relationships subscriptionId Customer 1:n Premises Customer Account retailCustomerId 1:n 1:n Service Agreement or Service Account 1:1 Service Point usagePointId 1:1 bulkId arbitrary collection of resources 1:n Meter HAN Device
Green Button Data Exchange Data Custodian Third Party Third Party Registration Web Service Provider Web Service Consumer Automated Transfer One-time Authorization Web Portal Web Portal User (Browser) Retail Customer
Components of Connect My Data Components of GBCMD Data Custodian Third Party Third Party Registration Web Service Provider Web Service Consumer Automated Transfer ApplicationInformation Web Portal Web Portal One-time Authorizatio n REST API, Notification SFTP, TLS, Access-Token User (Browser) Retail Customer Authorization Scope Governed by Function Blocks
Function Blocks for CMD FunctionBlocks for Green Button Connect My Data [FB_3] Core Green Button Connect My Data [FB_13] Security and Privacy classes [FB_14] Authorization and Authentication (OAuth) Oauth [FB_19] Partial update data [FB_31] Core Rest Services Min Description Core Services HTTPS support IntervalBlocks without full data sets (Ups,MR, ) Third Party Access to Subscription/Authorization Third Party Access to UsagePoints, MeterReading, and collections GET PUT POST DELETE individual resources SFTP delivery of Bulk for Bulk request Support the REST request for Bulk Use Case 1 [FB_32] Resource Level REST [FB_33] Management REST Interfaces [FB_34] SFTP for Bulk [FB_35] REST for Bulk [FB_36] Third Party (Client) Dynamic Registration [FB_37] Query Parameters [FB_38] On Demand Requests [FB_39] PUSH model Without Notification Notification followed by GET Allows manual Authorization without OAuth but produces Authorization resource XML [FB_40] Offline Authorization [FB_42] Third Party Core REST Services [FB_43] Third Party Management REST Services [FB_44] Manage ApplicationInformation Resource Allows PUT and DEL of ApplicationInformation [FB_41] Manage Authorization Resource Allows PUT and DEL of Authorization
Access Tokens and Their Data access-token Obtained: During retail customer authorization process resourceUri https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Batch/Subscription/{SubscriptionID} authorizationUri https://services.greenbuttondata.org/DataCustodian/espi/1_1//resource/Authorization/{authorizationUri} client_access_token Obtained: After ThirdParty registration resourceUri https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Bulk/{bulkId} authorizationUri https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Authorization/{authorizationId} registration_access_token Obtained: During ThirdParty registration (either dynamic or manually) Always results in an ApplicationInformation and Authorization data structure. resourceUri https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/ApplicationInformation/{applicationInformationId} authorizationUri https://services.greenbuttondata.org/DataCustodian/espi/1_1//resource/Authorization/{authorizationId}
Review of ApplicationInformation XML content and schema APPLICATIONINFORMATION
Review of Authorization XML content and schema AUTHORIZATION
Scope Term Scope FBTerms FBTerm Expansion [ FBTerms ], [ ValueTerms ], [ ResourceTerms ]; FB= , { [FBTerm], _ } , FBTerm, ScopeDelimiter ; 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 15 | 16 | 17 | 18 | 19 | 27 | 28 | 29 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 43 { ( "IntervalDuration=", namedOrNumber,{ _ , namedOrNumber}), | ( "BlockDuration=", namedOrNumber,{ _ , namedOrNumber}), | ( "HistoryLength=", nonNegativeNumber), | ( "SubscriptionFrequency=", nonNegativeNumber | namedFrequency), ScopeDelimiter }; { ( AccountCollection= , nonNegativeNumber) | BR= , brID), ScopeDelimiter} ValueTerms ResourceTerms ScopeDelimiter namedFrequency namedOrNumber brID nonNegativeNumber Digit Character ; billingPeriod | daily | monthly | seasonal | weekly | nonNegativeNumber | namedFrequency; Character, {Character}*; digit, { digit }; 0 | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ; Digit | - | "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" | "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" ;
Scope Term Descriptions Where: ResourceTerms If a Bulk resource is specified via the BR term, the value of the {bulkID} is provided after the equals sign ( = ). There could be one or more terms in this list that express the granularity of notifications about resource changes. If the Subscription has more than one UsagePoint, the AccountCollection term can indicate the number of UsagePoints included The function blocks supported These are parameterized terms This is the minimum default length of an interval in seconds (e.g. 900 for 15 minutes, 3600 for one hour, ) This is the length of a block that contains the intervals (based on enumeration of MacroPeriodKind in ESPI above as namedFrequency) This is the length of history buffer seconds BulkAccountCollection Used where the DC wants to provide for the reporting of multiple UsagePoints in a single Subscription. The number of UsagePoints is represented by the value in the assignment statement e.g. 4 UsagePoints would be BulkAccountCollection=4. FBTerms ValueTerms IntervalDuration BlockDuration HistoryLength
Examples for Connect My Data Example Scope Strings SCE Scope = FB=1_3_4_5_8_13_18_19_31_34_35_39; IntervalDuration=900_3600;BlockDuration=Daily; HistoryLength= 34128000;SubscriptionFrequency=Daily; AccountCollection=5;BR=1; PG&E Scope = FB=1_3_4_5_7_8_13_14_15_18_19_31_32_34_35_37_38_39_40; IntervalDuration=300_900_3600;BlockDuration=Daily_BillingPeriod_Weekl y_Monthly; HistoryLength=63072000;SubscriptionFrequency=Daily; AccountCollection=5;BR=1; SDG&E Scope = FB=1_3_4_5_8_13_14_18_19_31_34_35_39_40; IntervalDuration=300_900_3600;BlockDuration=Daily_BillingPeriod_Weekl y_Monthly; HistoryLength=94608000;SubscriptionFrequency=Daily; AccountCollection=5;BR=1;
Scope Negotiation Oversimplified sequence diagram of Use Case #2 showing essence of scope negotiation TP DC RC Logon Logon HTTP Redirect with Scope={scope1} {scope2} Authorization request Scope={scope2} Authorization response Scope={scope2} access-token resourceUri authorizationUri referenceId
PUSH Model Notify/Get When data is ready, data custodian will notify third party with Multiple URLS (1 Many) Third party will make call (GET) based on the URL(s) provided Data custodian will respond with the data as part of response to GET call
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
SFTP Data Transfer When data is ready, data custodian will notify third party with Multiple URLS (1) Third party will make call (sFTP) based on the URL(s) provided Data custodian will respond with the data as part of response to sFTP get call
Notification TP DC Request: HTTP POST https://localhost/ThirdParty/espi/1_1/Notification Content-type: application/xml Response: <?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>https://localhost:8080/DataCustodian/espi/1_1/resource/Batch/Subscription/1 </resources> <resources>https://localhost:8080/DataCustodian/espi/1_1/resource/Authorization/1 </resources> <resources>https://localhost:8080/DataCustodian/espi/1_1/resource/Batch/Bulk/1 </resources> </BatchList>
ReadServiceStatus TP DC Request: HTTP GET https://services.greenbuttondata.org:443/DataCustodian/espi/1_1/resource/ReadServiceStatus Content-type: application/xml Response: <?xml version="1.0" encoding="UTF-8"?> <ServiceStatus xmlns="http://naesb.org/espi" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://naesb.org/espi espiDerived.xsd"> <currentStatus>1</currentStatus> </ServiceStatus>
Retrieve UsagePoints for a Subscription <?xml version="1.0" encoding="UTF-8"?> <feed xmlns="http://www.w3.org/2005/Atom" xmlns:espi="http://naesb.org/espi" xsi:schemaLocation="http://naesb.org/espi espiDerived.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <id>urn:uuid:1DA5F5DD-312B-4896-B910-098F59C73965</id> <title>Green Button Subscription Feed</title> <updated>1899-12-30T00:00:00Z</updated> <link rel="self" href="https://localhost/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint "/> <entry> <id>urn:uuid:C8C34B3A-D175-447B-BD00-176F60194DE0</id> <link rel="self" href="https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1"/> <link rel="up" href="https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint"/> <link rel="related" href="https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/MeterReading"/> <link rel="related" href="https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/1/ElectricPowerUsageSummary"/> <link rel="related" href="https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/LocalTimeParameters/01"/> <title>Green Button Sample Data File</title> <content> <UsagePoint xmlns="http://naesb.org/espi"> <ServiceCategory> <kind>0</kind> </ServiceCategory> <ServiceDeliveryPoint> <name>sample tariff showing block and tier pricing</name> <tariffProfile>./TariffSample.xml</tariffProfile> </ServiceDeliveryPoint> </UsagePoint> </content> <published>2013-09-19T04:00:00Z</published> <updated>2013-09-19T04:00:00Z</updated> </entry> <entry> <id>urn:uuid:C8C34B3A-D175-447B-BD00-176F60194DE0</id> <link rel="self" href="https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/2"/> <link rel="up" href="https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint"/> <link rel="related" href="https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/2/MeterReading"/> <link rel="related" href="https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Subscription/1/UsagePoint/2/ElectricPowerUsageSummary"/> <link rel="related" href="https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/LocalTimeParameters/01"/> <title>Green Button Sample Data File</title> <content> <UsagePoint xmlns="http://naesb.org/espi"> <ServiceCategory> <kind>0</kind> </ServiceCategory> <ServiceDeliveryPoint> <name>sample tariff showing block and tier pricing</name> <tariffProfile>./TariffSample.xml</tariffProfile> </ServiceDeliveryPoint> </UsagePoint> </content> <published>2013-09-19T04:00:00Z</published> <updated>2013-09-19T04:00:00Z</updated> </entry> </feed> TP DC HTTP GET https://localhost/DataCustodian/espi/1_1/ resource/Subscription/{subscriptionID}/UsagePoint Content-type: application/atom+xml
SFTP for Bulk Transfer Pertinent to the SFTP discussion are the concepts that each Third Party has a defined relationship with the Data Custodian. For automated exchange of information about his relationship there is a special Authorization obtained in Use Case #1 (see the Authorization.docx -- http://osgug.ucaiug.org/sgsystems/OpenADE/Shared%20Documents/Testing%20and%20Certification/GreenButtonTe stPlan/referenceMaterial/GreenButtonAuthorization.docx). We anticipate that when the Data Custodian has data available, it sends an asynchronous Notification to the Third Party. This Notification provides URIs of note that it is assumed the Third Party will want to retrieve. For the purposes of Bulk transfer, this URI will be: sftp://hostname:port/DataCustodian/espi/1_1/resource/Batch/Bulk/{bulkId} where {bulkId} is a unique identifier assigned by the Data Custodian and the balance of the URI is presented in the ApplicationInformation resource that both parties share (contains all relevant URIs and data for interchange via OAuth etc ). The Third Party would then retrieve the bulk data by using an SFTP client with that URI. This is a straw man concept for discussion on the call. Its advantage is that it in harmony with overall architecture of the Green Button Connect My Data RESTful architecture and simply adds SFTP as a means of transfer when a large data set is to be returned. Used to Retrieve the data using SFTP protocols How to initiate the SSH connection? What is the role if any of the client_credentials authorization to control access to SFTP enabled resources? Discussion After authorization of TP, they use Pene test, so what is benefit of access-token? sftp user:pw, user=<tpname>, password=<tp client-credentials access-token> Summary sftp://hostname:port/DataCustodian/espi/1_1/resource/Batch/Bulk/{bulkId} sftp user:pw, user=<tpname>, password=<tp client-credentials access-token>
Separation of PII containing Resource RetailCustomer from Subscription* PII Containing information Anononymous EUI Subscription RetailCustomer UsagePoint ServiceLocation Customer Agreement Normal ESPI Resources EndDeviceAsset ServiceSupplier PostionPoint Key TariffProfile Account Resource Authorization 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 ERP Resource
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>
Parking Lot Clarify accesses client_access_token= Authorizations/{}, Batch/Bulk/{bulkid}, ServiceStatus registration_access_token= ApplicationInformation access_token = used for individual authorizations/subscriptions Chunking for RESTfull GET of Bulk data Replacement of RetailCustomer/{retailCustomerId} with Subscription/{subscriptionId} Deferred access due to request that cant be satisfied now but results in notification later. 202 http response to GET
Action Items AI: Mark OAuth parameters as from OAuth in Authorization AI: Add ex: to each annotation of Authorization and ApplicationInformation in the schema AI: remove The field MUST be a valid URI. AI: URI caps in Authorization.docx, schema, ApplicationInformation, Authorization AI: thirdPartyScopeSelectionScreenURI thirdPartyLandingScreenURI in schema, Authorization.docx, OpenESPI code AI: Dale will check on how to use access-token with SFTP AI: Replace RetailCustomer/{retailCustomerId} with Subscription/{subscriptionId} in all APIs and related documents
