http://nodal.ercot.com 1Lead from the front
Texas Nodal
Technical Communications Workshop
September 03, 2008
http://nodal.ercot.com 2Lead from the front
Texas Nodal
Antitrust Admonition
ANTITRUST ADMONITION
ERCOT strictly prohibits Market Participants and their employees who are participating in ERCOT activities from using their participation in ERCOT activities as a forum for engaging in practices or communications that violate the antitrust laws. The ERCOT Board has approved guidelines for members of ERCOT Committees, Subcommittees and Working Groups to be reviewed and followed by each Market Participant attending ERCOT meetings. If you have not received a copy of these Guidelines, copies are available at the Client Relations desk. Please remember your ongoing obligation to comply with all applicable laws, including the antitrust laws.
http://nodal.ercot.com 3Lead from the front
Texas Nodal
Workshop Agenda
• Antitrust Admonition 0900 – 0910• API Sub Group Topics 0910 – 0930
– Introduction – Overview of Agenda– API Sub Group Topics
• WSDL / XSD Overview 0930 - 1015– WSDL / XSD Overview– Basic Message Structures– EIS Specification– ERCOT WSS Security
• <break> 1015 – 1030 • Setting Up a client 1030 – 1145
– Java Example– .NET Example
http://nodal.ercot.com 4Lead from the front
Texas Nodal
Workshop Agenda
• Break for Lunch (on site) 1145 – 1230 • Setting up a Listener 1230 – 1300 • Maintenance 1300 – 1320
– Management of Certificates• Participant Requested Topics 1320 - 1400
– Trades Workflow (high level)– Alerts and Notifications– Data Review– ERCOT WAN (high level)
• Follow-up items From Original Workshop Held on 9/3/08
http://nodal.ercot.com 5Lead from the front
Texas Nodal
API Sub Group Topics
• To better serve the needs of the market, we are implementing several changes:– Focus the API Subgroup on technical, developer-to-developer issues– Direct discussions about data, report and extracts, and releases to the EDS team– Track communications at the program level
• Rationale for these changes:– The EDS team is the source of truth for Nodal schedules and is equipped to manage
market questions and responses– The old process was blurring the line between functional and technical
• Functional is the “what” and includes data elements, rules, structures, and formats• Technical is the “how” and includes delivery mechanisms, authentication/authorization, and performance
• What next:– The Friday EDS calls will include the EIP update – We will maintain the Google Group until a better solution is available– We are working with ERCOT to develop a long term process and site to better
communicate this information to the market
http://nodal.ercot.com 6Lead from the front
Texas Nodal
WSDL / XSD Overview
http://nodal.ercot.com 7Lead from the front
Texas Nodal
WSDL / XSD Overview – Supporting Documentation
• Enterprise Interface Specification Document– http://nodal.ercot.com/readiness/sandbox/websvc/index.html
• WSDL & XSD Package– http://nodal.ercot.com/readiness/sandbox/documents/index.html– Nodal.wsdl
• Describes external web services. Specifies location of service and the operations exposed by the service.
– XSDs• Defines the structure of the messages
http://nodal.ercot.com 8Lead from the front
Texas Nodal
WSDL / XSD Overview – Implementation Approach
• Define Web services needed for Market Participants to request market information and initiate transactions– Leverage IEC 61968 for definition of message– Use the IEC Common Information Model (CIM) where appropriate– Loosely coupled flexible design
• Provide the means for Market Participant Systems to receive notification messages from ERCOT systems– Leverage OASIS WS-Notifications specification– Participants will have notifications pushed to their listener
http://nodal.ercot.com 9Lead from the front
Texas Nodal
WSDL / XSD Overview – Application of IEC 61968 to Web Services
• Message structures based upon IEC 61968-1 defined for the input and output of operations (i.e. request and response)
• Header used for information needed for all messages, includes key control information such as verb, noun and source
• Request structure has parameters (some required, some optional) that are appropriate for the specific operation
• Reply structure indicates success, failure and errors as appropriate
• Payloads can be strongly typed or loosely coupled from message structures, where payloads can be compressed and encoded if needed
• Messages form the body of the underlying SOAP message
http://nodal.ercot.com 10Lead from the front
Texas Nodal
WSDL / XSD Overview – Web Service Message Payloads
• Message payloads carry the data that is needed for a specific request or reply
• The noun in the message header identifies the type of the payload
• Payloads can be supplied in one of the following forms:– Any type of XML element of any
namespace (with structure typically defined by an XSD)
– An XML document that is encoded as a string, compressed and base64 encoded
– Other base64 encoded content
http://nodal.ercot.com 11Lead from the front
Texas Nodal
Nodal.wsdl (WSDL Design View in XMLSpy)
WSDL / XSD Overview – WSDL Overview
http://nodal.ercot.com 12Lead from the front
Texas Nodal
WSDL / XSD Overview – WSDL Overview – Verbs/Nouns
Nodal.wsdl – Web Services
http://nodal.ercot.com 13Lead from the front
Texas Nodal
WSDL / XSD Overview – ERCOT XML Schema files
Message.xsd Underlying Messaging XML Schema
Notification.xsd Underlying Notification XML Schema
ErcotCommonTypes.xsd All common simple and complex types used throughout
ErcotTransactions.xsd
ErcotTransactionTypes.xsd
MarketTransaction Web Services – EIS Section 3.3.1 through 3.3.15 and its supporting types
ErcotInformation.xsd
ErcotInformationTypes.xsd
MarketInfo Web Services – EIS Section 4.3.1 through 4.3.30 and its supporting types
ErcotInformation2.xsd
ErcotInformation2Types.xsd
MarketInfo Web Services – EIS Section 4.3.31 through 4.3.45 and its supporting types
ErcotOutages.xsd
ErcotOutageTypes.xsd
Outage Scheduler Schema and its supporting types
ErcotAwards.xsd
ErcotAwardTypes.xsd
MMS Awards and Obligations structure and its supporting types – both Sync and Async
ErcotForecast.xsd Wind Forecast structure
WSS200401wssecurity-secext-10.xsd
WSS200401wssecurity-utility-10.xsd
xmldsig-core-schema.xsd
WSS Security Schema supporting files
ErcotNotifications.xsd
ErcotNotificationTypes.xsd
Asynchronous Notification Structure
ErcotDisputes.xsd
ErcotDisputeTypes.xsd
Registration Disputes XML schema and its supporting types
ErcotMiscTypes.xsd
ErcotUtilities.xsd
Reports Schema and its supporting types.
ErcotModelTypes.xsd NMMS Intended – Discontinued for now – will be deleted
MMSAwardSetSchema.xsd Interim Awards retrieval technique – Discontinued – will be deleted
http://nodal.ercot.com 14Lead from the front
Texas Nodal
WSDL / XSD Overview – XSD Overview
Nodal.wsdl
Message.xsd
ErcotCommonTypes.xsd
ErcotTransactionTypes.xsd
ErcotInformationTypes.xsd
ErcotAwardTypes.xsd
ErcotDisputesTypes.xsd
ErcotOutageTypes.xsd
ErcotMiscTypes.xsd
ErcotNotificationTypes.xsd
Defined in ERCOT CIM UML Model
Loose coupling
ErcotTransactions.xsd
ErcotInformation.xsd
ErcotNotifications.xsd
ErcotOutages.xsd
ErcotUtilities.xsd
Element Definitions for Message Payloads Type Definitions used by
Element Definitions
ErcotInformation2Types.xsdErcotInformation2.xsd
ErcotAwards.xsd
ErcotDisputes.xsd
http://nodal.ercot.com 15Lead from the front
Texas Nodal
– All messages exchanged between MP and ERCOT webservices use pre-defined structure for requests and responses.
– Messages are constructed with several sections• Header• Request (Valid for RequestMessage)• Reply (Valid for ResponseMessage)• Payload
Basic Message Structure – message.xsd
http://nodal.ercot.com 16Lead from the front
Texas Nodal
– Header is required in all messages exchanged between MP and ERCOT Web Services.
Basic Message Structure – Message Header Structure
http://nodal.ercot.com 17Lead from the front
Texas Nodal
– ‘Request’ is required to be populated in the Request Xml, depending on the type of transaction submitted
(Example: Queries [Verb: get Noun: BidSet]).
Basic Message Structure – Message Request Structure
http://nodal.ercot.com 18Lead from the front
Texas Nodal
– Used in Response to indicate success, failure and error details.
Basic Message Structure – Message Reply Structure
http://nodal.ercot.com 19Lead from the front
Texas Nodal
– Payload is required depending on the type of transaction that’s being submitted.
– Payload XML needs to conform to the ERCOT XSDs
Basic Message Structure – Message Payload Structure
http://nodal.ercot.com 20Lead from the front
Texas Nodal
Basic Message Structure – Example BidSet Sequence Diagram
http://nodal.ercot.com 21Lead from the front
Texas Nodal
EIS Specification - Role of EIS Specification
• You’ll need, the WS Contract + EIS to interact with ERCOT Web Services:
Element Req?
Datatype
Description Values
startTime N datetime
Start time for schedule
Valid 5 minute interval boundary for trade date
endTime N datetime
End time for schedule
Valid 5 minute interval boundary for trade date
externalId N string External ID QSE supplied
resource K string Resource Valid resource name
combinedCycle N string Combined cycle Valid combined cycle ID
deleteTPOs N Boolean
true if 3PO for resource are to be deleted
1 or 0 (default=0)
EnergySchedule/startTime N datetime
Not Used Not Used
EnergySchedule/endTime N datetime
Not Used Not Used
EnergySchedule/TmPoint/time
Y datetime
Absolute time for start of interval
Valid time between startTime & endTime for schedule
EnergySchedule/TmPoint/ending
N datetime
Absolute time for end of interval
Valid time between startTime & endTime for schedule
EnergySchedule/TmPoint/value1
Y float Megawatts >= 0
+
http://nodal.ercot.com 22Lead from the front
Texas Nodal
EIS Specification - Role of EIS Specification – Cont.
Yields:
<BidSet xmlns="http://www.ercot.com/schema/2007-06/nodal/ews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ercot.com/schema/2007-06/nodal/ews ErcotTransactions.xsd"><tradingDate>2008-01-01</tradingDate><OutputSchedule>
<startTime>2008-01-01T00:00:00-05:00</startTime><endTime>2008-01-02T00:00:00-05:00</endTime><marketType>DAM</marketType><resource>SANDHSYD_SH2</resource><deleteTPOs>true</deleteTPOs><EnergySchedule>
<startTime>2008-01-01T00:00:00-05:00</startTime><endTime>2008-01-02T00:00:00-05:00</endTime><TmPoint>
<time>2008-01-01T00:00:00-05:00</time><ending>2008-01-02T00:00:00-05:00</ending><value1>20</value1><value2>20</value2><value3>20</value3>
</TmPoint></EnergySchedule>
</OutputSchedule></BidSet>
http://nodal.ercot.com 23Lead from the front
Texas Nodal
Input Request Message
<?xml version = "1.0" encoding = "UTF-8"?><inputMessage>
<ns0:RequestMessage xmlns:ns0 = "http://www.ercot.com/schema/2007-06/nodal/ews/message"><ns0:Header>
<ns0:Verb>create</ns0:Verb><ns0:Noun>BidSet</ns0:Noun><ns0:ReplayDetection>
<ns0:Nonce>39b2fa420b9766e06a302ccef0531e7e</ns0:Nonce><ns0:Created>2008-08-27T17:20:51.65-05:00</ns0:Created>
</ns0:ReplayDetection><ns0:Revision>1.0</ns0:Revision><ns0:Source>TEST_LOOPBACK_MBALUSA</ns0:Source><ns0:UserID>NODALTEST</ns0:UserID><ns0:MessageID>MBALUSA_TEST</ns0:MessageID>
</ns0:Header><ns0:Payload>
<BidSet xmlns = "http://www.ercot.com/schema/2007-06/nodal/ews" xmlns:xsi = ErcotTransactions.xsd"><tradingDate>2007-11-30</tradingDate><status>Open</status><mode>Normal</mode><COP>
<startTime>2007-11-30T00:00:00-06:00</startTime><endTime>2007-11-30T00:00:00-06:00</endTime><resource>PBSES_UNIT5</resource><ResourceStatus>
<startTime>2007-11-30T00:00:00-06:00</startTime><endTime>2007-11-30T23:00:00-06:00</endTime><operatingMode>ON</operatingMode>
</ResourceStatus><Limits>
<startTime>2007-11-30T00:00:00-06:00</startTime><endTime>2007-11-30T23:00:00-06:00</endTime><hsl>70.25</hsl><lsl>7</lsl><hel>80</hel><lel>10</lel>
</Limits><ASCapacity>
<startTime>2007-11-30T00:00:00-06:00</startTime><endTime>2007-11-30T23:00:00-06:00</endTime><regUp>0</regUp><regDown>0</regDown><rrs>0</rrs><nonSpin>0</nonSpin>
</ASCapacity></COP>
</BidSet></ns0:Payload>
</ns0:RequestMessage></inputMessage>
http://nodal.ercot.com 24Lead from the front
Texas Nodal
Output Response Message
<?xml version = "1.0" encoding = "UTF-8"?><outputMessage>
<ns0:ResponseMessage xmlns:SOAP-ENV = "http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns0 = "http://www.ercot.com/schema/2007-06/nodal/ews/message" xmlns:wsu = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<ns0:Header><ns0:Verb>reply</ns0:Verb><ns0:Noun>BidSet</ns0:Noun><ns0:ReplayDetection>
<ns0:Nonce>39b2fa420b9766e06a302ccef0531e7e</ns0:Nonce><ns0:Created>2008-08-27T17:20:51.65-05:00</ns0:Created>
</ns0:ReplayDetection><ns0:Revision>1.0</ns0:Revision><ns0:Source>ERCOT</ns0:Source><ns0:UserID>NODALTEST</ns0:UserID><ns0:MessageID>MBALUSA_TEST</ns0:MessageID>
</ns0:Header><ns0:Reply>
<ns0:ReplyCode>OK</ns0:ReplyCode><ns0:Timestamp>2008-08-27T17:21:27.78-05:00</ns0:Timestamp>
</ns0:Reply><ns0:Payload>
<ns1:BidSet xmlns:ns1 = "http://www.ercot.com/schema/2007-06/nodal/ews"><ns1:tradingDate>2007-11-30</ns1:tradingDate><ns1:status>Open</ns1:status><ns1:mode>Normal</ns1:mode><ns1:COP>
<ns1:mRID>TEST_LOOPBACK_MBALUSA.20071130.COP.PBSES_UNIT5</ns1:mRID><ns1:status>SUBMITTED</ns1:status>
</ns1:COP></ns1:BidSet>
</ns0:Payload></ns0:ResponseMessage>
</outputMessage>
http://nodal.ercot.com 25Lead from the front
Texas Nodal
EIS Specification - EIS Specification Content
2. Services Organization • 2.1. Common Message Structure• 2.2. Common Security Implementation• 2.3. Modeling and Conventions• 2.4. Delivery Approach• 2.5. Technical Interoperability• 2.6. Service Level Agreements • …
3. Market Transaction Service • 3.3.1. Three-Part Supply Offer• 3.3.2. Self-Arranged Ancillary Service Quantities• 3.3.3. Incremental and Decremental Energy Offer • 3.3.4. Ancillary Service Offer• 3.3.5. Ancillary Service Trade• 3.3.6. Capacity Trade• 3.3.7. Congestion Revenue Rights (CRR) Offer• …
4. Market Information • 4.3.1. AwardSet• 4.3.2. AwardedAS• 4.3.3. AwardedCRR• 4.3.4. AwardedEnergyBid• 4.3.8. Forecasted Load …• 4.3.9. Real-Time System Load• 4.3.10. Market Totals • 4.3.11. Market LMPs and SPPs• 4.3.12. Market MCPCs• 4.3.13. Binding Constraints• 4.3.14. SCED Violated Constraints• 4.3.15. Ancillary Service Obligation• ….
5. Notifications • 5.3.1. Notices and Alerts ***• 5.3.2. Offer and Bid Set Acceptance• 5.3.3. Offer and Bid Set Errors• 5.3.4. Confirmed and Unconfirmed Trades• 5.3.5. Energy Offer Awards ...• ….
6. Acknowledgement of Alerts• 7.2.1. Close Alert
7. Outage Scheduling Interfaces • 7.2.1. Outage Creation• 7.2.2. Outage Query• 7.2.3. Outage Update• 7.2.4. Outage Cancellation
8. Utility Interfaces • 8.2.1. Get mRID• 8.2.2. System Status• 8.2.3. Request Test Notification• 8.2.4. Change Active Notification URL
9. Reports • get Reports
10. Resource Par Transactions• 10.3.1. Generator Resource Parameters• 10.3.2. Controllable Load Resource• 10.3.3. Non Controllable Load Resource• 10.3.4. Verbal Dispatch Instruction• 10.3.5. Resource Parameters
11. Registration Interfaces • Dispute Creation
http://nodal.ercot.com 26Lead from the front
Texas Nodal
EIS Specification - EIS Specification Review Upcoming Changes
• EIS 1.15 – MMS MarketTransaction Interface Updates
• Market Types to ASObligations (DAM or SASM) • SubmitTime to the BidSet header holding Bid request receipt timestamp by ERCOT • Added Market type to the startup/shutdown instructions with possible values of HRUC, DRUC, and DAM • Added MarketType to the get AwardSet = DAM/ADJ/RTM/SASM/RUC/SCED • Update 3PO with SuMeFipFop and EocFipFop introduced in MMS4 • Added MultiHourBlock to CRR, PTP Oblig, Energy bid and Energy only Offer input tables • Added RRS_ NCLR as a new ASType for SelfArrangedAS • Modified CompetitiveConstraints structure to hold new elements CompetitivenessStatus, deleted OperatorOverwrite – consistent
with CDR Interface • Corrected the possible values for MarketType for various Award Sets. • Updated ASOffer with nonControllableLoadFlag flag • Corrected PTP Obl. MaximumPrice/price • 3.3.2 Added RRS_NCLR to the list of ASType for SelfArrangedAS • 3.3.11 - Corrected figure 47 for EnergyOfferCurve/multiHourBlock (instead of under PriceCurve) and updated the example
– MMS MarketInfo Interface Updates • BindingConstraints - Schema • LoadDistributionFactors to have name and factor only – consistent with CDR interfaces • Merged in MIS Int Specification version .37 - Market Info Nouns into the section 4 of this spec – 4.3.31 thru 4.3.45 • 4.3.26 Unit Availability: Tagged BlackStart and Available megawatts as a place holder for future use. • Added equipmentType to Dynamic Ratings and Dynamic Ratings Deviations
– OS Interface Update • DisclaimerAck & Disclaimer as required fields for OS • Enumeration to equipment Outage, Outage states. • 3 more cancellation reasons (EXP, ERR, and ROM) • Transmission Opportunity Outage, designatedResource - station and HSL as required per OS.xsd • Added notes about OS query StartTime and endTime are optional but they should not be present when an mRID is sent. • ResourceType choices: UL or LR • Updated Outage opportunity outages with opportunity duration – consistent with OS application
– Reports • Reverted back to the original external reporting interface in section 9 – adjusted with supporting MID/MIR interface
– General • Updates/added examples for all interfaces • Updated the xsd files in the appendix C
http://nodal.ercot.com 27Lead from the front
Texas Nodal
EIS Specification - EIS Specification Review Upcoming Changes (continued…)
• EIS 1.16 (Sandbox Release only)– 10.0 - Added Resource Parameter Transaction Service Section – 11.0 – Added Disputes Interfaces section
• EIS 1.17 on MMS 4 Patch 3– OS Expanded Query– AS Insufficiency Report– Alerts R1 (framework only)– 1.16 Bug Fixes
• EIS 1.18 on MMS5– Policy Mgr + New WSRB– MarketInfo Services– getReports– LTLF– Alerts R2– 1.17 Bug Fixes
• EIS 1.18 on MMS5/OS Final– Chunking– Performance tuning– Bug Fixes– MMS5 Final– Alerts R3– 1.18 Bug Fixes
http://nodal.ercot.com 28Lead from the front
Texas Nodal
ERCOT WSS Security
http://nodal.ercot.com 29Lead from the front
Texas Nodal
ERCOT WSS Security - Security Requirements
• Industry good practices– Authentication – Confidentiality-protection– Integrity-protection– Prevent Replay Attacks– Access control– Auditing and logging– Consistent availability and performance
• Business requirements with security implications – Design a solution that is simple and readily implementable– Use industry standards– Enable leveraging of existing security infrastructure– Provide origin authentication at the transaction level
http://nodal.ercot.com 30Lead from the front
Texas Nodal
ERCOT WSS Security - Security Standards
• Transport level security via
– SSL (Secure Socket Layer) / TLS (Transport Layer Security)
• Message level security via signed SOAP messages according to the Web Services Security (WSS) standards
Authentication, confidentiality and integrityprotection (transport Level)
Origin authentication and integrityprotection (message level)
SOAP Message
Signed Message
Mutually authenticatedSSL/TLS session
http://nodal.ercot.com 31Lead from the front
Texas Nodal
ERCOT WSS Security - Trust Model
• Use Verisign Trust Network (VTN) Class 3 certificates• Provide two levels of authentication
– Transport– Message
• Implementations must ensure that :– Only ERCOT brand of certificate is used– Certificate has not been revoked
Market Participant
ERCOTMarket
Participant
End Users and/or Processes
End Users and/or Processes
End Users and/or Processes
VTN Public Key Infrastructure (PKI)
Signed Message
SignedMessage
MP
-Sp
ecific
Au
the
ntic
atio
n
ER
CO
T-S
pe
cific
Au
the
ntic
atio
n
MP
-Sp
ecific
Au
the
ntic
atio
n
http://nodal.ercot.com 32Lead from the front
Texas Nodal
ERCOT WSS Security - Authentication
• Transport-level– SSL/TLS is required while data travels on the Internet– Implement mutual authentication via SSL/TLS
• SSL/TLS version MUST be at least 3.0 • The SSL/TLS cipher suite MUST include AES 128 bit for encryption• The SSL/TLS cipher suite MUST include SHA-1 for integrity protection
• Message-level– Use OASIS Web Services Security (WSS) standards
• SOAP Message Security• X.509 Token Profile• http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.
0.pdf
– Signing entities are expected to be applications/systems with appropriate certificates
http://nodal.ercot.com 33Lead from the front
Texas Nodal
ERCOT WSS Security - Preventing Replay Attacks
• Each message must include:– A timestamp as specified by WSS <wsu:timestamp>– A random number as specified by WSS <wsu:nonce>
• Clocks need not be synchronized• Typical implementation
– Reject expired messages– Cache the nonce for the expected amount of clock skew and reject
messages whose nonce is in the cache (currently set to 5 Minutes)
http://nodal.ercot.com 34Lead from the front
Texas Nodal
ERCOT WSS Security - Implementation-Specific Security Functions
• Access Control– Use authenticated identity of message producer, as determined by
the signing certificate of the SOAP message• Auditing
– At the SOAP message level– At the Front Gateway (Policy Manager)
http://nodal.ercot.com 35Lead from the front
Texas Nodal
ERCOT WSS Security - What does this mean to Market Participants?
• Market Participants MUST– Deploy SSL/TLS
• Obtain client side certificate – Certificate is issued by Verisign under the ERCOT brand
• Implement mutual authentication• Ensure minimum SSL/TLS security settings
– Secure SOAP messages• Obtain application/system signing certificate
– Certificate is issued by Verisign under the ERCOT brand• Sign all SOAP messages• Use Web Services Security Standards and its X.509 Certificate Token Profile• Message headers MUST include a timestamp and a nonce• Validate all SOAP messages
– Signature– Certificates– Revocation status of certificates– Timestamp and nonce (to prevent replay attacks)
http://nodal.ercot.com 36Lead from the front
Texas Nodal
ERCOT WSS Security - Security Summary
• Web Services Client will need at most two certificates– SSL/TLS– SOAP Message Signing
• Security rules are equally applicable to request, reply.• Some security functions are deployment specific and each MP
must determine the best method of implementation• Implementation of industry standards promotes interoperability
and flexibility
http://nodal.ercot.com 37Lead from the front
Texas Nodal
Setting Up a Client(Java)
http://nodal.ercot.com 38Lead from the front
Texas Nodal
• Software used to build example java client to invoke ERCOT external web services– Java 1.5
• http://java.sun.com/javase/downloads/index_jdk5.jsp
– Apache Axis 1.4
• http://ws.apache.org/axis/
– Apache WSS4J 1.5
• http://ws.apache.org/wss4j/
– Apache XML Security 1.4.1
• http://xml.apache.org/security/index.html
– Apache ANT 1.7.1
• http://ant.apache.org/
– KeyTool GUI 1.7
• http://www.gria.org/downloads
Disclaimer: There can be different ways to implement the client to interact with ERCOT web services using different variety of software. Associated sample java client shows one way to implement the client to interact with ERCOT’s external web services using above mentioned software. Example java client not intended for production purposes.
Setting Up a Client (Java) - Supporting Software
http://nodal.ercot.com 39Lead from the front
Texas Nodal
Setting Up a Client (Java) – Client Overview
WSDL2JAVA client.wsdd
Request XML
Nodal.wsdl
SOAP Request SOAP Response
Client Implementation
Stubs
AXISWSS4J
XML Security
client.properties
crypto.properties
keystores
KeyTool GUI
http://nodal.ercot.com 40Lead from the front
Texas Nodal
Setting Up a Client (Java) - WSDL2Java
• Apache Axis Wsdl2Java tool is used to generate stubs from Nodal.wsdl. The generated stubs will be used to invoke web services.
• Command to invoke wsdl2java is– java org.apache.axis.wsdl.WSDL2Java (WSDL_FILE_PATH)
• Above command generates the stubs in below packages. namespace defined in wsdl maps to java packages.
– com\ercot\www\schema\_2007_06\nodal\ews\message– com\ercot\www\wsdl\_2007_06\nodal\ewsConcrete– org\w3\www\_2000\_09\xmldsig– org\oasis_open\docs\www\wss\_2004\_01\oasis_200401_wss_wssecurity_utility_1_0_xsd– org\oasis_open\docs\www\wss\_2004\_01\oasis_200401_wss_wssecurity_secext_1_0_xsd
• Demo
http://nodal.ercot.com 41Lead from the front
Texas Nodal
• Sample java client uses below configuration files• client.properties
– Contains security information used for transport level security such as keystores, truststores, passwords and type information for the keystores, truststores. It also contains location of the wsdd file.
• client.wsdd
– Contains properties needed by Axis when invoking web services.
• crypto.properties– Contains properties for the certificate used for request
signatures.
Setting Up a Client (Java) - Sample Java Client
http://nodal.ercot.com 42Lead from the front
Texas Nodal
• Code snippet from sample java client
#Construct the EngineConfiguration object based on the wsdd (Web service deployment definition) file.
EngineConfiguration config = new FileProvider("WSDDFILE");
#It is this object that provides the configuration for the Web service locator.
#Construct the Web service implementation object.
NodalServiceLocator locator = new NodalServiceLocator(config);
#Set the endpoint address (default endpointURL will be the one specified in wsdl file used in wsdl2java).
#default endpoint url will be the one specified in wsdl file.
locator.setHttpEndPointEndpointAddress("END_POINT_URL");
#Get the Binding Stub from the webservice implementation object
Operations stub = locator.getHttpEndPoint();
#Construct the request object that will be used during the execution of the service.
RequestMessage request = new RequestMessage();
request = parseRequestXML("INPUT FILE");
#Invoke the service method on the binding stub
#Response object will be returned upon invoking the service method on the binding stub that was created from the locator.
ResponseMessage response;
response = stub.marketTransactions(request);
Setting Up a Client (Java) - Example
http://nodal.ercot.com 43Lead from the front
Texas Nodal
• Java Client Demo (without security configuration)
– Sample Request Message <COP>
– XSD Request XML
– Execute Java Client
– Error Message• ERCOT Requires Authentication and Authorization• Client’s (even in sandbox) must use SSL and a valid digital certificate
Setting Up a Client (Java) - Client Demo w/o Security
http://nodal.ercot.com 44Lead from the front
Texas Nodal
• Security– Keystore & Truststore
• Storage file containing keys, certificates, trusted roots.
– KeyTool GUI is used to generate keystores and truststores.– KeyTool GUI Demo
• transport keystore entries– Client Certificate
• truststore entries– Verisign Root & Intermediate Certificates
• message keystore entries– Client Certificate– ERCOT Public Key
• Sample java client uses below configuration files• client.properties
– Contains security information used for transport level security such as keystores, truststores, passwords and type information for the keystores, truststores. It also contains location of the wsdd file.
• client.wsdd– Contains properties needed by Axis when invoking web services.
• crypto.properties– Contains properties for the certificate used for request signatures.
Setting Up a Client (Java) – Implementing Security
http://nodal.ercot.com 45Lead from the front
Texas Nodal
• (Review) Sample java client uses below configuration files
• client.properties
– Contains security information used for transport level security such as keystores, truststores, passwords and type information for the keystores, truststores. It also contains location of the wsdd file.
• client.wsdd
– Contains properties needed by Axis when invoking web services.
• crypto.properties– Contains properties for the certificate used for request
signatures.
Setting Up a Client (Java) - Implementing Security
http://nodal.ercot.com 46Lead from the front
Texas Nodal
• client.properties#The location of the client keystore used for the transport level security
javax.net.ssl.keyStore=transport_keystore.jks
#The type of keystore being used.
javax.net.ssl.keyStoreType=jks
#The keystore's password
javax.net.ssl.keyStorePassword=changeit
#Location of the truststore file
javax.net.ssl.trustStore=client_truststore.jks
#truststore’s password
javax.net.ssl.trustStorePassword=changeit
#The type of truststore being used
javax.net.ssl.trustStoreType=jks
#This is the location of the Web service deployment definition file.
webservice.deployment.definition.file=client.wsdd
Setting Up a Client (Java) - Implementing Security (client.properties)
http://nodal.ercot.com 47Lead from the front
Texas Nodal
• client.wsdd<deployment xmlns="http://xml.apache.org/axis/wsdd/" xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"><transport name="http" pivot="java:org.apache.axis.transport.http.HTTPSender"/> <globalConfiguration > <requestFlow > <!-- For each request sent from client... --> <handler type= "java:org.apache.ws.axis.security.WSDoAllSender" >
<!-- Insert signature in requests --> <parameter name="action" value="Signature"/> <!-- Alias name of the certificate from the keystore --> <parameter name="user" value=“<CERT_ALIAS_NAME>" /> <!-- This is the callback class that implements a method to get certs password. --> <parameter name="passwordCallbackClass" value=“<PasswordCallBackClassName>"/> <!– keystore is defined in crypto.properties file. --> <parameter name="signaturePropFile" value="crypto.properties" /> <!– Specifies the format used by handler to insert signature into request. DirectReference causes the handler to convert the signing certificate to BinarySecurityToken element that is pit in security header --> <parameter name="signatureKeyIdentifier" value="DirectReference" />
</handler> </requestFlow> <responseFlow> <handler type= "java:org.apache.ws.axis.security.WSDoAllReceiver" > <parameter name="action" value="Signature"/> <parameter name="passwordCallbackClass" value="PWCallback"/> <parameter name="signaturePropFile" value="crypto.properties" />
<parameter name="enableSignatureConfirmation" value="false"/> </handler> </responseFlow>
</globalConfiguration ></deployment>
Setting Up a Client (Java) - Implementing Security (client.wsdd)
http://nodal.ercot.com 48Lead from the front
Texas Nodal
• crypto.properties
org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
#Type of the keystore
org.apache.ws.security.crypto.merlin.keystore.type=<KEYSTORE_TYPE>
#Client keystores password
org.apache.ws.security.crypto.merlin.keystore.password=<KEYSTORE_PASSWORD>
#Alias name of the client cert in the keystore
org.apache.ws.security.crypto.merlin.keystore.alias=<CERT_ALIAS_NAME>
#Password of the client cert in the keystore
org.apache.ws.security.crypto.merlin.alias.password=<CERT_ALIAS_PASSWORD>
#The location of the client keystore used for the signing the message
org.apache.ws.security.crypto.merlin.file=<KEYSTORE_LOCATION>
Setting Up a Client (Java) - Implementing Security (crypto.properties)
http://nodal.ercot.com 49Lead from the front
Texas Nodal
• Java Client Demo– Sample Request Message
– Execute Java Client (with security)
– Sample Response Message
Setting Up a Client (Java) - Implementing Security (client demo)
http://nodal.ercot.com 50Lead from the front
Texas Nodal
Setting Up a Client(.NET)
http://nodal.ercot.com 51Lead from the front
Texas Nodalhttp://nodal.ercot.com 51
• .Net Development Tools– Visual Studio 2005 Express
• http://www.microsoft.com/express/2005/download/default.aspx
– Web Services Enhancements (WSE) 2.0 for Microsoft .NET
• http://www.microsoft.com/downloads/details.aspx?familyid=fc5f06c5-821f-41d3-a4fe-6c7b56423841&displaylang=en
• Post Installation– Add C:\Program Files\Microsoft Visual Studio 2005\SDK\v2.0\bin to PATH
• Pre Coding– Obtain certificate from ERCOT
– Download wsdl from http://nodal.ercot.com/readiness/sandbox/websvc/index.html
– Extract to local drive
Setting Up a Client (.NET) - Supporting Software
http://nodal.ercot.com 52Lead from the front
Texas Nodal
Setting Up a Client (.NET) - Supporting Software
WSDL.exe
Request XML
Nodal.wsdl
SOAP Request SOAP Response
Client Implementation
Stubs
Visual Studio
policyCachel.config WSE
Keystore
http://nodal.ercot.com 53Lead from the front
Texas Nodalhttp://nodal.ercot.com 53
Setting Up a Client (.NET) - Process Steps
Once you have installed the tools and downloaded the wsdl and xsds you will develop your client code by following these steps:
• Run wsdl Nodal.wsdl WSS200401wssecurity-secext-10.xsd WSS200401wssecurity-utility-10.xsd
• Open Visual Studio 2005
• Create a new console project
• Copy NodalService.cs to project folder
• Add Reference to Microsoft.Web.Services2
• Add Reference to System.Web.Services
• Edit Program.cs to make web service call.
• In NodalService.cs change System.Web.Services.Protocols.SoapHttpClientProtocol to Microsoft.Web.Services2.WebServicesClientProtocol
• Configure policy using WSE 2.0 Configurator tool
http://nodal.ercot.com 54Lead from the front
Texas Nodalhttp://nodal.ercot.com 54
Setting Up a Client (.NET) - Demo
http://nodal.ercot.com 55Lead from the front
Texas Nodalhttp://nodal.ercot.com 55
Setting Up a Client (.NET) - wsdl.exe
wsdl.exe• Installed as part of Visual Studio 2005
• Generates .NET client code using Nodal.wsdl
• Command to invoke wsdl.exe is
– wsdl.exe <options> <url or path> <url or path> <url or path> …
– Sample Command: wsdl Nodal.wsdl WSS200402wssecurity-secext-10.xsd WSS200401wssecurity-utility-10.xsd
– Creates: NodalService.cs
• Gotcha’s
– wsdl.exe does not resolve import so you have to specify the imported xsd using the command line parameters
http://nodal.ercot.com 56Lead from the front
Texas Nodalhttp://nodal.ercot.com 56
• Generated code does not contain everything you need
• You will need to write code to:– Create an instance of the NodalService– Set the certificate to use digital signature– Set the message information
• Noun
• Verb
• Payload
• Etc..
– Check the response message
Setting Up a Client (.NET) - Client Code
http://nodal.ercot.com 57Lead from the front
Texas Nodalhttp://nodal.ercot.com 57
Setting Up a Client (.NET) - Sample Code
NodalService nodalService = new NodalService();
RequestMessage requestMessage = new RequestMessage();
HeaderType header = new HeaderType();
header.Verb = HeaderTypeVerb.create;
header.Noun = "BidSet";
requestMessage.Header = header;
…
requestMessage.Payload = new PayloadType();
…
responseMsg = nodalService.MarketTransactions(requestMessage);
……
http://nodal.ercot.com 58Lead from the front
Texas Nodalhttp://nodal.ercot.com 58
• .Net Client Demo– Sample Request Message– Run NodalWSClient.exe
• Error Message
• What Happened?– No code for digital signature….
Setting Up a Client (.NET) - .Net Demo
http://nodal.ercot.com 59Lead from the front
Texas Nodalhttp://nodal.ercot.com 59
Setting Up a Client (.NET) - Managing Certificate
• Installing Certificate
– Save certificate file to disk
– Double click on file
– Follow prompts to add
• Windows Viewing Tools:
– Microsoft Management Console• Launch Microsoft Management Console by typing mmc from a command prompt• Select File => Add/Remove Snap In• Click on the “Add” button• Select “Certificates”• Navigate to Certificate• Double click to view certificate details• Check Valid From ….
http://nodal.ercot.com 60Lead from the front
Texas Nodalhttp://nodal.ercot.com 60
Setting Up a Client (.NET) - WSS Configuration
• Obtain Certificate from ERCOT
• Run Configuration Tool
• Enable this project for Web Services Enhancements
• Enable Policy
• Create Security Policy
• Add Policy file to project
• Add security code …
http://nodal.ercot.com 61Lead from the front
Texas Nodalhttp://nodal.ercot.com 61
Setting Up a Client (.NET) – Policy Cache Config
• policyCache config contains information on signing outbound message and accepting signed inbound message
• Defines which parts of the message to sign and certificate to use
• Need to modify policyCache.config file:
– Request message should only sign the body• Change
– wsp:Body() wsp:Header(wsa:To) wsp:Header(wsa:Action) wsp:Header(wsa:MessageID) wse:Timestamp()
– wsp:Body()
– Response message• Change
– wsp:Body() wsp:Header(wsa:Action) wsp:Header(wsa:FaultTo) wsp:Header(wsa:From) wsp:Header(wsa:MessageID) wsp:Header(wsa:RelatesTo) wsp:Header(wsa:ReplyTo) wsp:Header(wsa:To) wse:Timestamp()
– wsp:Body() wsp:Header(wsa:FaultTo) wsp:Header(wsa:From) wsp:Header(wsa:RelatesTo) wsp:Header(wsa:ReplyTo) wsp:Header(wsa:To)
http://nodal.ercot.com 62Lead from the front
Texas Nodalhttp://nodal.ercot.com 62
Setting Up a Client (.NET) - Sample Code
NodalService nodalService = new NodalService();
X509Store store = new X509Store(StoreName.My, StoreLocation.CurrentUser);
store.Open(OpenFlags.ReadOnly | OpenFlags.OpenExistingOnly);
X509Certificate2Collection col = store.Certificates.Find(X509FindType.FindBySerialNumber, certSubjectString, true);
X509Certificate certificate = null;
foreach (X509Certificate cert in store.Certificates) {
if (cert.Subject.Contains(certSubjectString)) {
certificate = cert;
break;}
}
nodalService.ClientCertificates.Add(certificate);
ServicePointManager.ServerCertificateValidationCallback = TrustAllCertificateCallback;
RequestMessage requestMessage = new RequestMessage();
HeaderType header = new HeaderType();
header.Verb = HeaderTypeVerb.create;
header.Noun = "BidSet";
……
http://nodal.ercot.com 63Lead from the front
Texas Nodalhttp://nodal.ercot.com 63
• Let’s try it again…– Sample Request Message– Run NodalWSClient.exe
Setting Up a Client (.NET) - .Net Demo
http://nodal.ercot.com 64Lead from the front
Texas Nodal
Setting Up a Listener
http://nodal.ercot.com 65Lead from the front
Texas Nodal
Setting Up a Listener - Notification Component
• Notification messages are asynchronously sent to the Market Participant listener systems, using a variation of WS-Notifications implementation, where Market Participants expose a notification web service that is invoked by ERCOT to send a notification.
• ERCOT provides the Notification message schema and abstract WSDL that MPs can use in building notification listener web service.
• MPs can setup primary & secondary Notification listener services to receive notifications from ERCOT.
• Notification component delivery mechanism– Attempts to deliver notification message to the primary listener address first – Retries to deliver to the secondary listener incase of unsuccessful delivery to
primary listener. – Sends an E-mail incase of unsuccessful delivery to both primary & secondary
notification listeners
http://nodal.ercot.com 66Lead from the front
Texas Nodal
Setting Up a Listener - Overview
Proxy Server
Notification Service
Event Source
HTTPS – Notify
(SOAP signed)
HTTPS – Acknowledge
(Unsigned)
MP Service
Event
HTTPS – Notify
(SOAP signed)
HTTPS – Acknowledge
(Unsigned)
1. ERCOT Notification Service establishes an HTTPS connection to target MP system at pre-specified URL (listen port 443) by MP
2. Notification message is signed by ERCOT using the ERCOT server certificate.
3. MP web service is invoked by ERCOT Notification service, sending the Notify message.
4. MP system validates the signature, using the ERCOT public key.
5. Notify message is consumed by the MP system
6. MP system replies with a simple, unsigned acknowledge message using the same HTTPS connection
7. ERCOT Notification service receives acknowledge message and marks the transmission as complete
http://nodal.ercot.com 67Lead from the front
Texas Nodal
Setting Up a Listener - Notification Service Security
• Notification security scheme is similar to the scheme used for other external web services
• SSL for transport layer security (server authentication)• WS Security (only SOAP signing) for message level security
(request only)
• MP’s server certificate, for transport layer security (SSL), must be issued by one of the following CAs
• Verisign• Thawte• Entrust• Equifax• Digital Signature Trust Co (DST)
http://nodal.ercot.com 68Lead from the front
Texas Nodal 68
Setting Up a Listener - Notification Listener Setup - How-To
• MP’s must get ERCOT’s public certificate in order to read & validate signature in notification request
• MP’s must get the abstract WSDL & XSD from ERCOT
(http://nodal.ercot.com/readiness/sandbox/websvc/index.html)
• MP’s are responsible for constructing the Notification listener web service, using any technologies
• MP’s must notify ERCOT of the Notification service listener addresses (primary & secondary), concrete WSDL and email address
• MP’s must set up their infrastructure to accept an https connection on port 443 from ERCOT
http://nodal.ercot.com 69Lead from the front
Texas Nodal
Setting Up a Listener - Notification Service Details
• WSDL & Schemas– Notification.xsd & Notification.wsdl
http://nodal.ercot.com 70Lead from the front
Texas Nodal
Setting Up a Listener - Notification Service Details
• Message Structure– Notification Request Message (Notification.xsd) structure is loosely
coupled. • Message element contains the Response Message (Message.xsd) which
contains notification message
http://nodal.ercot.com 71Lead from the front
Texas Nodal
Setting Up a Listener - Notification Service Details
• Response Message (Message.xsd) Structure– Response message is same as External Webservice Service
(EWS) response message schema– Noun and Verb combination are
used to identify the Notification type– Payload contains actual schema
element (ex. BidSet)
http://nodal.ercot.com 72Lead from the front
Texas Nodal
Setting Up a Listener - Example Notification Listener Setup-1
• Technology Used– Java 1.5
• http://java.sun.com/javase/downloads/index_jdk5.jsp
– Apache Axis 1.4• http://ws.apache.org/axis/
– Apache WSS4J 1.5• http://ws.apache.org/wss4j/
– Apache XML Security 1.4.1• http://xml.apache.org/security/index.html
– KeyTool GUI 1.7• http://www.gria.org/downloads
http://nodal.ercot.com 73Lead from the front
Texas Nodal
Setting Up a Listener - Example Notification Listener Setup-2
• Axis setup– Copy Axis project to webserver (Ex. tomcat’s) webapps folder
– Start web server & invoke happyaxis.jsp to validate the deployment (Ex. http://localhost:8080/axis/happyaxis.jsp for tomcat)
• WSDL2Java– To construct stub classes from WSDL
• java org.apache.axis.wsdl.WSDL2Java (WSDL_FILE_PATH)
– Copy compiled stub classes into Axis project
– Deploy service into Axis• Example
– java org.apache.axis.client.AdminClient -l http://localhost:8080/axis/services/AdminService deploy.wsdd
• <Demo to consume sample Notification Message>
http://nodal.ercot.com 74Lead from the front
Texas Nodal
Setting Up a Listener - Example Notification Listener Setup-3
• Security Setup– Enable SSL in webserver(ex. Tomcat)
• Configuration parameters– Sample security service params in deploy.wsdd
<requestFlow >
<handler type= "java:org.apache.ws.axis.security.WSDoAllReceiver" >
<parameter name="action" value="Signature"/>
<parameter name="passwordCallbackClass" value="PWCallback"/>
<parameter name="signaturePropFile" value="crypto.properties" />
<parameter name="enableSignatureConfirmation" value="false"/>
</handler>
</requestFlow>
– Crypto properties for messaging signature validation• org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin• org.apache.ws.security.crypto.merlin.keystore.type=<Type of key store> <Ex. JKS>• org.apache.ws.security.crypto.merlin.keystore.password=<Keystore password>• org.apache.ws.security.crypto.merlin.keystore.alias=<certificate alias in keystore>• org.apache.ws.security.crypto.merlin.alias.password=<certificate alias password in keystore>• org.apache.ws.security.crypto.merlin.file=<Keystore>
http://nodal.ercot.com 75Lead from the front
Texas Nodal
Maintenance
http://nodal.ercot.com 76Lead from the front
Texas Nodal
Maintenance (MPIM) – Requirements Overview
• MPIM – Market Participant Identity Management• Texas Nodal requires a level of sophistication in how it manages
the identities of external users that goes beyond the current Zonal solution. Managing user identities involves:
– Creating identities for each Market Participant’s users – Defining policies that govern how for Market Participant users access ERCOT
content– Guarding ERCOT’s content according to the access policies– Providing identity information to the component Nodal applications
• A further enhancement is to control web service access that will be provided to Market participants. This introduces further features necessary for the solution:
– Communications are Market Participant Machine to ERCOT, not Market Participant user to ERCOT, although Market Participant Machine can be made to be analogous to a user
– Requests are made based on a different messaging protocol – Frequency of requests can be much higher, implying that the certificate verification
should be done internally to maintain performance
http://nodal.ercot.com 77Lead from the front
Texas NodalAPI Subgroup04/19/23
Maintenance (MPIM) – User Access – High level
http://nodal.ercot.com 78Lead from the front
Texas Nodal
Maintenance (MPIM) – Application Access – High level
http://nodal.ercot.com 79Lead from the front
Texas Nodal
Maintenance (MPIM) – Digital Certificates
• Certificates are now administered via a self service model• API certificates are generally handled the same as user
certificates• The USA will issue and manage API certificates via the same
interface used for managing user certificates (IdM)• USA can run reports in IdM to view certificate status and
information, including the expiration date• During the certificate provisioning process in IdM the USA
selects an option which denotes the certificate as a API certificate
– The employee Id field is prefixed with ‘API_’– This prefix assists in routing the requests to the API access management tool
• Certificates are valid for only 1 year; they expire on their anniversary
http://nodal.ercot.com 80Lead from the front
Texas Nodal
Maintenance (MPIM) – API certificate re/issuance
http://nodal.ercot.com 81Lead from the front
Texas Nodal
Market ParticipantRequested Topics
http://nodal.ercot.com 82Lead from the front
Texas Nodal
Requested Topics – Trades Workflow / Market Timeline
Preparation forReal-Time Ops
Adj Period
18:00(D – 1)
60 MinutesPrior toOp Hour
QSE Deadline:Update Energy OffersSubmit HRUC Offers
Update Output SchedulesUpdate Inc/Dec Offers for DSRs
ERCOT Activity:LFC Process every 4 secs
Execute SCED every 5 minsCommunicate Instructions
& Prices
ERCOT Activity:Snapshot Inputs &
Execute HRUC
Operating Period
Operating Hour
ClockHour
T
Adjustment Period & Real-Time Operations
Real-Time Operations
QSE Deadline:Update Output Schedules for DSRs
Provide SCADA Telemetry
ERCOT Activity:Communicate
HRUC Commitments
Adjustment Period
http://nodal.ercot.com 83Lead from the front
Texas Nodal
Additional Requested Topics - Trades Workflow / Market Timeline
9/5/2008 12:00 AM 9/7/2008 12:00 AM
00:00 - 18:00Day Ahead
18:00 - 00:00Adjustment
Period
18:00 - 11:00
Each Party Must Enter Identical Trades For HE 13
11:00 - 12:00
Snapshot InputsHRUC Commitments
12:00 - 13:00Operating Hour
9/5/2008 6:00 PMAdjustment Period Opens for 9/6/08
Trade Example• PARTY A and PARTY B wish to enter an AS or Capacity trade for HE 1300 on 9/6
– Trade can be entered up to 7 days in advance
– Deadline for Trade is 1100 on 9/6/08
– Both parties must enter identical trades for trade to be confirmed
– Either Party may reject the trade before or after confirmation prior to the deadline of 1100.
– Note: For Energy Trades Only – these may be submitted up to 1430 of the following day
http://nodal.ercot.com 84Lead from the front
Texas Nodal
Additional Requested Topics - Trades Workflow / Market Timeline
• Confirmation of trades– Once a trade is submitted, a notification is sent to the counterparty
(Unconfirmed Trade notification)– Example/
• Party A Submits a trade with Party B• Party B will receive an unconfirmed trade notification• Party B Submits an identical trade• Trade is now confirmed
• Wildcard Query of Trades– Wildcard feature will allow QSE’s to query trades only supplying
one of the parties– QSE’s may query trades they submitted OR trades submitted by
another party that has them as either buyer or seller
http://nodal.ercot.com 85Lead from the front
Texas Nodal
Additional Requested Topics - Alerts and Messages
• QUESTION: Detail the difference between an ALERT and NOTIFICATION. What is ERCOT expecting from market participants regarding an ALERT that is different than a NOTIFICATION?
• “In practice” definitions:– Alerts: are higher priority (e.g. emergency conditions), but
from a technical stance are no different– Messages (aka “notifications”): Are informational or validation
communications issues from ERCOT.
• Note that these definitions are “in practice” as they apply to transactions sent from ERCOT to MP’s.
http://nodal.ercot.com 86Lead from the front
Texas Nodal
Additional Requested Topics - Alerts and Messages
• High Level Architectural Diagram of Alerts and Messages
MIS
Listener
Market Participants
Listener
MMS / Outage Scheduler
Publish
Manual Entry
Publish
Notification Service
EMS
Publish
Outage Scheduler
Market Manager
CRR
http://nodal.ercot.com 87Lead from the front
Texas Nodal
Additional Requested Topics – Market Interfaces to Obtain Data
• Interfaces Available to Market Participants for Retrieving Data– EIS (External Web Services)
• MarketInformation (direct query of data)• getReports (query to obtain list of reports types and related URLs)
– MP must use returned URL to download report via http
– MIS (Market Information System) – direct manual download– TML (Texas Market Link)– Report Explorer / piApp
• What is / will be Available on What Interfaces?– ERCOT will be working to provide a comprehensive approach to providing these
details– First Step: In 1 month ERCOT will provide a complete list of all market facing
reports.– Each month thereafter, ERCOT will either use an existing EDS Market call or
schedule special workshops to review a subset of these reports, covering,• Content of the report• How to retrieve the report and what interface will be leveraged• Samples and definitions of the structure and data (where applicable)
http://nodal.ercot.com 88Lead from the front
Texas Nodal
Additional Requested Topics – ERCOT WAN
Participant
CSU/DSU
CS
U/D
SU
CSU/DSU
CS
U/D
SU
CSU/DSU
Router
Router
Router
Router
DACSNetwork
MPLSNetwork
ERCOT Taylor
ERCOT Austin
Firewall
Firewall
3 connections to ERCOT MP Taylor (T1 connection) MP MPLS Network Taylor MP MPLS Network Austin
MPLS (Multiprotocol Label Switching) Network serve as the primary for http traffic T1 connection is primary for RTU and Voice data (back-up for all else)
http://nodal.ercot.com 89Lead from the front
Texas Nodal
Additional Requested Topics – ERCOT WAN
• 2 Methods for Resolving ERCOT addresses over the WAN1. Utilize the ERCOT DNS server by setting up all ercot.com addresses with
a forwarder to the ERCOT DNS2. Set up Zone Transfer which pushes the ERCOT updated zone file to a
local DNS server
• Managing MP Fail-Over– Local node to node node failover can use a network appliance
to provide a VIP for ERCOT to use (i.e. failovers would be invisible to ERCOT)
– Remote site site failover is still manual and requires a call over the hotline
• Refer to the Nodal Operating Guides Section 7: Telemetry and Communication for full details on the ERCOT WANURL: http://nodal.ercot.com/mktrules/noperating/cur.html
http://nodal.ercot.com 90Lead from the front
Texas Nodal
Action Items from Original Workshop on 9/3/08
• Message.xsd Compressed Element – Investigate why AXIS codegen does not produce relevant stubs for it.– Under investigation
• Nodal.wsdl - Non-compliancy – unique soap action – causes codegen errors in Apache CFX– Defined at: http://www.ws-i.org/Profiles/BasicProfile-1.1-2004-08-24.html– Investigation resulted in confirmation of this issue– The suggested change is kind of like this change:
• operation1....Name="element1" type="EWSRequest"> operaton1...Name ="element2" type="EWSResponse"> ...• operation2....Name="element1" type="EWSRequest"> operaton2...Name ="element2" type="EWSResponse"> ...
– Under investigation
• Provide documentation on certificate management– Explanation of each certificate to be used (e.g. root, intermediate, client, etc)– Direction on where / how to obtain each– Reviewing whether this will be an appendix to EIS or separate, referenced document
• Replay detection – better description of Nonce and concept– Reviewing ERCOT WSS Document and whether this can be distributed
• Post example for listener like “who am I” and “Boomerang” examples– Under investigation
• Accepting changes in EIS specification (remove tracking)– ERCOT will accept all change prior to current revision– This will be posted by 9/19/2008 to the readiness center sandbox location:
http://nodal.ercot.com/readiness/sandbox/documents/index.html – The version with full revision history will also remain available
http://nodal.ercot.com 91Lead from the front
Texas Nodal
Jar Files
• Apache Axis 1.4http://ws.apache.org/axis/
– axis.jar– commons-logging-1.0.4.jar– commons-discovery-0.2.jar– jaxrpc.jar– saaj.jar– wsdl4j-1.5.1.jar– axis-ant.jar
• Apache WSS4J 1.5http://ws.apache.org/wss4j/
– wss4j-1.5.1.jar
• Apache XML Security 1.4.1http://xml.apache.org/security/index.html
– xmlsec-1.4.1.jar– xercesImpl.jar– xalan.jar
• Javahttp://java.sun.com/javase/downloads/index_jdk5.jsp
– activation.jar– mail.jar
http://nodal.ercot.com 92Lead from the front
Texas Nodal
Certificates – Keystores – Properties : Overview
client.properties
client.wsdd
crypto.properties
KEYSTORES
Truststore
Transport Level Keystore
Message Level Keystore
CERTIFICATES
Verisign Class3 Root Certificate
Verisign Class3 Intermediate Certificate
Client Certificate
ERCOT Public Key
http://nodal.ercot.com 93Lead from the front
Texas Nodal
Certificates
• Certificates required to interact with ERCOT Web Services1. Verisign Class3 Root Certificate
(obtained from www.verisign.com)
2. Verisign Class3 Intermediate Certificate(obtained from www.verisign.com) Verisign Class3 Root and Intermediate Certificate are used to configure Transport Level Security.They are used by client program to trust the ERCOT server its interacting with.
3. Client CertificateClient Certificate is used to configure Transport Level Security and Message Level Security.At the Transport Level, it is used by client program to authenticate itself to the ERCOT server.At the Message Level, it is to digitally sign the request message sent to ERCOT Web Services.(obtained from each MP’s USA)
4. ERCOT Public KeyERCOT Public Key is used to configure Message Level Security.It is used by client program to verify the digital signature in the response message returned by ERCOT Web Services.(obtained from ERCOT Account Manager)
http://nodal.ercot.com 94Lead from the front
Texas Nodal
Certificates - Keystores
• Keystores– truststore.jks
• Verisign Class3 Root Certificate• Verisign Class3 Intermediate Certificate
– transport_keystore.jks• Client Certificate
– message_keystore.jks• Client Certificate• ERCOT Public Key
http://nodal.ercot.com 95Lead from the front
Texas Nodal
Certificates – Security Configuration
• System Properties– javax.net.ssl.keyStore = <LOCATION OF TRANSPORT LEVEL KEYSTORE>– javax.net.ssl.keyStorePassword = <PASSWORD TO ACCESS THE TRANSPORT LEVEL KEYSTORE>– javax.net.ssl.keyStoreType = <TYPE OF THE TRANSPORT LEVEL KEYSTORE>– javax.net.ssl.trustStore = <LOCATION OF THE TRUSTSTORE>– javax.net.ssl.trustStorePassword = <PASSWORD TO ACCESS THE TRUSTSTORE>– javax.net.ssl.trustStoreType = <TYPE OF THE TRUSTSTORE>
• Client WSDD Configuration Properties– <parameter name="user" value="<ALIAS OF CLIENT CERT STORED IN MESSAGE LEVEL KEYSTORE>" />– <parameter name="passwordCallbackClass" value="<PASSWORD CALL BACK CLASS>"/>
• Crypto Configuration Properties– org.apache.ws.security.crypto.merlin.keystore.type=<TYPE OF MESSAGE LEVEL KEYSTORE>– org.apache.ws.security.crypto.merlin.keystore.password=<PASSWORD TO ACCESS THE MESSAGE LEVEL
KEYSTORE>– org.apache.ws.security.crypto.merlin.keystore.alias=<ALIAS OF CLIENT CERT STORED IN MESSAGE LEVEL
KEYSTORE>– org.apache.ws.security.crypto.merlin.alias.password=<PASSWORD TO ACCESS THE CLIENT CERT STORED
IN MESSAGE LEVEL KEYSTORE>– org.apache.ws.security.crypto.merlin.file=<LOCATION OF THE MESSAGE LEVEL KEYSTORE>
http://nodal.ercot.com 96Lead from the front
Texas Nodal
• client.properties#The location of the client keystore used for the transport level security
javax.net.ssl.keyStore=transport_keystore.jks
#The type of keystore being used.
javax.net.ssl.keyStoreType=jks
#The keystore's password
javax.net.ssl.keyStorePassword=changeit
#Location of the truststore file
javax.net.ssl.trustStore=client_truststore.jks
#truststore’s password
javax.net.ssl.trustStorePassword=changeit
#The type of truststore being used
javax.net.ssl.trustStoreType=jks
#This is the location of the Web service deployment definition file.
webservice.deployment.definition.file=client.wsdd
Transport Level Security - Configuration
http://nodal.ercot.com 97Lead from the front
Texas Nodal
• client.wsdd<deployment xmlns="http://xml.apache.org/axis/wsdd/" xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"><transport name="http" pivot="java:org.apache.axis.transport.http.HTTPSender"/> <globalConfiguration > <requestFlow > <!-- For each request sent from client... --> <handler type= "java:org.apache.ws.axis.security.WSDoAllSender" >
<!-- Insert signature in requests --> <parameter name="action" value="Signature"/> <!-- Alias name of the certificate from the keystore --> <parameter name="user" value=“<CERT_ALIAS_NAME>" /> <!-- This is the callback class that implements a method to get certs password. --> <parameter name="passwordCallbackClass" value=“<PasswordCallBackClassName>"/> <!– keystore is defined in crypto.properties file. --> <parameter name="signaturePropFile" value="crypto.properties" /> <!– Specifies the format used by handler to insert signature into request. DirectReference causes the handler to convert the signing certificate to BinarySecurityToken element that is pit in security header --> <parameter name="signatureKeyIdentifier" value="DirectReference" />
</handler> </requestFlow> <responseFlow> <handler type= "java:org.apache.ws.axis.security.WSDoAllReceiver" > <parameter name="action" value="Signature"/> <parameter name="passwordCallbackClass" value="PWCallback"/> <parameter name="signaturePropFile" value="crypto.properties" />
<parameter name="enableSignatureConfirmation" value="false"/> </handler> </responseFlow>
</globalConfiguration ></deployment>
Message Level Security - Configuration
http://nodal.ercot.com 98Lead from the front
Texas Nodal
• crypto.properties
org.apache.ws.security.crypto.provider=org.apache.ws.security.components.crypto.Merlin
#Type of the keystore
org.apache.ws.security.crypto.merlin.keystore.type=<KEYSTORE_TYPE>
#Client keystores password
org.apache.ws.security.crypto.merlin.keystore.password=<KEYSTORE_PASSWORD>
#Alias name of the client cert in the keystore
org.apache.ws.security.crypto.merlin.keystore.alias=<CERT_ALIAS_NAME>
#Password of the client cert in the keystore
org.apache.ws.security.crypto.merlin.alias.password=<CERT_ALIAS_PASSWORD>
#The location of the client keystore used for the signing the message
org.apache.ws.security.crypto.merlin.file=<KEYSTORE_LOCATION>
Message Level Security – Configuration (Continued)
Top Related