1 Preamble

1.1 Abstract

The SIF Reporting web service is designed independently of SIF Implementation Specification versions to allow applications outside of SIF Zones to access the wealth of data in those Zones via SIF's reporting objects, ReportManifest, SIF_ReportObject and ReportAuthorityInfo. A Reporting service implementation may be closely bound to the reporting capabilities of a given Zone or Zones, or it may provide ad hoc access to data via the report generation capabilities of the service implementation itself. In either case, with the availability of this service description, state agencies, school districts, schools and other entities have an industry-standard method for retrieving report data from SIF Zones without knowledge of the internal details of--or the need to participate directly in the day-to-day operations of--given SIF Zones/Implementations.

1.2 Disclaimer

The information, software, products, and services included in this specification may include inaccuracies or typographical errors. Changes are periodically added to the information herein. SIFA may make improvements and/or changes in this document at any time without notification. Information contained in this document should not be relied upon for personal, medical, legal, or financial decisions. Appropriate professionals should be consulted for advice tailored to specific situations.

SIFA, ITS PARTICIPANT(S), AND THIRD PARTY CONTENT PROVIDERS MAKE NO REPRESENTATIONS ABOUT THE SUITABILITY, RELIABILITY, TIMELINESS, AND ACCURACY OF THE INFORMATION, SOFTWARE, PRODUCTS, SERVICES, AND RELATED GRAPHICS CONTAINED IN THIS DOCUMENT FOR ANY PURPOSE. ALL SUCH INFORMATION, SOFTWARE, PRODUCTS, SERVICES, AND RELATED GRAPHICS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. SIFA AND/OR ITS PARTICIPANT(S) HEREBY DISCLAIM ALL WARRANTIES AND CONDITIONS WITH REGARD TO THIS INFORMATION, SOFTWARE, PRODUCTS, SERVICES, AND RELATED GRAPHICS, INCLUDING ALL IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT.

IN NO EVENT SHALL SIFA, ITS PARTICIPANT(S), OR THIRD PARTY CONTENT PROVIDERS BE LIABLE FOR ANY DIRECT, INDIRECT, PUNITIVE, INCIDENTAL, SPECIAL, CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF USE, DATA, OR PROFITS, ARISING OUT OF OR IN ANY WAY CONNECTED WITH THE USE OR PERFORMANCE OF THIS DOCUMENT, WITH THE DELAY OR INABILITY TO USE THE DOCUMENT, THE PROVISION OF OR FAILURE TO PROVIDE SERVICES, OR FOR ANY INFORMATION, SOFTWARE, PRODUCTS, SERVICES AND RELATED GRAPHICS OBTAINED THROUGH THIS DOCUMENT OR OTHERWISE ARISING OUT OF THE USE OF THIS DOCUMENT, WHETHER BASED ON CONTRACT, TORT, STRICT LIABILITY, OR OTHERWISE, EVEN IF SIFA, ITS PARTICIPANT(S), OR THIRD PARTY CONTENT PROVIDERS HAVE BEEN ADVISED OF THE POSSIBILITY OF DAMAGES. BECAUSE SOME STATES/JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION MAY NOT APPLY TO YOU. IF YOU ARE DISSATISFIED WITH ANY PORTION OF THIS DOCUMENT OR WITH ANY OF THESE TERMS OF USE, YOUR SOLE AND EXCLUSIVE REMEDY IS TO DISCONTINUE USING THIS DOCUMENT.

This specification is released with the following provisos to developers and educators.

1.3 Certification and Compliance Claims

Though a product may be demonstrated to comply with this specification, no product may be designated as SIF Certified™ by an organization or individual until the product has been tested against and passed established compliance criteria, published separately.

2 Introduction

2.1 Specification Organization

2.2 Document Conventions

2.2.1 Definitions

The first time a term or concept is defined, it may be emphasized.

2.2.2 Structure and Values

SIF message and object names, XML element tags, attribute names and values, and other codes or values are typically presented as in this sentence.

2.2.3 Examples

