ISO Scheduling API Summary
The purpose of this portal is to describe the data structures and communication workflow (lifecycle) related to integration (inbound and outbound) of Independent System Operator (ISO) scheduling related data with the APX MarketSuite™ via Web Services (WS).
Cross Market Scope
The portal is designed to support functionality for nodal markets (CAISO (MRTU), ERCOT (TX), PJM, MISO, etc). The region specific details highlighted throughout the portal.
The data structures for the CAISO and ERCOT ISOs are similar, and can be found in a separate portal.
Transaction Scope
The scope of “scheduling related data” includes all data supported by the APX MarketSuiteTM required by the various regional ISOs to operate their wholesale power markets. Each region is unique, but in general this includes the following data elements:
- Energy Bids and Offers
- Ancillary Service Offers
- Self Arranged Energy and Ancillary Services
- Virtual Bids and Offers
- Imports, Exports and Wheels
- Resource specific operating parameters
- Bilateral Trades for various product types settled through the regional ISO markets
The range of transactional functionality that the APX MarketSuiteTM supports will vary by region based on APX client requirements. Please contact your APX Account Manager if additional functionality is desired.
Data Transfer
Transaction Lifecycle
Clients may submit data into the APX MarketSuiteTM from either the UI or the API. In both cases, all the data in the system is visible through the UI and can be submitted to the ISO via the Checkout application. In case of the API, a flag can be set that will result in the data being submitted immediately to the ISO without requiring any user intervention through the UI.
Transaction statuses are managed in a variety of ways as supported by the regional ISO. For example, for the MRTU market the APX dispatcher periodically checks the status of the submissions by querying the CAISO systems. For ERCOT Nodal the application processes asynchronous notifications from the ISO whenever they are sent and may also query the ERCOT systems.
Furthermore, for some regional ISOs after the market closes, an automation queries and updates the final data set as it appears in the ISO, as well as market awards, schedule cuts (where applicable) and mismatched trades (where applicable).
When submitting data via the API, clients will receive a file handle (a character string) that represents the file that was uploaded. The uploaded data may also use the external_id field to make it easier to identify and track data being sent to APX MarketSuiteTM, or to tag it at a level that is more granular than a file. The file handle may be used to query the status of the data that was submitted via the API.
Clients may use the GetScheduleData function to obtain either the most current schedule data that exists on the APX system (Client Image), or the schedule data that the ISO has at the close of the scheduling period (ISO image), or the market results.
Sequence Diagram
The diagram below provides a sample sequence for the life cycle of a scheduling based transaction.
Note that each regional ISO supports different types of communications in support of a transaction. The below describes the MRTU communications.
APX customers communicate by transferring XML schedule data via the APX Scheduling Web Service using the HTTP protocol. Specifically, they use the FRUploadService to upload a compressed XML file with schedule data. If an error occurs when attempting to upload a file, an error is returned (refer to the list of errors in the API Report Parameters section. After the file is uploaded, the file is validated against the XSD. If the XSD validation fails, then an error message is returned including the reason(s)) for the failure.
When the APX Web Service receives the file, it registers it in APX file registry system (these files can be viewed interactively by the user using the APX Platform Explorer). That registration triggers a ‘file arrival’ event that spawns an automated ETL (Extract Transform Load) workflow that parses the file and loads the data into the APX application database. The data is then visible for interactive review, modification and can be submitted to the ISO using the Checkout application of the MarketSuiteTM. The incoming client data can be submitted to the ISO without interactive review by using the SubmitToISO flag (not applicable for ERCOT zonal). The APX MarketSuiteTM will keep all versions of scheduling source files submitted for tracking and dispute resolution.
APX customers can download a copy of an uploaded Scheduling API file from the APX MarketSuiteTM via the FRDownloadService Web Service.
Data Flow
For information regarding how to submit or download files to the APX Web Service, refer to the API Report Parameters section of the portal. This data flow is illustrated below, which also illustrates how data is transferred between internal APX systems and the ISO.
XSD Diagram
Both the inbound and outbound web-services utilize the same ApxScheduleAPI.xsd to form and validate the format of the XML messages with the following variances:
Inbound Schema Variances:
The inbound schema is similar to the outbound schema with the following exceptions:
- The root element is named <Submit >
- The <Status > and <Message > elements are not used
- The <FileStatus > attribute is not used
- The <MarketStatus > attribute is not used
- The <CounterPartyMW > attribute of the BilateralScheduleDetail element is not used
-
The
attribute of the <SelfScheduleType > element is not used
Outbound Schema Variances:
The schema of the response looks very similar to the one used to submit data with the following differences:
- The root element is named <Response >
- The <SubmitToISO > attribute in the Response element is ignored.
- The <Status > and <Message > elements are added throughout to return the status of the row and optionally a message that contains error or informational message regarding the status of that row.
- The <FileStatus > attribute is provided in GetStatus responses to convey the file’s stage in the the APX MarketSuiteTM file processing lifecycle. This attribute is not used in GetScheduleData responses.
- The <MarketStatus > attribute is provided in GetScheduleData responses to indicate whether the response contains “Pre”, “Post”, or “Award” data.
- The <CounterPartyMW > attribute is added to the BilateralScheduleDetail element
- The <Price > attribute is added to the <SelfScheduleType > element
Inbound Data
The following section details how the API may be used to submit data to APX MarketSuiteTM.
Utilizing Multiple Data Sections in a single transaction:
The API Schema has been designed to provide a flexible method for interfacing data from multiple external systems. A single inbound transaction may contain data in one or more of the data sections (<BilateralSchedule>, <BidsOffers>, or <ResourceParameters>).
For example a client may want to push to the APX MarketSuiteTM the data necessary to populate the Three Part Offer in TX (Nodal). This includes an offer curve, start-up costs, and minimum energy costs. The offer curve aspect is populated via the <Bidsoffers> data section while the costs are part of the <ResourceParameters> data section. All data may be included in a single inbound API file.
NOTE: MISO and PJM functionality is still in development.
XSD Required/Optional Field – Required/Optional field by the APX XSD
ISO Required/Optional Field – Required/Optional field in order to submit data to ISO
<Submit> Data: XML Header
The <Submit> section is the same regardless of the dataset being passed in the XML file.
Item | Description | Validation |
---|---|---|
Version | Version of API (XSD Optional) (Default is current version) | Data Type: String ‘2.1’ |
Source System | Represents the system that produced the data (XSD Required) | Data Type: String |
CreateDate | Date and time that the data was pulled from the source system (XSD Required) | Data Type: XML dateTime (GMT) |
SubmitToISO | A flag that indicates that the bids/offers should be sent automatically to the ISO. ‘False’ means that the bids/offers will need to be reviewed and submitted interactively using the APX MarketSuiteTM Checkout application or via a separately configured automated workflow (XSD Optional) (Default is ‘False’) | Data Type: Boolean |
CreateDate | Date and time that the data was pulled from the source system (XSD Required) | Data Type: XML dateTime (GMT) |
Outbound Data
The following section details how the API may be used to obtain ISO Scheduling data from the APX MarketSuiteTM. There are two methods of obtaining ISO Scheduling related data:
- GetStatus – allows clients to programmatically obtain the status of prior submissions to the APX MarketSuiteTM by referencing the uploaded file. This method only reports the status of data that was submitted by this file; it will not include the status of data submitted in another file or directly the APX MarketSuiteTM User Interface or the regional ISO User Interface.
-
GetScheduleData – allows a client to programmatically obtain:
- a complete image of their scheduling data including status (APX image or ISO image at market close)
- market results including MW and the applicable market clearing price
All scheduling data coming out of APX via web services will adhere to the ApxScheduleAPI.xsd – the same schema that is used to submit data to APX
<Response> Data: XML Header
Item | Description | Validation/Values |
---|---|---|
Version | Version of API (XSD Optional) | Data Type: String ‘2.1’ |
Source System | Represents the system that produced the data (XSD Required) | Data Type: String |
CreateDate | Date and time that the data was pulled from the source system (XSD Required) | Data Type: XML dateTime (GMT) / DateTime that file was created by the APX MarketSuiteTM |
FileStatus | Used to convey the file level status in response to a GetStatus request. Not included in GetScheduleData responses. | Data Type: String / See GetStatus section below for list of valid FileStatus strings |
MarketStatus | Provided in GetScheduleData responses to indicate whether the response contains “Pre”, “Post”, or “Award” data. Not included in GetStatus responses. | Data Type: String / ‘Pre’, ‘Post’, or ‘Award’ |
Description of <Status> and <Message> attributes related to Outbound Data
Attribute | Description | Validation |
---|---|---|
Status | The status associated with the data row. | Data Type: Enumeration. Refer to table below for a list of statuses by Region separated by status category (APX statuses, ISO bid/offer statuses and ISO trade statuses) |
Message | Description of the error message or warning. | Data Type: String. For APX statuses, the message is generated by APX. Below is a table of typical messages; these messages are not fixed and are subject to change. |
APX Status | Message |
---|---|
APXCreated | Created by 'username' |
APXEdited | Edited by 'username' |
APXPending | Pending submittal to ISO |
APXPending Submit | Submittal to ISO in transit |
APXSubmitted | Submitted to ISO |
APXSubmitFailed | Submission to ISO failed |
APXRejected | The Status Messages are appended to one another if more than one condition is met. -The [Sink Location] OR [Source Location] are not valid locations. -The [Participant] is not valid. -The combination of parameters passed ([Transaction Type], [Product Type], [Schedule Type], [Market Stage], etc) does not map to a valid MarketSuite transaction. -The [Facility] is not valid. -The [resource parameter type] is not valid. -[Curve_point] violation. Number exceeds limit. -[External_ID] violation. Unique number exceeds limit. -[Interval_Length] violation. Proposed interval length does not match ISO interval length for given market offering. -[MW] range violation. Value found in XML is not within valid range values for MW. -[Price] range violation. Value found in XML is not within valid range values for Price. -[Interval] range violation. Value found in XML is not within valid range values for intervals given the intervaltype/intervalwindow. -The node specified is invalid for the market offering specified. -Exception with OnUpAs duplicate values passed |
APXCanceled | Canceled by 'username' |
APXObsolete | Replace by 'username' |
ISOError | ISO Error occurred |
For ISO statuses, the message is generated by the ISO based on what APX parses from the ISO response template. (There are hundreds of ISO messages so they are not specified here.)
Bid/Offer and Trade Status Table
Below is a table of statuses by Region and status category (APX statuses, ISO bid/offer statuses, ISO trade statuses)
Region | APX Statuses | ISO Bid/Offer Statuses | ISO Trade Statuses |
---|---|---|---|
MRTU | APXCreated APXEdited APXPending APXPendingSubmit APXSubmitted APXSubmitFailed APXRejected APXCanceled APXObsolete ISOError Submit Failed |
Green Category: CondValid Valid Canceled Clean (after market close) Yellow Category: Pending Submitted Red Category (from more severe to less severe): Rejected Invalid Priority = No Balanced = No Obsolete Blue Category: CondModified Modified |
Green Category: Matched CondValid Valid(after market close) Canceled Obsolete Yellow Category: Pending Submitted Red Category (from more severe to less severe): Rejected Invalid Blue Category: Unmatched Missing Content |
TX(ERCOT) | APXCreated APXEdited APXCanceled APXObsolete APXRejectedSubmit Failed |
Pending Submitted Accepted Error Canceled |
Pending Submitted Accepted Confirmed Unconfirmed Error Canceled |