This is an old revision of the document!
Table of Contents
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.
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. To search Evergreen with yaz-client, choose the GET query method and issue the find
command:
$ yaz-client 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
- Install a recent version of yaz (the Makefile.install should have installed a suitable version).
- Install Net::Z3950::Simple2ZOOM (
sudo cpan Net::Z3950::Simple2ZOOM
) - 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>utf8</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 behttp://dev.gapines.org/opac/extras/sru/BR1/holdings
to limit the search scope to BR1 and its children, and to expose its holdings. - Then we need to create a configuration file that will tell YAZ how to transform marcxml to binary MARC21. 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" outputcharset="utf-8"/> </backend> </retrieval> </retrievalinfo> </server> </yazgfs>
- 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 marcxml 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)