2.2.4 References

2.2.5 Terminology

2.3 Version Numbers

This specification uses the following version numbering scheme:

major version.minor versionrrevision number

This version of the specification is a major release, and the first release of a major version has a minor version of 0 (2.0); major version numbers start at 1 and are incremented as major versions are released (1.0, 2.0, 3.0, ...). Major versions typically introduce additions/changes that may impact deployed applications.

Minor releases typically introduce to the marketplace new optional functionality or optional extensions to existing functionality. The first minor version released subsequent to and within a major release has a minor version of 1 and is incremented as new minor versions are released (2.1, 2.2, ...). If a significant number of minor release features is introduced in a specification, SIFA may decide to increment the minor version number by more than 1 (e.g. 1.1 to 1.5), though a number like 1.5 is not an indication of being halfway to a major release, as minor version numbers may be incremented significantly past 10 (2.10, 2.11, ...) as optional functionality is released.

Corrections resulting from identified errata, as well as textual changes, may be incorporated into a revision release. These typically include minor corrections to specified functionality, corrections of typographical errors, or corrected/expanded documentation. If major errors in any release are identified, a revision release may incorporate changes more typical of a major or minor release. First major and minor releases have a revision number of 0, which is omitted from the version number (1.0, not 1.0r0); subsequent revision numbers start at 1 and are incremented as new revisions are released (1.0r1, 1.0r2, ...).

3 Architecture

3.1 Assumptions

The following assumptions are made of readers of this specification:

3.2 Concepts

A SIF Reporting client is also known as a Report Requester. The application submits a ReportManifest to a server and retrieves the resulting report as a SIF_ReportObject packet stream as it becomes available. Typically the Report Requester defines the ReportManifest itself, specifying the data it requires from the server, or Report Servicer, but it may also submit pre-defined ReportManifests, retrievable through the service itself, i.e. a ReportManifest defining all ReportManifests be returned in a report. Note that while the SIF vertical reporting functionality allows for a report to be resubmitted for a number of reasons (e.g. correction, revision, addition), in the Reporting web service there is a one-to-one mapping between a ReportManifest and the resulting report; if more than one report results for a given ReportManifest submission, it is implementation defined which report is singled out as the resulting report by the Report Servicer.

3.3 Interoperability

3.3.1 Requirements

4 Service Definition

This section describes the SIF Reporting Service at a high level and provides tabular descriptions of related XML structures. The normative source of these structures and definitions can be found in the corresponding WSDL files.

The namespace for this web service is http://specification.sifinfo.org/WebServices/Reporting/1.0.

4.1 GetResponderCapabilities

This method provides the client the ability to ascertain various capabilities of the server. Given the breadth of possible server implementations, especially with regard to "thin" implementations routing ReportManifests to SIF Zones or other systems where some of these capabilities truly lie, clients MAY attempt subsequent functionality not reflected as supported in ResponderCapabilities. Clients SHOULD consult ResponderCapabilities, as unnecessary errors can be avoided (e.g. a server not supporting a given SIF version or query type) in subsequent methods.

4.1.1 Request

4.1.2 Response

ResponderCapabilities returns the capabilities of the server to the client.

4.2 RequestReport

With this method the client submits a ReportManifest to the server indicating the data it would like to retrieve in the form of a report, which is a packet stream where each available packet consists of one or more SIF_ReportObjects. The client may optionally identify itself or its user with a ReportAuthorityInfo with optional contact information.

4.2.1 Request

4.2.2 Response

4.3 GetReportStatus

With this method the client can check the status of a given report submission. When the status is Ready, the client can commence retrieving the SIF_Object packet stream that makes up the generated report data.

4.3.1 Request

4.3.2 Response

4.4 GetReportResults

When a report submission status is Ready, the client uses this method to retrieve any associated SIF_ReportObjects in a stream of packets.

4.4.1 Request

4.4.2 Response

4.5 CloseReport

A client at any time can close a report; the server may terminate any processing associated with the corresponding report submission and may delete any information associated with the report token, as well as the token itself.

