Developer Guide to the MarkeTrak XML Interface

Last revised: 01 Aug 2019

Revision 1.2

---

Table of Contents

• 1. Introduction
  2. 1.1. Purpose
  3. 1.2. Overview
  4. 1.3. Requirements and Prerequisites
  5. 1.4. Background and History
  6. 1.5. Related Documents and Further Information
• 1. Design your application
  2. 2.1. Obtaining the Latest Specifications
  3. 2.2. Understanding the Network Architecture
     • 2.2.1. Issue Workflow: States and Transitions
  4. 2.3. Choosing Development Processes and Tools
  5. 2.4. Using a Component Approach
  6. 2.5. Handling Failed Responses
     • 2.5.1. Handling Timeouts
     • 2.5.2. Handling Lockouts When Calling the Update Service
     • 2.5.3. MarkeTrak Outage
     • 2.5.4. Parsing Errors
     • 2.5.5. Processing Errors
     • 2.5.6. Field Data Errors
  7. 2.6. Planning for a Specific Level of Certification
  8. 2.7. Understanding the API
     • 2.7.1. Managing Data Loads
• 1. Establishing a Connection to MarkeTrak
  2. 3.1. Configuration Information
  3. 3.2. Getting Through Your Firewall
  4. 3.3. Using the Correct Digital Certificate
  5. 3.4. Troubleshooting Connection Errors
     • 3.4.1. Digital Certificate Expired
     • 3.4.2. URL Page Timeout
• 1. Using Services
  2. 4.1. Using the Query List service
     • 4.1.1. Purpose of the Query List Service
     • 4.1.2. Definition in the API
     • 4.1.3. Description of a Query List Request Message
     • 4.1.4. Description of a Query List Response Message
     • 4.1.5. Hints and Tips on Implementing a Query List Client
  3. 4.2. Using the Query Detail Service
     • 4.2.1. Purpose of the Query Detail Service
     • 4.2.2. Definition in the API
     • 4.2.3. Description of a Query Detail Request Message
     • 4.2.4. Description of a Query Detail Response Message
     • 4.2.5. Hints and Tips on Implementing the Query Detail Client
  4. 4.3. Using the Query File Attachment service
     • 4.3.1. Purpose of the Query File Attachment Service
     • 4.3.2. Definition in the API
     • 4.3.3. Description of a Query File Attachment Request Message
     • 4.3.4. Description of a Query File Attachment Response Message
     • 4.3.5. Hints and Tips on Implementing a Query File Attachment Client
  5. 4.4. Using the Update Service
     • 4.4.1. Purpose of the Update Service
     • 4.4.2. Definition in the API
     • 4.4.3. Description of an Update Request Message
     • 4.4.4. Description of an Update Response Message
     • 4.4.5. Hints and Tips on Implementing the Update Service
  6. 4.5. Using the Submit Service
     • 4.5.1. Purpose of the Submit Service
     • 4.5.2. Definition in the API
     • 4.5.3. Description of a Submit Request Message
     • 4.5.4. Description of a Submit Response Message
     • 4.5.5. Hints and Tips on Implementing the Submit Client
• 1. Testing against the ERCOT sandbox
  2. 5.1. Obtain a digital certificate for testing
  3. 5.2. Notify ERCOT that you are beginning test phase
  4. 5.3. Error Messages
• 1. Obtaining ERCOT certification for your application
  2. 6.1. Levels of Certification
  3. 6.2. How to Request Certification
• 1. Tips and Suggestions On Implementing SOAP
  2. 7.1. Basic Syntax rules of SOAP
  3. 7.2. Accessing a service
     • 7.2.1. SOAP Message Formats
     • 7.2.2. Embedding the SOAP message in an HTTP Request
     • 7.2.3. Specifying the SOAP Envelope and Body
  4. 7.3. Summary
• 1. Tips and Suggestions on Reading the WSDL Document

---

1. Introduction

1.1. Purpose

This document explains development guidelines for creating an application to interface with ERCOT’s MarkeTrak application. This document is intended for functional and technical experts who need to understand how to develop an application that can interface with MarkeTrak.

1.2. Overview

You can approach the development of your application with the following 5 phases in mind:

1. Design your application

2. Write communication code, establish a connection from your application to MarkeTrak

3. Write remainder of code that accesses MarkeTrak web services

4. Test your application against the ERCOT sandbox and debug

5. Obtain application certification

By implementing programmatic interfaces, market participants can execute many of the same business functions that the ERCOT MarkeTrak web application supports through the browser interface. For example, you can use the programmatic interface to perform a query on a particular ESI ID.

1.3. Requirements and Prerequisites

From a functional perspective, the audience should understand what is required for the market participant’s systems to interact with ERCOT systems.

From a technical perspective, in order to design and implement the participant software interface to communicate with MarkeTrak programmatically through API calls, the reader should have a working knowledge of the following:

• Simple Object Access Protocol (SOAP)

• XML Schema Definitions (XSDs) version 1.1

• Web Services Description Language (WSDL) version 2.0

• XML parsing and validation.

• HTTPS and TCP/IP

The reader is also expected to have a basic understanding of:

• Security technologies including: encryption, digital certificates

• Authentication concepts and methods

• Methods for communicating over secure networks

1.4. Background and History

ERCOT created the MarkeTrak system to track retail market issues and data discrepancies. The number of issues and the amount of data that needs to be managed has increased steadily since 2001. For example, in 2007 there were over 200,000 issues logged from approximately 90 market participants.

Market participants worked with ERCOT to document the business needs and requirements around issue management. The documents SCR732 and SCR738 describe these needs and requirements.

The objectives of MarkeTrak include:

• Improve reporting functionality

• Improve tracking/metrics functionality

• Create usable issue status

• Create usable issue types and sub types

• Create a method to allow users to interface the solution

• Improve search functionality

• Improve monitoring and response capabilities

• Improve usability

• Provide all functionality that is deemed required with the legacy tool as part of the enhanced solution

1.5. Related Documents and Further Information

Please refer to the following related documents:

• Users Guide (MarkeTrak Users Guide.zip)

• Bulk Insert Appendix A (MarkeTrak Bulk Insert Appendix A.doc)

• States and Transitions spreadsheets (MarkeTrak States_Transitions.zip)

You can find a copy of the above documents and other MarkeTrak information on the ERCOT web site:

http://www.ercot.com/services/client_svcs/mktrk_info/

2. Design your application

Before you begin writing code for your application, we recommend that you read this chapter. This chapter explains some of the design considerations that will affect the stability and performance of your application.

2.1. Obtaining the Latest Specifications

Make sure that you are aware of the latest API specifications and documentation.

The latest API specifications for the MarkeTrak Application Programming Interface are defined in the XML Schema Definition (XSD) document and the Web Services Definition Language (WSDL) document.

Please refer to the following related documents:

• API WSDL and XSD (MarkeTrak API_rcX-YY.zip)

You can find a copy of the above document and other MarkeTrak information on the ERCOT web site:

http://www.ercot.com/services/client_svcs/mktrk_info/

2.2. Understanding the Network Architecture

From a market participant’s perspective, the MarkeTrak interface involves sending SOAP messages that include Extensible Markup Language (XML) payloads using Hypertext Transfer Protocol Secure (HTTPS) to connect to the appropriate ERCOT server host. To access a specific business function, the market participant’s client program sends messages to the ERCOT server host port that implements the service. The ERCOT server host receives the message, processes the request through business rules defined in MarkeTrak, and delivers a reply.

Be aware that the MarkeTrak application performs processing of business rules that are not necessarily visible to you through the API. When you send requests to MarkeTrak, the requests might be well-formed and valid according to the schema, but that does not mean that the request is necessarily valid according to the MarkeTrak business rules.

To understand the business rules that govern processing, see the MarkeTrak Users Guide.

2.2.1. Issue Workflow: States and Transitions

One important aspect of the MarkeTrak system is the use of workflows. Workflows determine how an issue moves through the system toward resolution.

The MarkeTrak systems routes all issues into one of several workflows based on the Type and Subtype of the issue. In order to understand how an issue moves through a workflow, you must understand two concepts: States and Transitions.

The State of an issue represents its position in the workflow.

Transitions represent the movement of an issue from one state to another. In the GUI version of MarkeTrak, buttons that are enabled indicate which transitions are available from a certain state. Transitions are represented as push buttons at the top of a GUI Issue screen. They will list all the transitions the current user has permissions to implement.

In the API version, you use the Update service to move an issue from one state to another. If you access the Update service through the API, your application needs to implement logic that creates a valid request based on the issue’s state, allowable transitions, and transition fields.

The diagram below shows the workflow of an Ercot-initiated issue. You can see that the issue first moves from the initial creation to the Pending Issue state. From that state, there are 2 possible transitions: Submit and Withdraw. Those transitions will be available only to roles that have permission to update the issue from the Pending Issue state.

You can see from this one diagram that there are many possible permutations that result from the combination of an issue’s type, state/transitions, and owner.

For more information about what you need to know about workflows when designing your application, see Hints and Tips on Implementing the Update Service on page 38.

Diagram: Workflow of Issue – D2D/Ercot Initiated

ERCOT provides information about workflows in spreadsheets and diagrams. You can find the spreadsheets and diagrams on the ERCOT web site:

• MarkeTrak State_Transitions (MarkeTrak_State_Transitions.zip)

http://www.ercot.com/services/client_svcs/mktrk_info/

2.3. Choosing Development Processes and Tools

ERCOT does not demand or assume that you follow any particular development methodology or use a specific development tool. This document suggests guidelines but not requirements about your development process. You should be aware of these guidelines regardless of your development methods.

The MarkeTrak system is based on open protocols and standards. For that reason, you are not required to use any specific tools to interface with the MarkeTrak API. MarkeTrak’s web services expose functionality on the server to your application.

Your client application may be a fat client app on a Windows OS, a fat server web application that runs on a standard web backend such as ASP, Cold Fusion, Web Connection etc., a browser based client application using script code, or even a Java applet running in a browser on a Unix machine. As long as your client application has support for the Simple Object Access Protocol (SOAP) it can call the remote web service and process the return data (assuming the user is authorized).

2.4. Using a Component Approach

We suggest that you design your application in a way that isolates each web service call. This means designing calls to web services so that each service can operate independently. Doing so allows you to disable a service without affecting other services. This might be useful if a certain web service is temporarily unavailable for maintenance reasons. This is also useful if you are updating your own system, but want to make sure that you are affecting only certain services.

2.5. Handling Failed Responses

It is always wise to consider your approach to error handling before you begin coding. With the MarkeTrak system, we recommend that you implement error handling routines for the following kinds of exception and errors.

2.5.1. Handling Timeouts

Your application should expect a response to a request within 5 minutes. After 5 minutes, MarkeTrak closes the communication session initiated by the request.

There are 2 main reasons that you might experience a timeout: either the MarkeTrak system is not available or there are system problems.

If your application makes exceedingly large web service calls, it is likely that the web service will time out due to your configuration. ERCOT requests and recommends that no more than 10 requests be passed in a web service call at a time. When this occurs, MarkeTrak still processes the request, but a response will no longer be able to be returned to the caller.

Your application should re-submit any request that does not receive a response within the 5 minute timeout. When re-submitting a Create Issue request, be sure to turn duplicate checking on, as this will help prevent duplicate issues from being created.

If the same Issue is re-submitted 5 times and fails, the issue should be removed from re-submit and an email sent to your internal Api support identifying the error.

2.5.2. Handling Lockouts When Calling the Update Service

If your application implements calls to the Update service, consider implementing some sort of retry functionality. Keep in mind that the MarkeTrak system serves not only calls through the API, but also serves users who have access through a Graphical User Interface (GUI) client. Because access from a GUI client can lock an issue, your application might encounter locking issues. Due to these locking issues, it is very likely that you will get errors from the system when attempting to update an issue.

The easiest solution to address this is to implement some sort of retry functionality - after detecting that there is a locking issue, your application should wait a short while and retry. When re-submitting a Create Issue request, be sure to turn duplicate checking on, as this will help prevent duplicate issues from being created.

If the same Issue is re-submitted 5 times and fails, the issue should be removed from re-submit and an email sent to your internal API support identifying the a problem.

2.5.3. MarkeTrak Outage

If your application is not receiving any response from the MarkeTrak server, it is possible that MarkeTrak is unavailable. An outage can come in 2 types: Scheduled and Unscheduled.

Normally when a Scheduled Outage occurs, there will have been an email sent prior to the planned outage. Contact your internal Production Admin about any scheduled outages.

In the event of an unscheduled outage, contact your Production Admin. Have them contact ERCOT and open an Incident ticket with your ERCOT Retail Client Service (RCS) representative or the ERCOT Help Desk.

Before attempting to re-connect and resend to MarkeTrak, we recommend that you shut down your API application, and restart it.

2.5.4. Parsing Errors

When you receive a response from MarkeTrak in which the FAIL response from MarkeTrak, you must determine what aspect of your request message was in error. Most errors result for 1 of 2 reasons.

• Invalid data element

