User Tools

Site Tools


Koha Greenstone Integration

Here are some notes about integrating Greenstone 2.83 with Koha. This enables Koha to link to the Greenstone version of a document if available. And enables Greenstone to download metadata from Koha using OAI for the documents in its collection.

See also

Setup Koha Server

Access Koha VM

This is a Debian server. After the VMWare Server detects the IP of this Koha VM, ssh login to the server with the following accounts.

  • root : katikoan (Login with root will bring you directly to Koha Management Console)
  • koha : katikoan (Login with this account allows you to access the VM via normal console)

Access Koha Web Interface

To visit the site via web browser - http://[IP of the Koha VM]:8080/, you will be able to login with the "kohaadmin" account

  • kohaadmin : katikoan

Other Access

The following are the MySQL account

  • root : katikoan
  • kohaadmin : katikoan

Enable Koha OAI Server

  • Access Koha via a web browser - http://[IP of the Koha VM]:8080/
  • Login with the “kohaadmin” account
  • Go to: More > Administration > Global system preferences
  • Under OAI-PMH, set the OAI-PMH parameter to “ON“

To test the OAI server is set up correctly, you need to make sure there are some records in the system. If there aren't any, add some new records via the "Cataloging" panel.

To show a list of OAI records

http://[IP of the Koha VM]:8080/cgi-bin/koha/opac/

In here, you will be able to find a list of OAI identifiers. By default, the identifier is constructed as "KOHA-OAI-TEST:" followed by the Koha internal ID. For example, "KOHA-OAI-TEST:1" is the OAI identifier for the first Koha record. Note: This OAI prefix can be changed in the “Global system preferences” page.

To retrieve OAI metadata for the specified OAI Identifier

http://[IP of the Koha VM]:8080/cgi-bin/koha/opac/[OAIIdentifier]&metadataPrefix=oai_dc

Setup Greenstone2.83

Important: Please install Greenstone under Linux. In this KOHA-Greenstone integration project, Greenstone uses KOHA OAI identifier as the document identifier. Unfortunately, KOHA OAI identifier uses “:” (column) to separate between OAI prefix and KOHA internal ID. Because Windows does not accept “:“ as a part of its folder name, Greenstone is unable to create the document folder in the archives directory.

  • Download gsdl2.83 installer from
  • Run the installer and follow the instructions.
  • Once Greenstone is installed, configure your web server to enable CGI execution in [GreenstoneInstallation]/cgi-bin

Example of Apache configuration

ScriptAlias /greenstone/cgi-bin/ "[Greenstone Installation]/cgi-bin/"
<Directory "[Greenstone Installation]/cgi-bin/">
    AllowOverride None
    Options ExecCGI +MultiViews FollowSymLinks
    Order allow,deny
    Allow from all
Alias /greenstone/ "[Greenstone Installation]"
<Directory "[Greenstone Installation]">
    AllowOverride All
    Options Indexes FollowSymLinks
  • Restart the web server to load the configuration.
  • If the web server alias for the Greenstone installation is not "/greenstone", configure [GreenstoneInstallation]/cgi-bin/gsdlsite.cfg to use the correct httppath.
  • Make sure Greenstone is working by visiting via a webbrowser. http://localhost/[[httppath|to Geenstone Installation]]/cgi-bin/library.cgi


  • The has been modified to allow the custom to work properly. However, the fix is not in any current tagged version. Please download [serverscriptpath/gsdoc/patches/gsdl-koha/] to replace the one in [GreenstoneInstallation]/perllib/plugins/
  • The customized Plugin requires a Perl module. This module is included in the standard Perl installation on Linux. However Greenstone's cut-down version does not include it. Please download [serverscriptpath/gsdoc/patches/gsdl-koha/] to the "perllib" directory in the main Greenstone's perllib folder
  • After the file is unzipped, you should see the following files/folders:
 [Greenstone Installation]/perllib/
 [Greenstone Installation]/perllib/
 [Greenstone Installation]/perllib/Bundle
 [Greenstone Installation]/perllib/File
 [Greenstone Installation]/perllib/HTML
 [Greenstone Installation]/perllib/HTTP
 [Greenstone Installation]/perllib/LWP
 [Greenstone Installation]/perllib/NET
 [Greenstone Installation]/perllib/URI
 [Greenstone Installation]/perllib/WWW

Please note that these files have to sit directly under the perllib directory.

  • If you have perl 5.10 installed on the server. One of the Perl modules (XMLParser:Expat) in Greenstone will no longer function correctly and you will have to rename it so Greenstone can fall back to use the system version. Change [Greenstone Installation]/perllib/cpan/perl-5.8 to [Greenstone Installation]/perllib/cpan/perl-5.8.renamed