4.5.1 Request

4.6 CancelReport

A client at any time may cancel a report; the server may have special processing associated with this request that distinguishes it from a CloseReport or the processing may be identical. The results of both methods should appear the same to the client, though servers MAY return a ReportStatus/Code of Cancelled when a client requests the status of a cancelled report.

4.6.1 Request

Appendix A: SIF Agent Implementation (non-normative)

While some Reporting Service implementations will likely bypass the data distributed across SIF Applications in a Zone and service report requests directly against, for instance, data warehouses, there is a natural standard SIF Agent-based Reporting service implementation that routes incoming ReportManifests to a SIF Zone and listens for corresponding SIF_ReportObject reports that result in a Zone, making those reports available to Reporting Service clients. This appendix presents a very high-level functional specification for such an Agent, called SIF Reporting Agent here. It is by no means definitive and creative implementations could provide richer functionality.

A.1 Assumptions

There exists a SIF Zone that is the source for ReportManifest objects, and there exists a Zone that is the source for SIF_ReportObject reports that are submitted in response to available report manifests. These may be the same Zone, two Zones or a multitude of Zones. For the sake of this appendix they will be referred to as a single Zone. An actual implementation can easily support multiple Zones as a configuration option.

A.2 Preconditions

The SIF Reporting Agent must have permissions in the Zone to publish events for ReportManifest and ReportAuthorityInfo. It must have permissions to send requests for ReportManifest and SIF_ReportObject and to receive events for SIF_ReportObject. If there is no Provider in the Zone for ReportManifest or if the Provider does not update its database to reflect ReportManifests added to the Zone, the Reporting Agent may need permissions to respond to requests for and/or provide ReportManifest. The same applies for ReportAuthorityInfo.