• Wrong order – XML elements are listed out of order, element order is important.

• Wrong size – XML element exceeds defined maximum or minimum length.

• Enumerations – XML element text does not match one of the enumerations defined.

• Format – XML element value is specified in an invalid format for the given element according to the element type.

• Missing required data elements – Required XML element is not specified.

2.5.5. Processing Errors

When you receive a response from MarkeTrak in which the FAIL response from MarkeTrak, you must determine what aspect of your request message was in error. Most errors result from 1 of 3 reasons.

• Invalid transition

• Invalid transition given issue state – API Update request is trying to transition an issue and the transition specified is invalid because the transition is not available given the issue’s current state.

• Invalid transition given user permissions – API request is trying to transition an issue and the transition specified is invalid due to user permissions.

• Missing Fields – API request contains an optional field that while executing the transition it was determined was required. These types of fields are usually content specific dependant on another fields value.

• Too Many Fields – API request contains more field data than expected. One or more fields specified data that was not required by the transition.

2.5.6. Field Data Errors

When you receive a response from MarkeTrak in which the FAIL response from MarkeTrak, you must determine what aspect of your request message was in error. Most errors result 1 or 3 types of Validation Errors.

• Validation Errors

• Data Invalid transition given issue state – API XML field contains a value that is invalid for the given MarkeTrak Issue Type/Sub-type or Issue State.

• Length/Data type – API XML field contains a value that has an invalid minimum/maximum length for the fields data type.

• Format – API XML field contains a value that is not formatted correctly.

2.6. Planning for a Specific Level of Certification

Be aware of the certification level that your application needs to pass.

To use the MarkeTrak services through API calls, your application must be certified by ERCOT. There are 3 levels of certification, each based on the type of web service calls your application will make:

• QueryList and QueryDetail: certifies that your application makes proper use of these services, which are read-only access to the system

• QueryList, QueryDetail, and Update: certifies proper use of the above plus the Update service. This will allow the API server to transition active Issues.

• QueryList, QueryDetail, Update, and Submit: certifies proper use of the above plus the Submit service

2.7. Understanding the API

When we talk about understanding the API we are really talking about understanding the XSD and WSDL files. Those files contain the definition of the data fields and messages that are transmitted between client and server.

For example, to learn about the possible kinds of issues, you could look for the element called IssueType:

XSD snippet showing IssueType element

<element name="IssueType" type = "TTISSUE:issueDef"\>

You can see from the snippet that the element (“IssueType”) is defined as a data type named “issueDef” in the “TTISSUE” namespace. Looking further in the XSD document you can see the definition of the “issueDef” data type.

XSD snippet showing issueDef data type

<simpleType name="issueDef">
  <restriction base="xsd:string">
    <enumeration value="D2D"/>
    <enumeration value="DEV-Char"/>
    <enumeration value="DEV-Existence"/>
    <enumeration value="DEV-IDR Usage"/>
    <enumeration value="DEV-LSE"/>
    <enumeration value="DEV-Non-IDR Usage"/>
    <enumeration value="ERCOT Initiated"/>
    <enumeration value="LPA"/>
  </restriction>
</simpleType>

You can see in the example above that an “issueDef” can be: D2D, DEV-Char, DEV-Existence, DEV-IDR Usage, DEV-LSE, DEV-Non-IDR Usage, ERCOT Initiated, or LPA. (To learn more about these issue types, refer to the MarkeTrak User’s Guide.)

In addition, the WSDL file defines other information about the web services, such as the address at which the services can be found. This kind of information would probably be picked up automatically by your development tool. For example, if you are developing in a .Net environment, the WSDL.exe tool would read the information in the MarkeTrak WSDL file, and create the code stubs for your application. To learn more about the specific information contained in the WSDL document, see Tips and Suggestions on Reading the WSDL Document on page 59.

2.7.1. Managing Data Loads

The recommended design for API users is to make QueryList calls often, for example once every 5 minutes to look for data that has changed (LastModifiedDate) since the last call. Then, for each Issue Id returned, a subsequent QueryDetail web service call should be made. Using this type of architecture allows for small amounts of data to be pulled consistently rather than requesting large amounts of data that might impact other users of the system.

At this time ERCOT requests that API design limit the number of requests per connection to 10. ERCOT should, at maximum, receive 10 requests per connection. Please keep in mind that the ERCOT API application was designed for a 1:1 environment (1 connection, 1 request, 1 response).

3. Establishing a Connection to MarkeTrak

We recommend that you establish a connection to the MarkeTrak system early in the development process. This will allow you to work through and solve errors related to making a connection while you work through coding/errors related to specific web services.

As a basic test of connectivity, you could send a PING signal over an SSL connection. This kind of test would allow you to confirm that you are communicating through your firewall with ERCOT. However, this kind of test is not sufficient. It doesn’t allow you to validate that the MarkeTrak application recognizes your request. Also, a simple PING doesn’t validate that you can receive a response from the MarkeTrak application.

To make a connection to MarkeTrak:

1. Create a connection script or program
   We recommend that you create some sort of script or automated method of connecting to the server to test connectivity. The script should send a simple request (XML data) to a particular web service, such as Query Detail, and be able to receive a response. Use the XSD and WSDL to guide you in forming the request message.

2. Obtain appropriate digital certificate
   Make sure that you have a digital certificate that authenticates against the MarkeTrak server.

3. Coordinate test time with ERCOT
   Make arrangements to have a window of time to work with the test server. You can arrange the date and time with the person in charge of the test server. Ask your ERCOT Retail Client Service (RCS) representative if you do not know who that is.

4. Run your connection script
   Run the script or program that you created to test connectivity.

3.1. Configuration Information

All messages exchanged between your application and MarkeTrak need to use HTTPS over a TCP/IP connection. The messages are transported in a SOAP envelope.

We recommend that you use the sandbox environment (testing environment) initially to test your connection. Remember to use the appropriate digital certificate.

MarkeTrak sandbox: https://testmisapi.ercot.com/marketrakAPI/

MarkeTrak production server: https://misapi.ercot.com/marketrakAPI/

3.2. Getting Through Your Firewall

Be aware of restrictions caused by your firewall. Your network firewall might be configured to restrict internet access to certain sites or ports. If this is the case, you will need to make sure that your network allows access to the following domains and ports:

https://*.ercot.com

port: 443

You should also make sure that there are no firewall restrictions that might prohibit sending/receiving messages through HTTPS. As a simple test try the following:

Verify that you can connect to the server.

There are several ways to verify this, one of which is to use the ping utility.

To ping the server:

1) Open a terminal window.

In a Windows operating system you can open the Command window:

Start > All Program > Accessories > Command Prompt

2) On the command line, type:

ping testmisapi.ercot.com

3) Press Enter.

4) If the ping utility shows replies from the server, this means that you are able to connect to the server.

If you are able to connect to the server but still not able to connect through port 443, or are still not receiving any response from the MarkeTrak application, contact the ERCOT administrator of the test server. Be prepared to provide the following information:

• Description of problem

• Steps to reproduce

• Screenshot if applicable

• Date and Time of error

• Contact information

3.3. Using the Correct Digital Certificate

Make sure to use the appropriate digital certificate.

The digital certificate that you use to communicate through an API call is different than the digital certificate you use to communicate through the MarkeTrak GUI (the web application accessed through a browser).

The digital certificate that you use to communicate with the test server is different than the digital certificate you use to communicate with the production server. Plan to keep the 2 Digital Certificates on separate machines (1 Test/1 Prod).

3.4. Troubleshooting Connection Errors

The following section explains how to troubleshoot common connection problems:

• Digital Certificate Expired

• URL Page Timeout

3.4.1. Digital Certificate Expired

Problem:

Digital certificate not accepted by MarkeTrak.

Explanation:

When your application presents a digital certificate to MarkeTrak, it is evaluated to make sure that:

• the certificate has not expired

• each certificate in the certification path (certificate chain) is valid

Once a certificate’s validity has expired, it is up to you (the subject of the certificate) to request a new certificate from the issuing certification authority.

When connecting to the sandbox (test server), the issuing certification authority is the administrator at ERCOT who is responsible for the MarkeTrak sandbox. This person issues a digital certificate that can be used with the sandbox. Ask your ERCOT Retail Client Service (RCS) representative if you do not know who that is.

When connecting to the production server, the issuing certification authority is the user security administrator (USA) designated by the market participant. The market participant USA is responsible for registering digital certificate holders and administering the use of the digital certificates.

Resolution:

Verify the expiration date of the personal digital certificate.

To view the certificates on a Windows operating system:

1) Open Internet Explorer (version 5 or later)

2) Select Tools from the menu

3) Select Internet Options

4) Click on Content tab

5) Click Certificates button

**Certificates** window opens.

![](./media/image4.png)

6) From Personal tab, select the certificate that was issued to you for test purposes.

7) Click View button.

**Certificate** window opens.

![](./media/image5.png)

8) Look at Valid from date range

9) If the certificate is expired, contact the administrator of the MarkeTrak sandbox.

For more information about renewing expired digital certificates for the production server, contact your ERCOT Retail Client Service (RCS) representative.

For policies on digital certificates in general, refer to the ERCOT web site:

http://www.ercot.com/mktrules/guides/data_transport

3.4.2. URL Page Timeout

Problem:

Connection hangs - no response from MarkeTrak.

Explanation:

There are several reasons that you might experience a timeout of your request:

• connection requires an update to your page cache

• server is running, but MarkeTrak application is not available

• packet lost in transmission

If you are connecting for the first time, it is not uncommon for the response to hang due to your local client not having certain information in the page cache.

It is also possible that the server is running, but that the MarkeTrak application is not running. Make sure to coordinate with the test server administrator at ERCOT to verify that the MarkeTrak application is available.

Resolution:

1. Log out from MarkeTrak and submit request again.

   If the packet was lost in transmission or if your local page cache was not initialized, sending the request a second time should result in a successful connection.

2. If re-submitting the request fails, make sure to close other connections to the server and close other sessions to MarkeTrak that might be open through a browser.

3. If re-submitting the request fails, delete temporary internet files stored by your browser.

4. If re-submitting the request fails, verify that you have a connection to port 443. There are several methods for verifying this, one of which is to connect with the telnet utility.

To use Telnet to verify connectivity:

1) Open a terminal window.

In a Windows operating system you can open the Command window:  
**Start** \> **All Program** \> **Accessories** \> **Command Prompt**

2) On the command line, type:

>telnet testmisapi.ercot.com 443

3) Press Enter.

The telnet utility attempts to connect to port 443 over TCP/IP.

4) If telnet successfully connects to port 443, you will see a blank screen. The server does not send a response.

Press CTRL+C to exit telnet.

If you are able to successfully telnet to port 443, but not able to make
a connection through an http request, contact the ERCOT administrator of
the test server.

If telnet cannot telnet to port 443, you will see the error message:

“Could not open connection to the host, on port 443: Connect failed.”

1. If you cannot telnet to port 443, verify that you can connect to the server.

There are several ways to verify this, one of which is to use the ping utility.

To ping the server:

5) Open a terminal window.

In a Windows operating system you can open the Command window:  
**Start** \> **All Program** \> **Accessories** \> **Command Prompt**

6) On the command line, type:

>ping testmisapi.ercot.com

7) Press Enter.

8) If the ping utility shows replies from the server, this means that you are able to connect to the server.

If you are able to connect to the server but still not able to connect through port 443, or are still not receiving any response from the MarkeTrak application, contact the ERCOT administrator of the test server. Be prepared to provide the following information:

• Description of problem

• Steps to reproduce

• Screenshot if applicable

• Date and Time of error

• Contact information

4. Using Services

The MarkeTrak application provides 5 services that you can access programmatically through calls to the application programming interface (API):

• Query List

• Query Details

• Update

• Submit

• Query File Attachment

Be aware that you do not have to implement all five services. The services are not interdependent. This means that based on your application requirements, you might access only the Query List service and Query Details service.

This chapter suggests guidelines for implementing a client that accesses these services. This chapter includes the following information about each service:

• Purpose of the service

• Definition in the API

• Description of a request message

• Description of a response message

• Hints and Tips on Implementation

To fully understand the data requirements of a service, you will need to understand the API. The API is defined by the latest XML Schema Definition (XSD) and the Web Service Definition Language (WSDL) documents published by ERCOT.

This chapter explains where in the XML Schema Definition (XSD) document you can find the definitions of data fields required by each service.

Comments in the XSD Document

You might notice in the XSD document that there are comments that contain text such as

<!-- MPT... REQ ... -->

For example, in July of 2008, ERCOT added a new field called PremiseType to the QueryType element. There is a comment in the XSD document that documents this change as shown in the following snippet.

XSD Snippet: Comment Identifying New Element

<!-- MPT    07/10/2008  REQ 26    - Add Premise Type field to most sub-types, autopopulate -->
    <element ref="TTISSUE:PremiseType" minOccurs="0" maxOccurs="3"/>

The comments in the XSD document provide a convenient way for you to identify changes that have been made to the schema. The comments at the beginning of the XSD document contain a list of all the changes related to a specific requirement. You can search for the requirement number, such as REQ 26, in the XSD document to find all the changes related to that requirement.

