yellow highlighted text = information still to be added
This location is no longer being updated. Please see the NISO SUSHI website for updated FAQs: http://www.niso.org/workrooms/sushi/faq/
What is SUSHI?
SUSHI stands for Standardized Usage Statistics Harvesting Initiative. It is a protocol (and a proposed standard) that can be used by electronic resource management (and other) systems to automate the transport of COUNTER formatted usage statistics. The SUSHI protocol is a standard client/server web services utilizing a SOAP request/response to retrieve the XML version of the COUNTER report. It can also be used to retrieve non-COUNTER reports that meet the specified requirements for retrieval by SUSHI.
What is COUNTER?
COUNTER (Counting Online User NeTworked Electronic Resources) is a not-for-profit organization formed in 2002 to develop standardized methods and reports for measuring the use of electronic resources. COUNTER created Codes of Practice, which define how to count and record usage, and the fields, formats, and schedule of reports. In the context of SUSHI, the COUNTER reports, formatted in XML, are the payload which is request and delivered using the SUSHI protocol. COUNTER currently provides two Codes of Practice, one for Journals and Databases and one for Books and Reference Works.
What is SOAP?
SOAP is an XML-based protocol used for exchanging messages between two networked computers. The communication occurs through HTTP, just like a Web browser. The SOAP specification is a Recommendation of the World Wide Web Consortium (WC3).
What is an ERM?
Electronic Resource Management (ERM) software is developed for the specific purpose of managing a library’s electronic resource collections and subscriptions. ERM systems, which can be either standalone or directly tied to a library system vendor’s other modules, usually track the life cycle of an electronic resource. This can include management areas such as: access, acquisitions, licensing, cost, invoicing, workflow, trial use of electronic products, and resource usage.
Many of today’s ERM systems are based on the Digital Library Federation’s Electronic Resource Management Initiative report.
What is an XML schema?
An XML schema is “is a description of a type of XML document, typically expressed in terms of constraints on the structure and content of documents of that type, above and beyond the basic syntax constraints imposed by XML itself. An XML schema provides a view of the document type at a relatively high level of abstraction”. [Source: XML schema. (2006, July 6). In Wikipedia, The Free Encyclopedia. Retrieved July 27, 2006.]
More on XML
What is the relationship of the SUSHI standard (Z39.93), the SUSHI schema, and the SUSHI WSDL?
The SUSHI standard is the high-level framework in which the SUSHI Schema, SUSHI WSDL, and COUNTER reports operate. The SUSHI WSDL describes, with a high level of abstraction, how the client and server sides of the web services transaction will interoperate. The WSDL gives information referring to the lower level, more detailed and specific information about the transaction, which is described in the schema. The schema is the XML code that is used to perform the SUSHI operation. Variable information in the schema is modified at the time the code is executed. The COUNTER XML report is the actual payload of the transaction.
What are the benefits of using the SUSHI protocol?
The primary benefit of SUSHI is that it automates a tedious and repetitive process. Current practice for statistics retrieval calls for library staff to go to each individual publisher’s website and manually retrieve statistical data. In some cases, this data is in COUNTER format, but sometimes it is the publisher’s own internal format. Occasionally it is available only through a web screen and cannot be downloaded; only printed. The SUSHI protocol automates the process; but also, by default, encourages the publishers to put usage data into a standard format (COUNTER XML). Therefore the retrieval is not only automatic but far easier to use.
How does the SUSHI protocol work?
The following graphic describes the basic functionality of SUSHI:
[Comment: We are considering how to turn the "text" graphic below into an animated web graphic. Suggestions on this graphic are welcome.] -Adam 8/9/06, 4:37pm
Client Server
Creates request message
Includes customer ID, login
Information, name of report,
Date range to be included in
Report.
Request is “wrapped” in a
SOAP “envelope” and sent to
The server ---------------------------------------------------------------------------------------------------
Server opens the incoming SOAP message
Reads the envelope to discover what WSDL
And schema are to be used to process the
Incoming request.
Once the request is parsed, the server prepares
A response. Some servers may have pre-pack-aged
The statistics and can simply supply the data file
In COUNTER format. Otherwise, the server may
Initiate a process that searches through the vendor’s
Data warehouse in order to create the new payload
For shipment.
Once the payload is ready, it is “wrapped” in a
SOAP envelope and sent back to the calling
Process.
----------------------------------------------------------------------------------------------------------------------------
The requester receive the response message
And opens the “SOAP” envelope. The envelope
Is separated from the payload. The payload is
Passed to the application for processing.
What is the relationship of the COUNTER payload schema to the SUSHI schema?
The COUNTER schema describes the internal structure of the XML file that is being delivered via the SUSHI protocol. The COUNTER schema is included in SUSHI as a "payload", i.e. the actual data to be retrieved. Separating this "payload" from the SUSHI request/response schema provides two benefits:
1) It enables users of the payload to anticipate and to build their applications with the knowledge of the structure of the incoming data file.
2) It enables alternate payloads to be used with the SUSHI protocol, such as a customized publisher report.
According to the terms of a Memorandum of Understanding signed by NISO and COUNTER in 2006, the NISO SUSHI maintainers are responsible for creating COUNTER XML payload schemas for any issued COUNTER Codes of Practice. This will ensure that the COUNTER schemas and the SUSHI protocol schema will remain compatible.
What is the difference between the client and the server implementation of SUSHI?
The SUSHI client application packages a request for a usage statistics report and sends it to a compliant SUSHI server. The SUSHI server parses the incoming request from the client, including the specific report requested and the identity of the customer for whom data is to be retrieved. A server may either have prepackaged customer’s data ready for immediate delivery or it may search its data store contemporaneously with the request and create the response ad hoc. In either case, the server returns the requested report in XML format.
What variable information has to be supplied in a SUSHI (client) request?
In the current release of SUSHI (version 1.0 dated September 20, 2006), the mandatory variable information to be supplied in a SUSHI request is:
Requestor ID
CustomerReference ID (which may or may not be the same as the Requestor ID)
Name of the report being requested
Release (i.e. version) number of the report being requested
Begin date of the report being requested
End date of the report being requested
What variable information has to be supplied in a SUSHI (server) response?
In the current release of SUSHI (version 1.0 dated September 20, 2006), the mandatory variable information to be supplied in a SUSHI response is:
Requestor ID (repeated from request message)
Report name, release, and dates (repeated from request message)
Report (the actual XML payload with the report data)
Exceptions (if applicable, any exception or error messages)
What COUNTER reports can be delivered with SUSHI?
COUNTER currently has two Codes of Practice: one for Journals and Databases, which contains four reports for journals (two are optional) and three reports for databases, and one for Books and Reference Works, which contains six reports.
SUSHI 1.0 supports retrieval of any COUNTER report. The standardized names of the COUNTER reports to be used with the SUSHI protocol are listed on the SUSHI Report Name Registry.
Does SUSHI support older Releases of the COUNTER reports?
The SUSHI 1.0 protocol will support any release of COUNTER for which an XML payload schema exists. Currently such a schema exists for Release 2 of the Code of Practice for Journals and Databases. An XML schema for Release 1 of the Code of Practice for Books and Reference Works will be developed shortly.
Server support -- COUNTER recommends that the current release and one previous release of its Code of Practice be supported. However, support for different release versions is dependent on the report suppliers. It is up to the publisher or aggregator of the COUNTER reports whether they will provide reports for earlier Releases and when they will begin to support new Releases. Contact the provider of your COUNTER reports for specific information. The COUNTER website provides a Register of Vendors, indicating who is supporting the different releases.
Client support -- Release support is dependent on the set up of the database that was created and maintained to ingest and store the SUSHI delivered COUNTER reports. If you are using a commercial ERM product, you will need to contact the ERM vendor to determine the COUNTER releases supported.
Can SUSHI request and aggregate multiple vendor reports?
The protocol is designed as a one-report-at-a-time service. If a client needs multiple reports of different types or from different vendors, then it would simply make a separate SUSHI call for each one.
Results will need to be aggregated by the requesting library, either manually or using software such as an ERM system. In many cases, the request and aggregation process will be automated within the software that makes the request. For example, the system could be programmed to request all of last month’s reports on the 15th of this month, assuming that all of the content providers had their report data complete by that date. However, such automation is outside the scope of the SUSHI protocol.
How does SUSHI handle the requesting of consortium reports?
SUSHI allows the report to be requested for one institution (COUNTER expectation). If the consortium is viewed as its own entity by the content provider, then the client would make one request from the server for the consortium-level report. If, on the other hand, the consortium is truly a collective of a number of different institutions, then the customer would be responsible for requesting reports for each institution and merging the data, possibly with ERM/Usage consolidation software.
Can I use SUSHI to receive or deliver non-COUNTER reports?
Yes. COUNTER reports are the primary focus of the SUSHI standard, but other reports, agreed upon by the trading partners, can be retrieved as well. These custom reports would have to meet the standard's requirements for report naming and would have to be deliverable in an XML format.
There is a Registry of standardized report names. All COUNTER reports are included in the registry, however, registration of other customized reports is voluntary, so not all reports in use may appear here.
What security features does SUSHI offer to protect access to reports?
The SUSHI protocol does not include an integrated security mechanism, however, security was a consideration in developing the standard. Appendix F of the standard discusses several recommended mechanisms by which security can be addressed. These include:
· Securing the data communication channel (through use of HTTPS, Secure Socket Layer)
· Authenticating the requesting organization (through such methods as SUSHI Requstor ID validation, IP authentication, or Username/password)
· Validating the rights of a requesting organization to access usage data for a specific customer
For additional information on these methods, see Appendix F of the standard.
Are there any limits to how many or how often I can request reports with SUSHI?
No, there are no SUSHI-based limits. The individual content provider servers may have access rules relating to frequency of requests and numbers of downloads. If the server is unable or unwilling to deliver a requested report through SUSHI, an Exception message is returned in the SUSHI response that describes the problem.
Is there any limit to the time frame of the reports content which I can request?
SUSHI places no time limits on the time frame of reports. Availability of reports for a particular range of months or years is determined by the content provider and the service provider of the SUSHI server that makes available the publisher’s data. If the publisher has not made statistics for certain years available, then SUSHI cannot retrieve it. If a request is made for an unavailable report, the SUSHI protocol will return an exception indicating why no data was returned.
Can issuance of the SUSHI request be automated?
Absolutely. Most current client-side SUSHI implementers are building automated triggering into their system to initiate SUSHI retrieval based on a known calendar of expected availability of usage reports. The initiating software package needs to know the publisher’s URL, a customer number and password, and a calendar of when the vendor makes their updates statistics available, and the process can be automated.
Do I need an ERM system to use SUSHI?
No. Any software that can initiate a web service request using the SUSHI WSDL and Schema can use the SUSHI protocol. The SUSHI protocol does not presume the end of the line repository for the retrieved report. Some libraries are creating master spreadsheets or in-house databases for their usage data. Many of the libraries interested in SUSHI have or are planning to implement a commercial electronic resource management (ERM) system that will integrate this usage data into their overall management of e-resources, but this is not a requirement.
Where can I find the SUSHI schemas and WSDL?
The latest SUSHI schemas and WSDL are available at the NISO SUSHI schema webpage.
A general page about SUSHI contains additional resources for SUSHI-related information.
How often is the SUSHI schema updated?
During the 8 month Draft Standard for Trial Use phase, no changes will be made to the SUSHI schema. This will allow potential implementers to have a stable version to test. During this time comments will be accepted, both for "bug" reports and for suggested enhancements or changes to the protocol. Following this trial use phase, all the comments from the trial participants will be reviewed by the committee and if necessary a new version of the SUSHI schema will be issued along with the final version of the standard.
Once the final standard is approved, changes to the schema that meet the standard's definition of allowable changes will be made as needed, but no more than annually. The protocol is intended to be robust enough to accommodate new COUNTER reports and releases without any changes to the SUSHI schema.
[Comment: We will address this further after Ted F. makes his recommendations and the committee agrees on the approach.] -Adam 8/9/06, 4:41pm
What are the SUSHI toolkits?
Two starter/developer kits for SUSHI exist. One is written for .NET development and is available from EBSCO. The other is for Java development and is made available by Swets. Both of these kits are available for the use of developers interested in creating SUSHI servers for their electronic resources. Both toolkits were originally developed for the beta version of the SUSHI protocol but are intended to be updated to support version 1.0- Check the toolkit websites to determine the current version supported.
These toolkits were developed by the organizations listed and are not officially supported or maintained by the SUSHI support team.
How do I implement the client side of SUSHI?
From the perspective of a library customer, it will probably only be necessary to purchase a system that supports SUSHI, then manually input the connection information for all the various vendors you buy content from that support also support SUSHI.
System developers should
review the SUSHI WSDL, SUSHI schema, and COUNTER schema in detail
download and review the SUSHI toolkits
review the SOAP specification
[Comment: We probably need more information here. Suggestions welcome from anyone who's doing a client-side implementation.] -Adam 8/9/06, 4:42pm
How do I implement the server side of SUSHI?
COUNTER report providers should:
review the SUSHI WSDL, SUSHI schema, and COUNTER schema in detail
download and review the SUSHI toolkit
review the SOAP specification
[Comment: We probably need more information here. Suggestions welcome from anyone who's doing a server-side implementation. E.g., what do you have to put in place to have a SUSHI-compliant server?] -Adam 8/9/06, 4:43pm
Are there any testbeds or test servers I can use?
Yes. See the instructions at the bottom of the following URL: http://www.niso.org/committees/SUSHI/SUSHI_comm.html
[Comment: This section needs more works. E.g,.more narrative either here or with the testbed info on the web page with background on exactly what this test server is for and perhaps how to use it.] -Adam 8/9/06, 4:43pm
What vendors have implemented the SUSHI protocol in their ERM products?
Innovative Interfaces has released a version of their ERM product that supports the SUSHI protocol. Ex Libris is in the process of building SUSHI into their next version of Verde, their ERM product. Other vendors that have announced support for SUSHI are available on the SUSHI partners webpage.
[Comment: Should we consider having a webpage that lists all the implementers of SUSHI? Then this question can just point to that list.] -Adam 8/9/06, 4:44pm
What vendors have implemented a SUSHI server for delivering COUNTER reports?
The SUSHI partners webpage lists some of content providers that have announced support for SUSHI:
[See comment above. Webpage could have separate lists for client and server support.] -Adam 8/9/06, 4:44pm