1、 ANSI/NISO Z39.93-2014 ISSN: 1041-5653 The Standardized Usage Statistics Harvesting Initiative (SUSHI) Protocol Abstract: This standard defines an automated request and response model for the harvesting of electronic resource usage data utilizing a Web services framework that can replace the user-me
2、diated collection of usage data reports. It was designed as a generalized protocol extensible to a variety of usage reports. An extension designed specifically to work with COUNTER reports is provided. The standard is built on SOAP (Simple Object Access Protocol) for transferring request and respons
3、e messages. The GetReport method is used for transferring ReportRequest as the input message and returning ReportResponse as the output message. The standard is accompanied by a versioned Web Services Description Language (WSDL) to describe the Web service namespace and operations, and an XML schema
4、 constraining the syntax of the SUSHI transaction. Rules for report naming are outlined and complemented by an external reports registry, which provides for the definition of both COUNTER and non-COUNTER reports. An American National Standard developed by the National Information Standards Organizat
5、ion Approved December 5, 2014 by the American National Standards Institute ANSI/NISO Z39.93-2014 About NISO Standards NISO standards are developed by the Working Groups and Standing Committees of the National Information Standards Organization, with oversight by a Topic Committee. The development pr
6、ocess is a strenuous one that includes a rigorous peer review of proposed standards open to each NISO Voting Member and any other interested party. Final approval of the standard involves verification by the American National Standards Institute that its requirements for due process, consensus, and
7、other approval criteria have been met by NISO. Once verified and approved, NISO Standards also become American National Standards. These standards may be revised or withdrawn at any time. For current information on the status of this standard contact the NISO office or visit the NISO website at: www
8、.niso.org. Published by National Information Standards Organization (NISO) 3600 Clipper Mill Road Suite 302 Baltimore, MD 21211 www.niso.org Copyright 201x by the National Information Standards Organization All rights reserved under International and Pan-American Copyright Conventions. For noncommer
9、cial purposes only, this publication may be reproduced or transmitted in any form or by any means without prior permission in writing from the publisher, provided it is reproduced accurately, the source of the material is identified, and the NISO copyright status is acknowledged. All inquiries regar
10、ding translations into other languages or commercial reproduction or distribution should be addressed to: NISO, 3600 Clipper Mill Road, Suite 302, Baltimore, MD 21211. ISSN: 1041-5653 (National information standards series) ISBN: 978-1-937522-47-6 ANSI/NISO Z39.93-2014 i Contents Foreword iii 1 Purp
11、ose . 1 2 Scope. 1 3 References 1 4 Definitions . 2 5 Element Reference Guide . 3 5.1 Element Listings 3 5.2 Data Types 3 6 SUSHI Protocol . 4 6.1 Namespace 4 6.2 Data Contract. 5 6.2.1 ReportRequest . 5 6.2.2 ReportResponse . 10 6.2.3 Exceptions and Errors 12 6.3 Service Contract (WSDL) 16 6.3.1 Se
12、rvice Contract Definitions and Types . 17 6.3.2 Service Contract Operation 17 6.3.3 Service Contract Messages 17 6.3.4 COUNTER-SUSHI Service Contract 17 7 Report Naming . 18 7.1 Types of Reports . 18 7.2 Report Naming Requirements . 18 7.3 Registry of Reports 19 8 Versions and Extensions 19 8.1 SUSH
13、I Versioning 19 8.2 Extending Data Contract for Additional Reports 19 Appendix A (informative) SUSHI Protocol XML Schema 22 Appendix B (informative) Core SUSHI WSDL 23 Appendix C (informative) COUNTER-SUSHI Extension for COUNTER reports . 24 Appendix D (informative) Utilizing SUSHI to Harvest Additi
14、onal Reports 25 Appendix E (informative) Continuous Maintenance Procedures Standardized Usage Statistics Harvesting Initiative (SUSHI) Protocol (ANSI/NISO Z39.93) . 26 Appendix F (informative) SUSHI Data Exchange Examples 28 Appendix G (informative) Security Considerations 29 Appendix H (informative
15、) Creating Proprietary SUSHI Extensions 31 Bibliography 33 ANSI/NISO Z39.93-2014 ii Tables Table 1: Description of Element Tables . 3 Table 2: Data Type Definitions . 3 Table 3: SUSHI Protocol Header . 4 Table 4: SUSHI Protocol ReportRequest Schema 5 Table 5: Elements for ReportRequest . 5 Table 6:
16、SUSHI Protocol Requestor Schema 7 Table 7: Elements for Requestor . 7 Table 8: SUSHI Protocol CustomerReference Schema 8 Table 9: Elements for CustomerReference 8 Table 10: SUSHI Protocol ReportDefinition Schema 9 Table 11: Elements for ReportDefinition 9 Table 12: Elements for UsageDateRange . 10 T
17、able 13: Elements for Filter . 10 Table 14: Elements for ReportAttribute 10 Table 15: SUSHI Protocol ReportResponse Schema 11 Table 16: Elements for ReportResponse . 12 Table 17: SUSHI Protocol Exception Reporting Schema 12 Table 18: Elements for Exception . 13 Table 19: Standard SUSHI Exceptions 14
18、 Table 20: SUSHI Service Contract Definitions and Types . 17 Table 21: SUSHI Service Contract Operation 17 Table 22: SUSHI Service Contract Messages . 17 Table 23: COUNTER-SUSHI Service Contract Definitions and Types . 18 Table 24: Example of Extending SUSHI 32 Figures Figure 1: Diagram of SUSHI Rep
19、ortRequest . 6 Figure 2: Diagram of SUSHI ReportResponse 11 Figure 3: Diagram of SUSHI Exception Reporting 14 Figure 4: Diagram of COUNTER-SUSHI Extension ReportRequest . 20 Figure 5: Diagram of COUNTER-SUSHI Extension ReportResponse . 21 Figure 6: Diagram of “Extended” SUSHI Schema . 32 ANSI/NISO Z
20、39.93-2014 iii Foreword (This foreword is not part of ANSI/NISO Z39.93-2014, The Standardized Usage Statistics Harvesting Initiative (SUSHI) Protocol. It is included for information only.) About This Standard This standard was developed in response to the need in libraries to more efficiently collec
21、t COUNTER (Counting Online Usage of NeTworked Electronic Resources) compliant usage statistics. COUNTER was launched in March 2002 as an international initiative to help librarians and publishers in the recording and exchange of usage statistics for electronic resources. By following COUNTERs Code o
22、f Practice, vendors can provide library customers with Excel, CSV (comma delimited), or XML files of usage data using COUNTERs standardized formats and data elements. As of June 2014, COUNTER has nearly 220 members and over 50 vendors have certified compliance to one or more Code of Practice release
23、s. COUNTER Usage Difficulties The success of COUNTER created a new problem for librariansthe amount of time they spend retrieving, storing, and aggregating their COUNTER reports. For each supplier of COUNTER reports, a library must manually connect to the suppliers website and download the Excel or
24、CSV files. Once retrieval is complete, the librarian is presented with multiple data files from multiple providers, which, while standardized, still require significant manipulation and normalization of the data to aggregate reports. Many libraries are creating or purchasing electronic resource mana
25、gement (ERM) systems to help them in storing and managing all this data. But the process for transferring the Excel/CSV data into the repository is either manual or requires custom programming. Background on SUSHI Development The idea for an automated method to solve the COUNTER report problem was f
26、irst discussed by Adam Chandler and Ted Fons at the 2004 Charleston Conference. Fons was Product Manager for the Innovative Interfaces Inc. (III) Electronic Resource Management module. Chandler was Coordinator, Service Design Group, Information Technology and Technical Services at Cornell University
27、 Library, and was active in the Digital Library Federations Electronic Resource Management Initiative (ERMI). The two agreed to push forward a Web service protocol for handling the XML version of the COUNTER reports. Tim Jewell (University of Washington) and Oliver Pesch (EBSCO) were recruited at th
28、e American Library Association meeting in June 2005 to further refine the concept. A project team was formed and from there the project was expanded to include additional members. Draft requirements and specifications for the protocol began in July 2005. In October 2005, NISO agreed to sponsor the i
29、nitiative, the group was officially named SUSHI (Standardized Usage Statistics Harvesting Initiative), and work began on creating this standard defining the protocol. The SUSHI Web Service The Standardized Usage Statistics Harvesting Initiative (SUSHI) represents a “Web services” approach to solving
30、 the COUNTER retrieval and consolidation problem. The protocol is a SOAP (Simple Object Access Protocol) request/response Web services “wrapper” for the XML version of COUNTER reports. In the protocol, a transaction begins when a client service running as part of an application developed by a librar
31、yor running as part of a usage data consolidation service or ILS/ERM systemidentifies itself, identifies the customer whose statistics are being requested, and specifies the desired report to the SUSHI server service running at a data provider. In response, the server provides the report in XML form
32、at, along with the requestor and customer informationor an appropriate error message. The SUSHI developers envision a system in which the client system is programmed to automatically retrieve reports on a monthly schedule for all the COUNTER-compliant vendors with which the library ANSI/NISO Z39.93-
33、2014 iv does business. The ability for the client to manually trigger requests may also be desirable to allow for easier testing with new SUSHI implementations and for retrieving previous months usage data. Although developed primarily for COUNTER reports, SUSHI was written as a generalized protocol
34、 that accommodates extensions for customized non-COUNTER usage reports. The COUNTER-specific schema extension is provided to accompany the general protocol. Trial Use The SUSHI protocol was issued as a Draft Standard for Trial Use from September 20, 2006 through May 20, 2007. During the trial period
35、, dozens of implementations of both the client or server sides of the protocol were successfully conducted. Minor revisions to the schemas were made to address issues identified during the trial. The 2007 standard reflected those changes. The schema version at the time of the trial was 1.0; the sche
36、ma version at the time of the 2007 publication of this standard was 1.5. The most current version of the schema is maintained on the SUSHI schema website (http:/www.niso.org/schemas/sushi/). 2013 Revision At the time the standard was due for its five-year reaffirmation review, the SUSHI Standing Com
37、mittee recommended that a revision be issued to make two minor changes: Addition to Table 17 of a new error code 1020 when a client exceeds the number of allowable requests to a server in a particular timeframe. This accommodates the need of some SUSHI server providers to set limits on access in ord
38、er to manage server performance. Revised informative Appendix G on Security Considerations. Although security is not part of the standard protocol, security was considered in developing the standard and this appendix provides recommendations on security-related issues. It was updated to reflect tech
39、nology changes and experience gained since the initial implementation of the SUSHI protocol. This version of the standard was approved by NISO on January 24, 2013 and by ANSI on February 20, 2013. 2014 Revision The SUSHI standard was created with the notion of “filters;” however, the only filter pro
40、vided for was that of the date range for the report. With use, a number of cases have surfaced where additional filters and other report attributes would be beneficial. Within the current standard, the only work-around is to overload the Requester/ID element or the CustomerReference/ID elementa less
41、 than ideal situation. This revision of the SUSHI Standard extends the filter support to allow multiple optional filters and/or report attributes to be included in the SUSHI Request. Examples of such filters are: Specify a specific platform for harvesting when a given SUSHI server provides usage for
42、 multiple platforms. Specify one or more IP ranges when usage is desired for a subset of a customers account. Specify a department when usage is desired for a subset of a customers account. Examples of such report attributes are: Allow a user to exclude items with zero usage from a report in order t
43、o keep the report size small. Specify the granularity of usage dates to be reported. (By default, COUNTER reports provide monthly totals for ReportItems; however, in some circumstances it might be desirable to request usage totals by day, quarter, or even year.) This revision also updates the exampl
44、es and figures provided throughout the document to reference updated versions of schemas and related files. ANSI/NISO Z39.93-2014 v Trademarks, Service Marks Wherever used in this standard, all terms that are trademarks or service marks are and remain the property of their respective owners. NISO Vo
45、ting Members At the time this standard was balloted, the following organizations were members of the NISO Z39.93 SUSHI 2014 Revision Voting Pool that approved this standard. NISO approval of this standard does not necessarily imply that all Voting Pool members voted for its approval. AIP Publishing
46、LLC Aravind Akella American Chemical Society (ACS) John Ochs American Library Association (ALA) Nancy Kraft American Psychological Association (APA) Janice Fleming Association for Information Science therefore, the XML formatted data can be collected in spreadsheets, in-house databases, commercial e
47、lectronic resource management (ERM) systems, or any other repository that the user establishes for that purpose. 3 References This standard references the following documents: The COUNTER Code of Practice for e-Resources. Release 4. Edinburgh, UK: COUNTER, published April 2012; valid from January 1,
48、 2014. Available from: http:/www.projectcounter.org/code_practice.html COUNTER Register of Vendors. http:/www.projectcounter.org/compliantvendors.html The Unicode Consortium. The Unicode Standard. Version 7.0.0. Mountain View, CA: The Unicode Consortium, 2014. ISBN 978-1-936213-09-2. Online version
49、available from: http:/www.unicode.org/versions/Unicode7.0.0/ W3C Note-datetime, Date and Time Formats. http:/www.w3.org/TR/NOTE-datetime W3C Recommendation. Simple Object Access Protocol (SOAP), version 1.2. World Wide Web Consortium, April 27, 2007. http:/www.w3.org/TR/soap12 W3C Recommendation. Extensible Markup Language (XML), version 1.0 (Fifth Edition). World Wide Web Consortium, November 26, 2008. http:/www.w3.org/TR/2008/REC-xml-20081126/ ANSI/NISO Z39.93-2014 2 4 Definitions The following terms, as used in this standard, have the meanings indicated. T