Using the WSDL Document as a Reference

In addition to using the XSD document, you can also understand some of the requirements of accessing each service by looking at the WSDL document. For example, you can see in the WSDL file the definition of the server endpoint where the services can be found:

WSDL snippet showing definition of endpoint (port)

<wsdl:service name="TeamTrackExternal">
    <wsdl:port name="input" binding="tns:inputBinding">
        <soap:address 
        location="https://localhost:8443/BusinessService
        /WS/TeamTrack/External/TeamTrackExternal.serviceagent/input"/>
    </wsdl:port>
</wsdl:service>

It is likely that the tool that you are using for development will programmatically read the WSDL document, which means that you do not have to actually read through the WSDL document yourself. For example, if you are using MS Visual Studio .NET, you might use the WSDL.exe tool that comes with that development suite. Microsoft’s WSDL tool generates code for your web service client from the WSDL contract file and XSD document. The WSDL.exe tool reads the document and generates the appropriate stub code.

However, even if your development tool provides the stub code, there are still benefits to being aware of the role of the WSDL document in your development. For example, you can see in the WSDL file the definition of the services that are available to your application:

WSDL snippet showing definition of services

<wsdl:portType name="Operations">
  <wsdl:operation name="QueryDetail">
    <wsdl:input message="tns:QueryIssueDetailRequest"/>
    <wsdl:output message="tns:QueryIssueDetailResponse"/>
    <wsdl:fault name="exception" 
                message="tns:ExceptionRequestMessage"/>
  </wsdl:operation>
  <wsdl:operation name="Submit">
    <wsdl:input message="tns:SubmitIssueRequest"/>
    <wsdl:output message="tns:SubmitIssueResponse"/>
    <wsdl:fault name="exception" 
                message="tns:ExceptionRequestMessage"/>
  </wsdl:operation>
<wsdl:operation name="QueryFileAttachment ">
    <wsdl:input message="tns:QueryFileAttachmentRequest "/>
    <wsdl:output message="tns:QueryFileAttachmentResponse "/>
    <wsdl:fault name="exception" 
                message="tns:ExceptionRequestMessage"/>
  </wsdl:operation>
  <wsdl:operation name="QueryList">
    <wsdl:input message="tns:QueryIssueListRequest"/>
    <wsdl:output message="tns:QueryIssueListResponse"/>
    <wsdl:fault name="exception" 
                message="tns:ExceptionRequestMessage"/>
  </wsdl:operation>
  <wsdl:operation name="Update">
    <wsdl:input message="tns:UpdateIssueRequest"/>
    <wsdl:output message="tns:UpdateIssueResponse"/>
    <wsdl:fault name="exception" 
                message="tns:ExceptionRequestMessage"/>
  </wsdl:operation>
</wsdl:portType>

For more information about how to interpret information in the WSDL document, see Tips and Suggestions on Reading the WSDL Document on page 59.

4.1. Using the Query List service

This section describes the Query List service, and covers:

• Purpose of the service

• Definition in the API

• Description of a request message

• Description of a response message

• Hints and Tips on Implementation

4.1.1. Purpose of the Query List Service

The Query List service returns a list of issues that match search criteria defined in a Query List request. A market participant typically requests (queries) the system for a list of issues within a certain date range.

4.1.2. Definition in the API

Request

The Query List service expects the XML payload of a request to conform to the IssueQueryRequest data type. The following snippet from the XSD document shows the definition.

XSD Snippet: Definition of IssueQueryRequest

<complexType name="IssueQueryRequest">
  <complexContent>
    <extension base = "TTISSUE:QueryType"/>
  </complexContent>
</complexType>

You can see in the XSD snippet that IssueQueryRequest extends the QueryType data type. This means that to better understand the information that you are expected to provide in IssueQueryRequest, you need to look at the QueryType data type. The following snippet shows the definition of the QueryType data type.

XSD Snippet: Definition of QueryType

<complexType name="QueryType">
  <sequence>
    <element ref="TTISSUE:DateRangeName" minOccurs="0"
             maxOccurs="unbounded"/>
    <element ref="TTISSUE:IssueType" minOccurs = "0" maxOccurs = "50"/>
    <element ref="TTISSUE:IssueSubType" minOccurs = "0" maxOccurs = "50"/>
    <element ref="TTISSUE:MPInvolved" minOccurs = "0" maxOccurs="50"/>
    <element ref="TTISSUE:MPGroupNumber" minOccurs = "0" maxOccurs="50"/>
    <element ref="TTISSUE:MPGroupName" minOccurs = "0" maxOccurs="50"/>
    <element ref="TTISSUE:MPOwner" minOccurs="0" maxOccurs="50"/>
    <element ref="TTISSUE:IssueStatus" minOccurs = "0" maxOccurs = "5"/>
    <element ref="TTISSUE:IssueState" minOccurs = "0" maxOccurs = "50"/>
    <element ref="TTISSUE:SubmitSource" minOccurs = "0" maxOccurs = "50"/>
    <element ref="TTISSUE:ResponsibleMP" minOccurs="0" maxOccurs="50"/>
    <element ref="TTISSUE:LastModifier" minOccurs="0" maxOccurs="50"/>
    <element ref="TTISSUE:LastStateChanger" minOccurs="0" maxOccurs="50"/>
    <element ref="TTISSUE:PremiseType" minOccurs="0" maxOccurs="3"/>
  </sequence>
  <attribute name="app" type = "NCName"/>
</complexType>

IMPORTANT: The above snippet is an example. Please refer to the latest XSD document for current definitions.

As you can see in the above snippet, the QueryType contains several elements: DateRangeName, IssueType, IssueSubtype, MPInvolved, etc. When you submit a request, the data you specify for each element represents the search criteria you want to use. For example, if you want to search for all issues within a certain date range that are in a particular status, you would need to specify values for the DateRangeName element and the IssueStatus element.

To understand the format of each of these data types, look for their definitions in the XSD document.

To see an example of a request, see the section titled Example Payload: Query List Request on page 24.

Response

In response to a valid request, the Query List service sends a reponse that conforms to the IssueQueryResponse data type. The XSD document defines IssueQueryResponse as follows:

XSD Snippet: Definition of IssueQueryResponse

<complexType name="IssueQueryResponse">
  <complexContent>
    <extension base = "TTISSUE:QueryType">
      <sequence>
         <element ref="TTISSUE:IssueNumber" minOccurs="0" 
                  maxOccurs="unbounded"/>
         <element ref="TTISSUE:Response"/>
      </sequence>
     </extension>
  </complexContent>
</complexType>

You can see above that the IssueQueryResponse data type extends QueryType. It extends the data type by adding 2 elements: the IssueNumber element and the Response element. This means that your application should expect a response that contains the following elements, in this sequence:

• QueryType

• IssueNumber

• Response

You can see the definitions of QueryType and Issue Number in the XSD document. Let’s take a closer look at the Response element.

The XSD defines the last element, Response, as being of type ResponseType. The following snippet shows the definition in the XSD document.

XSD Snippet: Definition of ResponseType

<complexType name="ResponseType">
  <sequence>
   <element ref="TTISSUE:ResponseStatus"/>
   <element ref="TTISSUE:ResponseDateTime"/>
   <element ref="TTISSUE:Error" minOccurs = "0"/>
   <element ref="TTISSUE:WarningDescription" minOccurs="0"/>
  </sequence>
 </complexType>

The above snippet shows that the ResponseType comprises 4 elements: ResponseStatus, ResponseDateTime, Error, and WarningDescription.

This means that when your application receives a response from the Query List service, it must be able to process all of these elements. When you put these elements together with QueryType and IssueNumber, you get a response that can contain (in this order):

• QueryType

• IssueNumber

• ResponseStatus

• ResponseDateTime

• Error

• WarningDescription

To see an example of what this response looks like, see the section titled Example Payload: Query List Response on page 25.

4.1.3. Description of a Query List Request Message

Your query to the Query List service should consist of a well-formed XML payload, contained in a properly formatted request message. Every request message should contain:

• a header

• an xml payload

The following is an example of a message header sent to the MarkeTrak application.

Example Header: Query List Request

/POST / HTTP/1.1
soapaction: "/BusinessService/WS/TeamTrack/External/TeamTrackExternal.serviceagent/OperationsEndpoint1/QueryList"
Host: misapi.ercot.com:443/marketrakAPI
content-type: text/xml; charset=utf-8
Content-length: 832
Expect: 100-continue

Definition of Fields in a Request Header

Field Name	Data Description	Data Type
soapaction	The action the market participant wishes to perform (example: QueryList)	Character
Host	Name of the ERCOT host, including the port; can be either an IP address or DNS listed name.	Character
Content-type	Indicates the media type of the message body. Query List requests should be sent as text/xml; charset=utf-8 or charset=utf-16	Character
Content-length	Indicate the size of the message body in decimal number of OCTETs. Any Content-Length greater than or equal to zero is valid.	Character
Expect	Indicates the server behaviors required by the client. The server responds with a 417 (Expectation Failed) status if the server cannot meet all expectations. If there are other problems with the request, the server returns a error status based on the other problem. Query List requests can be sent with 100-continue. The purpose of the 100-continue status is to allow a client that is sending a request message with a request body to determine if the origin server is willing to accept the request (based on the request headers) before the client sends the request body.	Character

Query List Request Message Payload

The following is an example of the XML payload of a message (created by a market participant) to query the MarkeTrak application.

Example Payload: Query List Request

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope 
   xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <IssueQueryRequest app=”MarkeTrak”
       xmlns="http://www.ercot.com/schema/retail/2006-01">
         <DateRangeName name=”LastModified”>
            <FromDateTime>2008-04-13T11:41:07</FromDateTime>
            <ToDateTime>2008-04-13T12:42:07</ToDateTime>
         </DateRangeName>
         <IssueType>IssueD2D</IssueType>
         <IssueSubType>CancelWA</IssueSubType>
      </IssueQueryRequest>
   </soap:Body>
</soap:Envelope>

In the above example, the search criteria includes DateRangeName, IssueType, and IssueSubType. Based on the criteria in the example, we would expect the response to contain a list of all issues that were:

• last modified between April 13, 2008 at 11:41:07 and April 13, 2008 at 12:42:07

• are Issues of Type D2D (Day-to-day), and

• are SubType CancelWA (Cancel with approval)

NOTE: To understand the business definition of these fields, see the Marketrak Users Guide.

4.1.4. Description of a Query List Response Message

The response message from the Query List service is made up of:

• a header

• an XML payload

The header information is similar to the HTTP header information of the request. The part of the message that you need to process is in the XML payload.

When your application receives a response from the Query List service, it must be able to process all of the elements in the XML payload. The XSD document defines the elements that are valid in the payload. In this case, the IssueQueryResponse data type defines the payload for a Query List response. At the time of this writing, the elements of this response are (in this order):

• QueryType

• IssueNumber

• ResponseStatus

• ResponseDateTime

• Error

• WarningDescription

Example Payload: Query List Response

<?xml version="1.0" encoding="UTF-8" ?> 
<ns0:IssueQueryResponse 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
   xmlns:jms1="http://www.tibco.com/namespaces/tnt/plugins/jms" 
   xmlns:ns0="http://www.ercot.com/schema/retail/2006-01" 
   app="MarkeTrak">
      <ns0:IssueType>DEV-Char</ns0:IssueType> 
      <ns0:IssueNumber>6178</ns0:IssueNumber> 
      <ns0:IssueNumber>6182</ns0:IssueNumber> 
      <ns0:IssueNumber>6188</ns0:IssueNumber> 
      <ns0:IssueNumber>6189</ns0:IssueNumber> 
      <ns0:IssueNumber>6190</ns0:IssueNumber> 
      <ns0:Response>
         <ns0:ResponseStatus>SUCCESS</ns0:ResponseStatus> 
         <ns0:ResponseDateTime>2006-06-01T21:30:20.281-05:00
         </ns0:ResponseDateTime> 
      </ns0:Response>
</ns0:IssueQueryResponse>

In the example above, the response lists 5 issues of type DEV-Char. The issue numbers are: 6178, 6182, 6188, 6189, and 6190.

The Response element shows that the response completed successfully at 21:30:20.281 on June 1, 2006. There was no error nor any warning associated with this response.

IMPORTANT: Refer to the latest published XSD document to make sure that you know the current elements of a Query List response.

4.1.5. Hints and Tips on Implementing a Query List Client

Once you understand how to create a request message and how to handle the response, you might still ask yourself, “But how do I use the Query List service in my application?”

The reason to use the service is to obtain a list of issues that meet certain search criteria. For most market participants, the point of obtaining that list is to be aware of issues that have changed since the last QueryList request, to know if an issue requires action.

We suggest that you submit regular requests (perhaps every 15 minutes or so) to the Query List service based on the following criteria:

• DateRangeName

• LastModified

The idea is to regularly query the service with search criteria that results in a list of recently modified issues. Let’s say that you want to query MarkeTrak every 15 minutes. You should query for issues that have been modified since the last response from MarkeTrak.

