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.

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://wiki.ssdt-ohio.org/x/EBMO

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 smith@nwoca.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:

1. Invoke _login _operation with credentials for an account on the USPS server
2. Optional: Invoke _getDistrictList _to return a list of districts the user can access
3. 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.

{{note|
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.|Important}}

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.

Threaded Clients

The USPS SOAP service will accept multiple simultaneous requests for a given session. However, no guarantees are given regarding the order that the requests will be processed. Threaded client applications must use care if using a shared session.

For this reason, the SSDT recommends that threaded clients synchronize access such that only one thread performs operations for a given session. If multiple threads need to access the service simultaneously, it is preferable to have a separate session per thread, perhaps by maintaining a pool of active sessions.

XML Namespaces

Three distinct namespaces are used to define the service operations and parameters used by the service. These are described briefly below. See the SSDT web site for links to the WSDL and associated XML Schemas.

• http://xml.ssdt.nwoca.org/usps/ws defines the implementation and interface for the SOAP service itself. It defines parameters and operations of the SOAP service. The type definitions for this name space are contained wholly within the WSDL document.
• http://xml.ssdt.nwoca.org/USPS/42 defines the USPS data model. An XML schema is provided that defines the complex types. For certain important USPS data types, user defined types are specified with restrictions that define the allowable content. However, the XML schema does not attempt to express all restrictions imposed by USPS. The service may reject or, in some cases, truncate values that are outside USPS’s normal limits.
• http://xml.ssdt.nwoca.org/OECN-RPC/10 defines complex types used generically by several SSDT products as part of the RPC (Remote Procedure Call) infrastructure. Many of the elements in this namespace are not relevant for the USPS service. The only element of any relevance for USPS developers is the response-msgs, which is used in custom faults to return additional error and warning details (See SOAP Faults below).

SOAP Faults

The WSDL defines custom SOAP faults for application specific errors. The faults are defined to clearly indicate the type of “normal” faults the client should be expected to handle. For example, getEmployee _can throw an _EmployeeNotFoundFault.

However, not all possible faults are defined by the WSDL. All operations are capable of returning generic SOAP faults that indicate general failures. Examples of general failures include: “SessionId not found” (perhaps due to a timeout), connection failures, security violations (the user is not authorized for the operation). The client application should be written to expect and handle both application specific faults and general SOAP faults. The client must not assume that the only faults are those defined by the WSDL.

UspsGeneralFault

UspsGeneralFault is the base fault from which all other application faults are extended. The operations return either UspsGeneralFault directly or a fault message extended from it.

UspsGeneraFault messages always contain at least the standard SOAP fault elements (“faultcode” and “faultstring”). Client applications may minimally use these elements to retrieve the basic error information. Also included are several custom elements that are specific to USPS. The client may use these additional elements to retrieve detailed information about the fault.

The USPS system has the concept of “severity” when returning error conditions. Furthermore, USPS may return multiple errors for a single request. In general, multiple errors are associated with posting and update operations, but may occur for any operation.

When USPS returns multiple conditions of the same or differing severities, the messages are encapsulated in a response-msgs element and included in the fault response. The client may use this element to display to the user or for logging. A response-msgs _element, if present, will contain one or more _fatal, error, or warning elements that define the severity and contain the details of the message. Within these elements, a text element will contain the human readable error message. source, code, _or _vmsstatus elements may also appear, but are not intended for end-users. The latter elements may be useful for debugging or diagnosing problems with the SSDT.

Two other elements of UspsGeneralFault are also for convenience of clients that don’t wish to interpret the entire response-msgs _element. _UspsErrorMessage contains the text of the first message of the highest severity. Clients should use UspsErrorMessage, if only one message is to be displayed or logged. The _Severity _element is an enumerated element that contains the highest severity (Fatal, Error or Warning) of any message in the _response-msgs _element. The _Severity _can be regarded as the overall severity of the fault.

Qualified Success (Warning) Faults

In certain circumstances, USPS business rules require reporting one or more warning conditions as the result of a posting or validation operation. From a SOAP point of view, these faults are unusual because the fault does not indicate failure of the operation. Rather, the operation was successful but was qualified with warnings according to USPS business rules.

