USPS SOAP Developers Guide
Introduction
This guide describes the OECN State Software USPS SOAP service. This guide is intended for software developers interested in using SOAP to integrate with or add alternative interfaces to USPS.
This guide assumes basic familiarity with USPS. It also assumes the reader is familiar with SOAP, XML and other related technologies.
This documentation applies to both the Classic and Redesign versions of USPS. Except as noted in the document the Redesign and Classic API's of the SOAP services are compatible.
Glossary
ITC, Information Technology Centers are regional data processing centers that provide computer services to member school districts. Among the services ITCs provide is hosting of the USPS application for school districts.
OECN, Ohio Education Computer Network
SSDT, State Software Development Team develops USPS, and other software, for school district on behalf of the Ohio Department of Education.
USPS, Uniform School Payroll System, USPS refers to the USPS software developed by the SSDT on behalf of the Ohio Department of Education.
Status of this Document
This document is updated routinely to reflect the current version of the USPS SOAP service.
Links to the latest version of this document can be obtained from the SSDT Public Wiki site at: https://mcoecn.atlassian.net/wiki/x/_AYm
Resources
This document does not represent the complete documentation for the USPS SOAP service. The actual API documentation is contained in the WSDL, the USPS XML Schema and the OECN RPC XML schema. These documents are available from the the actual installation of the USPS SOAP service. Developers can find the current development version of the documents at: http://devel.ssdt.nwoca.org/uspssoap/
Developers who need background documentation on USPS may wish to refer to the USPS User and Reference Manuals or the USPS System Managers Guide. These documents are available on-line at http://ssdt.oecn.k12.oh.us/documentation .
Developers who have questions or need technical advice on integrating with the USPS web service are encouraged to join the ssdt-usps-dev-l list. This list is operated by the SSDT to assist developers with integration issues. For subscription options and to view the archives, visit http://listserv.oecn.k12.oh.us/archives/ssdt-usps-dev-l.html.
To view a list of changes made to the USPS XML Schema for version 1.6 onward of the USPS SOAP service, view the Updates to USPS XML Schema page.
Status of the USPS SOAP Service
The USPS SOAP service provides a limited subset of USPS functionality via a standards based SOAP service. See the WSDL document and documentation for supported functions.
Other USPS functionality will be added in the future. Developers, who need access to specific USPS functions or transactions, should contact the SSDT so we can prioritize our work in this area appropriately.
Standards Compliance
The SSDT believes that USPS SOAP service complies with the WS-I1 Basic Profile 1.0a (http://www.ws-i.org/). The artifacts (definitions and messages) produced by and consumed by the service have passed all assertions tested by the “WS-I Testing Tools v1.0.1” provided by WS-I.
The SSDT believes that the WS-I BP is the best solution to ensuring interoperability between various SOAP implementations. Developers wishing to use the USPS SOAP service are encouraged to use client tools that can support WS-I compliant services. Any developer detecting a WS-I compliance issue in the service artifacts is encouraged to contact the SSDT.
Test Accounts
Developers intending to integrate with USPS may not have access to a USPS server for development and testing. The SSDT can provide access to a test server to interested developers. The test server will always have the most recent released version of the webservice. A user account can be provided which has access to a sample district database with limited test data.
Developers interesting in a test account should send mail to davis@ssdt-ohio.org with their request. Please include contact information, company and a brief description of your application and intended use.
USPS Service Architecture Overview
The USPS system is hosted on servers operated by individual ITCs for their member school districts. Each server hosts a USPS database for one or more school districts.
District Database Identification
For Classic USPS a single SOAP service endpoint is used to access all district databases at an ITC. Each unique database is identified by a "district code" or IRN. Some ITC's also support the use of NCES codes to identify district databases. After a SOAP client authenticates with the SOAP service, it must declare the district database on which it intends to operate. Alternatively, the SOAP client may query the service for the databases the user has access to and allow the user to select the district code.
For Redesign USAS, a separate endpoint is used for each district. In Redesign implementations of the SOAP service, the setDistrictAccess operation is a NOOP and is not necessary.
SOAP Service Endpoints
Each ITC that supports the Classic USAS SOAP service will provide one “SOAP endpoint” URL's for accessing the service for their districts. In most cases, a single endpoint will be used for all districts hosted by a given ITC Site. However, in some cases, an ITC may provide a different endpoint for specific districts.
For Redesign USAS SOAP, a separate endpoint will be provided for each school district.
ITC's will provide an HTTPS (SSL) end-point to encrypt SOAP messages on the wire. Developers are required to use HTTPS for production instances.
Authentication and Authorization
When a client connects to the service, it must provide username and password credentials for an account on the ITC server. Usernames and access rights are administered by the ITC on behalf of the member district. Rights granted by the ITC and any USPS security profiles established by the district limit the access rights and functions the account can perform.
The account used to access the SOAP service may be a normal end-user account of a standard USPS user. A normal user account does not need special rights to use the SOAP service. This sort of access is appropriate, for example, when providing an alternative interface to USPS and the back-end service is being used for authentication (pass-through authentication).
Alternatively, the ITC may provide a specific account to be used for SOAP access by specific trusted applications. This might be appropriate for an application that has its own authentication scheme that is being integrated with USPS.
For example, an “Employee Kiosk” application might have it’s own user accounts and authentication scheme and might be configured to use a single USPS account to query employee information. This type of access must be negotiated between the developer, ITC and school district. All parties must be aware that this access model effectively turns much of the USPS security over to the third party application. The district and ITC must determine if the developer’s product is to be trusted in this model.
A given user account on a USPS server may be granted access to one or more school district databases. Therefore, the ITC might provide a single account to access multiple districts, or a separate account for each district. If when a single account is used, the users rights in each district may vary based on the USPS profile established by the district (see USPS User Profiles below).
USPS User Profiles
The USPS SOAP service applies all business rules and security implemented by the USPS system. This includes per-district user profiles. User profiles are a feature of USPS that permit fine-grained control over what functions a user is able to perform. A school district can establish profiles that control what any user (including users of the SOAP service) are able to perform.
A developer need not have any special understanding of how USPS security works or how it is applied. The security is applied automatically by the server based on the security settings and profiles established on the server. However, faults can be returned if an operation is performed that the user account is not authorized to perform.
USPS SOAP Service Details
This section contains details of using the USPS SOAP service operations and parameters. Items in italics refer to operations (methods), parameters or element names provided used the service. See the WSDL or generated WSDL documentation for more detailed description of the operations, parameters and data types.
SOAP Sessions
The USPS SOAP service is a “statefull” service. The login _operation, upon successful authentication, establishes a new session and returns a _sessionId. The session retains a connection to the USPS server and context for subsequent invocations of the service. The client application must retain this session id and pass it as a parameter to subsequent invocations of the service.
The steps for establishing a session are:
Invoke _login _operation with credentials for an account on the USPS server
Optional: Invoke _getDistrictList _to return a list of districts the user can access
Optional for Redesign: Invoke _setDistrictAccess _to bind the session to a given district database
After these steps are completed, the client may invoke any other USPS operation. The client may perform as many operations as necessary to perform its work. When the client is finished using the service, it should invoke the _logout _operation to cleanly close down the session.
It is important that the client invoke setDistrictAccess code to establish the district database to which the session is bound. This must be done exactly once after login and prior to any other USPS operation.
A client must not invoke _setDistrictAccess _more than once for a session. A fault will be returned if such an attempt is made and the session will be left in an indeterminate state. Client applications that need to access more than one district, must establish at least one session for each district.
Session Timeout
Sessions consume resources on both the SOAP server and the back-end USPS server. Therefore, inactivity timeouts apply to the SOAP sessions. The timeout interval is configurable by each ITC and defaults to approximately 45 minutes. If there is no activity for a session during the timeout interval, the session will be deleted from the SOAP service. Any subsequent invocations using an expired sessionId will result in a fault being returned. Client applications that attempt to maintain long running connections, must be prepared to handle such faults.