Use the time of the last response minus some kind of short time period to act as a buffer. You could use 5 seconds or 10 seconds as a buffer. For this is example, let’s use 1 minute.

In other words, your criteria would look something like this:

FromDateTime = (time of last QueryList response) – (1 minute)

For example, if the last response time was exactly 9:00 am on February 14, 2008, the date range you would specify would be:

<DateRangeName name=”LastModified”>
  <FromDateTime>2008-02-14T08:59:00</FromDateTime>
</DateRangeName>

The above example would return any issues that have been modified since 08:59.

Let’s suppose that you made this initial request at 11:00 am. And suppose that the response came back with a response time of 11:05.

If your application performs the next query in 15 minutes (to request issues that were modified in that 15 minute block), the date range would again be from the last response time less 1 minute. In this case, the response time was 11:05, so the FromDateTime would be 11:04:

<DateRangeName name=”LastModified”>
  <FromDateTime>2008-02-14T11:04:00</FromDateTime>
</DateRangeName>

There are many ways to implement this logic in your application. But the general idea is to have regular occurring queries that cover the time period since the last query.

Keep in mind that MarkeTrak returns only those issues that you have permissions to see.

Note that MarkeTrak treats a blank field as a wildcard for that field. For example, if you don’t specify an IssueState, MarkeTrak considers the query to be for all states. The response will include issues in all states.

We recommend that when you make a request that specifies IssueSubType, that you also specify IssueType. MarkeTrak does not require that both fields be specified together, but because empty fields are considered wildcards, specifying IssueType in conjunction with IssueSubType helps narrow your query results.

4.2. Using the Query Detail Service

This section describes the Query Detail service, and covers:

• Purpose of the service

• Definition in the API

• Description of a request message

• Description of a response message

• Hints and Tips on Implementation

4.2.1. Purpose of the Query Detail Service

The Query Detail service returns all information related to a specific MarkeTrak issue number.

4.2.2. Definition in the API

Request

The Query Detail service expects the XML payload of a request to conform to the IssueQueryDetailsRequest data type. The following snippet shows the definition in the XSD document.

XSD Snippet: Definition of IssueQueryDetailsRequest

<element name="IssueQueryDetailsRequest">
   <complexType>
      <sequence>
         <element ref="TTISSUE:IssueNumber"/>
      </sequence>
   </complexType>
</element>

NOTE: The above snippet is an example. Please refer to the latest XSD document for current definitions.

As you can see in the snippet, the IssueQueryDetailsRequest contains one element: IssueNumber. You can see an example of what the XML payload might look like in the section titled Example Payload: Query Detail Request on page 30.

Response

In response to a valid request, the Query Detail service sends a response that conforms to the IssueQueryDetailsResponse element.

The XSD document defines IssueQueryDetailsResponse as shown in the following snippet.

XSD Snippet: Definition of IssueQueryDetailsResponse

<element name="IssueQueryDetailsResponse">
    <complexType>
      <sequence>
        <element ref="TTISSUE:IssueResponse" minOccurs = "0"/>
        <element ref="TTISSUE:Response"/>
      </sequence>
    </complexType>
</element>

IMPORTANT: The above snippet is an example. Please refer to the latest XSD document for current definitions.

You can see above that the IssueQueryDetailsResponse element contains two elements:

• IssueResponse

• Response

This means that your application should expect a response that contains these two elements, in that order. Seeing as the response contains the details of an issue, you would expect quite a bit of data to be contained in those two elements. Let’s first take a look at the IssueResponse element.

In the XSD document, the IssueResponse element is defined as being a data type called QueryResponseIssueType. You can see the definition of this data type in the following XSD snippet.

XSD Snippet: Definition of QueryResponseIssueType

<complexType name="QueryResponseIssueType">
  <complexContent>
   <extension base = "TTISSUE:ResponseIssueType">
    <sequence>
     <element ref="TTISSUE:IssueNumber"/>
     <element ref="TTISSUE:SubmitDateTime"/>
     <element ref="TTISSUE:SubmitSource"/>
     <element ref="TTISSUE:Title"/>
     <element ref="TTISSUE:MPInvolved" minOccurs = "0" maxOccurs = "50"/>
     <element ref="TTISSUE:IssueState" minOccurs="0"/>
     <element ref="TTISSUE:MPOwner" minOccurs="0" maxOccurs="6"/>
     <element ref="TTISSUE:MPGroupName" minOccurs="0" maxOccurs="6"/>
     <element ref="TTISSUE:MPGroupNumber" minOccurs="0" maxOccurs="6"/>
     <element ref="TTISSUE:Submitter"/>
     <element ref="TTISSUE:LastModified" minOccurs="0"/>
     <element ref="TTISSUE:LastModifier" minOccurs="0"/>
     <element ref="TTISSUE:LastStateChangeDate" minOccurs="0"/>
     <element ref="TTISSUE:LastStateChanger" minOccurs="0"/>
     <element ref="TTISSUE:ResponsibleMP" minOccurs="0"/>
     <element ref="TTISSUE:CloseDateTime" minOccurs="0"/>
     <element ref="TTISSUE:Comments" minOccurs="0" maxOccurs="unbounded"/>
     <element ref="TTISSUE:IssueAvailableDate"/>
     <element ref="TTISSUE:ParentIssueNumber" minOccurs="0"/>
     <element ref="TTISSUE:FirstTouched" minOccurs = "0"/>
     <element ref="TTISSUE:FileAttachments" minOccurs = "0" 
              maxOccurs="unbounded" />
     <element ref="TTISSUE:URLAttachments" minOccurs = "0" 
              maxOccurs="unbounded" />
     <element ref="TTISSUE:LinkedIssues" minOccurs = "0" 
              maxOccurs="unbounded" />
     <element ref="TTISSUE:NoteAttachments" minOccurs = "0" 
              maxOccurs="unbounded" />    
    </sequence> 
    <attribute name="app" type = "NCName"/>
   </extension>
  </complexContent>
</complexType>

The XSD snippet above shows the elements (the details) you would expect to be associated with an issue, such as IssueNumber, SubmitDateTime, SubmitSource, Title, MPInvolved, etc.

Several of these elements have further nested sub-elements. To understand all the fields that are returned in a Query Details response, you need to drill down through the definition of each of the data types in the XSD document. Your development suite probably provides a way to programatically read the XSD document and generate the stubs you need to handle each possible data field in the response.

As mentioned above, the IssueQueryDetailsResponse element contains two elements:

• IssueResponse

• Response

Let’s look at the Response element. The XSD document defines the Response element as being a ResponseType data type. The following snippet shows the definition of ResponseType.

XSD Snippet: Definition of ResponseType

<complexType name="ResponseType">
   <sequence>
      <element ref="TTISSUE:ResponseStatus"/>
      <element ref="TTISSUE:ResponseDateTime"/>
      <element ref="TTISSUE:Error" minOccurs = "0"/>
      <element ref="TTISSUE:WarningDescription" minOccurs="0"/>
   </sequence>
</complexType>

As you can see above, at the time of this writing, the elements of this part of the response are (in this order):

• ResponseStatus

• ResponseDateTime

• Error

• WarningDescription

Your application must handle the above elements in addition to the long list of elements in the IssueResponse portion of the response.

You can see an example of a Query Detail response in the section titled Example Payload: Query Detail Response on page 30.

4.2.3. Description of a Query Detail Request Message

Market participants send a request message to ERCOT based on the web service information defined by the programmatic interface (XSD and WSDL file). Every request message contains:

• a header

• one xml payload

Query Detail Request Message Header

The following is an example of the header of a message (created by a market participant) to query the MarkeTrak application.

Example Header: Query Detail Request

/POST / HTTP/1.1
soapaction: "/BusinessService/WS/TeamTrack/External/TeamTrackExternal.serviceagent/OperationsEndpoint1/QueryDetail"
Host: misapi.ercot.com:443/marketrakAPI
content-type: text/xml; charset=utf-8
Content-length: 112
Expect: 100-continue

Definition of Fields in a Query Detail Request Header

Field Name	Data Description	Data Type
soapaction	The action the market participant wishes to perform (Example: QueryDetail)	Character
Host	Name of the ERCOT host, including the port; can be either an IP address or DNS listed name.	Character
Content-type	Indicates the media type of the message body. Query List requests should be sent as text/xml; charset=utf-8 or charset=utf-16	Character
Content-length	Indicate the size of the message body in decimal number of OCTETs. Any Content-Length greater than or equal to zero is valid.	Character
Expect	Indicates the server behaviors required by the client. The server responds with a 417 (Expectation Failed) status if the server cannot meet all expectations. If there are other problems with the request, the server returns a error status based on the other problem. Query List requests can be sent with 100-continue. The purpose of the 100-continue status is to allow a client that is sending a request message with a request body to determine if the origin server is willing to accept the request (based on the request headers) before the client sends the request body.	Character

Query Detail Request Message Payload

The following is an example of the XML payload of a message, sent by a market participant to request issue detail from the MarkeTrak application. In the following example, the market participant sends a query on issue number 6113.

Example Payload: Query Detail Request

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope 
   xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <IssueQueryDetailsRequest 
         xmlns="http://www.ercot.com/schema/retail/2006-01">
         <IssueNumber>6113</IssueNumber>
      </IssueQueryDetailsRequest>
   </soap:Body>
</soap:Envelope>

Definition of elements in a Query Detail Request Payload

Element	Data Description	Data Type
IssueQueryDetailsRequest	Contains the IssueNumber element.	n/a
IssueNumber	The issue ID being queried. Maximum length is 16 characters.	Character

4.2.4. Description of a Query Detail Response Message

As with other services, the response message from the Query Detail service is made up of

• a header

• an XML payload

Your application needs to be able to process all the elements of the XML payload of the response from the Query Detail service.

In this case, the IssueQueryDetailsResponse data type defines the payload you should expect to receive in a Query Detail response. There are many elements (data fields) returned in this response.

At the time of this writing, some of these elements are:

• IssueType

• IssueSubType

• Depending on the Subtype:ResponseDateTime, Assignee, EsiID, etc.

• SiebelStatus, SiebelSubStatus

• IssueNumber

• etc.

There are too many elements in the response to list here. Refer to the XSD document to learn about all the data fields that your application must handle in the response. The following example shows the response to a query for a missing transaction issue.

Example Payload: Query Detail Response

<?xml version="1.0" encoding="UTF-8" ?> 
<ns0:IssueQueryDetailsResponse 
     xmlns:ns0="http://www.ercot.com/schema/retail/2006-01">
  <ns0:IssueResponse ns0:app="MarkeTrak">
     <ns0:IssueD2DResponse>
       <ns0:SubTypeD2DResponse>
         <ns0:MissTrxn>
            <ns0:Assignee>183999333</ns0:Assignee> 
            <ns0:EsiID>123456789</ns0:EsiID> 
            <ns0:OrigTrxnID>123456789</ns0:OrigTrxnID> 
            <ns0:TrxnType>814_01</ns0:TrxnType> 
         </ns0:MissTrxn>
       </ns0:SubTypeD2DResponse>
       <ns0:SiebelStatus /> 
       <ns0:SiebelSubStatus /> 
     </ns0:IssueD2DResponse>
     <ns0:IssueNumber>6113</ns0:IssueNumber> 
     <ns0:SubmitDateTime>2006-05-25T14:42:44</ns0:SubmitDateTime> 
     <ns0:SubmitSource>api</ns0:SubmitSource> 
     <ns0:Title>D2D Test</ns0:Title> 
     <ns0:MPInvolved 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
          xmlns:jms1="http://www.tibco.com/namespaces/tnt/plugins/jms" 
          xmlns:ns0="http://www.ercot.com/schema/retail/2006-01" 
          ns0:role="ERCOT">
        <ns0:Duns>123456789</ns0:Duns> 
     </ns0:MPInvolved>
     <ns0:MPInvolved 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
          xmlns:jms1="http://www.tibco.com/namespaces/tnt/plugins/jms" 
          xmlns:ns0="http://www.ercot.com/schema/retail/2006-01" 
          ns0:role="Submitter">
        <ns0:Duns>987654321</ns0:Duns> 
     </ns0:MPInvolved>
     <ns0:MPInvolved 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
          xmlns:jms1="http://www.tibco.com/namespaces/tnt/plugins/jms" 
          xmlns:ns0="http://www.ercot.com/schema/retail/2006-01" 
          ns0:role="Assignee">
        <ns0:Duns>123456789</ns0:Duns> 
     </ns0:MPInvolved>
     <ns0:MPInvolved 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
          xmlns:jms1="http://www.tibco.com/namespaces/tnt/plugins/jms" 
          xmlns:ns0="http://www.ercot.com/schema/retail/2006-01" 
          ns0:role="PriorInvolved">
         <ns0:Duns>123456789</ns0:Duns> 
     </ns0:MPInvolved>
     <ns0:MPInvolved 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
          xmlns:jms1="http://www.tibco.com/namespaces/tnt/plugins/jms" 
          xmlns:ns0="http://www.ercot.com/schema/retail/2006-01" 
          ns0:role="PriorInvolved">
        <ns0:Duns>987654321</ns0:Duns> 
     </ns0:MPInvolved>
     <ns0:IssueState>New</ns0:IssueState> 
     <ns0:MPOwner 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
          xmlns:jms1="http://www.tibco.com/namespaces/tnt/plugins/jms" 
          xmlns:ns0="http://www.ercot.com/schema/retail/2006-01" 
          ns0:role="Submitter">
        <ns0:UserID>987654321$JWilson</ns0:UserID> 
     </ns0:MPOwner>
     <ns0:Submitter /> 
     <ns0:LastModified>2006-05-25T14:42:46</ns0:LastModified> 
     <ns0:LastModifier>987654321$MarkeTrakAPI</ns0:LastModifier> 
     <ns0:LastStateChangeDate>2006-05-25T14:42:44
     </ns0:LastStateChangeDate> 
     <ns0:LastStateChanger>987654321$MarkeTrakAPI</ns0:LastStateChanger> 
     <ns0:ResponsibleMP>188899999</ns0:ResponsibleMP> 
     <ns0:Comments 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
          xmlns:jms1="http://www.tibco.com/namespaces/tnt/plugins/jms" 
          xmlns:ns0="http://www.ercot.com/schema/retail/2006-01">
        <ns0:UserName>John Smith</ns0:UserName> 
        <ns0:DateTime>2006-05-25T14:42:45</ns0:DateTime> 
        <ns0:CommentsText>This is a TEST comment.</ns0:CommentsText> 
     </ns0:Comments>
     <ns0:AttachmentExists>true</ns0:AttachmentExists> 
  </ns0:IssueResponse>
  <ns0:Response 
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
     xmlns:jms1="http://www.tibco.com/namespaces/tnt/plugins/jms" 
     xmlns:ns0="http://www.ercot.com/schema/retail/2006-01">
     <ns0:ResponseStatus>SUCCESS</ns0:ResponseStatus> 
     <ns0:ResponseDateTime>2006-05-25T14:42:55.205-05:00
     </ns0:ResponseDateTime> 
  </ns0:Response>
