Probid B2B programmer guide

Transcription

1 Probid Version 11 18/04/2017 Printed on 2/06/17 15:21 Page 1 of 26

2 Table of Contents Chapter 1. History... 4 Chapter 2. Introduction... 5 Chapter 3. Bidladder protocols Introduction Balance Follow-up R3E protocol The TSO initiates a BFU-R3E adjustment (= R3EActivation) The BSP answers the BFU-R3E request (= R3EAcknowledgment) Communication of network constraint program... 7 Chapter 4. Messages specifications Data structure Error: Error message Balance Follow-up R3E activation protocol Data structure TsoCompensation: Base information for activations in Balance Follow-up R3E context Data structure BspBfuResponse: BSP Response to the TSO BFU Decision Generic message parts Data structure Partner: Partner identifier Data structure Activation: Base information for an Incremental or a Decremental activation Data structure activatedaccesspoints: Base information for the activated access points Data structure GlobalDelta: Base information for a Global Delta for a period Data structure Compensation: Base information for a Compensation Data structure NetworkConstraintsProgram: Message for network constraints program Data structure NetworkConstraint: Message part for network constraint s Chapter 5. Using the B2B portal Using the Probid B2B portal -.NET Code samples ProbidBaseURL Printed on 2/06/17 15:21 Page 2 of 26

3 Table of Figures Figure : IDPCR Acceptance process.... Error! Bookmark not defined. Figure : TSO accepts IDPCR.... Error! Bookmark not defined. Figure : TSO rejects IDPCR.... Error! Bookmark not defined. Figure : TSO rejects invalid IDPCR.... Error! Bookmark not defined. Figure : TSO sends network constraint program Printed on 2/06/17 15:21 Page 3 of 26

4 Chapter 1. History Version Date Changes Probid Initial Release Printed on 2/06/17 15:21 Page 4 of 26

5 Chapter 2. Introduction The 'partner doc' is a developer guide for the use of the Probid B2B API. This document is organized into three sections. Bidladder protocols The first part describes the protocols required for Bidladder communication. Currently we only have the Balance Follow-Up R3E (BFU-R3E) protocol. Messages specifications The second part is a detailed message specification. Using the Probid B2B portal The last part explains how the communication with the B2B portal actually works. C# code samples are supplied. Printed on 2/06/17 15:21 Page 5 of 26

6 Chapter 3. Bidladder protocols 3.1. Introduction This section specifies protocols enabling Bidladder activations. Following protocols are described. The Balance Follow-Up R3E (BFU-R3E) Throughout this section, references are made to the detailed specification of XML messages. This specification is provided in the following section (Message specification). Please note that, despite a few changes in the messages structure, the BFU-R3E protocol is very similar to the BFU protocol used for production coordination Balance Follow-up R3E protocol This part concerns messages related to Balance Follow-Up R3E (BFU-R3E) mechanism. The following diagram illustrates the R3E protocol The TSO initiates a BFU-R3E adjustment (= R3EActivation) The Dispatcher decides to generate program modifications (I/Ds) on specific Unit(s) (= BFU) and on specific Bidladder contracts (= BFU-R3E) and therefore sends the message to the corresponding ARPs (for BFU) and BSPs (for BFU-R3E). Printed on 2/06/17 15:21 Page 6 of 26

7 The message contains for each ContractReference, Bid number (= also called BidId in BMap) and for each concerned quarter of hour the nominated value and the delta (I/D) compared to the nominated value. It also contain the global delta value for each concerned quarter of hour (for each quarter of hour, the sum of delta of the contracts / BidIDs found in the message) [TsoCompensation: Base information for activations in Balance Follow Up R3E Activations] Notes 1. The term 'compensation' was used to designate I/Ds requested for a BFU/TER adjustment. This is not an appropriate usage of that term that is dedicated to the Balance Follow-Up R3E context. 2. The BSP will receive only 1 message for all contracts / Bids that have been activated 3. The nominations which are used are coming directly from the BMap application The BSP answers the BFU-R3E request (= R3EAcknowledgment) The BSP acknowledges the TSO request on the Probid URL. URL: {ProbidBaseURL}\app\b2b\submitBfuDecisionBsp.aspx Message: BspBfuResponse: BSP Response to the TSO BFU Decision Communication of network constraint program Upon reception of an IDPCR, validation is performed against network constraints. Network constraints will be communicated to the ARPs and BSPs in day ahead, at the end of the nomination procedure of the CIPU. Network constraints can eventually be updated due to modifications of the operational conditions of the Elia grid. Updated network constraints will be communicated to the ARPs and BSPs. Following sections provide detailed specifications of network constraint publishing scenario TSO sends network constraints program Printed on 2/06/17 15:21 Page 7 of 26

