File Structure and XSD
Scheduling data can be submitted to the APX MarketSuite® through Inbound file upload, and can be queried from the system with the Outbound GetStatus (exception data) and GetScheduleData methods.
Both the inbound and outbound web-services utilize the same ScheduleData.xsd to form and validate the format of the XML messages, with some variances:
Scope
Many organizations may represent multiple ‘participants’ within a single market. For this reason, the XML schema allows BidsOffers, ResourceParameters and BilateralSchedules for multiple participants to be submitted (Inbound) and pulled (Outbound) in one file.
Users may also upload up to seven days worth of data in a single submission.
Inbound Data Variances
The inbound data is similar to the outbound schema with the following exceptions:
· The root element is named ‘Submit’
· The ‘Status’ and ‘Message’ elements are not used for inbound data.
· The ‘FileStatus’ attribute is not used for inbound data.
· The ‘CounterPartyMW’ attribute of the BilateralScheduleDetail element is not used for inbound data.
· The ‘Price’ attribute of the ‘SelfScheduleType’ element is not used for pre-market data, but may be present for outbound post-market awards.
Outbound Data Variances
The data of the response looks very similar to submitted 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 presence or absence of any exception data associated with the submission. This attribute is not used in GetScheduleData responses.
· The ‘CounterPartyMW’ attribute is added to the BilateralScheduleDetail element
· The ‘Price’ attribute is added to the ‘SelfScheduleType’ element for post-market awards.
Inbound Data
The following section details how the API may be used to submit data to APX MarketSuite® through the Upload File method. Inbound XML files will have a ‘Submit’ root element, plus the ‘MarketBidData’ or ‘MarketTradeData’ complex type. MarketBidData includes BidsOffers and ResourceParameters, and MarketTradeData includes BilateralSchedules. ‘MarketBidData’ and ‘MarketTradeData’ may not be submitted in the same file.
Example Submission for one bid hour
<Submit Version="2.1" SourceSystem="APX" CreateDate="2019-10-26T14:39:12Z" Region="PJM" SubmitToISO="true" xmlns="http://service.apx.com/ScheduleData">
<MarketBidData Date="2019-12-06">
<BidsOffers MarketParticipant="ACME" Location="DPL" Transaction="DA Fixed Demand Bid">
<SelfSchedule>
<Schedule MW="10" IntervalEndGmt="2019-12-06T06:00:00Z"></Schedule>
</SelfSchedule>
</BidsOffers>
</MarketBidData>
</Submit>
The specifics of the ‘MarketBidData’ and ‘MarketTradeData’ complex types are the same in the inbound and outbound files, and are described later in this portal.
Inbound Data Validation
The different types of inbound data are validated differently. Inbound BidsOffers data undergoes two phases of validation:
Phase 1 Validation
The first phase of validation is for file format and syntax (xsd validation). If the file fails this validation, the entire file will be rejected and no data will be saved.
Phase 2 Validation
The second phase validation is for business rules. Data failing phase 2 validation can only be returned by the Get Status method. Reasons for failing phase 2 validation include:
· Invalid Transaction name
· Invalid location name
· Location not valid for transaction
For ResourceParameters and BilateralSchedules, all validations are in one phase, and any failure will result in the entire file being rejected. Note that APX may introduce two-phase validation for these data in the future.
Root ‘Submit’
The ‘Submit’ section is the header for all submissions regardless of the dataset being passed in the XML file.
Header Attribute | Description | Data Type |
---|---|---|
Version | Version of API (XSD Optional) (Default is current version) | String |
SourceSystem | Represents the system that produced the data (XSD Required) | String |
CreateDate | Date and time that the data was pulled from the source system (XSD Required) | XML dateTime (GMT) |
Region | ISO Code for the submission | String |
SubmitToISO | A flag that indicates that the data should be sent automatically to the ISO. ‘False’ means that the bids/offers will need to be reviewed and submitted interactively using the APX MarketSuite® Checkout application or via a subsequent API submission (XSD Optional) (Default is ‘False’). | Boolean |
xmlns | xsd | http://service.apx.com/ ScheduleData |
Outbound Data
The following section details how the API may be used to obtain ISO Scheduling data from the APX MarketSuite®. There are two methods of obtaining ISO Scheduling related data:
- GetStatus – allows clients to programmatically obtain the exception (error) data associated with prior submissions by referencing the uploaded file. This method only reports the status of exception data that was submitted by this file; it will not include the status of data submitted in another file or directly the APX MarketSuite® User Interface or the regional ISO User Interface.
-
GetScheduleData – allows a client to programmatically obtain:
- A complete image of their scheduling data including status.
- Market awards including MW and the applicable market clearing price
Outbound XML files will have a ‘Response’ root element, plus the ‘MarketBidData’ or ‘MarketTradeData’ complex type. MarketBidData includes BidsOffers and ResourceParameters, and MarketTradeData includes BilateralSchedules. ‘MarketBidData’ and ‘MarketTradeData’ may not be requested or returned in the same request.
Example Response for One Bid Hour (GetScheduleData method)
<Response SourceSystem="APX" CreateDate="2019-12-03T23:03:07.091-08:00" Region="PJM" xmlns="http://service.apx.com/ScheduleData" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<MarketBidData Date="2019-12-06">
<BidsOffers MarketParticipant="ACME" Location="DPL" Transaction="DA Fixed Demand Bid">
<SelfSchedule>
<Schedule MW="10" IntervalEndGmt="2019-12-06T06:00:00Z" Status="APXCreated"/>
</SelfSchedule>
</BidsOffers>
</MarketBidData>
</Submit>
The specifics of the ‘MarketBidData’ and ‘MarketTradeData’ complex types are the same in the inbound and outbound files, and are described later in this portal.
Root ‘Response’
The ‘Response’ section is the header for all outbound data regardless of the data being requested.
Header Attribute | Description | Data Type |
---|---|---|
SourceSystem | Represents the system that produced the data (XSD Required) | String |
CreateDate | Date and time that the data was pulled from the source system (XSD Required) | XML dateTime (GMT) |
Region | ISO Code for the submission | String |
FileStatus | Get Status method only. Conveys the header-level status of the results. Possible responses include: · ‘SUCCESS: No exception data found’ · ‘SUCCESS’ [File will include details on exceptions for the submission] · ‘ERROR: The file is not a valid Scheduling file’ · 'File load in progress | String |
xmlns | xsd | http://service.apx.com/ ScheduleData |