</ns0:IssueQueryDetailsResponse>

4.2.5. Hints and Tips on Implementing the Query Detail Client

The reason to use the service is to obtain the details of an issue. For most market participants, the request for details comes as a result of having received a list of issue numbers from the Query List service. For that reason, you most likely want to use the response from a Query List in conjunction with a request to the Query Detail service.

In other words, when you receive a list of issues that have been modified, you should send a request to the Query Details service for each of those issues. This will keep the data in your database in sync with the MarkeTrak database.

4.3. Using the Query File Attachment service

This section describes the Issue File Attachment service, and covers:

• Purpose of the service

• Definition in the API

• Description of a request message

• Description of a response message

• Hints and Tips on Implementation

4.3.1. Purpose of the Query File Attachment Service

The Query File Attachment service allows market participants to retrieve and download attachments to MarkeTrak issues via the API. Typically, a Query File Attachment call is preceded by a Query Detail call to first retrieve the file attachment number for a specific MarkeTrak issue.

4.3.2. Definition in the API

Request

The Query File Attachment service expects the XML payload of a request to conform to the IssueFileAttachmentRequest data type. The following snippet from the XSD document shows the definition.

XSD Snippet: Definition of IssueFileAttachmentRequest

<complexType name="IssueFileAttachmentRequest">
  <sequence>
      <element ref="TTISSUE:IssueNumber"/>
      <element ref="TTISSUE:FileAttachmentNumber"/>
  </sequence>
  <attribute name="app" type="xsd:NCName"/>
</complexType>

You can see in the XSD snippet that IssueQueryRequest contains two elements: IssueNumber and FileAttachmentNumber.

To understand the format of each of these data types, look for their definitions in the XSD document.

To see an example of a request, see the section titled Example Payload: Query File Attacment Request.

Response

In response to a valid request, the Query File Attachment service sends a response that conforms to the IssueFileAttachmentResponse data type. The XSD document defines IssueFileAttachmentResponse as follows:

XSD Snippet: Definition of IssueFileAttachmentResponse

<complexType name="IssueFileAttachmentResponse">
  <complexContent>
    <extension base="TTISSUE:FileAttachmentResponseType">
      <sequence>
        <element ref="TTISSUE:IssueNumber"/>
        <element ref="TTISSUE:Response"/>
      </sequence>
      <attribute name="app" type="xsd:NCName"/>
    </extension>
  </complexContent>
</complexType>

You can see above that the IssueFileAttachmentResponse data type extends FileAttachmentResponseType. It extends this data type by adding 2 elements: the IssueNumber element and the Response element. This means that your application should expect a response that contains the following elements, in this sequence:

• FileAttachmentResponseType

• IssueNumber

• Response

You can see the definitions of these elements in the XSD document. Let’s take a closer look at the FileAttachmentResponseType element.

XSD Snippet: Definition of FileAttachmentResponseType

<complexType name="FileAttachmentResponseType">
  <sequence>
    <element ref="TTISSUE:DateTime"/>
    <element ref="TTISSUE:FileTitle" minOccurs="0"/>
    <element ref="TTISSUE:FileName"/>
    <element ref="TTISSUE:FileAttachmentNumber"/>
    <element ref="TTISSUE:Base64FileContents" minOccurs="0"/>
  </sequence>
</complexType>

The above snippet shows that the FileAttachmentResponseType comprises 5 elements: DateTime, FileTitle, FileName, and Base64FileContents.

Your application must handle the above elements in addition to the IssueNumber element and the elements included in the Response element.

To see an example of what this response looks like, see the section titled Example Payload: Query File Attachment Response on page 36.

4.3.3. Description of a Query File Attachment Request Message

Your query to the Query File Attachment service should consist of a well-formed XML payload, contained in a properly formatted request message. Every request message should contain:

• a header

• an xml payload

The following is an example of a message header sent to the MarkeTrak application.

Example Header: Query File Attachment Request

/POST / HTTP/1.1
soapaction: "/BusinessService/WS/TeamTrack/External/TeamTrackExternal.serviceagent/OperationsEndpoint1/QueryFileAttachment"
Host: misapi.ercot.com:443/marketrakAPI
content-type: text/xml; charset=utf-8
Content-length: 832
Expect: 100-continue

Definition of Fields in a Request Header

Field Name	Data Description	Data Type
soapaction	The action the market participant wishes to perform (example: QueryFileAttachment)	Character
Host	Name of the ERCOT host, including the port; can be either an IP address or DNS listed name.	Character
Content-type	Indicates the media type of the message body. QueryFileAttachment requests should be sent as text/xml; charset=utf-8 or charset=utf-16	Character
Content-length	Indicate the size of the message body in decimal number of OCTETs. Any Content-Length greater than or equal to zero is valid.	Character
Expect	Indicates the server behaviors required by the client. The server responds with a 417 (Expectation Failed) status if the server cannot meet all expectations. If there are other problems with the request, the server returns a error status based on the other problem. Query List requests can be sent with 100-continue. The purpose of the 100-continue status is to allow a client that is sending a request message with a request body to determine if the origin server is willing to accept the request (based on the request headers) before the client sends the request body.	Character

Query File Attachment Request Message Payload

The following is an example of the XML payload of a message (created by a market participant) to query the MarkeTrak application.

Example Payload: Query File Attachment Request

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope 
   xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Body>
      <IssueFileAttachmentRequest app=”MarkeTrak” xmlns="http://www.ercot.com/schema/retail/2006-01">
         <IssueNumber>2007809</IssueNumber>
         <FileAttachmentNumber>306766</FileAttachmentNumber>
      </IssueFileAttachmentRequest>
   </soap:Body>
</soap:Envelope>

In the above example, the search criteria includes IssueNumber and FileAttachmentNumber. Based on the criteria in the example, we would expect the response to return information about file attachment 306766 that is attached to the MarkeTrak issue 2007809.

4.3.4. Description of a Query File Attachment Response Message

The response message from the Query File Attachment service is made up of:

• a header

• an XML payload

The header information is similar to the HTTP header information of the request. The part of the message that you need to process is in the XML payload.

When your application receives a response from the Query File Attachment service, it must be able to process all of the elements in the XML payload. The XSD document defines the elements that are valid in the payload. In this case, the IssueFileAttachmentResponse data type defines the payload for a Query File Attachment response. At the time of this writing, the elements of this response are (in this order):

• DateTime

• FileTitle

• FileName

• FileAttachmentNumber

• Base64FileContents

• IssueNumber

• ResponseStatus

• ResponseDateTime

• Error

• WarningDescription

Example Payload: Query File Attachment Response

<?xml version="1.0" encoding="UTF-8" ?> 
<ns0:IssueFileAttachmentResponse 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
   xmlns:jms1="http://www.tibco.com/namespaces/tnt/plugins/jms" 
   xmlns:ns0="http://www.ercot.com/schema/retail/2006-01" 
   app="MarkeTrak">
      <ns0:DateTime>2017-04-11T11:09:08-05:00</ns0:DateTime>
      <ns0:FileTitle>test.jpg</ns0:FileTitle>
      <ns0:FileName>test.jpg</ns0:FileName>
      <ns0:FileAttachmentNumber>494693</ns0:FileAttachmentNumber>
      <ns0:Base64FileContents>dGVzdA==</ns0:Base64FileContents>
      <ns0:IssueNumber>2604968</ns0:IssueNumber>
      <ns0:Response>
        <ns0:ResponseStatus>SUCCESS</ns0:ResponseStatus>
        <ns0:ResponseDateTime>2017-05-31T13:49:52.651-05:00</ns0:ResponseDateTime>
      </ns0:Response>
</ns0:IssueFileAttachmentResponse>

The Response element shows that the response completed successfully at 13:49:52 on May 31, 2017. There was no error nor any warning associated with this response.

IMPORTANT: Refer to the latest published XSD document to make sure that you know the current elements of a Query File Attachment response.

4.3.5. Hints and Tips on Implementing a Query File Attachment Client

The reason to use the Query File Attachment service is to download attachments from an issue. Typically, a Query List is initially performed to query for issues that meet a set of criteria. Then for each issue number returned in the Query List response, a Query Detail request is performed to get specific information about that particular issue. At this point if an issue contains an attachment, a Query File Attachment request would be performed using the attachment number returned in the Query Detail response and the issue number used in the Query Detail request. If the Query File Attachment request is successful, the attachment contents will be returned in the Query File Attachment response in the Base64FileContents element as a base 64 encoded string. Finally, you can use a base 64 decoding tool to decode the contents of this element and view the file attachment in its original state.

4.4. Using the Update Service

This section describes the Update service, and covers:

• Purpose of the service

• Definition in the API

• Description of a request message

• Description of a response message

• Hints and Tips on Implementation

4.4.1. Purpose of the Update Service

The Update service allows market participants to update (or transition from one state to another) a specific issue in the MarkeTrak system.

4.4.2. Definition in the API

Request

The Update service expects the XML payload of a request to conform to the IssueUpdateRequest data type. The following snippet from the XSD document shows the definition.

XSD Snippet: Definition of IssueUpdateRequest

<complexType name="IssueUpdateRequest">
  <complexContent>
    <extension base = "TTISSUE:UpdateRequestIssueType">
      <sequence>
        <element ref="TTISSUE:IssueNumber"/>
        <element ref="TTISSUE:NewOwner" minOccurs = "0"/>
        <element ref="TTISSUE:GroupName" minOccurs = "0"/>
        <element ref="TTISSUE:GroupNumber" minOccurs = "0"/>
      </sequence>
    </extension>
  </complexContent>
</complexType>

IMPORTANT: The above snippet is an example. Please refer to the latest XSD document for current definitions.

As you can see in the above XSD snippet, the IssueUpdateRequest extends the UpdateRequestIssueType element by adding 4 elements:

• IssueNumber

• NewOwner

• GroupName

• GroupNumber

To understand the format of each of these elements, look for their definitions in the XSD document. For example, if you search for NewOwner in the XSD document, you can see that it is defined as the data type IDDef. The following snippet shows this definition.

XSD Snippet: Definition of NewOwner element

<element name="NewOwner" type="TTISSUE:IDDef"/>

Looking further in the XSD document, you can see that the valid value for IDDef is a string of maximum 64 characters. The following snippet shows the definition in the XSD document:

XSD Snippet: IDDef data type

<simpleType name="IDDef">
  <restriction base="string">
    <maxLength value="64"/>
  </restriction>
</simpleType>

It is likely that the development tool that you use will automatically read these data type from the schema, and provide the stubs in your source code that represent these data types.

To see an example of what the XML payload of an Update request looks like, see the section titled Example Payload: Update Request on page 37.

Response

In response to a valid request, the Update service sends a response that conforms to the IssueUpdateResponse element.

The XSD document defines IssueUpdateResponse as shown in the following snippet.

XSD Snippet: Definition of IssueUpdateResponse