8 Figure 1: TSO sends network constraint program. 1) Elia dispatcher specify constraints 2) Probid system sends network constraints program The NetworkConstraintProgram message is sent to each ARP and BSP. Message: NetworkConstraintsProgram: Message for network constraints program Printed on 2/06/17 15:21 Page 8 of 26

9 Chapter 4. Messages specifications Data structure Error: Error message XML Namespace: This structure is returned by any page that encounters an error. The cause of the error can be an invalid user request or an internal error Synopsis Field Description errordescription A description of the error errorsource The source of the error request optional The request that was received and that might have caused the error Detailed fields information Field errordescription A description of the error Min len Field errorsource The source of the error Min len. 1 The following table indicates the valid values: Value CLIENT SERVER Description The origin of the error is the client application (e.g. invalid message). The origin of the error is the server application (e.g. a problem with the TSO's system). Printed on 2/06/17 15:21 Page 9 of 26

10 Field request The request that was received and that might have caused the error. optional Min len Balance Follow-up R3E activation protocol Data structure TsoCompensation: Base information for activations in Balance Follow-up R3E context. XML Namespace: Synopsis Field Description compensation 0 <= n list of Compensation List of Compensations globaldelta 0 <= n list of GlobalDelta List of global delta context optional(default= congestion) Balance Decision context. bsp Partner BSP reference. tso Partner TSO reference. tsoreference Tso reference for the request Detailed fields information Field compensation List of Compensations 0 <= n list of Compensation This information describes the list of the compensations Field globaldelta List of global delta 0 <= n list of GlobalDelta This information describes the list of the global delta. For each concerned period in the compensation list, the delta is cumulated in order to obtain a global delta. Printed on 2/06/17 15:21 Page 10 of 26

11 Field context Balance Decision context. Optional (default= balancefollowupr3e) Min len. 1 The following table indicates the valid values for Bidladder: Value Description balancefollowupr3e balancefollowupr3e valid as from This information represents the context in which the balance decision has been taken Field bsp BSP reference. Partner This information represents the Energy Coordinator identifier or EIC Field tso TSO reference. Partner This information represents the Tso identifer Field tsoreference Tso reference for the request. Min len. 1 Max len. 30 This information represents a unique identifier given by the TSO Data structure BspBfuResponse: BSP Response to the TSO BFU Decision XML Namespace: Printed on 2/06/17 15:21 Page 11 of 26

12 Synopsis Field Description begindatetime datetime Begin Date and Time bsp Partner BSP reference compensation 0 <= n list of Compensation List of Compensations tso Partner Tso reference tsoreference Tso reference for the message. decision BSP Decision Detailed fields information Field begindatetime Begin Date and Time datetime This is the considered begin period (date+time) Field bsp BSP reference Partner It references the bsp managing the balance follow up R3E decision for the observed period Field compensation List of Compensations 0 <= n list of Compensation This information describes the list of the compensations Field tso Tso reference Partner It references the tso to which is sent the response. Printed on 2/06/17 15:21 Page 12 of 26

13 Field decision ARP Decision Min len. 1 The following table indicates the valid values: Value Accept Confirm Description BSP accepts the activation to the TSO BFU Decision and sends potential activation volumes BSP confirms the activation to the TSO BFU Decision and sends real activation volumes Field tsoreference Tso reference for the message. Min len. 1 Max len. 30 This information represents a unique identifier given by the TSO Generic message parts Data structure Partner: Partner identifier XML Namespace: This data structure is used to identify a partner in a transaction. It forms part of several message structures. The fact that the code type must be specified in addition to the code itself, allows users to use their preferred code type, provided it is recognised by the system. In addition, the identity of a partner can be indicated in words to make messages easier to read for humans Synopsis Field Description code Code codetype Code type Printed on 2/06/17 15:21 Page 13 of 26

14 Field Description friendlyname optional Friendly name Detailed fields information Field code Code Min len Field codetype Code type Min len. 1 The following table indicates the valid values: Value C03 C11 Description EIC code ELIA proprietary coding scheme Field friendlyname Friendly name optional Min len. 1 This field is optional and not used by the system which is processing the messages. It is only there to facilitate human reading of the message Data structure Activation: Base information for an Incremental or a Decremental activation XML Namespace: Synopsis Field Description begindatetime datetime Begin Date and Time Printed on 2/06/17 15:21 Page 14 of 26

15 Field Description enddatetime datetime End Date and Time delta activatedaccessp oint Optional within decimal TsoCompensation Optional 0 <= n within BspBfuResponse List of activatedaccessp oints Delta value List of activated access points with their volume Detailed fields information Field begindatetime Begin Date and Time datetime This is the considered begin period (date + time) Field enddatetime End Date and Time datetime This is the considered end period (date + time) - enddatetime is excluded Field delta Delta value optional decimal Fraction digits 1 Value of the activated volume This can be a positive or a negative value and it is expressed in MW. Only present during the R3EActivation Field activatedaccesspoints List of activated volumes 0 <= n List of activatedaccesspoints This information describes the list of the activated volumes. Only present during the R3EAcknowledge Printed on 2/06/17 15:21 Page 15 of 26

16 Data structure activatedaccesspoints: Base information for the activated access points XML Namespace: Synopsis Field Description ean Ean of the access point powerdelta decimal Delta value Detailed fields information Field ean Ean of the access point This is the ean of the activated access point Field powerdelta Delta value optional decimal Fraction digits 1 Value of the activated volume This can be a positive or a negative value and it is expressed in MW Data structure GlobalDelta: Base information for a Global Delta for a period XML Namespace: Synopsis Field Description begindatetime datetime Begin Date and Time enddatetime datetime End Date and Time delta decimal Delta value Detailed fields information Field begindatetime Begin Date and Time Printed on 2/06/17 15:21 Page 16 of 26

17 datetime This is the begin date (date + time) for the total activated volume Field enddatetime End Date and Time datetime This is the end date (date + time) for the total activated volume. enddatetime is excluded Field delta Delta value decimal Fraction digits 1 This information represents the global activated value for this period. It is the cumulated value of all delta for the same period and for all bids. This can be a positive or a negative value and is expressed in MW Data structure Compensation: Base information for a Compensation XML Namespace: Synopsis Field Description contractreference Contract reference bidid int Bid number generated by Bmap newactivation 0 <= n list of Activations List of activated volumes Detailed fields information Field contractreference Contract reference This information represents the contract reference. Printed on 2/06/17 15:21 Page 17 of 26

18 Field bidid bidid int This information represents the bid number generated by the Bmap tool Field newactivations List of activated volumes 0 <= n list of Activations This information describes the list of the activated volumes Data structure NetworkConstraintsProgram: Message for network constraints program XML Namespace: This message is used by the TSO to communicate the network constraint program to ARPs and BSPs. The program is provided as a set of network constraints, each constraint being characterized by a period (start time / end time), an electrical zone, a direction (increments / decrements) and a maximum power delta (MWCap). The day-ahead version of the program is published before 18:00. Both day-ahead and intraday updates are authorized. Program updates have an immediate effect Synopsis Field Description ExecutionDate date Execution date Printed on 2/06/17 15:21 Page 18 of 26

19 Field Description NetworkConstrain0 <= n list of Network constraints ts NetworkConstrain t Detailed fields information Field ExecutionDate Execution date date The program execution date. The execution date is either the current day (intraday program updates) or the next day (day-ahead program updates) Field NetworkConstraints Network constraints 0 <= n list of NetworkConstraint The complete set of network constraints that are effective on the specified execution date. When an empty set is provided, no network constraint apply for the specified execution date Data structure NetworkConstraint: Message part for network constraint XML Namespace: Synopsis Field Description begindatetime datetime Begin date and time enddatetime datetime End date and time. ElectricalZone code Electrical zone Direction Direction MWCap decimal MWCap Detailed fields information Field begindatetime Begin Date and Time Printed on 2/06/17 15:21 Page 19 of 26

20 datetime This is the considered begin period (date+time) for the network constraint on the specific ElectricalZone and of the specific Direction Field enddatetime Begin Date and Time datetime This is the considered end period (date+time) for the network constraint on the specific ElectricalZone and of the specific Direction Field ElectricalZone Electrical zone Code list code Following identification codes must be used. ST (Stalen) SC (Schaerbeek / Brussels) RU (Ruien) MK (Merksem) LG (Liège) LAE (Langerbrugge East) LAW (Langerbrugge West) HTE (Hainault East) HTW (Hainault West) 380 (380 kv) N/A (Not applicable because foreign PP) Field Direction Direction Min len. 1 The following table indicates the valid values: Printed on 2/06/17 15:21 Page 20 of 26

21 Value I D Description Increment Decrement Field MWCap MWCap decimal Fraction digits 1 A zero value indicates that no power program modification is authorized for the specified direction, period and electrical zone s The following table describes all the datatypes allowed in XML data structure specifications. Data type Typical XML representation Lexical pattern Comments.* The following constraints can be expressed: minimum length, maximum length, pattern, choice of valid values int -1, 0, , decimal -1.23, , , 210 boolean 1, 0, true, false [-+]?[0-9]+ The following constraints can be expressed: minimum value, maximum value. Values must be between and inclusive. [-+]?[0-9]+(\.[0-9]+)? 1 0 true false The following constraints can be expressed: minimum value, maximum value. Values must have at most 28 digits, with. code.* This is similar to, but allowed values must be part of a documented "code table". The actual signification of the code table constraint is application-dependent datetim e To indicate 1:20 pm on May the 31st, 1999 in Brussels which is 2 hours ahead of UTC, one would write: [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}(:[0-9]{2}(:[0-9]{2})?)?([+- ][0-9]{2}(:[0- Represents a time instant. If the time zone offset is not indicated, UTC is assumed. See also the example below for daylight saving time handling. Printed on 2/06/17 15:21 Page 21 of 26

22 Data type Typical XML representation 31T13:20:00+02 :00 Lexical pattern Comments 9]{2})?)? time 13:20:00+02:00 [0-9]{2}(:[0-9]{2}(:[0- Represents a time instant in the day. If the time zone offset is not indicated, UTC is 9]{2}?)?([+-][0- assumed. See also the example below for 9]{2}(:[0- daylight saving time handling. 9]{2})?)? date binary To indicate May the 31st, 1999, one would write: [0-9]{4}-[0-9]{2}-[0-9]{2} Encoded binary data (the default encoding is base64) Represents a calendar date. Used to transfer data that is not unicode text. The daylight saving times (25th hour) issue is solved by the use of UTC time or by indicating the time-zone delta. Example: summer time to winter time in Belgium in ISO Local time UTC : h : : h : : h : :00+01 at 3h it is 2h : : h :00 Example: winter time to summer time in Belgium in ISO Local time UTC : h : : h : :00+02 at 2h it is 3h : : h :00 Printed on 2/06/17 15:21 Page 22 of 26

23 Chapter 5. Using the B2B portal 5.1. Using the Probid B2B portal -.NET Code samples Probid B2B portal uses XML messaging over the HTTP protocol. XML request messages are posted in the body of an HTTP request. XML response messages are retrieved from the body of the HTTP response. Note Currently, standard Web services technology (SOAP) is not suported. Following.NET code sample illustrates this principle using the Ping service of the ProBid B2B portal. The Ping service is supplied for testing purpose. This service accepts an input message ("hello", in the following example) and responds with an output message ("Probid hello", in the following example). Usually, following operations must be performed to invoke a service of the B2B portal. 1) Initialization of the HttpWebRequest object (System.Net library). Following properties must be specified: a) The URL of the ASP.NET page. The URL of the ASP.NET page that implements the service must be specified. For the Ping service, the ping.aspx page must be specified. ASP.NET pages are documented in the section Balance Follow-up R3E protocol. b) Credentials User account and password must be supplied. c) HTTP method Only the post method is allowed. d) Content type Only the text/xml content type is allowed. 2) Initialization of the input message object (Probid.R3EB2bMsg library). Probid B2B message objects are data objects used to communicate data to/from a service. For the Ping service, a Probid.R3EB2bMsg.Ping object must be supplied as input message. Message classes are documented in the section Messages specifications. 3) Serialization of the input message object. The input message object must be serialized to the HTTP request stream. Standard.NET XML serialization must be used. B2B message classes can be generated from the B2B XSD schema (Probid.R3EB2bMsg.xsd, supplied by Elia). For the.net platform, the xsd command line tool must be used (command : xsd Probid.R3EB2bMsg.xsd /classes /namespace:probid.r3eb2bmsg). 4) Posting of the HTTP request. Printed on 2/06/17 15:21 Page 23 of 26

