Introduction

This guide describes the OECN State Software USAS SOAP service. This guide is intended for software developers interested in using SOAP to integrate with or add alternative interfaces to USAS.

This guide assumes basic familiarity with USAS and the USAS account coding scheme. It also assumes the reader is familiar with SOAP, XML and other related technologies.

Glossary

• DAS or DA Site - Data Acquisition Sites. This term is obsolete. OECN sites are now refered to as ITC's
• ITC - Information Technology Centers are regional data processing centers that provide computer services to member school districts. Among the services ITC's provide is hosting of the USAS application for school districts.
• OECN -
   Ohio Education Computer Network
• SSDT - State Software Development Team develops USAS, and other software, for school district on behalf of the Ohio Department of Education.
• USAS - Uniform School Accounting system. USAS refers to both the USAS software developed by the SSDT on behalf of the Ohio Department of Education, and the USAS accounting structure defined by the Ohio Auditors of State and Ohio Department of Education.

Status of this Document

This document is updated routinely to reflect the current version of the USAS SOAP service. Links to the latest version of this document can be obtained from the SSDT Public Wiki at httphttps://wiki.ssdt.oecn.k12.oh.us/USAS_SOAP_Developers_-ohio.org/display/CTD/USAS+SOAP+Developers+Guide

Resources

This document does not represent the complete documentation for the USAS SOAP service. The actual API documentation is contained in the WSDL, the USAS XML Schema and the OECN RPC XML schema.

The WSDL and Schemas are distributed by the SSDT as part of the SOAP service installation kit. Vendors should contact the school district's ITC or the SSDT for the WSDL for currently supported versions. The current development version of the USAS SOAP service is available at: http://devel.ssdt.nwoca.org/usassoap/. The latest WSDL and Schemas are available on that page The latest WSDL and Schemas are available at /wiki/spaces/rtd/pages/2753089.

Developers who need background documentation on USAS may wish to refer to the USAS User and Reference Manuals or the USAS System Managers Guide. This . These documents are available on-line at httphttps://ssdtmcoecn.oecn.k12.oh.us/projects/usas .

Developers who have questions or need technical advice on integrating with the USAS webservice are encouraged to join the ssdt-usas-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.nwoca.org/cgi/wa.exe?A0=ssdt-usas-dev-l.

Status of the USAS SOAP Service

The USAS SOAP atlassian.net/wiki/x/6oA2 .

Status of the USAS SOAP Service

The USAS SOAP service provides a limited subset of USAS functionality via a standards based SOAP service. See the WSDL for business functions supported by the service.

Standards Compliance

The SSDT believes that USAS SOAP service complies with the WS-I Basic Profile 1.0a WS-I Basic Profile 1.0a . The artifacts (definitions and messages) of the service have passed all assertions tested by the “WS-I Testing Tools v 1.0.1” provided by WS-I.

The SSDT believes that the WS-I BP 1.0a is the best solution to ensuring interoperability between various SOAP implementations. Developers wishing to use the USAS 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 USAS may not have access to a USAS server for development and testing. The SSDT can provide access to a test server for development and testing. The test server will always have the most recent released version of the web service. 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 becher@ssdt-ohio.org with their request. Please include contact information, company and a brief description of your application and intended use.

USAS Service Architecture Overview

The USAS system is hosted on servers operated by individual ITC's for their member school districts. Each server hosts a USAS database for one or more school districts.

District Database Identification

Each 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.

SOAP Service Endpoints

Each ITC that supports the USAS SOAP service will provide one or more “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 DA Site. However, in some cases, an ITC may provide a different endpoint for specific districts.

Most ITC Separate endpoints are used for each district.   

SOAP Service Endpoints

A separate endpoint will be provided for each school district.

ITC's will provide an HTTPS (SSL) end-point can be used to encrypt SOAP messages on the wire. Developers are encouraged required to use HTTPS when available. Each ITC decides whether HTTPS is available or required and may have other local security policies regarding from what networks SOAP connections are available.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 DA Site ITC on behalf of the member district. The access rights and functions the account can perform are limited by rights granted by the ITC and any USAS security profiles established by the district.

...

A given user account on a USAS 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 USAS profile established by the district (see USAS User Profiles below).

USAS User Profiles

The USAS SOAP service applies all business rules and security implemented by the USAS system. This includes per-district user profiles. User profiles are a feature of USAS that permit fine grained control over what functions a user is able to perform and which USAS budget accounts they can see or use in transactions. 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 USAS 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.

Assuming Profile of Another User

