Data API Data Exchange Guide

Binder Cover

Contents

Scope and Prerequisite Knowledge......

Change Summary......

What’s New in this Document......

1. Web Service Overview......

1.1 Deployment Environment......

1.1.1 Client Side......

2. Description of SOAP Messages......

2.1 Format and Construction......

2.2 Data Types......

2.2.1 Handling Times......

2.3 Responses......

3. Registration Process......

4. Data Packages Overview......

5. Data Packages Details......

5.1.1 PostCompleteRequestNumber......

5.1.2 PostImplementRequest......

5.1.3 PostImplementRequestNumber......

5.1.4 PostSubmitRequest......

5.1.5 GetOutageProfileQuery......

5.1.6 GetInitialize

5.1.7 GetLoadItem

5.1.8 GetPowerSystemResource

5.1.9 PostAddChangeRequest

5.1.10 PostSaveChanges

5.1.11 Post AddCancellationRequest......

6. XML Examples:......

7. Psuedo Code:......

Appendix A. Appendices......

A.1 Appendix A – Types......

About This Document

This document describes the SOAP messages used to retrieve and submit data from the SPP CROW Outage Scheduler API. This document describes the background for each message and lays out the format and construction of SOAP messages.

Scope and Prerequisite Knowledge

This document is intended to be used by SPP Members and participating vendors as an aid in developing interfaces to access the SPP CROW API (Outage Management System) data packages.

Users of this Guide should be familiar with SOAP, Extensible Markup Language (XML), Web Services and HTTP/HTTPS protocols.

Change Summary

Rev / Author / Date / Comments
1.0 / J. Weaver / 01/11/12 / Initial draft.
1.1 / J. Weaver / 01/24/12 / Modified PostSubmitRequest to remove user\pwd parameters. Added new web method for querying equipment (PowerSystemResource)
1.2 / L. Poteet / 2/7/12 / Update with additional information for web methods, XML examples, etc
1.3 / J. Weaver / 2/8/12 / Added code examples
1.4 / J. Weaver / 02/16/12 / Removed PostCompleteRequest, updated some verbage , changes names of web services to adhere to SPP standard for web method calls
1.5 / J. Weaver / 03/15/2011 / Removed unused methods
1.6 / L. Poteet / 4/19/2012 / Update WSDL URL pg. 7; Remove Econ (18) pg 10, 12; Update Outage Priority and Cause Codes with Opportunity (5) for Generation
1.7 / D. Welker / 4/23/2012 / Added PostAddChangeRequest, PostSaveChanges methods to section 5.
1.8 / J.Norman / 6/8/2012 / Added getLoadItem method to section 5.
1.9 / L. Poteet / 7/27/12 / Updating with 5.3.0.207 changes; GetOutageProfileQuery; added webmethod example for returnFields; added comments on a new Flag, Pending Change Request
1.10 / L. Poteet / 8/21/12 / Updated Post Add Cancellation Request; cancellation codes to use; additional wording around Return Fields; non-recallable in Post Submit Request

What’s New in this Document

getOutageProfileQuery - Addition of the returnFields method, which takes an Array of String as the data type.

<returnField>outageState</returnField>

<returnField>requestedEquipment/properties/InstanceProperty[propertyName ='EMS Key']</returnField>

<returnField>requestedEquipment/properties/InstanceProperty[propertyName='Fuel Type']</returnField>

Where the returnFields parameter is left empty, CROW will continue to return the ReturnedProfile object using the existing schema; this provides backwards compatibility for existing systems using this feature.

Where values for the returnedFields parameter are specified, the ReturnProfile object will consist of the original ReturnProfile schema plus those values noted in the returnedFields: i.e. new values are incrementally added to the ReturnedProfile object.

If a value in the returnedField is incorrectly specified (i.e. there is a spelling error or the XPath-like structure it uses does not correspond to a CROW object) there will be no corresponding <returnedField> name/value for that particular value; all other returnedFields values that are correctly specified will be returned.

With respect to the hideRequestedEquipment property of the OutageProfileQuery, if this value is set to false (i.e. the details of the Requested Equipment should be shown) then the following values are always included for that element:

typeName
label

Examples:

Where <returnedFields> contains the following value:

<returnField>requestedEquipment/properties/InstanceProperty[propertyName ='EMS Key']</returnField>

</returnFields>

Any ReturnedProfile object would contain the current ReturnedProfile elements/values plus the following element under the <RequestedEquipment> element:

<…>

<typeName>TYPENAMEVALUE</typename>

<label>LABELVALUE</label>

<value>EMSKEYVALUE</value>

</instanceProperty>

</instanceProperties>

</requestedEquipment>

<…>

Where returnedFields contains the following value:

<returnField>requestedEquipment/properties/InstanceProperty[propertyName ='EMS Key']</returnField>

<returnField>recallTime</returnField>

<returnField>recallTimeUnits</returnField>

</returnFields>

Any ReturnedProfile object would contain the existing values plus the following element under the <RequestedEquipment> element:

<…>

<typeName>TYPENAMEVALUE</typename>

<label>LABELVALUE</label>

instanceProperty>

<value>EMSKEYVALUE</value>

</instanceProperty>

</instanceProperties>

</RequestedEquipment>

<recallTime>RECALLTIMEVALUE</recallTime>

<recallTimeUnits>RECALLTIMEUNITSVALUE</recallTimeUnits>

A complete list of fields available to query is in the SPP API Crow Reference Guide, Returned Profiles object

Get Outage Profile Query – Pending Change Request Flag

A new flag will be returned in the <outageIndicators> object. This flag indicates if a Pending Change Request is present, values are True and False.

Response Example:

<Flag>

<name>Pending Change Request</name>

<value>False</value>

</Flag>

</outageIndicators>

<Flag>

<name>Pending Change Request</name>

</Flag>

1.Web Service Overview

The SPP CROW API (Outage Management System) web services will use SOAP over HTTPSand have operations and message content defined usingWeb Services Definition Language (WSDL).

Within this document, all web service operations have been described using a request/reply pattern that is typical of HTTPS communication.A request must contain a message that queries or submits data. A reply contains a message that is either: 1) an error, or 2) the response to the action taken.

It is required that all data be transported using digital certificates

1.1Deployment Environment

From an HTTPS point of view, client software initiates a request, while server software responds to a client request.

Client-side software is used under the following scenarios:

A data-consuming application requests data from a data owning application (sends an HTTPS GET)

Server-side software is used under the following scenarios:

A data-owning application receives a request for data from a data consuming application (responds to an HTTPS GET)

1.1.1Client Side

The client software needs to:

Have the ability to use X.509 digital certificates (Required)
Rely on configuration to obtain endpoints and certificate locations (Suggested)
Rely on configuration to specify the maximum number of retries for sending requests to endpoints (Suggested)

2.Description of SOAP Messages

This section describes the documentation conventions used and provides details about the constructs of SOAP messages.

2.1Format and Construction

SOAP messages are an XML-formatted structure wrapped in a SOAP envelope. A sample instance of an XML document with a SOAP envelope is shown below:

soapenv:Envelope
xmlns:soapenv="
xmlns:mes="
soapenv:Header/
soapenv:Body
mes:SubmitSomeMessage
!--1 or more repetitions:--
mes:Message day="2010-06-01" ID="1234"
mes:HourlyData
!--Up to 25 repetitions:--
mes:Values hour="2010-06-01T00:00:00-06:00"
mes:Value1SomeValue/mes:Value1
mes:Value2AnotherValue/mes:Value2
/mes:Values
/mes:HourlyData
/mes:Message
/mes:SubmitSomeMessage
/soapenv:Body
/soapenv:Envelope

The sample message above shows the format of messages used in the descriptions for each interface (described more in section5 - Data Packages Details).

2.2Data Types

Within the XSD, both native XML data types and custom-defined data types are used. Below is a list of the common data types used with a description of their format. See the SPP CROW API (Outage Management System) Reference guide that defines the types used by these services.

2.2.1Handling Times

The XML data types shown in the following table are used to represent date and time values. The lexical representation for these data types is specified by the ISO 8601 standard. The table shows the common notation for each, though the standard allows for great flexibility in formats.

Data Type / Lexical Representation / Example
date / yyyy-mm-dd / 2011-02-01
dateTime / yyyy-mm-ddThh:mm:sss-hh:mm / 2011-02-01T00:00:00.000-06:00
2011-02-01T06:00:00.000Z
2011-02-01T06:00:00.000-00:00

Note that the dateTime format includes the time zone indicator and the example shows time in Central Standard Time. XML messages that have dateTime elements or attributes are required to specify a time zone indicator to avoid confusion during the daylight savings transition periods.

Having"-05:00" and "-06:00" at the end of dateTime representations specifiesCentral Daylight and Central Standard respectively. All samples in this document show timestamps referencing GMT zone.

The samples below show different examples of dates within different time zones.

Date Time / Example
Jan 1, 2011 Midnight
Central Standard Time / 2011-01-01T00:00:00.000-06:00
2011-01-01T06:00:00.000-00:00
2011-01-01T06:00:00.000Z
May 25, 2011 7:30 pm
Central Standard Time / 2011-05-25T19:30:00.000-06:00
2011-05-26T01:30:00.000-00:00
2011-05-26T01:30:00.000Z

2.3Responses