<complexType name="IssueUpdateResponse">
  <complexContent>
    <extension base="TTISSUE:ResponseType">
      <sequence>
        <element ref="TTISSUE:IssueNumber" minOccurs="0"/>
      </sequence>
    </extension>
  </complexContent>
</complexType>

IMPORTANT: The above snippet is an example. Please refer to the latest XSD document for current definitions.

You can see above that the IssueUpdateResponse element extends the ResponseType element by adding one element: IssueNumber.

To better understand the elements in the response, let’s take a closer look at the ResponseType data type. The following snippet from the XSD document shows the definition.

XSD Snippet: Definition of ResponseType

<complexType name="ResponseType">
  <sequence>
    <element ref="TTISSUE:ResponseStatus"/>
    <element ref="TTISSUE:ResponseDateTime"/>
    <element ref="TTISSUE:Error" minOccurs = "0"/>
    <element ref="TTISSUE:WarningDescription" minOccurs="0"/>
  </sequence>
</complexType>

The above snippet shows that the ResponseType comprises 4 elements: ResponseStatus, ResponseDateTime, Error, and WarningDescription.

This means that when your application receives a response from the Update service, it must be able to process all of these elements. When you put these elements together with IssueNumber, you get a response that can contain (in this order):

• ResponseStatus

• ResponseDateTime

• Error

• WarningDescription

• IssueNumber

To see an example of what this response looks like, see the section titled Example Payload: Update Response on page 42.

4.4.3. Description of an Update Request Message

Market participants send a request message to ERCOT based on the web service information defined by the programmatic interface (XSD and WSDL file). Every request message contains:

• a header

• an xml payload

Update Request Message Header

The following is an example of the header of a message (created by a market participant) to query the MarkeTrak application.

Example Header: Update Request

/POST / HTTP/1.1
soapaction:"/BusinessService/WS/TeamTrack/External/TeamTrackExternal.serviceagent/OperationsEndpoint1/Update"
Host: misapi.ercot.com:443/marketrakAPI
content-type: text/xml; charset=utf-8
Content-length: 832
Expect: 100-continue

Definition of Fields in an Update Request Header

Field Name	Data Description	Data Type
soapaction	The action which a market participant wishes to perform (e.g., QueryList, QueryDetail, Update, or Submit)	Character
Host	Name of the ERCOT host, including the port; can be either an IP address or DNS listed name.	Character
Content-type	Indicates the media type of the message body. Requests should be sent as text/xml; charset=utf-8	Character
Content-length	Indicate the size of the message body in decimal number of OCTETs. Any Content-Length greater than or equal to zero is valid.	Character
Expect	Indicates the server behaviors required by the client. The server responds with a 417 (Expectation Failed) status if the server cannot meet all expectations. If there are other problems with the request, the server returns a error status based on the other problem. Requests can be sent with 100-continue. The purpose of the 100-continue status is to allow a client that is sending a request message with a request body to determine if the origin server is willing to accept the request (based on the request headers) before the client sends the request body.	Character

Update Request Message Payload

The following is an example of the XML payload of a message (created by a market participant) to send information to the Update service of the MarkeTrak application.

Example Payload: Update Request

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope 
   xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <IssueUpdateRequest 
      xmlns="http://www.ercot.com/schema/retail/2006-01"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.ercot.com/schema/retail/2006-01
      file:/C:/xsd/FasTrakIssue_rc4-6XSD">
      <UpdateIssue>
        <IssueUpdateD2D>
            <SubTypeUpdateD2D>
              <Assignee>777666555</Assignee>
            </SubTypeUpdateD2D>
        </IssueUpdateD2D>
      </UpdateIssue>
      <Transition>Re-Assign</Transition>
      <CommentsText>Test of the Re-Assign transition</CommentsText>
      <IssueNumber>2222</IssueNumber>
    </IssueUpdateRequest>
  </soap:Body>
</soap:Envelope>

In the above example, the market participant has requested that issue number 2222 re-assign the Assignee to the market participant with the DUNs number 777666555.

4.4.4. Description of an Update Response Message

The response message from the Update service is made up of:

• a header

• an XML payload

The part of the message that you need to process is in the XML payload.

When your application receives a response from the Update service, it must be able to process all of the elements in the XML payload. The XSD document defines the elements that are valid in the payload. In this case, the IssueUpdateResponse data type defines the payload for an Update response. At the time of this writing, the elements of this response are (in this order):

• ResponseStatus

• ResponseDateTime

• Error

• WarningDescription

• IssueNumber

Example Payload: Update Response

<?xml version="1.0" encoding="UTF-8"?>
<ns0:IssueUpdateResponse 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
  xmlns:jms1="http://www.tibco.com/namespaces/tnt/plugins/jms" 
  xmlns:ns0="http://www.ercot.com/schema/retail/2006-01">
  <ns0:ResponseStatus>SUCCESS</ns0:ResponseStatus>
  <ns0:ResponseDateTime>2006-06-13T13:27:49.387-05:00</ns0:ResponseDateTime>
  <ns0:IssueNumber>1111</ns0:IssueNumber>
</ns0:IssueUpdateResponse>

In the example above, the IssueUpdateResponse element shows that the response completed successfully at 13:27:49.387 on June 13, 2006. There was no error nor any warning associated with this response. The affected issue number was 1111.

IMPORTANT: Refer to the latest published XSD document to make sure that you know the current elements of an Update response.

4.4.5. Hints and Tips on Implementing the Update Service

The algorithm that creates a request message for the Update service is probably the most complex logic you will have to implement for your application. The reason that the logic is complex is that the required elements of the payload vary depending on the transition that is being requested. The transition being requested depends on:

• the Type/SubType of the issue,

• the current state of the issue, and

• the Responsible MP/MP Type

Your application needs to implement logic that determines the above information, and then properly forms a request based on that information.

To create a request for the Update service, your application may implement logic similar to the following:

1. Use the Query Detail service to get:

   a. the Type/SubType of the issue that is to be changed

   b. the current state of the issue

   c. the Responsible MP

2. Refer to workflow (States/Transitions) information to identify:

   a. the actionable transitions that are possible given the state of the issue

   b. the information that is required to accompany the transition

   c. the MP Type or Responsible MP who can perform the transition

For workflow (States/Transition/Fields) information, refer to the States_Transitions spreadsheets available in a zip file on the ERCOT web site:

http://www.ercot.com/services/client_svcs/mktrk_info/

1. Refer to the XSD document to populate the XML fields with properly formatted, and valid data

Example: Creating an Update Request

The best way to understand the steps for creating a request is to go through an example. Let’s say that you want to update issue number 2222. Your application might implement the logic outlined in the following steps to create that request.

Step 1: Perform a Query Detail Request

If you do not know the details of the issue, you might first perform a Query Detail request to find out the issue Type/SubType and the state of the issue. Let’s suppose that you perform the Query Detail request, and that the MarkeTrak response indicates:

Type = D2D (Day-to-day)

SubType = MissTrxn (Missing Transaction), and

IssueState = Pending Complete

(You can see an example of a Query Detail response in the section titled Example Payload: Query Detail Response on page 31.)

From the response, you can also identify the Responsible MP. Let’s say that the response shows that ResponsibleMP is 188899999. If you are the responsible MP, then you can take action.

But what actions are possible? The next step outlines how to identify the transitions that you can request.

Step 2: Refer to Workflow (States/Transitions) Information

ERCOT provides workflow information in several spreadsheets. You can find the spreadsheets on the ERCOT web site:

http://www.ercot.com/services/client_svcs/mktrk_info/

The spreadsheets contain tables that show the transitions that are possible for each state of an issue. Some transitions can be performed at any time. Some transitions can be performed at any time only by certain market participants. You need to refer to the appropriate spreadsheet based on the issue type. Then refer to the state of the issue to learn about which transitions are possible.

For example, knowing that issue number 2222 is of Type D2D and the SubType is MissTrxn and the IssueState is Pending Complete, you can find the transition information by looking at the appropriate spreadsheet.

In this example, we’d refer to the spreadsheet titled D2D-Other.xls. In that spreadsheet, there is a tab labeled D2D Overview. The following table shows a small portion of that spreadsheet.

State_Transition spreadsheet: D2D-Other.xls

You can see on the spreadsheet that Re-Assign is a valid transition for the Submitting MP from the state Pending Complete. Knowing that the Re-Assign transition is valid, the next step is to refer to the XSD document to learn how to properly format the request.

Step 3: Refer to XSD document

Refer to the XSD document to identify the valid values of the XML payload.

The following example payload shows a request for a Re-Assign transition for issue 2222, which is Type D2D and SubType MissTrxn. The example assumes that the IssueState equals Pending Complete. If the issue is not in that state, MarkeTrak will return a response with the ResponseStatus equal to FAIL.

Example Payload: Elements of Update Request for Re-Assign Transition

<UpdateIssue>
  <IssueUpdateD2D>
    <SubTypeUpdateD2D>
      <Assignee>777666555</Assignee>
    </SubTypeUpdateD2D>
  </IssueUpdateD2D>
</UpdateIssue>
<Transition>Re-Assign</Transition>
<CommentsText>Test of the Re-Assign transition</CommentsText>
<IssueNumber>2222</IssueNumber>

To summarize: the example payload above specifies data for the following elements:

• Assignee

• Transition

• CommentsText

• IssueNumber

These elements are required as specified in the workflow information you got from the States_Transitions spreadsheet, and the definition of UpdateIssue in the XSD document. A request for a transition for an issue of a different type and state might result in a different list of elements. You should go through the above steps to formulate the request for each Type/SubType/State/Transition combination.

Other Tips

Use the GUI version to verify that a transition makes sense. Or use the test environment to generate GUI test cases that walk through a specific workflow. You can then verify the results of the GUI workflow against your results from the API.

Implement one Subtype and test it before trying to write the logic for all possible transitions at once.

4.5. Using the Submit Service

This section describes the Submit service. This section covers:

• Purpose of the service

• Definition in the API

• Description of a request message

• Description of a response message

• Hints and Tips on Implementation

4.5.1. Purpose of the Submit Service

The Submit service allows market participants to create a new issue in the MarkeTrak system.

CRs might create a new issue for various reasons, such as:

• Question related to why an ESIID is not in the ERCOT system

• Question related to an inadvertent gain

• Question related to 997 reports

TSPDs might crete a new issue for various reasons, such as:

• Requests for cancellation of transactions

• Questions related to why a transaction was cancelled

• Questions related to who ERCOT shows as the Rep of Record in the ERCOT system

4.5.2. Definition in the API

Request

The Submit service expects the XML payload of a request to conform to the IssueSubmitRequest data type. The following XSD snippet shows the definition of this data type.

XSD Snippet: Definition of IssueSubmitRequest

<complexType name="IssueSubmitRequest">
  <complexContent>
    <extension base = "TTISSUE:IssueType">
    <sequence>
       <element ref="TTISSUE:Transition"/>
       <element ref="TTISSUE:AlternateUserID"/>
    </sequence>
    <attribute name="app" type = "NCName"/>
    </extension>
  </complexContent>
</complexType>

NOTE: The above snippet is an example. Please refer to the latest XSD document for current definitions.

You can see above that the IssueSubmitRequest data type extends IssueType by adding 2 elements: the Transition element and the AlternateUserID element.

This means that a valid request should contain the following elements, in this sequence:

• IssueType

• Transition

• AlternateUserID

To see an example of a request, see the section titled Example Payload: Submit Request on page 50.

Response

In response to a valid request, the Submit service sends a response that conforms to the IssueSubmitResponse data type.

The XSD document defines IssueSubmitResponse as shown in the following snippet.

XSD Snippet: Definition of IssueSubmitResponse

<complexType name="IssueSubmitResponse">
  <complexContent>
    <extension base="TTISSUE:ResponseType">
      <sequence>
        <element ref="TTISSUE:IssueNumber" minOccurs="0"/>
      </sequence>
    </extension>
  </complexContent>
</complexType>

IMPORTANT: The above snippet is an example. Please refer to the latest XSD document for current definitions.

You can see above that the IssueSubmitResponse element extends the ResponseType element by adding one element: IssueNumber.

To better understand the elements in the response, let’s take a closer look at the ResponseType data type. The following snippet from the XSD document shows the definition.

XSD Snippet: Definition of ResponseType

<complexType name="ResponseType">
  <sequence>
    <element ref="TTISSUE:ResponseStatus"/>
    <element ref="TTISSUE:ResponseDateTime"/>
    <element ref="TTISSUE:Error" minOccurs = "0"/>
    <element ref="TTISSUE:WarningDescription" minOccurs="0"/>
  </sequence>
</complexType>

The above snippet shows that the ResponseType comprises 4 elements: ResponseStatus, ResponseDateTime, Error, and WarningDescription.

This means that when your application receives a response from the Submit service, it must be able to process all of these elements. When you put these elements together with IssueNumber, you get a response that can contain (in this order):

• ResponseStatus

• ResponseDateTime

• Error

• WarningDescription

• IssueNumber

To see an example of a response to a successful request, see the section titled Example Payload: Submit Response Successful on page 51.

To see an example of a response to a failed request, see the section titled Example Payload: Submit Response Failure on page 51.

