Openade 1.0 Service Definition - Web Services Extension

1 UCAIug OpenSG OpenADR Task Force 2 OpenADE 1.0 Service Definition - Web Services Extension

1OPENADE 1.0 SERVICE DEFINITION - WEB SERVICES EXTENSION

2VERSION: DRAFT V0.1

3Release Date: 8/13/2010

4 Acknowledgements

5The following individuals and their companies have contributed and/or provided support to the work of 6the OpenADR 1.0 Service Definition - REST Extension:

7  Ed Koch from Akuacom 8  Albert Chiu from Pacific Gas & Electric 9  Gerald Gray from CIMple Integrations 10  Mark Ortiz from Consumers Energy 11  Shawn Hu from Xtensible Solutions 12  Steve Van Ausdall from Xtensible Solutions 13  Bruce Bartell from Xtensible Solutions

14The OpenADR Task Force wishes to thank all of the contributors to OpenADR, especially the above- 15mentioned individuals and their companies for their support of this important endeavor, as it sets a key 16foundation for an interoperable Smart Grid. 17

18 Document History

19 Revision History

20Date of this revision: Apr. 15, 2010

Revision Revision Revision Summary of Changes Changes Number Date By marked

0.1 08/13/2010 Gerald R. Gray Initial draft discussion version. N

21 Open Issues Log

22Last updated: Aug. 13, 2010

Issue Issue Date Provided By Summary of the Issue

24 Contents

251 Introduction 6

26 1.1 Rights / Management / Governance 6

27 1.1.1 Intellectual Property Rights 6

28 1.1.2 CIM Object Models 6

29 1.1.3 SERVICE RESOURCE Definitions 7

30 1.2 Referenced Specifications 7

31 1.3 Referenced Guidance 7

32 1.4 Namespaces 7

33 1.5 SCOPE 7

342 RESOURCES 8

35 2.1 URI FORMAT / SYNTAX 9

36 2.2 Message Document Format 9

37 2.3 Payload Entities 9

38 2.3.1 Resources 9

393 Patterns 11

40 3.1 Creating, Updating, Deleting 11

41 3.2 Query, Request and Response (Retrieve) Formats 11

42 3.2.1 Format 11

43 3.2.2 Category 11

44 3.2.3 Reference Expansion 11

45 3.2.4 Sorting 11

46 3.2.5 Filtering 12

47 3.2.6 Iteration 12

48 3.2.7 Conditional Retrieval 12

49 3.3 Event Notification 12

50 3.4 Batch Transfers 12

514 Discovery 12

525 Metadata 13

536 Extensibility 13

547 Versioning 13

558 Concurrency 13

569 Resource Definitions 13

57 9.1 Resource Definition 14

58 9.2 Resource Details 14

59 9.2.1 Collection (Feed) 14 60

61 62 List of Figures

63 No table of figures entries found. 64 List of Tables 65Table 1: Scope of OpenADR 1.0...... 7 66Table 2: Resource Inventory List...... 13 67

69 1 INTRODUCTION

70This document contains only the extensions necessary to the OpenADR Common specification to build an AtomPub 71resource representation syndication server. It is based heavily on GData, an open specification of Atom Pub 72extensions required for general-purpose data synchronization.

73These extensions define a collection of resource feeds as a discoverable, stateless data service, using HTTPS to 74send and receive requests and information in AtomPub XML. This resource-oriented architecture is proposed, 75similar to efforts elsewhere, such as web / Internet of things, GData, and OData. This architecture provides secure 76access to scalable methods and data resources hosted by the provider, while maintaining concurrency and 77integrity. All data is secured at the user level, so that access to individual operations can be provided or revoked to 78external services, and other users’ data will still be protected.

79 1.1 RIGHTS / MANAGEMENT / GOVERNANCE

80 1.1.1 INTELLECTUAL PROPERTY RIGHTS

81This document and the information contained herein is provided on an "AS IS" basis. UCAIug DISCLAIMS ALL 82WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 83INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF 84MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

85UCAIug requests any party that believes it has a patent claim that would necessarily be infringed by 86implementations of this UCAIug work, to notify UCAIug immediately, so that fair and reasonable licensing terms 87can be negotiated. UCAIug invites any party aware of applicable undisclosed patent claims to contact the UCAIug. 88UCAIug may include such claims on its website, but disclaims any obligation to do so.