A query will return either the Standard Error Response as shown below or a response message that is specific to the query. If an empty body is returned there either is no data to return based on your query parameters or there is a server side error that hasn’t been captured for formatting as of this document’s writing.

Standard Query Response:

soapenv:Envelope
xmlns:soapenv="
soapenv:Header/
soapenv:Body
!--Zero or more repetitions:--
mes:Data xmlns:mes="
mes:Row?/mes:Row
/mes:Data
/soapenv:Body
/soapenv:Envelope

Standard Error Response:

soapenv:Envelope
xmlns:soapenv="
soapenv:Header/
soapenv:Body
soapenv:Fault
!--One or more repetitions:--
faultcode?/faultcode
faultstring?/faultstring
/soapenv:Fault
/soapenv:Body
/soapenv:Envelope

3.Registration Process

The Registration process will require the user to submit a form with the company’s relevant information.

This process and tutorial information is located here:

The user will need to complete the Member User Access Form and Email.

4.Data Packages Overview

This chapter provides a high level overview of the SPP CROW API provided data packages.

Data Package / URL / Input Parameters
OutageManagementService / / Varies per web method call

5.Data Packages Details

5.1.1PostCompleteRequestNumber

Method Name: / PostCompleteRequestNumber
Description: / This method allows users to move an outage request to the Completed state.
If the user does not have permission to update the outage request content, but may move the outage request to the Completed state, this method should be used.
This method should be used to Complete an outage request.
Input Parameters:
Parameter Name / Requirement? / Parameter Type / Description
outageNumber / Required / String / The number of the outage request to be Completed.
thePerson / Person / The person who performed the action. If this person is the same as the logged in user, pass null.
actualComplete / Required / String / String representation of the actual time that the outage request completed.
returnType / Integer / Pass 0 to return the entire outage request.
Pass 1 to only return the current outage period.

5.1.1.1PostCompleteRequestNumberResponse

Returns: OutageSchedule
This method returns the OutageSchedule object. Check the errorCodes array in the returned object for error codes. If the errorCode for the first element in the array is not 0, the "PostCompleteRequestNumber" method failed.
If successful. The outage status is updated to completed.

5.1.2PostImplementRequest

Method Name: / PostImplementRequest
Description: / This method allows users to move an outage request to the implemented state.
This method should be used for FORCED Outages.
Input Parameters:
Parameter Name / Requirement / Parameter Type / Description
theOutageSchedule / Required / OutageSchedule / The input OutageSchedule object.
restorationComplete / Required / Planned End / This is part of the Outage Schedule object.
continuousDaily / Required / Continuous/Daily / This is part of the Outage Schedule object. Valid Values are:
Continuous
Return Evenings
Return Weekends
Returns Evenings and Weekends
Noncontinuos
reqRangeType / Required / Outage Duration / This is partofthe Outage Schedule object. Valid Values are:
Exactly
Window
woNumber / Optional / Work Order Number / This is part of the Outage Schedule object.
causeCode / Required / Outage Cause / This is part of the Outage Schedule object. Valid Values depend on priority of the outage. T = Transmission, G = Generation.
(T) BES - BES Condition (Stability, Loading)
(G) BSR – BES Reliability
(G) BSS – Bes Stability
(T, G) EQF - Equipment Failure
(T) Foreign Interference including Contamination
(T) FPS - Protection System Failure including Undesired Operations
(G) FUS – Fuel Supply
(T) L - Lightning
(G) LOI – Loss of Interconnection
(T, G) OTR - Other
(G) RSE – Regulatory/Safety/Environmental
(T, G) UKN - Unknown
(T) V - Vegetation
(T) VTM - Vandalism, Terrorism, or Malicious Acts
(T) W - Weather/Environment/Fire, excluding lightning
OutagePriority / Required / Priority / This is part of the Outage Schedule object. Valid Value for Forced Outage is 4.
reasonPriority / Optional / Requestor Notes / This is part of the Outage Schedule object. This is the Requestor Notes box and is free form.
constraintType / Optional / Equipment/Req. Type / This is part of the Outage Schedule object. This is used if the outage is something other than Out of Service. Valid Values are:
(T, G) 0 – OOS – Out of Service (defaulted if tag is not present)
7 –GSP – General System Protection
6 – HLW – Hot Line Work
20 – Info- Informational
21 – InSvcNO – In Service Normally Open
3 – Derated to
***values can be numeric, abbreviation, or full text.
woNumber / Optional / Work Order Number / This is part of the Outage Schedule object. This is the Work Order Number
requestedEquipment / Required / RequestedEquipment / The Requested Equipment for the Outage Schedule.
assetLongName / Required / Alternate Name / The name of the Equipment.
externalName / Required / Common Name / Only one name is required either assetLongName or externalName.
portionOutType / Required* / Derate on Generating Unit / *Use this when outage is for Derating a Generating Unit. The valid value is 3
deratedToAmt / Required* / MW value unit is derated to / *Use this when an outage is for Derating a Generating Unit. The value to enter is the MW value the Generating Unit is going to
deratedToUnits / Required* / *Use this when outage is for Derating a Generating Unit. The valid value is MW.