4.5.3. Description of a Submit Request Message

Your request to the Submit service should consist of a well-formed XML payload, contained in a properly formatted request message. Market participants send a request message to ERCOT based on the web service information defined by the programmatic interface (XSD and WSDL file). Every request message contains:

• a header

• an xml payload

Submit Request Message Header

The following is an example of the header of a message (created by a market participant) to query the MarkeTrak application.

Example Header: Submit Request

/POST / HTTP/1.1
soapaction:"/BusinessService/WS/TeamTrack/External/TeamTrackExternal.serviceagent/OperationsEndpoint1/Update"
Host: misapi.ercot.com:443/marketrakAPI
content-type: text/xml; charset=utf-8
Content-length: 832
Expect: 100-continue

Definition of Fields in a Submit Request Header

Field Name	Data Description	Data Type
soapaction	The action which a market participant wishes to perform (e.g., QueryList, QueryDetail, Update, or Submit)	Character
Host	Name of the ERCOT host, including the port; can be either an IP address or DNS listed name.	Character
Content-type	Indicates the media type of the message body. Requests should be sent as text/xml; charset=utf-8	Character
Content-length	Indicate the size of the message body in decimal number of OCTETs. Any Content-Length greater than or equal to zero is valid.	Character
Expect	Indicates the server behaviors required by the client. The server responds with a 417 (Expectation Failed) status if the server cannot meet all expectations. If there are other problems with the request, the server returns a error status based on the other problem. Requests can be sent with 100-continue. The purpose of the 100-continue status is to allow a client that is sending a request message with a request body to determine if the origin server is willing to accept the request (based on the request headers) before the client sends the request body.	Character

Submit Request Message Payload

The following is an example of the XML payload of a message (created by a market participant) to query the MarkeTrak application.

In the following example the market participant is creating an issue of Type D2D (Day-to-Day) and SubType CancelWoA (Cancel without approval).

Example Payload: Submit Request

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope 
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <IssueSubmitRequest 
      xmlns=http://www.ercot.com/schema/retail/2006-01
      xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
      xsi:schemaLocation="http://www.ercot.com/schema/retail/2006-01 file:
                          /C:/xsd/FasTrakIssue_rc4-6XSD">
      <IssueD2D>
        <SubTypeD2D>
          <CancelWoA>
            <EsiID>99999912345000</EsiID>
            <OrigTrxnID>2345678903</OrigTrxnID>
          </CancelWoA>
        </SubTypeD2D>
      </IssueD2D>
      <Transition>Create</Transition>
      <ValidateESIID>false</ValidateESIID>
      <CheckDuplicateESIID>false</CheckDuplicateESIID>
      <CheckDuplicateGlobalID>false</CheckDuplicateGlobalID>
    </IssueSubmitRequest>
  </soap:Body>
</soap:Envelope>

4.5.4. Description of a Submit Response Message

The response message from the Submit service is made up of:

• a header

• an XML payload

The part of the message that you need to process is in the XML payload.

When your application receives a response from the Submit service, it must be able to process all of the elements in the XML payload. The XSD document defines the elements that are valid in the payload. In this case, the IssueSubmitResponse data type defines the payload for a Query List response.

At the time of this writing, the possible elements of this response are (in this order):

• ResponseStatus

• ResponseDateTime

• Error

• WarningDescription

• IssueNumber

The following example shows a successful response. Because the response was successful there is no Error element nor any WarningDescription.

The issue was created as issue number 1234.

Example Payload: Submit Response Successful

<?xml version="1.0" encoding="UTF-8"?>
<ns0:IssueSubmitResponse 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
    xmlns:jms1="http://www.tibco.com/namespaces/tnt/plugins/jms" 
    xmlns:ns0="http://www.ercot.com/schema/retail/2006-01">
  <ns0:ResponseStatus>SUCCESS</ns0:ResponseStatus>
  <ns0:ResponseDateTime>2006-05-25T14:23:30.665-05:00</ns0:ResponseDateTime>
  <ns0:IssueNumber>1234</ns0:IssueNumber>
</ns0:IssueSubmitResponse>

The following example shows a response indicating that the request failed with the ErrorDescription:

Error invoking FasTrak adapter for submit issue request.

Example Payload: Submit Response Failure

<?xml version="1.0" encoding="UTF-8"?>
<ns0:IssueSubmitResponse 
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
     xmlns:jms1="http://www.tibco.com/namespaces/tnt/plugins/jms" 
     xmlns:ns0="http://www.ercot.com/schema/retail/2006-01">
  <ns0:ResponseStatus>FAIL</ns0:ResponseStatus>
  <ns0:ResponseDateTime>2006-06-08T14:18:21.019-05:00</ns0:ResponseDateTime>
  <ns0:Error>
    <ns0:ErrorCode>MT-SU-1002</ns0:ErrorCode>
    <ns0:ErrorDescription>Error invoking FasTrak adapter for submit issue request.</ns0:ErrorDescription>
    <ns0:ErrorDateTime>2006-06-08T14:18:20.926-05:00</ns0:ErrorDateTime>
  </ns0:Error>
</ns0:IssueSubmitResponse>

IMPORTANT: Refer to the latest published XSD document to make sure that you know the current elements of the Submit response.

In the above example there is no issue number because the Submit service failed to create the issue.

4.5.5. Hints and Tips on Implementing the Submit Client

The important thing to note about the Submit request is that the elements required for one SubType are not necessarily the same as those required for another SubType. In the example payload on page 50, the SubType CancelWoA (Cancel without approval) specifies data for the following elements:

• EsiID

• OrigTrxnID

Those 2 elements are not necessarily the same elements that would be required to create an issue of a different SubType. For example, if the request were for an issue of Type D2D but SubType CancelWA (Cancel with approval), there would be an additional element required. For that SubType, MarkeTrak would expect an Assignee element to be specified in the request.

To see the required fields for each Type/Subtype combination, see the document titled MarkeTrak Bulk Insert Appendix A. You can find a copy on the ERCOT web site:

http://www.ercot.com/services/client_svcs/mktrk_info/

That document contains tables that show the required fields for each of the different combinations of Type and Subtype. For example, the following table is a fragment of the table that shows the required fields for Issue Type D2D.

Table From MarkeTrak Bulk Insert Appendix A

You can see in the table above that if you are creating (submitting) an issue of Type D2D and SubType Cancel With Approval, that you must provide data for 3 fields:

• ESI ID

• Orig Tran ID (required if 867_03F)

• Assignee

Contrast that with the requirements of Type D2D and SubType Cancel Without Approval, indicated on the second column: There are two fields that require data:

• ESI ID

• Orig Tran ID (required if 867_03F)

For each request that you send to the Submit service, you must ensure that you provide data for the fields that MarkeTrak requires based on the Type/Subtype combination you are creating.

5. Testing against the ERCOT sandbox

Before you ask ERCOT to certify your application, you need to run your application against the test server (also referred to as the sandbox). At the time of this writing the URL of the test server is:

https://testmisapi.ercot.com/marketrakAPI/

The above URL points to a server running a version of MarkeTrak available to you for testing purposes. It is separate from the production version. Data submitted to the test server does not affect the live data in the production system.

5.1. Obtain a digital certificate for testing

The digital certificate you use to communicate through an API call is different than the digital certificate you use to communicate through the MarkeTrak GUI (the web application accessed through a browser). MarkeTrak will not respond to your application if you use a digital certificate intended for the GUI version of MarkeTrak.

Be aware that the digital certificate that you use to communicate with the test server is different than the digital certificate you use to communicate with the production server.

Once a certificate’s validity has expired, it is up to you (the subject of the certificate) to request a new certificate from the issuing certification authority.

When connecting to the sandbox (test server), the issuing certification authority is the administrator at ERCOT who is responsible for the MarkeTrak sandbox. This person issues a digital certificate that can be used with the sandbox. If you don’t know who the administrator is, ask your ERCOT Retail Client Service (RCS).

After you have received your digital certificate, make sure that it is valid:

• the certificate has not expired

• each certificate in the certification path (certificate chain) is valid

Refer to the section titled Digital Certificate Expired to learn more

5.2. Notify ERCOT that you are beginning test phase

The test server is not always available for testing. You must coordinate test times with the ERCOT test server administrator.

ERCOT occasionally updates the functionality of the MarkeTrak application. When there is an upgrade or release, the MarkeTrak Taskforce working group decides whether there needs to be a test by market participants (MPs). That group works with the Script Sub Team to develop test scripts for the new functionality. Any new MP that wishes to use the API or an existing MP that currently uses the API must perform tests against the MarkeTrak application. Retail Client Services sends a market notice to MPs to notify them about the signup period and test dates.

After an MP signs up for testing, if the MP does not already have a valid digital certificate, ERCOT issues a test digital certificate. When MPs test their application through the API, ERCOT requests that the MPs provide a sample of the response file.

5.3. Error Messages

The Error messages table describes errors that are returned by ERCOT or, in the case of the asynchronous message, returned by the participant.

The table shows:

• The Error Severity Code which identifies the error by number and the severity of the error using the codes F, E, and W. See description below describing error numbers.

• Description briefly describes error.

Table: Error Severity Codes

Error Severity Code	Description
F	Fatal indicates that processing aborted prematurely and results are indeterminate. A fatal error is the result of various circumstances outside of the control of the participant. Examples include software error, system failure, and application unavailable. When a fatal error occurs, often the participant’s only recovery action is to retry the message or contact ERCOT support staff.
E	Error indicates that there is a processing error as defined by the error number range described below. Error typically means that the message and content are not formatted correctly. The participant recovery action is to correct the formatting or data and resubmit the message.
W	Warning indicator means that an unusual or abnormal situation exists but that the message is accepted and processed anyway. There are no defined W warning level errors in this specification at this time.
I	Informative indicator is not an error or warning but merely an informative code returned to the client. This indicator is defined for completeness but there are no instances where the informative indicator is used by this specification.

The error number range is ordered according to type and cause of error as shown in the following table.

Error Number Range	Source of Error
01 – 99	Network addressing, communications, MIME encoding or other message structure or format errors.
100 – 199	XML parse errors caused by ill-formed XML.
200 – 299	XML validation errors caused by XML that does not match the DTD.
300 – 399	XML semantic errors caused by incorrect DTD or in appropriate DTD for message content.
400 – 499	Data validation errors resulting from improper range or domain, invalid date or time, improper data-type for data value, and so on.
500 – 999	Business rule violation errors or incomplete data (improper use of optional fields).

6. Obtaining ERCOT certification for your application

To use the MarkeTrak services through API calls, your application must be certified by ERCOT.

6.1. Levels of Certification

There are 3 levels of certification, each based on the type of web service calls your application will make:

• QueryList, QueryDetail, and QueryFileAttachment: certifies that your application makes proper use of these services, which are read-only access to the system

• QueryList, QueryDetail, QueryFileAttachment, and Update: certifies proper use of the above plus the Update service

• QueryList, QueryDetail, QueryFileAttachment, Update, and Submit: certifies proper use of the above plus the Submit service

6.2. How to Request Certification

ERCOT will not allow your application to access the production server until the application has been certified. Request certification of your application only after you have conducted your own test of your application against the sandbox, and have established that your application is stable.

To request certification, contact the Certification administrator at ERCOT. This person will instruct you on when and how to connect to the server. If you don’t know who the administrator is, ask your ERCOT Retail Client Service (RCS).

7. Tips and Suggestions On Implementing SOAP

The MarkeTrak application expects messages to be transported with the Simple Object Access Protocol (SOAP). A SOAP message is an XML document that consists of a mandatory SOAP envelope, an optional SOAP header, and a mandatory SOAP body.

Skeleton of a SOAP Message

<?xml version="1.0"?>
<soap:Envelope
  xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
  soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">
  <soap:Header>
  ...
  ...
  </soap:Header>
  <soap:Body>
  ...
  ...
  </soap:Body>
</soap:Envelope>

7.1. Basic Syntax rules of SOAP

Here are some important syntax rules:

• A SOAP message MUST be encoded in an XML document

• A SOAP message MUST use the SOAP Envelope namespace

• A SOAP message MUST use the SOAP Encoding namespace

• A SOAP message must NOT contain a DTD reference

• A SOAP message must NOT contain XML Processing Instructions

7.2. Accessing a service

You must use SOAP to access MarkeTrak’s services (methods). In SOAP terminology, a MarkeTrak service is a method that exists with the scope of an endpoint, accessed through an HTTP communication.

A SOAP endpoint is a URL (the same as other HTTP-based resources). A SOAP method is defined by a namespace URI and an NCName. The NCName maps to the symbolic name of the method. The namespace URI scopes the method name, much like an interface name scopes a method in Java, CORBA, or COM. SOAP method requests are transported in HTTP POST requests.

7.2.1. SOAP Message Formats

A WSDL binding describes how the service is bound to a messaging protocol, particularly the SOAP messaging protocol. A WSDL SOAP binding can be either a Remote Procedure Call (RPC) style binding or a document style binding. A SOAP binding can also have an encoded use or a literal use. This combination gives you four style/use models: RPC encoded, RPC literal, document encoded, and document literal.