In all cases when a warning fault (e.g. PostingWarningFault) is returned, the USPS operation was completed successfully. When performing a posting operation, the client application must check for warning faults and process them as appropriate for the application. The warning might be shown to the user, logged or discarded. If the warning is displayed to the user, it must be shown in context of a successful operation.
The SSDT choose this approach so that the reporting of both errors and warnings in a single response could be handled via the same fault structure. USPS may return a mixture of error and warning messages. Regardless of the severity of the fault, the messages will be returned in a fault derived from UspsGeneralFault and can be extracted from the message in the same manner by the client.

All cases where warning fault can occur are explicitly defined in the WSDL. A client application need only be concerned about a warning fault, if explicitly declared in the binding for the operation.

Document Resource Retrieval

template:Since|Version 1.4-0

The USPS web service provides an optional feature that allows districts and ITC's to provide document resources to a client application. For example, if an ITC or district has Form W2's archived for employees, the archive can be configured in the USPS web service. An application may access these archives by providing key information (e.g. employee id and tax year) to retrieve the archived document.

The archived documents are secured via the same mechanism as the other USPS services. The client application must provide a SOAP sessionId and access to documents is restricted to documents for the authorized district.

REST-style Interface

Because resources are expected to be unstructured (non-XML) or binary documents, this portion of the USPS web service is not based on standard SOAP. Although SOAP has extensions which support unstructured attachments, the interfaces are more complex. Therefore, resource retrieval is based loosely on a REST concepts to ease access by simple HTTP clients.

The protocol for accessing archived resources is based exclusively on HTTP/1.0 features and does not depend on any other SOAP or XML standards.

URL Syntax

The "retrieval" service resides at the same context as the standard USPS SOAP endpoint. Except, instead of "/services/USPSWS", the retrieval service resides at "/retrieve/". For example, if the endpoint address is "https://domain.com/uspsoap/services/USPSWS" then the address of the retrieval service will be "https://domain.com/uspsoap/retrieve/".

The retrieval service uses the remainder of the path info and query string to determine the desire resource to retrieve. The syntax is:

• resourceType defines the type of resource being requested (e.g. "W2", "check", "resume").

• p1 thru pN are optional positional parameters which may be used to define the requested resource.

  field=value are named parameters passed as query string fields which may be used to define the requested resource. For example "employee.id" and "tax.year" might be used to define a "W2" resource. A wild card ("") may be specified for a variable to request a list of matching documents that are available.

The service is agnostic regarding the types of resources available. They are configured by the ITC hosting the service. Therefore, the ITC and developer must agree on the resource type, parameters and field names for each resource.

SOAP Session Id Header

Prior to accessing a resource, the client application must acquire a SOAP Session Id from the "login" and use "setDistrictAccess" to select the appropriate district prior to attempting to retrieve a resource. The retrieval service will use the district configuration and login credentials to determine if the client is authorized to access the requested resource.

The SOAP Session Id must be provided in a custom HTTP header called "x-USPSSOAP-sessionid", for example:

If the session id is not provided the request will fail with a 400 (BAD REQUEST) response code.

template:note|It may appear that this URL may be sent to a user's browser to allow the user's browser to access the resource. This is not the case. Aside from the difficulty of getting a browser to insert a custom header, the SOAP session Id should never be exposed to an end-user client. This is especially true of a "kiosk" type application where multiple end-users share a master SOAP account. Exposing the SOAP session id would introduce a significant security vulnerability. Further, the SOAP service endpoint may not be directly accessible to an end-user browser due to firewall constraints at the ITC.|Important

Request Methods

The retrieve service currently supports these HTTP request methods:

• GET attempts to retrieve the resource and returns it's contents.
• HEAD determines if the resource is available and returns an appropriate response code.

Response Codes

The retrieval service returns the following response codes:

• 200 resource was located (and returned if GET request)
• 404 the resource type is configured but the specified resource was not found
• 400 all other permanent errors. The response message may further indicate the reason for the failure. 400 response errors include:
  • Resource type not configured
  • Resource type configured incorrectly
  • Missing SOAP session header

Response Type

The response will be a standard HTTP response with "Content-Type" set to the type of resource being returned (application/pdf, text/html, etc).

If a wild card was specified in a request variable, or more than one document was found to match the request, then the content-type will be "text/x-resources". The body of the response will contain a list of URL's delimited by a new line character. The URLs will be in a format suitable for making a subsequent request for the individual documents.

Examples

Assume the ITC has established a resource archive called "W2" which contains archives of PDF W2 Forms by employee for multiple tax years. The following are valid requests and the like responses:

Returns all URL's found for the specified employee

Returns all URL's for all documents for the specified year