About Features Downloads Getting Started Documentation Events Support GitHub

Site Tools


How to index Koha with VuFind

These are general instructions for setting up indexing of bibliographic records from Koha into VuFind's Solr index.

Koha uses an ILS driver to connect the records with their holdings and status information. You still need to manually import the MARC data from Koha, so VuFind has the records that can be searched. Once those records are there, VuFind can determine the real time status of the items using the ILS driver.

VuFind also supports fetching records from Koha using OAI-PMH. It can be useful for automating regular index updates. If you decide to use OAI-PMH, you will also need to set it up in Koha using a configuration file to include item information (see also Koha Manual).

VuFind Indexing Configuration

Start by configuring indexing settings in VuFind. The default settings contain everything needed for a basic setup apart from location-related fields.

There are several ways to index location-related fields. The first one is to put library and location to separate fields, but also a single hierarchical facet can be specified as shown further below.

Using the export command described below, Koha will include MARC field 952 for each item (see Koha's wiki for more information). These fields can be mapped to VuFind's facet fields. The values are typically codes that are not very user-friendly, and while you could translate them to user-readable strings in marc_local.properties, translating them with VuFind's translation mechanism allows more flexibility. See Addind Facets for more information.

Copy your marc_local.properties from $VUFIND_HOME/import to the $VUFIND_LOCAL_DIR/import (local settings) directory. Make all the changes you need to this file.

Example settings:

institution = 952b
building = 952c
collection = 9528
id = 999c, first

The id = 999c is needed for Vufind to find Koha's biblionumbers properly. The 'id =' field is not in every version of the marc_local.properties file, so you may need to add that manually. This is the field that the IDs are stored in. Koha and VuFind use different fields by default (vufind = 001, koha = 999c).

You can also set any of the index fields to static strings if desired, for example:

institution = "City Library"

Hierarchical Location Facet

You can combine library and location into a hierarchical facet that may be more user-friendly than separate fields in the eaxmple above. Instead of mapping institution and building separately, use the following lines in marc_local.properties:

building = 952b, (pattern_map.building_0), unique
building += 952bc, join("/"), (pattern_map.building_1), unique
pattern_map.building_0.pattern_0 = (.+)=>0/$1/
pattern_map.building_1.pattern_0 = (.+)=>1/$1/

You'll need to tell VuFind to handle the building field as a hierarchical one in $VUFIND_LOCAL_DIR/config/vufind/facets.ini:

hierarchical[] = building

translated_facets[] = building:building

Hierarchical facet values can be translated just like normal facet values, but you need to add translations for the different hierarchy levels. E.g. for library CPL's location FIC, you would add the following translations to $VUFIND_LOCAL_DIR/languages/building/en.ini:

0/CPL/ = "Centerville Public Library"
1/CPL/FIC/ = "Fiction"

Suppressed Records

If you want to exclude suppressed records from display in VuFind, you may need to add additional settings to your import configuration. Koha stores suppressed status in MARC field 942, subfield n. A value of “1” or “Y” in 942n indicates a suppressed record. Adding a line similar to this to your marc_local.properties may help:

suppressed_str = 942n ? ($n matches "[^1Y]*.*"), DeleteRecordIfFieldEmpty

Exporting Records From Koha

Koha has a misc/export_records.pl file which allows you to export to MARC format.

To run the export script, you will need to enter a Koha shell for the instance (<instance> is the Koha instance name):

koha-shell <instance>

Alternatively, you can manually set the path for PERL5LIB (or whatever your perl lib variable is) and the variable that points to the Koha configuration file:

export PERL5LIB=/usr/share/koha/lib:$PERL5LIB
export KOHA_CONF=/etc/koha/sites/<instance>/koha-conf.xml

To do the export, you will want to do something like this (the paths may differ):

/usr/share/koha/bin/export_records.pl --format marc --record-type bibs --filename kohabibs.mrc

Importing Into VuFind

Once you have exported the koha records, you will need to import the records into VuFind.

If necessary, transfer the file over so that VuFind can find it.

Now you are ready to run the import:

./import-marc.sh [directory]/kohabibs.marc

The Koha ILS Driver

:!: The example here describes the simple, database-driven Koha driver; newer VuFind releases may include KohaILSDI and/or KohaRest drivers that implement additional functionality using APIs found in newer Koha versions.

You will need to change the $VUFIND_LOCAL_DIR/config/vufind/config.ini file to have

driver = "Koha"

This will enable the Koha ILS driver. But you will still need to configure it. Copy the Koha.ini file from $VUFIND_HOME/config/vufind/Koha.ini to $VUFIND_LOCAL_DIR/config/vufind/Koha.ini (from the global directory to the VuFind local settings directory).

Change your Koha.ini file to reflect your site.

host        = localhost
port        = 3306
username    = mysqluser
password    = mysqlpass
database    = koha_database
url         = http://library.myuniversity.edu/
AV          = "Audio Visual"
CART        = "Book Cart"
CHILD       = "Children's Area"
DISPLAY     = "On Display"
FIC         = "Fiction"
GEN         = "General Stacks"

The Koha username may not be the MySQL root user. It is safest to have an alternate user for such things. This MySQL user needs to have access to the Koha database. The MySQL password should be the MySQL password that corresponds to the MySQL username. If you want to test this, from the command line you can run:

mysql -u [mysqluser] -p [kohadatabase]

It will prompt you for the password. If it works, then you are fine. If it fails, then you will need to verify the username / password / database with your system administrator.

Once you have your koha.ini file set up, restart Solr and check to see that your Koha records show up, and that the holdings information shows up.


For Koha exporting troubleshooting, reach out to the Koha community.

For MARC import/export, look at the page on marc import/export

There is a page for ILS troubleshooting

indexing/koha.txt · Last modified: 2021/08/11 10:30 by demiankatz