Evergreen: SRU and Z39.50 server support

Search/Retrieval via URL (SRU) is a specification for searching resources that relies on standard Web technology (HTTP, XML) for its implementation. Evergreen 1.4 supports basic SRU access through the /opac/extras/sru service defined in the Apache eg_vhost.conf configuration file and implemented in the sru_search() method in Open-ILS/src/perlmods/OpenILS/WWW/SuperCat.pm.

NOTE: This documentation is also available in the Evergreen documentation at http://libdog.mohawkcollege.ca/evergreen_documentation/1.6/draft/html/. In github: http://github.com/rsoulliere/Evergreen-DocBook/blob/master/1.6/admin/z3950.xml.

Testing Evergreen SRU with yaz-client

yaz-client is installed as a part of Index Data's YAZ software. Recent versions include support for querying SRU servers. Evergreen has shipped an SRU configuration that works out of the box since Evergreen 1.4. To search Evergreen with yaz-client, choose the GET query method and issue the find command. In the following example, we connect to the Evergreen test server “dev.gapines.org”; substitute this hostname with your own Evergreen server hostname:

$ yaz-client http://dev.gapines.org/opac/extras/sru
Z> sru GET 1.1
Z> find hemingway

If your database has records that match that term, you will get the corresponding MARCXML records in your response from yaz-client.

Here's what the SRU request looks like as sent to the Evergreen web server:

GET /opac/extras/sru?version=1.1&operation=searchRetrieve&query=hemingway&maximumRecords=0

You can see what the response looks like by hitting the same URL in your Web browser: http://dev.gapines.org/opac/extras/sru?version=1.1&operation=searchRetrieve&query=hemingway&maximumRecords=0

CQL queries

Evergreen supports some CQL index-sets for advanced queries such as a subset of Dublin Core (DC) elements. Those DC elements that are supported map to Evergreen default indexes as follows:

DC element Evergreen index
title title
creator author
contributor author
publisher keyword
subject subject
identifier keyword
type none
format none
language lang

Here are a few examples of SRU searches against some of these indexes:

Setting up Z39.50 server support in Evergreen

Prerequisite: You must have Evergreen's SRU server running before you can enable Z39.50 server support.

This support uses an Z39.50-to-SRU translator service supplied by the Net::Z3950::Simple2ZOOM Perl module to enable Evergreen to act as a Z39.50 server. You can run the Z39.50 server on a different machine; it just needs to be able to connect to the Evergreen SRU server.

Setting up the Z39.50 server

  1. Install a recent version of yaz (the Makefile.install should have installed a suitable version).
  2. Install Net::Z3950::Simple2ZOOM (sudo cpan Net::Z3950::Simple2ZOOM)
  3. Create a Simple2ZOOM configuration file. Something like the following is a good start, and is based on the Simple2ZOOM documentation example. We'll name the file dgo.conf for our example:
    <client>
       <database name="gapines">
         <zurl>http://dev.gapines.org/opac/extras/sru</zurl>
         <option name="sru">get</option>
         <charset>marc-8</charset>
         <search>
           <querytype>cql</querytype>
           <map use="4"><index>eg.title</index></map>
           <map use="7"><index>eg.keyword</index></map>
           <map use="8"><index>eg.keyword</index></map>
           <map use="21"><index>eg.subject</index></map>
           <map use="1003"><index>eg.author</index></map>
           <map use="1018"><index>eg.publisher</index></map>
           <map use="1035"><index>eg.keyword</index></map>
           <map use="1016"><index>eg.keyword</index></map>
         </search>
       </database>
    </client>

    You can have multiple <database> sections in a single file, each pointing to a different scope of your consortium. The name attribute on the <database> element is used in your Z39.50 connection string to name the database. The <zurl> element must point to http://hostname/opac/extras/sru. As of Evergreen 1.6, you can append an optional organization unit shortname for search scoping purposes, and you can also append /holdings if you want to expose the holdings for any returned records. So your zurl could be http://dev.gapines.org/opac/extras/sru/BR1/holdings to limit the search scope to BR1 and its children, and to expose its holdings.

Using your z39.50 server to access remote databases

  1. Simple2zoom is not concerned if your data is local or remote, so you can use your server to query remote data as well as local holdings. For instance, to set up a the server to query Evergreen Indiana bibs, you would add the following stanza to your /openils/conf/oils_z3950.xml file:
          <database name="egin">
             <zurl>http://evergreen.lib.in.us/opac/extras/sru/</zurl>
             <option name="sru">get</option>
             <charset>marc-8</charset>
             <search>
               <querytype>cql</querytype>
               <map use="4"><index>eg.title</index></map>
               <map use="7"><index>eg.isbn</index></map>
               <map use="8"><index>eg.issn</index></map>
               <map use="21"><index>eg.subject</index></map>
               <map use="1003"><index>eg.author</index></map>
               <map use="1018"><index>eg.publisher</index></map>
               <map use="1035"><index>eg.keyword</index></map>
               <map use="1016"><index>eg.keyword</index></map>
             </search>
         </database>
     
    1. To query that from the Evergreen staff-client you would add “Evergreen Indiana” to your list of custom z3950 targets with the URL if your own server and the database name of “egin” and the port that your server is listening on, i.e. 210.

Setting up Yaz Configuration

  1. We need to create a configuration file that will tell YAZ how to transform marcxml to binary MARC21. Along the way, we force the output character set to be MARC-8, because in the dinosaur world of library technology some major Z39.50 clients such as RefWorks and OCLC VDX still appear to be unable to support Unicode UTF-8 encoding. We will call this one xml2marc-yaz.cfg:
<yazgfs>
    <server id="server1">
    <retrievalinfo>
        <retrieval syntax="xml"/>
        <retrieval syntax="marc21">
            <backend syntax="xml">
                <marc inputformat="xml" outputformat="marc" inputcharset="utf-8" outputcharset="marc-8"/>
            </backend>
        </retrieval>
    </retrievalinfo>
    </server>
</yazgfs>
  1. As root, run simple2ZOOM as a daemon, specifying the configuration files and one or more listener addresses that the Z39.50 server will be accessible on. If you do not specify a port, it will automatically run on port 9999. In the following example, we tell it to listen both to localhost on port 2210, and on dev.gapines.org on port 210:
    simple2zoom -c dgo.conf -- -f xml2marc-yaz.cfg localhost:2210 dev.gapines.org:210 &

To test the Z39.50 server, we can use yaz-client again:

yaz-client
Z> open localhost:2210/gapines
Connecting...OK.
Sent initrequest.
Connection accepted by v3 target.
ID     : 81/81
Name   : Simple2ZOOM Universal Gateway/GFS/YAZ
Version: 1.03/1.128/3.0.34
Options: search present delSet triggerResourceCtrl scan sort namedResultSets
Elapsed: 0.010718
Z> format xml
Z> find "dc.title=zone and dc.author=king"
Sent searchRequest.
Received SearchResponse.
Search was a success.
Number of hits: 0, setno 4
records returned: 0
Elapsed: 0.611432
Z> find "dead zone"
Sent searchRequest.
Received SearchResponse.
Search was a success.
Number of hits: 4, setno 5
records returned: 0
Elapsed: 1.555461
Z> show 1
Sent presentRequest (1+1).
Records: 1
[]Record type: XML
<record xmlns:... (rest of record deliberately truncated)
evergreen-admin/sru_and_z39.50.txt · Last modified: 2013/01/23 07:56 by wolf29
 
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 3.0 Unported
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Debian Driven by DokuWiki

© 2008-2013 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a member of Software Freedom Conservancy.