Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

z2folio - the Z39.50-to-FOLIO gateway

Copyright (C) 2018-2021 The Open Library Foundation

This software is distributed under the terms of the Apache License, Version 2.0. See the file "LICENSE" for more information.


z2folio is a Z39.50 server for FOLIO bibliographic and holdings data, supporting record retrieval in USMARC, OPAC, XML and JSON formats. The functionality is all provided by the Net::Z3950::FOLIO library, which is also part of this distribution. It is written in Perl, and follows standard Perl-module conventions.

The name of the Docker container is mod-z3950.


Dependencies are defined in the module descriptor but since the FOLIO Z39.50 server is strictly a client to the rest of FOLIO it does not need to be installed as a part of FOLIO itself, and can run outside of a FOLIO installation provided it is pointing to an Okapi server with the following modules enabled:

Of these, the last three are fairly ubiquitous in FOLIO installations, but mod-graphql may need to be added.

The Okapi connection details (url, tenant, username, password) are defined in the configuration file or via environment variables: see Authentication below.


To install this module type the following:

perl Makefile.PL
make test
make install

On some platforms (e.g. my MacBook running MacOS 10.13.6 with YAZ and libxml2 installed from Homebrew 1.8.4), installing the prerequisite SimpleServer with cpan install Net::Z3950::SimpleServer fails. I fixed it using:

C_INCLUDE_PATH=/usr/local/Cellar/libxml2/2.9.4_3/include/libxml2 cpan install Net::Z3950::SimpleServer


If you don't want to install, you can run directly from the development checkout as:

perl -I lib bin/z2folio -c etc/config -- -f etc/yazgfs.xml

Building and running from Docker

terminal1$ docker build -t zfolio .
terminal1$ docker run -it --rm -p9997:9997 -e OKAPI_PASSWORD=swordfish --name run-zfolio zfolio

terminal2$ yaz-client @:9997
Z> find @attr 1=4 a
Z> format opac
Z> show 1

Note: if running in Kubernetes, it may be useful to turn of session logging by adding the -v-session parameter to the arguments. For example, perl -I lib bin/z2folio -c etc/config -- -f etc/yazgfs.xml -v-session. Session logs can be quite noisy on Kubernetes due to tcp healthchecks.

Docker containers get published as folioorg/mod-z3950 and folioci/mod-z3950.


Whichever approach to running the server you prefer, the default configuration file specifies that the password used to authenticate onto the back-end FOLIO system must be specified in the FOLIO_PASSWORD environment variable. You can provide that however seems best to you -- e.g. injecting it into a Docker container with the -e name=value as above -- or indeed use a different configuration file that hardwires the credentials.

Access via SRU

Thanks to the magic of the protocol-polyglot YAZ GFS, the FOLIO Z39.50 server also serves the SRU (REST-like) and SRW (SOAP-based) protocols. For example, if running the server on your local host, you can use the following to obtain an XML-formatted OPAC record containing both bibliographic metadata in MARCXML format and holdings-and-item information such as might be used by an OPAC. Replace placeholder with the real database name (or tenant id).



If when you perform a search your Z39.50 client reports

Cannot query field "search_instances" on type "Query".

The problem is that the back-end FOLIO service you are searching in does not have mod-search (ElasticSearch-based searching in inventory), which was first released in FOLIO R1-2021 (Iris). In this case, you should configure the Z39.50 server to use the older approach of searching directly in mod-inventory-storage. You can most easily do this by changing the graphqlQuery entry in etc/config.json from "mod-search.graphql-query" to "instances.graphql-query". Note, however, that as of FOLIO R2-2022 (Morning Glory), searching directly in inventory will no longer work for full-text searches such as author and title, only for exact-value searches such as HRID and ISBN.

Additional information

Other documentation

Other modules are described, with further FOLIO Developer documentation at

Issue tracker

See project ZF at the FOLIO issue tracker.