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 
 * Greenstone-Koha Live CD project http://gsdlkohalive.sourceforge.net/
 * Greenstone support for South Asia has some information about Greenstone-Koha integration. In particular, it links to Digital Library Network South Asia, which emphasises use of Greenstone and Koha.

Setup Koha Server

 * Visit Koha official site - http://koha.org. In the download page, you can download Koha as a virtual machine from http://kylehall.info/index.php/projects/koha/koha-virtual-appliance.
 * Start up your VMWare Server after the Koha VM (Virtual Machine) is downloaded, and use "Add Virtual Machine to Inventory" to add Koha VM to your VMWare 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
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.
 * 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 show a list of OAI records
http://[IP of the Koha VM]:8080/cgi-bin/koha/opac/oai.pl?verb=ListIdentifiers&metadataPrefix=oai_dc 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/oai.pl?verb=GetRecord&identifier=[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 http://www.greenstone.org/download
 * 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/"  AllowOverride None Options ExecCGI +MultiViews FollowSymLinks Order allow,deny Allow from all  Alias /greenstone/ "[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

IMPORTANT: [Greenstone Installation]/perllib/LWP.pm [Greenstone Installation]/perllib/URI.pm [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.
 * The MetadataXMLPlugin.pm has been modified to allow the custom OAIMetadataXMLPlugin.pm to work properly. However, the fix is not in any current tagged version. Please download [/gsdoc/patches/gsdl-koha/MetadataXMLPlugin.pm MetadataXMLPlugin.pm] to replace the one in [GreenstoneInstallation]/perllib/plugins/MetadataXMLPlugin.pm
 * 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 [/gsdoc/patches/gsdl-koha/koha_required.zip koha_required.zip] to the "perllib" directory in the main Greenstone's perllib folder
 * After the file is unzipped, you should see the following files/folders:
 * 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)
metadata: oaiextracted.type sort: oaiextracted.title buttonname: Koha Catalog Type VList [link][icon][/link] [highlight][link]{Or}{[classifyTitle],[Title]}[/link] {If}{[numleafdocs],,{If}{[Title], Extracted Title: [Title] }}[highlight] {If}{[Date], _textdate_[Date] } {If}{[NumPages], _textnumpages_[NumPages] } {If}{[Source], _textsource_[Source] } DocumentText [classifyTitle] Greenstone Metadata  dls.Title: [dls.Title] dls.Subject: [dls.Subject] dc.Identifier: [dc.Identifier] {If}{[oaiextracted.title],Koha Metadata, Koha Metadata (No Koha Metadata Extracted) }  {If}{[oaiextracted.title], dc.Title: [oaiextracted.title] } {If}{[oaiextracted.type], dc.Type: [oaiextracted.type] } {If}{[oaiextracted.date], dc.Date: [oaiextracted.date] } {If}{[oaiextracted.koharecordlink], Koha Record } Extracted Metadata  {If}{[Title], Title: [Title] } {If}{[Date], Publication Date: [Date] } {If}{[NumPages], No. of Pages: [NumPages] } {If}{[FileFormat], File Format: [FileFormat] } {If}{[ImageWidth], Image Width: [ImageWidth] } {If}{[ImageHeight], Image Height: [ImageHeight] } Source  {Or}{[screenicon],[Text]} DocumentImages true NOTE: Koha OAI metadata is extracted and stored as "oaiextracted.metadata_name", these metadata can be used in the format statement as [oaiextracted.type]
 * Starting up the GLI server by running ./gli.sh
 * 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 [/gsdoc/patches/gsdl-koha/OAIMetadataXMLPlugin.pm OAIMetadataXMLPlugin.pm] 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/oai.pl
 * 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
 * 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

Customization in Koha for linking back to Greenstone
Koha code  Description:  Modified Koha code  Description: </li>  Greenstone Link: <a href="http://[HTTP Path to your Greenstone library CGI]?a=d&c=kohaoai&d=KOHA-OAI- TEST:" target="_blank"> here </a> </li> Note:
 * 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:
 * “c=kohaoai” is the Greenstone collection shortname
 *  “d=KOHA-OAI-TEST:”  is the dc.Record Identifier for this record