Setup Koha OAI collection with GLI (Linux)

  • Starting up the GLI server by running ./
  • Create a new collection under File > New…
  • In this example we use "kohaoai".
  • Gather Panel
    • Use the Gather panel and put the source files into the kohaoai collection.
  • Enrich Panel
    • Add Dublin Core Metadata to the source documents.
    • IMPORTANT: Add the “Koha OAI identifier” for the source document to the "dc.Resource Identifier" field. This is how the system links between Greenstone and Koha.
  • Manual process for installing OAIMetadataXMLPlugin
    • Quit out GLI
    • Enter your kohaoai collection from a terminal [Greenstone Installation]/collect/kohaoai
    • Create perllib/plugins and download [serverscriptpath/gsdoc/patches/gsdl-koha/] into there
  • Design Panel
    • Re-enter GLI and move on to the Design Panel
    • Enter Document Plugins, choose the plugins that processes your source documents.
    • IMPORTANT: at this point, you should see the OAIMetadataXMLPlugin as an option in the "Select plugin to add" list. Add the plugin and set "oai_server" to http://[IP of the Koha VM]:8080/cgi-bin/koha/opac/
    • Under the Librarian mode (the default mode), move the OAIMetadataXMLPlugin to the end of your plugin list (by default, it would go after the NulPlugin).
    • Under the Expert mode,move the OAIMetadataXMLPlugin to the front of MetadataXMLPlugin (by default, it would also go after the NulPlugin).
    • OPTIONAL - Creates a classifier based on the extracted OAI metadata
    • Enter Browsing Classifiers, and add a new Hierarchy classifier, set the following fields

metadata: oaiextracted.type sort: oaiextracted.title buttonname: Koha Catalog Type

  • Create Panel
    • Under Librarian mode (the default mode), enable the OIDtype and set it assigned.
    • Build the collection
  • Format Panel
    • Enter Format Features and configure the page to have the following formats


<td valign=top>[link][icon][/link]</td>
<td valign=top>[highlight][link]{Or}{[classifyTitle],[Title]}[/link]<br/>
{If}{[numleafdocs],,{If}{[Title],<small>Extracted Title: [Title]</small>}}[highlight]
{If}{[Date], <small><i>_textdate_[Date]</i></small>}
{If}{[NumPages], <small><i>_textnumpages_[NumPages]</i></small>}
{If}{[Source], <small><i>_textsource_[Source]</i></small>}</td>


<b>Greenstone Metadata</b>
<hr width=\"100%\"/>
<b>dls.Title:</b> [dls.Title]<br/>
<b>dls.Subject:</b> [dls.Subject]<br/>
<b>dc.Identifier:</b> [dc.Identifier]<br/>
<b>{If}{[oaiextracted.title],Koha Metadata, <span style=\"color: #B0B0B0\">Koha Metadata (No
Koha Metadata Extracted)</span>}</b>
<hr width=\"100%\"/>
{If}{[oaiextracted.title], <b>dc.Title:</b> [oaiextracted.title]<br/>}
{If}{[oaiextracted.type], <b>dc.Type:</b> [oaiextracted.type]<br/>}
{If}{[], <b>dc.Date:</b> []<br/>}
{If}{[oaiextracted.koharecordlink], <a href=\"[oaiextracted.koharecordlink]\">Koha
<b>Extracted Metadata</b>
<hr width=\"100%\"/>
{If}{[Title], <b>Title:</b> [Title]<br/>}
{If}{[Date], <b>Publication Date:</b> [Date]<br/>}
{If}{[NumPages], <b>No. of Pages:</b> [NumPages]<br/>}
{If}{[FileFormat], <b>File Format:</b> [FileFormat]<br/>}
{If}{[ImageWidth], <b>Image Width:</b> [ImageWidth]<br/>}
{If}{[ImageHeight], <b>Image Height:</b> [ImageHeight]<br/>}
<hr width=\"100%\"/>



NOTE: Koha OAI metadata is extracted and stored as "oaiextracted.metadata_name", these metadata can be used in the format statement as [oaiextracted.type]

Customization in Koha for linking back to Greenstone

  • Log in to the Koha VM with the “koha” user.
  • Edit ./kohaclone/koha-tmpl/intranet-tmpl/prog/en/modules/catalogue/detail.tmpl
  • To add the Greenstone link after the Description, update the following:

Koha code

 <!-- TMPL_IF name="pages" --> <!-- /TMPL_IF --><!-- TMPL_VAR name="pages" --> <!-- TMPL_IF
NAME="illus" --><!-- TMPL_VAR NAME="illus" --><!-- /TMPL_IF -->
  <!-- TMPL_IF name="size" --><!-- TMPL_VAR name="size" --><!-- /TMPL_IF -->

Modified Koha code

 <!-- TMPL_IF name="pages" --> <!-- /TMPL_IF --><!-- TMPL_VAR name="pages" --> <!-- TMPL_IF
NAME="illus" --><!-- TMPL_VAR NAME="illus" --><!-- /TMPL_IF -->
  <!-- TMPL_IF name="size" --><!-- TMPL_VAR name="size" --><!-- /TMPL_IF -->
 <strong>Greenstone Link:</strong>
 <a href="http://[HTTP Path to your Greenstone library CGI]?a=d&c=kohaoai&d=KOHA-OAI-
TEST:<!-- TMPL_VAR NAME="biblionumber" -->" target="_blank">

Note: *“c=kohaoai” is the Greenstone collection shortname *“d=KOHA-OAI-TEST:<!-- TMPL_VAR NAME="biblionumber" -->” is the dc.Record Identifier for this record

en/developer/koha_greenstone_integration.txt · Last modified: 2023/03/13 01:46 by