A special feature of the service allows a sufficiently privileged account to assume (or impersonate) the profile of another USAS user. If a SOAP client impersonates another profile, any operations it performs will be limited by the impersonated user’s profile.

This may be useful in situations where the client application uses a single account to access USAS, but still wishes to use USAS security features to limit what accounts can be seen or functions performedUSAS security features to limit what accounts can be seen or functions performed.

When posting requisitions, the username used in the impersonation call will also be used as the "requisitioner" in USAS.  This is currently true only for requisitions and not for any other data types.

Mapping Foreign Users to USAS Profiles by Convention

When assuming the role of another user, USAS does not interpret the username in any special way against a particular authentication source. USAS simply uses the profile name “as is” and looks for a corresponding profile.

...

USAS SOAP Service Details

This section contains details of using the USAS 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 details for each operation, parameters and data types.

SOAP Sessions

The USAS 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 USAS 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.

...

1. Invoke _login _operation with credentials for an account on the USAS server
2. Optional: Invoke _getDistrictList _to return a list of districts the user as access to
3. Optional for Redesign: Invoke _setDistrictAccess _to bind the session to a given district database
4. Optional: Invoke assumeUserProfile to assume the profile of another user

After these steps are completed, the client may invoke any other USAS 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 client may invoke any other USAS 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.

After the database context is established, the client application may optionally invoke assumeUserProfile to impersonate the profile of a different USAS user. This operation will only succeed if the authenticated user is authorized to impersonate other users and if a suitable profile exists on the USAS server. The _assumeUserProfile _operation may be used multiple times for a given session.

Session Timeout

Sessions consume resources on both the SOAP server and the back-end USAS server. Therefore, inactivity timeouts apply to the SOAP sessions. The timeout interval is configurable by each DA Site ITC and defaults to approximately 45 minutes. If there is no activity for a session in 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 USAS 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, especially when using multiple invocations of _assumeUserProfile _with other operations.

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/usas/ws

http://xml.ssdt.nwoca.org/USAS/61

http://xml.ssdt.nwoca.org/OECN-RPC/10

See #Resources for links to the schemas.

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, getBudgetAccount can throw an AccountNotFoundFault.

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.

UsasGeneralFault

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

...

Two other elements of UsasGeneralFault are also for convenience of clients that don’t wish to interpret the entire response-msgs _element. _UsasErrorMessage contains the text of the first message of the highest severity. Clients should use UsasErrorMessage, 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, USAS 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 USAS business rules.

...

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.

Auto-Assignment of Transaction Numbers

As of version 2.0 of the USAS SOAP service, most of the "posting" operations now support automatic assignment of transaction numbers. In previous versions, the application was required to determine the transaction number (e.g. purchase order number) before posting a new transaction.

In version 2.0, the transaction numbers are optional elements (may be omitted or empty). When the transaction number is not provided, the SOAP service will automatically assign the next available number.

Response Document

Prior to version 2.0, posting operations, such as "postNewPurchaseOrder", returned an empty ("void") response. In version 2.0, it will return the actual <PurchaseOrder> element as posted with the assigned transaction number. Therefore, the client application will be able to determine the number that was assigned to the new transaction.

The use of this new feature is optional. The client application may continue to assign transaction numbers, if desired. In either case, an instance of the posted element will be returned on "post" operations.

"Split" Items on Requisitions or Purchase Orders

USAS requisitions and purchase orders support "splitting" an item into multiple accounts, allowing it to be printed as one line on the requisition or purchase order but stored as multiple lines each charged to a separate account code.

...

There are 2 ways of combining items, splitting the quantity and splitting the price.

Splitting the Quantity

This type of split involves splitting the quantity of a particular item among several different account codes. The unit price must be the same for each item. For example:

...

Resulting printed PO item:

Splitting the Price

This type of split involves splitting the price of a particular item among several different account codes. The quantity field must be 1 for the combined item and zero for the split items.

...

Resulting printed PO item:

Usage of "<SplitTag>"

In the requisition or purchase order xml document, the tag <SplitFlag> is required to be included as a part of the <item> information for both the combined and split items. The following values are accepted:

Restrictions

There must always be a "Combined" item first, immediately followed by one or more "Split_Price" or one or more "Split_Quantity" items. There cannot be both "Split_Price" and "Split_Quantity" items associated with the same "Combined" item.

...

The quantity field must be 1 for the "Combined" item and zero for all "Split_Price" items.

Appendixes

Fault Message Codes

The table below defines response message codes returned by the USAS SOAP service faults. The codes define the nature of the fault in greater detail.

...