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.

csv file examples sequence diagram

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.

csv file examples data flow

XSD Diagram

csv file examples xsd

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