Add to this list a pattern which is commonly called the document literal wrapped pattern and you have five possible binding styles.

MarkeTrak expects a document/literal SOAP format. The following explains what this means.

WSDL 1.1 distinguishes between two message styles: document and RPC. Here's how each style affects the contents of \<soap:Body>.

• Document: \<soap:Body> contains one or more child elements called parts. There are no SOAP formatting rules for what the \<soap:Body> contains; it contains whatever the sender and the receiver agree upon.

• RPC: RPC implies that \<soap:Body> contains an element with the name of the method or remote procedure being invoked. This element in turn contains an element for each parameter of that procedure.

For applications that use serialization/deserialization to abstract away the data wire format, there's one more choice to be made: the serialization format. There are two popular serialization formats today:

• SOAP Encoding: SOAP encoding is a set of serialization rules defined in section 5 of SOAP 1.1 and is sometimes referred to as "section 5 encoding." The rules specify how objects, structures, arrays, and object graphs should be serialized. Generally speaking, an application using SOAP encoding is focused on remote procedure calls and will likely use RPC message style. The rest of this article ignores SOAP encoding and focuses on literal format.

• Literal: Data is serialized according to a schema. In practice, this schema is usually expressed using W3C XML Schema. Although there are no prescribed rules for serializing objects, structures, and graphs, etc., the service's schema describes the application-level Infoset of each of the service's messages.

7.2.2. Embedding the SOAP message in an HTTP Request

Because MarkeTrak communicates through HTTP, you must embed the SOAP messages you send in an HTTP request. This means that your message will consist, at minimum, of an HTTP header, a SOAP envelope, and a SOAP body.

The following snippet shows the minimal HTTP header information required by a SOAP message embedded in an HTTP request. Notice the field called soapaction.

POST /objectURI HTTP/1.1
soapaction: “urn:methodName”
Host: www.service_providers_hostname.com
Content-Type: text/xml
Content-Length: nnnn

The following shows an example of an HTTP header written specifically to communicate with MarkeTrak’s Query Detail service:

/POST / HTTP/1.1
soapaction: "/BusinessService/WS/TeamTrack/External/TeamTrackExternal.serviceagent/OperationsEndpoint1/QueryDetail"
Host: misapi.ercot.com:443/marketrakAPI
content-type: text/xml; charset=utf-8
Content-length: 832
Expect: 100-continue

The HTTP header above indicates that the Query Detail service (defined by soapaction) should be invoked against the SOAP endpoint, which is defined by the host+objectURI:

https://misapi.ercot.com/marketrakAPI/BusinessService/WS/TeamTrack/External/TeamTrackExternal.serviceagent/OperationsEndpoint1/QueryDetail

7.2.3. Specifying the SOAP Envelope and Body

In addition to the HTTP header, your message must also specify the payload. The payload of a SOAP method request is an XML document that contains the information needed to invoke the request. The payload includes a SOAP envelope and SOAP body.

The following is the minimal information needed to define a payload:

<?xml version='1.0'?>
<SOAP:Envelope xmlns:SOAP='urn:schemas-xmlsoap-org:soap.v1'>
  <SOAP:Body>
    …
    {body}
    …
  </SOAP:Body>
</SOAP:Envelope>

The following shows an example of a payload specifically intended for the Query Detail service.

<?xml version=”1.0” encoding=”UTF-8”?>
<soap:Envelope 
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <IssueQueryDetailsRequest xmlns="http://www.ercot.com/schema/retail/2006-01">
            <IssueNumber>58427</IssueNumber>
        </IssueQueryDetailsRequest>
    </soap:Body>
</soap:Envelope>

7.3. Summary

To re-cap, to define a successful SOAP message, you must:

• define an HTTP header that specifies the soapaction field

• define a SOAP body

• define a SOAP envelope

Remember that:

• SOAP endpoints are URLs

• SOAP methods are XML element declarations identified by a namespace URI and an NCName.

8. Tips and Suggestions on Reading the WSDL Document

The Web Services Description Language (WSDL) file defines the programming interface of the web services. The WSDL document contains the following elements:

abstract definitions

• portType

• types

• message

concrete aspect of the specification

• binding

• service

There are 3 parts of the WSDL file that you need to understand in order to create valid messages:

• portType element, which defines the name and structure of operations

• types element, which defines the data types used in messages

• binding element, which defines the protocol and format used for transport

The portType element contains the operation element that defines the web service. The operation is defined by combining multiple message elements. The web services receive a request message and send a response message. For that reason, the operation element specifies an input element and an output element. An operation can also specify a fault element to encapsulate possible errors. Refer to the latest WSDL file to see the definition of the web service. The following example gives you an idea of what to look for in the WSDL file.

WSDL snippet showing the definition of the Query List web service

<wsdl:portType name="Operations">
  <wsdl:operation name="QueryList">
    <wsdl:input message="tns:QueryIssueListRequest"/>
    <wsdl:output message="tns:QueryIssueListResponse"/>
    <wsdl:fault name="exception" 
                message="tns:ExceptionRequestMessage"/>
  </wsdl:operation>
</wsdl:portType>

The binding element defines how the service is bound to a messaging protocol (such as HTTP GET, HTTP POST, MIME, or SOAP). It defines, in other words, the message format and protocol to be used to transport information about the operation and message over the wire. The binding element also defines where the service is located on the server. The \<wsdl:binding> element of the WSDL document contains a pair of parameters that influence the form of the resulting SOAP messages: binding style (RPC or document) and use (encoded or literal).

In the example below, the binding element specifies that messages should be sent using SOAP messages with HTTP protocol. Notice that the type attribute identifies the port to be used in the binding. In the example below the type attribute points to the ‘”tns:Operations” port. Refer to the latest WSDL file to see the current specifications for the Query List service.

WSDL snippet showing SOAP binding of Query List web service

<wsdl:binding name="inputBinding" type="tns:Operations">
  <soap:binding style="document" 
            transport="http://schemas.xmlsoap.org/soap/http"/>

  <wsdl:operation name="QueryList">
      <soap:operation style="document" soapAction="/BusinessService/WS/TeamTrack/External/TeamTrackExternal.serviceagent/OperationsEndpoint1/QueryList"/>
      <wsdl:input>
          <soap:body use="literal" parts="request"/>
      </wsdl:input>
      <wsdl:output>
          <soap:body use="literal" parts="response"/>
      </wsdl:output>
      <wsdl:fault name="exception">
          <soap:fault use="literal" name="exception"/>
      </wsdl:fault>
  </wsdl:operation>
</wsdl:binding>

soap:binding

This element indicates that the binding will be made available via SOAP. The style attribute indicates the overall style of the SOAP message format. A style value of document specifies that the content of \<soap:body> is specified by the schema. You can find that definition in the \<wsdl:type> section of the schema.

The transport attribute indicates the transport of the SOAP messages. The value http://schemas.xmlsoap.org/soap/http indicates the SOAP HTTP transport (compare with http://schemas.xmlsoap.org/soap/smtp which would indicate the SOAP SMTP transport).

soap:operation

This element indicates the binding of a specific operation to a specific SOAP implementation. The soapAction attribute specifies that the SOAPAction HTTP header be used for identifying the service.

soap:body

This element enables you to specify the details of the input and output messages.

The use attribute indicates the encoding rules of the SOAP message. It refers to the serialization rules followed by the SOAP client and the SOAP server to interpret the contents of the \<body> element in the SOAP XML payload.

If use="literal", this means that the type definitions are defined in the XML schema definition. If use="encoded", this means that the encoding rules can be found at the location defined by an additional attribute called encodingStyle.

The parts attribute identifies the part of the message that will appear in the \<soap:body> of the message.

The types element describes all the valid data types that can be used in messages between the client and server. There is too much information defined in the wsdl:types element of the Query list service to list in this document. Refer to the WSDL file itself to learn about the data types.

Glossary of Terms

The following terms and acronyms are used in this document.

ACK – an abbreviation for acknowledgement, indicating a normal and successful acknowledgement message or signal. Contrast with NAK.

Character Data –the XML term that defines the non-markup data that exists between an XML start and end tag. For example, given a start and end tag of UNITMW, the character data in the following example is the number 400.0: \<UNITMW>400.0\</UNITMW>.

Digital Certificate –packet encoding that defines a public key to be used with public key encryption, detailed information about the owner of the digital certificate, expiration date of digital certificate, and other optional data. Digital certificates are used to authenticate all parties (ERCOT and participants) that use the programmatic interface. Digital certificates are also used to establish the secure connection between the participant and ERCOT. The secure connection is made using the SSL protocol. Encryption and digital certificates and how they are used by the programmatic interface are described in the document “ERCOT Programmatic Interface Specification”.

DUNS number – a D-U-N-S® number is a unique nine-digit number assigned to a company by Dun & Bradstreet (D&B). This number is a business standard for identifying each physical location of a corporation. See also digital certificate.

First-Normal-Form –the specification that character data defined by XML start and end tags (see definition of character data in this terminology section) represents a single data item. Data that does not fit the First-Normal-Form definition is data that includes sets of information, repeating groups, or structured elements. For the purposes of this specification, Date and Time data is considered to be First-Normal-Form data, even though it defines sets of information (e.g. month, day, year, hour, minute).

HTTPS – stands for Hyper-text Transfer Protocol Secure. HTTPS is a secure protocol where the security is established by SSL (see terminology entry). HTTPS does not define nor does it add new communications features to HTTP; it is merely a secure version of HTTP. The HTTPS name is used to specify the protocol in the URL declaration to identify it as being secured by SSL.

IETF – stands for Internet Engineering Task Force, the body whose members work together to define, specify, and regulate the various standards used for Internet network communications. The RFCs referenced by this specification are defined and maintained by the IETF. The IETF web site can be consulted for more information: www.ietf.org.

ISO – acronym with two different, unrelated, meanings used in this specification. ISO, on one hand, means Independent System Operator; this usage of the term represents the kind of organization and operations center established by ERCOT. The other definition for ISO is International Standards Organization, the standards body responsible for a number of international standards used implicitly and explicitly in this document. Explicit ISO standards cited by this specification include ISO-8601, used to define Date and Time standards and conventions; and, ISO-8859-1, used to define the XML operative character set.

NAK – an abbreviation for negative-acknowledgement, indicating a negative response message or signal. Contrast with ACK.

RFC – stands for Request For Comments. The RFC is the documentation method used by the IETF for developing and documenting network communications standards for the Internet community. Several network communications standards cited by this specification are defined by RFCs. Each RFC is numbered. For a complete list of RFCs, and to obtain copies of RFCs, see the information located at the IETF web site: www.ietf.org.

Request/Response –a messaging style in which a client sends a request message to a server and the server responds with a reply message. Request/Reply is also sometimes called ‘Client-Server’ messaging. For purposes of this document, the participant is always the client who initiates the request, and ERCOT is the server that responds with a reply. Contrast ‘Request/Reply’ with ‘Push Messaging’ (a/k/a asynchronous).

SOAP – stands for Simple Object Access Protocol is a protocol for exchanging XML-based messages over computer networks. SOAP forms the foundation layer of the Web services stack, providing a basic messaging framework that more abstract layers can build on.

SSL – stands for Secure Sockets Layer. SSL is a protocol standard used to establish a secure, encrypted connection between a given client and server. SSL Version 3.0 is the protocol used for establishing the secure communications between participants and ERCOT. SSL is an industry de-facto standard developed originally by the Netscape Corporation. More information on the definition and use of SSL by ERCOT can be found in the document ERCOT Programmatic Interface Specification.

TCP/IP – stands for Transport Control Protocol over Internet Protocol. TCP/IP is actually two separate protocol standards; however, as used in this specification (and, in most other applications), TCP/IP is a single network communications protocol. TCP/IP is the protocol specified by various RFC documents published by IETF (RFCs in this case are not as useful as other more popular publications of the TCP/IP standard). TCP/IP is used as the carrier protocol for all messages defined by this specification.

URL – stands for Uniform Resource Locator. URL is the standard method for specifying network addresses and resources used by Internet protocols. The URL defines the protocol, network host address, optional port number, resource path and fragments. URLs specify ERCOT server addresses that receive messages sent by the participants. Participants that support the reception of push-style messages must also define their server network address using a URL declared during the participant registration process. URL is defined by RFC 1738.

Valid – as used in this context, valid is the measurement of an XML document that is correctly formatted according to its DTD. ERCOT accepts only valid XML documents in messages received from participants. All valid XML documents are implicitly also well-formed.

Well-formed – refers to an XML document that is formatted according to the syntax rules set forth by the XML recommendation. An XML parser will correctly parse a well-formed document.. A document that is not well-formed may fail to parse completely.

WSDL – stands for Web Service Definition Language, an XML-based language for describing Web services and how to access them.

XML – stands for Extensible Markup Language. XML is a W3C published recommendation. XML is used as the basic format for all messages defined by this specification. More information on XML can be found at the web site: www.w3c.org/xml.