24 5) De-serialization of the HTTP response. HTTP response must be de-serialized to a Probid B2B message object. For the Ping service, the Probid.R3EB2bMsg.Ping class must be used. Message classes are documented in the section Messages specifications. In case of an error, two situation may arise. HTTP request status code is 510. This indicates a Probid specific error. The error message can be retrieved by de-serializing the error stream to a Probid.R3EB2bMsg.Error object. HTTP request status code is not 510. This indicates an unforeseen error. using System; using System.IO; using System.Net; using System.Xml.Serialization; // This sample code illustrates how to invoke the Ping service of the ProBid // B2B interface. Other services can be invoked in a similar way. // Note: // In this sample code, B2B message classes (namespace Probid.R3EB2bMsg) are // generated from the B2B XSD schema (supplied by Elia). // Use following command line to generate message classes: // xsd Probid.R3EB2bMsg.xsd /classes /namespace:probid.r3eb2bmsg public class PingSampleCode { static void Main([] args) { ProbidBaseURL = " username = "UserAccount"; password = "Pasword"; // Init HTTP Request on ping.aspx HttpWebRequest httprequest = (HttpWebRequest)WebRequest.Create(ProbidBaseURL + "ping.aspx"); httprequest.contenttype = "text/xml"; httprequest.method = "POST"; httprequest.timeout = 30000; httprequest.credentials = new NetworkCredential(userName, password); // Init Ping request message Probid.R3EB2bMsg.Ping pingrequest = new Probid.R3EB2bMsg.Ping(); pingrequest.data = "hello"; // Serialize Ping message to the HTTP Request stream XmlSerializer xs = new XmlSerializer(pingRequest.GetType(), " using (Stream poststream = httprequest.getrequeststream()) xs.serialize(poststream, pingrequest); Printed on 2/06/17 15:21 Page 24 of 26

