======Evergreen: SRU and Z39.50 server support======
[[http://www.loc.gov/standards/sru/|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 [[https://git.evergreen-ils.org/?p=Evergreen.git;a=blob;f=Open-ILS/src/perlmods/lib/OpenILS/WWW/SuperCat.pm|Open-ILS/src/perlmods/lib/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:
<code>
$ yaz-client http://dev.gapines.org/opac/extras/sru
Z> sru GET 1.1
Z> find hemingway
</code>
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:<code>
GET /opac/extras/sru?version=1.1&operation=searchRetrieve&query=hemingway&maximumRecords=0
</code>

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 [[http://zing.z3950.org/cql/intro.html|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:

  * [[http://dev.gapines.org/opac/extras/sru?version=1.1&operation=searchRetrieve&query=dc.title+all+%22complete+dinosaur%22&maximumRecords=0|dc.title all "complete dinosaur"]]
  * [[http://dev.gapines.org/opac/extras/sru?version=1.1&operation=searchRetrieve&query=dc.subject+all+%22britain+france%22&maximumRecords=0|dc.subject all "britain france"]]
  * [[http://dev.gapines.org/opac/extras/sru?version=1.1&operation=searchRetrieve&query=dc.title+exact+%22The%20Empire%20strikes%20back%22&maximumRecords=0|dc.title exact "The Empire Strikes Back"]]
  * [[http://dev.gapines.org/opac/extras/sru?version=1.1&operation=searchRetrieve&query=dc.author%3Dking%20and%20dc.title%3Dzone&maximumRecords=0|dc.author=king and dc.title=zone]]

=====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:<code xml><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>
</code> 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=====
  - 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:   <code xml>      <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>
  </code>
    - 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=====
  - 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'':
<code xml>
<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>
</code>
  - 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:<code bash>
simple2zoom -c dgo.conf -- -f xml2marc-yaz.cfg localhost:2210 dev.gapines.org:210 &</code>

To test the Z39.50 server, we can use yaz-client again:<code>
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)
</code>