Given these permissions, it is assumed the Agent has then registered in the Zone and announced subscriptions for SIF_ReportObject and optionally ReportManifest and ReportAuthorityInfo if it wishes to dynamically track added/changed/deleted ReportManifest and ReportAuthorityInfo objects rather then sending requests for these objects as needed. If it maintains its own database of these objects, the Agent has synchronized/requested all necessary objects accordingly. Finally, it maintains a database of tokens that correspond to ReportManifests it has submitted/will submit to the Zone, along with the RefId of the ReportManifest and any related status information (e.g. status, state of handling SIF_ReportObjects, etc.

A.3 Reporting Service Operation/Message Handling

A.3.1 GetResponderCapabilities

The Reporting Agent needs to return its capabilities, but as the Agent is essentially a go-between between a Reporting client and one or more SIF Zones and for the most part is not creating reports in response to submitted ReportManifests, the Agent needs to return the SIF versions of any Zones to which it is connected in ResponderCapabilities/SupportsSIFVersion. It should return false in ResponderCapabilities/SupportsOutOfOrderPacketRequests unless it will locally store SIF_ReportObject responses without discarding them after being returned, in which case it should be able to support out-of-order packet requests, within the bounds of current packets received. As it is other Agents in the Zone that actually produce SIF_ReportObjects, determining the query languages supported in the Zone is difficult--it is best left to a configuration option how to populate ResponderCapabilities/SupportsQueryLanguage, though if the Reporting Agent will itself produce a report of available ReportManifests, it could include that it supports SIF_Query and/or SIF_ExtendedQuery. SupportsQueryLanguage MAY be omitted, if necessary.

A.3.2 RequestReport

If the Agent wishes to handle report generation for ReportManifest-related reports and the incoming Manifest/ReportManifest specifies query conditions isolated to ReportManifest, it may handle the ReportManifest itself or forward it on as any other report (below) to the Zone if it is known that an Agent will handle such a ReportManifest (possible configuration option). If it does generate the report itself, no events need be published to the Zone and the Agent bypasses related steps below with generation of the report locally, either from its own database of ReportManifests in the Zone or by sending out a request for ReportManifests in the Zone.

The Reporting Agent allocates a new report token in its database.

Upon receipt of a report request, the Reporting Agent should submit Add event(s) for the submitted Manifest/ReportManifest and optional Authority/ReportAuthorityInfo. The Agent must have a buffer size compatible with the SIF_MaxBufferSize in the submitted ReportManifest, or reduce the SIF_MaxBufferSize in the ReportManifest accordingly. The Agent must never increase the SIF_MaxBufferSize, otherwise it may exceed the client's buffer capabilities. It is intended that Reporting clients submitting ReportAuthorityInfo use the same RefId for ReportAuthorityInfo structures used consistently, so the Agent could check the Zone or its local database of ReportAuthorityInfo objects before adding the ReportAuthorityInfo to the Zone, as it may already exist.

The Agent updates the status associated with this report token/submission depending on the success/failure of these Add events.

The Agent returns the allocated token in ReportID.

A.3.3 GetReportStatus

The Agent refers to its database of report tokens. If the supplied ReportIDForStatus does not exist, it returns a ReportStatus/Code of NoSuchReport. Otherwise it checks the current status associated with the token. If a corresponding report is available, the Agent returns Ready, otherwise if no error has occurred with regard to the submission, NotReady is returned. If the client has cancelled the report or for some reason the Reporting Agent has cancelled the report, the Agent returns Cancelled. Otherwise the Agent returns an appropriate error condition, currently either Error or Rejected, the latter due primarily to configured permissions.

A.3.4 GetReportResults

If the submitted ReportPacketRequest/ReportID does not match a report token in the Agent's database or if the status of the report is an error condition or if the submitted PacketNumber is invalid (e.g. not equal to the current available packet number when out-of-order packets aren't supported, or when the packet number is out of bounds when they are), it returns a SOAP fault. If the status of the report is NotReady, the Agent returns a NextPacketNumber equal to the submitted PacketNumber. Otherwise the Agent attempts to retrieve the packet from a local database or its message queue. If the packet is available, it returns a NextPacketNumber of PacketNumber + 1 unless this is the last packet (the corresponding SIF_Response with SIF_MorePackets of No has been reached), in which case it returns a NextPacketNumber of 0. If the packet is not yet available, the Agent returns a NextPacketNumber of PacketNumber. Otherwise the Agent supplies the SIF version of the corresponding packet (SIF_Response) in SIF_Version and any SIF_ReportObjects from the response in ReportObjects. The Agent updates any state information with regard to the packet stream.

A.3.5 CloseReport

If the submitted ReportPacketRequest/ReportID matches a report token in the Agent's database, it deletes the associated ReportManifest from the Zone and the associated ReportAuthorityInfo, if any, and clears any associated state information related to the token, then deletes the token from its database.

A.3.6 CancelReport

The Agent performs the same functionality as for CloseReport.

A.4 SIF_Event Handling

A.4.1 SIF_ReportObject Add

If ReportInfo/@ReportManifestRefId is equal to the ReportManifest/@RefId submitted to the Zone by the Agent, it sets the status associated with the corresponding report token to Ready. This SIF_ReportObject is the first SIF_ReportObject in the packet stream; it may be stored or it may be discarded, as when the Agent sends out a request for the report, this same SIF_ReportObject will be the first SIF_ReportObject in the response stream. The Agent does then indeed send out a SIF_Request for the SIF_ReportObject, specifying SIF_ReportObject/@RefId from this SIF_ReportObject in the query condition for the request. Each SIF_Response received is a packet. The Agent may store these locally as they arrive, referring to the local store when handling GetReportResults, or, less likely, could pull them out of its queue as needed when handling GetReportResults.

Appendix B: WS-Security Examples (non-normative)

For implementers undertaking a secure SIF Reporting implementation with WS-Security opposed to or in addition to HTTPS, two examples of a SIF Reporting SOAP invocation (GetResponderCapabilities), one signed using an X.509 certificate and one encrypted using an X.509 certificate, are provided here.

B.1 Unencrypted

B.2 Encrypted

Appendix C: Index of Tables

Appendix D: Index of Examples

Appendix E: References