2. Web Service Channel Configuration
2.1 Steps to create a self-signed certificate using Keytool
2.2 Configuration of a machine user
4. Guideline for Data Provider’s submissions
4.1 Main Goals of the Guideline
4.2.1 Repeating Submission for All Previous Hours
4.2.2 Too Frequent Submissions
4.3.1 Incorrect Submission Resolution
4.3.2 Too Detailed Data in Curves
4.4.1 Too Frequent / Regular Updates
5. Web Service Client Troubleshooting
REFERENCED DOCUMENTS
1 Transparency Regulation 543/2013
2 Transparency Platform Manual of Procedures
3 ECP Integration Guide for transparency platform
4 Web Services Integration Guide for transparency platform
1. Overview
Web Services are one of the integration channels, which can be used for communication with ENTSO-E Transparency Platform.
Web service design and message format are based on the REE document Electronic data interchanges on the Internal Electricity Market[1] [SPEC], which is based on Part 100 of the IEC 61968 standard [STAND]. Knowledge of these documents is necessary for the successful application of this guide.
1.1 Usage of Web Services
Data Providers may use Web Services for the following purposes:
- Sending data to ENTSO-E Transparency Platform
- Receiving Acknowledgement Documents from the ENTSO-E Transparency Platform.
- Receiving Notification of missing data in form of a problem statement document
- Listing and requesting submitted messages
- Retrieving data (also for Public Users)
Please note that Acknowledgements are normally held for 30 days in Energy Gateways WS EP. After this period 'GET' Operation for Acknowledgements results in 'WS message processing failed.' Acknowledgements can be manually downloaded from the Public Website from Data Flow Process Monitoring under the Administration section.
2. Web Service Channel Configuration
2.1 Steps to create a self-signed certificate using Keytool
Generating self-signed Certificate ( Caution: Keep note of password):
keytool -genkeypair -alias “Your key name” -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore “Your certificate name”_Certificate.p12 -validity “No of days of validity”
Importing to the Key store (Caution: Keep note of password:
keytool -importkeystore -srckeystore “Your certificate name”_Certificate.p12 -srcstoretype pkcs12 -destkeystore “Your certificate name”_Certificate.jks -deststoretype JKS
Listing the keying the Key store:
keytool -list -v -keystore “Your keystore name”.jks
Open SSL for generating generation public and private keys pair in PEM Format:
openssl pkcs12 -in “Your certificate name”_Certificate.p12 -out “Your certificate name”_Certificate.pem
2.2 Configuration of a machine user
To enable Web Service support the Web Service information in your Machine User settings in ENTSO-E Transparency Platform must be appropriately configured as described below.
Step 1: Login as Organisation Adminstrator to https://transparency.entsoe.eu/
Step 2: Go to Administration Menu
Step 3: Select Registers -> Machine user
Figure 1
Step 4: Create Machine user and Save Machine User.
Step 5: Start adding Integration Channel
Check the Web service checkbox, insert your Public part of the PEM certificate and specify the required strategy for messages from the Platform. Pull strategy has been discontinued and is no longer possible to use. Push strategy means that the Platform will push a message to your WS. For the "Push" strategy please provide also your WS endpoint address. Please see the informative wireframe (Figure 1).
WS URIs for all environments are provided in the table below. The version of WSDL defined by [SPEC], on which the Data Service WSDL is built on, is available at https://webstore.iec.ch/publication/22465.
| Environment | WSDL URI | Endpoint URI |
| PROD |
https://ws-submission.tp.entsoe.eu ( 20.71.78.90) |
https://ws-submission.tp.entsoe.eu/data-receiver-ws/endpoints/DataService |
| IOP |
https://ws-submission.tp-iop.entsoe.eu ( 20.31.194.118) |
https://ws-submission.tp-iop.entsoe.eu/data-receiver-ws/endpoints/DataService |
| UAT |
https://ws-submission.tp-uat.entsoe.eu (51.137.9.102) |
https://ws-submission.tp-uat.entsoe.eu/data-receiver-ws/endpoints/DataService |
Table 1: WS URIs
- WS connection requires client HTTPS authentication. The client certificate is checked against the certificate provided in the Machine user settings.
- Currently, Acknowledgments are pushed from 52.174.254.237 to the endpoint configured against the machine user, in cases, when ProblemStatementDocument is sent notifying delays to processing.
3. Data Service
Please note that this description addresses only specific aspects of the Platform’s Web Service implementation. General concepts with examples can be found in [SPEC].
3.1 Data Submission
Data are submitted in XML Payload element. See [SPEC], Chapter 5.3 Put Messages. Element with the message shall be the only child of the Payload element. No binary data are currently expected.
The format of submitted messages (data) is defined by ENTSO-E implementation guides and XSDs which are available from the ENTSO-E website.
As a response to submitted data, the acknowledgement document is generated and returned. In the case that submitted data are not processed before timeout configured in the Platform, problem statement document is generated instead of acknowledgement. An Acknowledgement document is then generated after data processing and depending on the selected strategy, is either pushed to data provider’s web service or stored in the data provider’s message queue from which it may be pulled by GET request.
3.2 List Messages
The data provider may list unread messages from the Platform or messages submitted by this data provider. Only messages not older than 30 days may be listed. See [SPEC], Chapter 5.1 List Messages.
3.3 Get Messages
The data provider may get messages from his message queue or messages submitted by him. See [SPEC], Chapter 5.2 Get Message.
3.4 Data Retrieval
Machine user may retrieve data from the Platform using web services. Refer to our Subscription user guide for the steps to configure data subscription.
3.5 Digital Signatures
Web service invocations that convey “business” XML messages should be signed. Please see the following table which defines the services that should be signed. Services not mentioned in the table below are not signed.
| Service | Signed |
| Data Service PUT | Request and Response |
| Data Service GET | Response |
| Data Service QueryData | Response |
| Data Service LIST | Not signed |
Table 3: Signatures
The digital signature is described in [SPEC], Chapter 10 Security with an example in Annex A. 6 Digital Signature.
For data submissions (PUT) certificate in Signature element is checked against the certificate provided in Machine User settings. Data responses from the Platform are signed using Platform’s certificate.
4. Guideline for Data Provider’s submissions
4.1 Main Goals of the Guideline
The main goal of this guideline is to raise awareness about unnecessary submissions of data performed by Data Providers. Descriptions are based on actual experience from the legacy Transparency platform and Release 1 of the new Transparency platform. Expectations for Release 2 (extensions to support transparency regulation) are also taken into account.
Data Providers can help to fulfil their performance expectations of the platform by following these guidelines.
The document also provides Data Providers with information that should be used during the implementation and maintenance of their systems used for data submissions into the ENTSO-E Transparency Platform.
4.2 Handling of Versions
Current issues related to versions of XML files are described in the following sub-chapters.
4.2.1 Repeating Submission for All Previous Hours
There are cases when data for all previous hours of the day were resent every hour although nothing has changed in those previous hours. This led to a situation when the system had to receive, process, store and publish not only data for one hour (e.g. 13:00-14:00), but also for hours 00:00-01:00, 01:00-02:00, 02:00-03:00 … 12:00-13:00, etc.
Recommendation:
To send XML files with higher versions only in cases where values were changed.
Submission of XML Files with Lower/Same Version
It appears quite often that the Transparency platform receives XML files with a lower or the same version than the one which is already stored in the platform.
Recommendation:
Increase the version of the XML file with each change within the XML file. Do not submit historical versions of XML files. These are not published anyway.
4.2.2 Too Frequent Submissions
There are situations when despite data are supposed to be received for each hour (for example the deadline for the time interval 13:00-14:00 is at 15:00) the platform had to receive, process, store and publish many XML files (tens of files where one file is sufficient) submitted during that time interval (13:00-14:00).
Recommendation:
Meet the deadline requirement, but to submit only the latest data. It is not necessary and even not required by Regulation to submit the complete evolution of data.
Moreover, the evolution of such data is not shown on the Transparency Platform – only the latest version is displayed and users would need to log in and drill down to see historical values.
4.3 Data Granularity
Issues with the amount of data in XML files were identified and described in the following paragraphs.
4.3.1 Incorrect Submission Resolution
Data are submitted in different resolutions than the system expects. This will lead to the rejection of data.
Recommendation:
To submit data in the resolution that is configured in the Transparency platform. The expected resolution is defined in the Configuration Matrix via the rule Submission Resolution.
Data Providers can update the rule and it can be set differently for different time periods.
4.3.2 Too Detailed Data in Curves
Release 2 of the transparency platform offers the possibility to display the evolution of values during some time period. Data can be delivered as a curve. For example results of a Yearly allocation can be submitted in one-hour resolution. This creates 8 760 values that need to be received, processed, stored and published. But the Implementation Guides enable submission in thirty minutes (about 17 500 values) or even fifteen-minute (about 35 000 values) resolution.
This requires a lot of processing time and a lot of storage is needed. Moreover, transparency platform release 2 has a limit of processing a maximum of 10 000 positions within XML.
Recommendations:
Use the lowest possible resolution. For example, in case the Implementation Guide allows delivery in PT15M, PT30M, PT60M and P1D, please use P1D. Market Time Unit resolution should only be used when transparency regulation requires it.
Use the CurveType “A03” as much as possible. When this curve type is used, only positions with changes are delivered. This leads to a smaller size of XML files and faster processing time. For example, submit CurveType “A03” and then only the value for the first position in case that value does not change during the time interval.
4.4 Master Data Management
Potential issues related to Master data are described in the following paragraphs.
4.4.1 Too Frequent / Regular Updates
Modification or Synchronization messages do not contain any changes.
Recommendation:
Modification or Synchronization of master data should be done in the very same way as suggested for Data Items. New documents should be submitted only when there is some real change in the data itself.
Recurring submissions without any actual changes would generate an unnecessary burden for the system.
5. Web Service Client Troubleshooting
In general, Web Service communication is established through the Transparency platform access point which operates with TLS 1.2 and 1.3 (TLS 1.0. and 1.1 is deprecated and not supported any more). Thus, a used client intended for messaging has to be compliant with the supported TLS standards.
In case of a communication failure, please check the following in your client:
- A client in use does not support TLS 1.2 or 1.3,
- A client in use does not use supported cypher suites,
- TP supported SSL Cipher Suites "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384",
- A client certificate in use is not compliant with the supported SSL Cipher Suites,
- A client in use does not have imported the ENTSO-E certificate in the trust store,
- The public certificate is available and downloadable for example on https://transparency.entsoe.eu/ website, certificate export is possible in certificate details.
- The public certificate is available and downloadable for example on https://transparency.entsoe.eu/ website, certificate export is possible in certificate details.
6. References
| SPEC |
AF_284 Electronic data interchanges on the Internal Electricity Market |
| STAND |
IEC 61968-100 Application integration at electric utilities – System interfaces for distribution management –Part 100: Implementation Profiles |
| QUERY_SPEC | Parameters for query data. |
[1] Document Electronic data interchanges on the Internal Electricity Market is to be superseded by the Technical Specification for the utilization of web services for electronic data interchanges on the European Energy Market for Electricity when published. These two documents contain the same information.
Copyright notice
Copyright © ENTSO-E. All Rights Reserved.
This document and its whole translations may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, except for literal and whole translation into languages other than English and under all circumstances, the copyright notice or references to ENTSO-E may not be removed.
This document and the information contained herein are provided on an "as is" basis.
ENTSO-E DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Comments
0 comments
Please sign in to leave a comment.