SOAP / XML Interface

Pensra offers a general purpose XML based mechanism permitting pre-approved sites to query the Pensra database for information stored within it.

Obtaining authorization for Pensra access

Programmatic access to Pensra data via www.pensra.org is controlled by specific Internet IP Address. Thus, if you represent an organization that would like to interface to Pensra, you'll be required to be operating on an identifiable, static IP Address with appropriate/standard DNS (Domain Name Service) entries on the Internet.

Provide the IP Address, the Domain Name, and your Organization's identity to the Pensra Webmaster with a request for approval to access the XML service point.

Formatting a request for information

Data requests (and responses) are sent and received using standard SOAP (Simple Object Access Protocol) mechanisms. The technical description and SOAP calling URL is at http://www.pensra.org/psrService.wsdl

The basic interface permits the caller to provide basic information about who the caller is and the action desired. Available actions are:

Display

Retrieves a single data record from a Pensra table and return the data fields and their existing values from it that have been authorized for return

Show

Specifies a general criteria for searching the Pensra data table and establishes the number of data rows that should be returned.

Request Display service from Pensra

The following example represents an example Request to Display information about a single Match.

<?xml version="1.0" encoding="UTF-8"?> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" xmlns:ns1="urn:pensra.org/rsrService" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ns2="http://xml.apache.org/xml-soap" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:enc="http://www.w3.org/2003/05/soap-encoding"> <env:Body> <ns1:display env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"> <request> <item><key>Set</key><value><item><key>Table</key><value>Matches</value></item></value></item> <item><key>Criteria</key><value><item><key>dmaKey</key><value>107660</value></item></value></item> </request> </ns1:display> </env:Body> </env:Envelope>

A PHP Example

There are a wide variety of languages and mechanisms, as well as programming styles that can be used to request information from the Pensra SOAP Server. The following PHP code snippet represents a very simple example that will retrieve information from Pensra about Match 107660:

$client = new SoapClient('http://www.pensra.org/psrService.wsdl'], array('cache_wsdl'=>WSDL_CACHE_NONE, 'soap_version' => SOAP_1_2)); $request=array('Set'=>array('Table'=>'Matches'),'Criteria'=>array('Key'=>107660)); $values=$client->display($request);

Once a response has been received, the $values variable will contain a multi-level PHP array of keywords and corresponding values.

Server will be an array containing at least:

• Code: the general return code from the Pensra Server, 0 indicates success
• Message: a text message indicating success or the reason for failure of the request
• Rows: the number of Rows in the Data, for Display this should alway be 1
• Version: the software version of the SOAP Server inside Pensra

Data will be an array containing individual elements in Field=>Value format for each data field retrieved from Pensra. As an example, $values['Data']['Date'] will be the scheduled date of the Match. The exact data fields that are available during Display is under the control of the Pensra Webmaster.

The following example is an unparsed SOAP Response from the SFYS TimeSlots SOAP Server containing a Match Key, Date, Time, and Status for the Match:

<?xml version="1.0" encoding="UTF-8"?> <env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" xmlns:ns1="urn:pensra.org/rsrService" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ns2="http://xml.apache.org/xml-soap" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:enc="http://www.w3.org/2003/05/soap-encoding"> <env:Body xmlns:rpc="http://www.w3.org/2003/05/soap-rpc"> <ns1:displayResponse env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"> <rpc:result>response</rpc:result> <response> <item><key>Server</key><value> <item><key>Version</key><value>4.8.0</value></item> <item><key>Code</key><value>0</value></item> <item><key>Message</key><value>Success</value></item> <item><key>Rows</key><value>1</value></item> </value></item> <item><key>Data</key><value> <item><key>Key</key><value>107660</value></item> <item><key>Date</key><value>2012-01-21</value></item> <item><key>Time</key><value">09:00:00</value></item> <item><key>Status</key><value>Normal</value></item> </item> </response> </ns1:displayResponse> </env:Body> </env:Envelope>

Please note that the information presented on this page should not be taken literally. It is, instead, intended to introduce you to how to contact the SFYS TimeSlots SOAP Server for information transfer. The interface itself contains a substantial number of variations and alternatives including access requiring Userid and Password, searching capabilities to retrieve a series of responses meeting complex criteria, etc.

You are encouraged to experiment with the interface (provided your site is authorized to do so) and communicate with the SFYS TimeSlots Webmaster about more complicated requirements you may have.

Standards

For information regarding information transfer standards seehttp://www.w3.org/TR/REC-xml/ For information on how RidgeStar sites exchange XML data via the SOAP server/client see http://www.ridgestar.com/xml/processing

Revised: January 2012