89UCAIug takes no position regarding the validity or scope of any intellectual property or other rights that might be 90claimed to pertain to the implementation or use of the technology described in this document or the extent to 91which any license under such rights might or might not be available; neither does it represent that it has made any 92effort to identify any such rights. Copies of claims of rights made available for publication and any assurances of 93licenses to be made available, or the result of an attempt made to obtain a general license or permission for the 94use of such proprietary rights by implementers or users of this UCAIug recommendation, can be obtained from the 95UCAIug. UCAIug makes no representation that any information or list of intellectual property rights will at any time 96be complete, or that any claims in such list are, in fact, Essential Claims.

97 1.1.2 CIM OBJECT MODELS

98The recommendations herein build on work owned by the IEC. Required extensions identified in this 99recommendation will be submitted to the IEC, and will be tracked for inclusion in the model.

100Information on the management of rights and governance can be found at the page below. 101http://www.iec.ch/tctools/patent-guidelines.htm

102 1.1.3 SERVICE RESOURCE DEFINITIONS

103If necessary, UCAIug is willing to work with standards development organizations to incorporate additional aspects 104of this recommendation into standards, including the specification of how to use profiled (restricted) CIM objects 105within the SOAP over HTTP environment, and possibly the web service definitions themselves.

106 1.2 REFERENCED SPECIFICATIONS

107  [1] IEC CIM (TC 57 61968/61970) - http://tc57.iec.ch

108  [2] Open Authorization (oAuth)

109  [3] HTTP/1.1 – IETF RFC 2616

110  [4] Atom Publishing Protocol – IETF RFC 5023

111  [5] PubSubHubBub

112 1.3 REFERENCED GUIDANCE

113  [G1] OpenADR System Requirements Specification

114  [G2] OpenSG OpenADR SD – Common

115  [G2] 3PDA – Security Profile for Third Party Data Access (ASAP-SG)

116  [G3] GData

117  [G4] OData

118 1.4 NAMESPACES

119This document does not define any namespaces. Namespaces defined in referenced specifications shall be used as 120defined.

121 1.5 SCOPE

122The use cases with their associated priority are defined in the OpenADR SRS, copied here for convenience:

123 Table 1: Scope of OpenADR 1.0

Use Case Service Name Functional Description of the Service Priority Scenario

Administrate DR Customer Customer is Registered for, Updated or Removed from a DR Program. 3 Customer for DR Agreement

Administrate DR DR Resource / DR Resource is registered and associated with a DR Program and 2 Resource DRAS Client Customer. The Resource is updated and/or removed from DR Program.

Use Case Service Name Functional Description of the Service Priority Scenario

Administrate DR DR Asset DR Asset is registered and associated with a DR Resource. The Resource 2 Asset is updated and/or removed from DR Program.

Execute DR Event Notify DR Event DR Event information is sent to participants prior to the DR Event start 1 based on defined intervals and is Updated, and/or Canceled.

Execute DR Event DR Event DR Event is a polymorphic message type that supports Direct Load 1 Control, DR Instructions (Objectives), Price Schedule

Execute DR Event Forecast Multiple levels of aggregated DR Demand and Telemetry data is 6 – Operational Demand provided for the purpose of coordinating a DR Event and to provide Coordination checks against circuit limits.

Execute DR - Asset / Resource The DR Resource or Asset (in the event of DLC) provides status for opt 1 Event Status (State) in / out or other state that impacts Demand Response. Monitoring / Confirmation The Status message may be as a confirmation reply to a DR Signal or as an update resulting from a state/status change or in response to a Get message.

Post DR Event – Meter Read & The process and messages used for settlement of a DR event are the 4 M&V / Billing same as defined in the Utility AMI AMI-ENT System Requirements Settlement Specification, Utility AMI-ENT Task Force.

The meter read interval is determined by the interval of DR Event participation.

DR Bidding 5

124It is noted that for some use cases, such as 1.0 Administrate DR Program and 2.0 Administrate Customer, that with 125so many differences between regions that “it is unlikely that these will be automated”. Assuming once the 126differences in the business processes and data exchange have been resolved. Therefore the scope of the web 127services will be on those use cases and scenarios ranked with a priority of 1 or 2 in the table above.

128 2 RESOURCES

129 This RESTful implementation profile uses a Resource Oriented Architecture approach. This architecture 130 provides similar operations for external data consumer applications to request data and methods. Generally, 131 data is made available as a feed, which is an agreement about how to query, create, update, request, and 132 delete entries (individual object records, which have a defined schema according to their type).

133 The resource extensions are listed below for the following objects from the OpenADE SD – Common 134 document:

135 AssetResourceStatus 136 Direct Load Control 137 DR Asset

138 DR Event 139 DR Message 140 DR Resource

142 2.1 URI FORMAT / SYNTAX

143The URIs of the resources defined in OpenADR take the general form below. The does not need to be 144the same across different implementations, since resource addresses include the entire string.

145http :///?

146Resource requests require inputs of user, key, and resource object. Additional path elements may be required for 147some resources. Resources return a list (feed) or an individual entry.

148Requests for protected resources require https, and require authorization token in HTTP header.

149The query section contains additional inputs that can be specified to affect processing, passed as a list of 150name=value pairs.

151 2.2 MESSAGE DOCUMENT FORMAT

152Message documents shall use the extended version of the Atom Publishing Protocol (AtomPub), which extends the 153Atom Syndication Protocol) defined in [G2] GData for the elements described in this document, to fulfill this need.

154In addition to the recommended format, it is possible to support additional representations. An input can be 155accepted to provide RSS or other formats, but these additional formats are all optional, and will only be considered 156for this specification if needed.

157 2.3 PAYLOAD ENTITIES

158Payload entities will be specializations (subclasses) of the message document “entry”. They will therefore inherit all 159elements defined in the message document entry, as well as implement an XML schema representation of a CIM 160class defining additional schema elements.

161Feed payloads will contain a list of references to resource entries that match the request query criteria.

162The batch payload defined in the Common document allows a number of documents or resource requests to be 163included in a single request.

164 2.3.1 RESOURCES

165Domain data objects build on the IEC CIM model. In general, resources will be named using the CIM class as the 166resource part of the URI. Collections are returned if no specific entry ID is specified in the resource path. For 167listings of fields, see the details for each resource, defined in OpenADR Common document.

168Examples are shown below. Note that these are separate examples of a GET request issued to the resource path in 169the comment before the example result.

170AssetResourceStatus 171 172 173 17412345678910 175 176 177 178DRAsset 179 180 181 18212345678910 183 184 185 186DREvent 187 188 189 19056421587 191 192 193 1932011-12-17T00:00:00Z 1942010-12-17T00:00:00Z 195 196 197 198 199 200DRMessage 201 202 203 20485945261 205 20619283746 207 208 209Guest House 210 211electricity 212 213 214 215DRResource 216 217 218 21985945261 220 22119283746

222 223 224Guest House 225 226electricity 227 228 229

230 3 PATTERNS

231This section contains guidance and decisions on how message exchanges flow for the general scenarios below. In 232general, the constructs and operations defined in AtomPub shall be used, including requests for Services, 233Workspaces, Collections, Members, Categories, and Media Types. Extensions are generally refined subsets of the 234full specifications detailed in [G2] GData, and full implementations should not break clients who only implement 235these recommendations.

236 3.1 CREATING, UPDATING, DELETING

237The POST method is to be used for the creation of new entries, while PUT is to be used for updates to existing 238entries. DELETE is to be used to delete an entry.

239 3.2 QUERY, REQUEST AND RESPONSE (RETRIEVE) FORMATS

240This section specifies the input parameters that can be passed to GET method operations for format, category, 241reference expansion, sorting, filtering, and iteration through list items.

242 3.2.1 FORMAT

243The default, and only required format, will be CIM-extended AtomPub feed / entry XML.

244 3.2.2 CATEGORY

245Specification of the category of entries is not included in this recommendation. However it can be accomplished 246using the Atom element “term”, and if needed could be supported as a qualifier in queries by accepting category 247terms as inputs. In general, each CIM object class would be a category of entry, so that the representations of 248entries can be specified with a schema.

249 3.2.3 REFERENCE EXPANSION

250By default, feed queries will return a list of resource links. If the reference expansion flag is set, entries returned 251will be expanded to contain their full representation.

252Note: [G3] OData uses an m:inline extension to the atom:link element for this purpose.

253 3.2.4 SORTING

254Ability to specify the sort order of resulting query / request entries is not necessary - subsequent processing of 255received data can display or rearrange data however desired. However, ordering of entries shall remain consistent 256across requests, so that an iterator can be used to page through results. Collection results shall be sorted by date 257of last modification in descending order. (Latest to earliest updated)

258 3.2.5 FILTERING

259Filtering requires inputs that allow the specification of the resource name and/or path, as well as a range of 260publication or update date/times. Properties of the entry element (defined by its category type) could be defined 261to be acceptable by default as filter terms for the associated resource. Need to determine if it is feasible to 262implement all, or if identification is necessary of only the filter terms required for specific use cases. Possibly usage 263patterns could determine the need for indexing, etc.

264If a specific entry ID is specified, that entry is returned.

265 3.2.6 ITERATION

266Iteration inputs allow actors to request a subset of entries or references at a time, and then page through them for 267processing. Inputs include the starting entry index, and number of entries per page.

268Query results shall include the additional openSearch terms as defined in [G2] GData for iteration.

269 3.2.7 CONDITIONAL RETRIEVAL

270If-None-Match in HTTP header shall be used to retrieve entries only if they have changed as defined in both [G3] 271OData and [G2] GData.

272 3.3 EVENT NOTIFICATION 273 274The Publish / Subscribe pattern may be useful in the implementation of some OpenADR services, and is specified 275mostly in AtomPub. However, there is no mechanism defined in AtomPub to notify subscribers of new feed 276entries. This requires the actors to “poll” for new data, and while this is sufficient in many cases, some business 277processes require ability to notify in order to achieve reduced latency in client updates.

278[5] PubSubHubbub defines a mechanism for this purpose, and may be implemented for this purpose.

279 3.4 BATCH TRANSFERS

280If desired, a feed for each data service consumer could be provided through which all subscribed content would be 281returned in a single request (or series of large chunks). This mechanism should allow any resource type to be 282included within a single feed. The regular synchronization behavior shall be implemented as a regular feed request 283or subscription notification with reference expansion specified, as defined in [G2] GData.

284 4 DISCOVERY

285Discovery of available resources may utilize the [9] AtomPub constructs defining services, workspaces, and 286collections. This is accomplished with a client request to GET the definition of all collections, followed by 287enrollment / authorization, and finally subscription to the appropriate feeds.

288 5 METADATA

289A “Resource” resource may allow retrieval of the representation of all available resources, and the currently 290implemented version of each.

291[9] AtomPub defines a “workspace collection” for this.

292 6 EXTENSIBILITY

293[9] AtomPub is specified to be extensible, and implementations should be able to function even with different 294versions of client or server. In addition, section 6.2 in AtomPub provides recommended behavior.

295Extensions to the CIM objects will be associated with specific versions of the namespace, specified in the version 296attribute of the schema element.

297 7 VERSIONING 298 299As additional capabilities are added to the interface definition, a specification of the version of the definition will 300be needed to help in service discovery negotiation. This should not change the namespace of any definitions. 301[Insert specific example here]

302 8 CONCURRENCY 303 304In most cases, Resources that are being utilized are Read Only. Should a need for an update to a Resource be 305determined; in order to ensure data integrity, clients may only update resources if they are updating the current 306version of the resource. If an update request fails due to conflict (not current version), the client must request the 307latest version, apply changes to that representation, and retry the update. 308[G2] GData and [G3] OData both use ETags for versioning / concurrency management, and are largely compatible. 309Additional details will be specified as identified during initial implementations. 310See GData Resource Versioning for more information.

311 9 RESOURCE DEFINITIONS

313The following tables provide an overview of the service resources to be implemented by provider and consumer. 314Full definitions and expected behavior will be developed in a subsequent publication.

315 Table 2: Resource Inventory List

Resource Method Inputs Outputs Description

GET POST POST … …

317 9.1 RESOURCE DEFINITION

318All resources support the patterns in Section 3, returning a (possibly expanded) collection of data resource stream 319entries. Individual entries can be managed using POST, UPDATE, and DELETE. Permissions may be set according to 320policy, but guidance is provided regarding the typical configuration in resource details following this table.

321 9.2 RESOURCE DETAILS

322Many of the resources below are necessary to support initial setup and authorization. Implementations shall 323conform to referenced specifications for details on these interfaces. Clarifications and refinements made to 324support these service resources are denoted where necessary.

325All resources are to be implemented as collections, with the elements listed in the sections below. Additional 326allowed values may be specified, and will be included here as necessary.

327 9.2.1 COLLECTION (FEED)

328Collections consist of feeds, and exhibit behavior as defined in [9] AtomPub.