25 // Post HTTP Request and get Response HttpWebResponse httpresponse = null; try { httpresponse = (HttpWebResponse)httpRequest.GetResponse(); } catch (WebException ex) { // Handle exceptions // Status code 510 is dedicated to ProBid build-in exceptions WebResponse resp = ex.response; if (resp!= null && resp is HttpWebResponse && (int)((httpwebresponse)resp).statuscode == 510) { // De-serialize Error message Probid.R3EB2bMsg.Error error; xs = new XmlSerializer(typeof(Probid.R3EB2bMsg.Error), " error = (Probid.R3EB2bMsg.Error)xs.Deserialize(resp.GetResponseStream()); } Console.WriteLine(error.errorDescription); } else { throw ex; } // De-serialize Ping response message Probid.R3EB2bMsg.Ping pingresponse; xs = new XmlSerializer(typeof(Probid.R3EB2bMsg.Ping), " pingresponse = (Probid.R3EB2bMsg.Ping)xs.Deserialize(httpResponse.GetResponseStream()); } } Console.WriteLine(pingResponse.data); // expected "Probid hello" Printed on 2/06/17 15:21 Page 25 of 26

26 5.2. ProbidBaseURL The {ProbidBaseURL} depends of the environment in which the message exchange takes place. Demo environment: Acceptance environment: Production environment: (Access credentials for this environment will only be given once all testing is validated by ELIA) Before all testing please notify your ELIA contractual contact well in advance. Printed on 2/06/17 15:21 Page 26 of 26