Setting up the Z39.50 and SRU Server

Setting up the Z39.50 and SRU Server

This page is about the standalone Z39.50/SRU responder that is available starting with Koha 19.11. It is mostly relevant to installations using Elasticsearch as the search engine, since Zebra can act as a Z39.50 and SRU server for sites using it. The responder can also be used with Zebra e.g. if different settings or its advanced features are needed. The responder supports both Z39.50 and SRU queries with the same listening port.

Usage with Debian Packages

If you have Koha installed with Debian packages, the basic setup for the responder is easy:

koha-z3950-responder --enable <instancename>

Start the server with:

koha-z3950-responder --start <instancename>

Enabling the server copies configuration files to /etc/koha/sites/<instancename>/z3950/. By default the server listens to incoming connection in TCP port 2100. The port can be modified in config.xml. pqf.properties contains the mappings used to translate the incoming queries. Make sure to restart the server for any configuration changes to take effect:

koha-z3950-responder --restart <instancename>

Advanced Usage

These instructions are useful if you need to run the server without the Debian scripts.

The responder is started with the misc/z3950_responder.pl script. The responder can be started without arguments for default behavior, which means that the service runs in foreground without much logging unless something goes wrong. You can run the script with the -h parameter for brief help:

misc/z3950_responder.pl -h

Use the following parameters to start the responder as a background daemon:

misc/z3950_responder.pl -D -p <pidfile>

You will need to copy the sample configuration files to the z3950 subdirectory of the Koha config directory (etc):

mkdir <koha_conf_dir>/z3950
cp etc/z3950/* <koha_conf_dir>/z3950/

Modify config.xml ie.g. to change the listening port from the default (2100). pqf.properties defines rules for translating the incoming Z39.50 queries, and may need to be customized for any custom search fields.

The responder is also capable of including item statuses in the returned records. See the --add-item-status and --add-status-multi-subfield parameters. The returned statuses are controlled by the authorized value category named Z3950_STATUS. The following keys are used and their descriptions added to the records: AVAILABLE, CHECKED_OUT, LOST, NOT_FOR_LOAN, DAMAGED, WITHDRAWN, IN_TRANSIT or ON_HOLD.

Further Documentation

The responder is based on the YAZ GFS (Generic Frontend Server). More information about accepted parameters can be found the GFS documentation for server invocation and the configuration file.

If you want to test your SRU server try this call in the cmdline of your Koha server:

 curl "http://localhost:2100/biblios?version=1.1&operation=searchRetrieve&query=php&maximumRecords=20&recordSchema=marcxml"

And don't forget the parameter maximumRecords!! Otherwise the result does only show the number of of records found but not the MarcXML of every single record.

See also

• Koha manual - Webservices - SRU-Server.
• How to set up SRU Server on Koha.

Troubleshooting

If your Koha was upgraded from a version older than 21.05, you might not have the correct permissions on your Koha instance's log4perl.conf file.

See Bug 28364 - koha-z3950-responder breaks because of log4perl.conf permissions for information on how to fix the permissions on the file, which prevent your Z39.50 server from starting.