5.1.2.1PostSubmitRequestResponse

Returns: OutageSchedule
This method returns the OutageSchedule object. Check the errorCodes array in the returned object for error codes. If the errorCode for the first element in the array is not 0, the "PostImplementRequest" method failed.
If successful, an outage number is assigned to the request.

5.1.3PostImplementRequestNumber

Method Name: / PostImplementRequestNumber
Description: / This method allows users to move an outage request to the implemented state.
If the user does not have permission to update the outage request content, but may move the outage request to the implemented state, this method should be used.
This method should be used for all outages that are not FORCED
Input Parameters:
Parameter Name / Requirement / Parameter Type / Description
outageNumber / Required / String / The number of the outage request to be implemented.
thePerson / Required / Person / The person who performed the action. If this person is the same as the logged in user, pass null.
actualStart / Required / String / String representation of the actual time that the outage request started.

5.1.3.1PostImplementRequestNumberResponse

Returns: OutageSchedule
This method returns the OutageSchedule object. Check the errorCodes array in the returned object for error codes. If the errorCode for the first element in the array is not 0, the "PostImplementRequestNumber " method failed. The outage status is updated to Implemented.

5.1.4PostSubmitRequest

Method Name: / PostSubmitRequest
Description: / This method posts the input OutageSchedule object to the CROW database and submits it.
Input Parameters:
Parameter Name / Requirement / Parameter Type / Description
theOutageSchedule / Required / OutageSchedule / The input OutageSchedule object.
switchingStart / Required / Planned Start / This is part of the input Outage Schedule object. This is the Planned Start of the Outage.
restorationComplete / Required / Planned End / This is part of the input Outage Schedule object. This is the Planned End of the Outage
recallTime / Required / Recall Time / The numeric value represented in minutes, hours, days
recallTimeUnits / Required / Recall Time Units / The valid values are:
Minutes
Hours
Days
Non-recallable / Required / Recall Time and Recall Time Units / Recall Time = 0
Recall Time Units = N
continuousDaily / Required / Continuous/Daily / This is part of the Outage Schedule object. Valid Values are:
Continuous
Return Evenings
Return Weekends
Returns Evenings and Weekends
Noncontinuos
reqRangeType / Required / Outage Duration / This is part of the Outage Schedule object. Valid Values are:
Exactly
Window
reasonPriority / Optional / Requestor Notes / This is part of the Outage Schedule object. This is the Requestor Notes box and is free form.
constraintType / Optional / Equipment/Req. Type / This is part of the Outage Schedule object. This is used if the outage is something other than Out of Service. Valid Values are:
(T, G) 0 – OOS – Out of Service (defaulted if tag is not present)
7 –GSP – General System Protection
6 – HLW – Hot Line Work
20 – Info- Informational
21 – InSvcNO – In Service Normally Open
3 – Derated to
***values can be numeric, abbreviation, or full text.
woNumber / Optional / Work Order Number / This is part of the Outage Schedule object. This is the Work Order Number
causeCode / Required / Cause Code / This is part of the Outage Schedule object. Valid Values depend on priority of the outage. T = Transmission, G = Generation.
(T) BES - BES Condition (Stability, Loading) – 6, 25
(G) BSR – BES Reliability – 6, 25
(T, G) EQF - Equipment Failure – 6, 25
(T) Foreign Interference including Contamination – 6, 25
(T) FPS - Protection System Failure including Undesired Operations – 6, 25
(G) FUS – Fuel Supply – 6, 25
(T, G) OTR – Other – 5, 6, 7, 23, 24, 25
(G) RSE – Regulatory/Safety/Environmental – 5, 6, 7, 25
(T) V – Vegetation – 6, 25
(T) VTM - Vandalism, Terrorism, or Malicious Acts – 6, 25
(T) MC – Maintenance & Construction – 5, 7, 23
(T) TPR – Third Party Requests – 5, 7, 23
(T) SVL – Voltage Mitigation - 24
(T) SOL – SOL Mitigation (Thermal) - 24
(G) RGM – Routine Generator Maintenance – 5, 6, 7, 25
(G) STO – Supporting Transmission Outage – 5, 7
(G) – ECE – Excess Capacity/Economic – 5, 7
*Numeric value indicates which reason code to use with outagePriority
outagePriority / Required / Outage Priority / This is part of the Outage Schedule object. T= Transmission, G = Generation Valid values are: