====== 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/
  * [[http://greenstonesupport.iimk.ac.in/|Greenstone support for South Asia]] has some information about Greenstone-Koha integration. In particular, it links to [[http://www.dlnetsa.org/|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=====
  * 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==== 
 <nowiki>http://[IP of the Koha VM]:8080/cgi-bin/koha/opac/oai.pl?verb=ListIdentifiers&amp;metadataPrefix=oai_dc</nowiki>

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==== 
 <nowiki>http://[IP of the Koha VM]:8080/cgi-bin/koha/opac/oai.pl?verb=GetRecord&amp;identifier=[OAIIdentifier]&amp;metadataPrefix=oai_dc</nowiki>
=====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 <nowiki>[GreenstoneInstallation]/cgi-bin</nowiki>

Example of Apache configuration
<code>
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
</Directory>
Alias /greenstone/ "[Greenstone Installation]"
<Directory "[Greenstone Installation]">
    AllowOverride All
    Options Indexes FollowSymLinks
</Directory>
</code>
  *Restart the web server to load the configuration.
  *If the web server alias for the Greenstone installation is not "/greenstone", configure <nowiki>[GreenstoneInstallation]/cgi-bin/gsdlsite.cfg</nowiki> to use the correct httppath.
  *Make sure Greenstone is working by visiting via a webbrowser. <nowiki>http://localhost/[[httppath|to Geenstone Installation]]/cgi-bin/library.cgi</nowiki>

**IMPORTANT:**
  * 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 [{{SERVER}}{{SCRIPTPATH}}/gsdoc/patches/gsdl-koha/MetadataXMLPlugin.pm MetadataXMLPlugin.pm] to replace the one in <nowiki>[GreenstoneInstallation]/perllib/plugins/MetadataXMLPlugin.pm</nowiki>
  * 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 [{{SERVER}}{{SCRIPTPATH}}/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:
<code>
 [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
</code>
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 <nowiki>[Greenstone Installation]/perllib/cpan/perl-5.8</nowiki> to <nowiki>[Greenstone Installation]/perllib/cpan/perl-5.8.renamed
</nowiki>

=====Setup Koha OAI collection with GLI (Linux)=====
  * 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 <nowiki>[Greenstone Installation]/collect/kohaoai</nowiki>
    * Create perllib/plugins and download [{{SERVER}}{{SCRIPTPATH}}/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 <nowiki>http://[IP of the Koha VM]:8080/cgi-bin/koha/opac/oai.pl</nowiki> 
    * 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

**VList**
<code>
<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></code>
**DocumentText**
<code><h3>[classifyTitle]</h3>
<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/>
<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}{[oaiextracted.date], <b>dc.Date:</b> [oaiextracted.date]<br/>}
{If}{[oaiextracted.koharecordlink], <a href=\"[oaiextracted.koharecordlink]\">Koha
Record</a><br/>}
<br/>
<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/>}
<br/>
<b>Source</b>
<hr width=\"100%\"/>
{Or}{[screenicon],[Text]}
</code>

**DocumentImages** 
<code>
 true
</code>
**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**
<code><li>
 <strong>Description:</strong>
 <!-- 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 -->
</li></code>
**Modified Koha code**
<code><li>
 <strong>Description:</strong>
 <!-- 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 -->
</li>
<li>
 <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">
  here
 </a>
</li>
</code>
**Note:**
***“c=kohaoai”** is the Greenstone collection shortname
***<nowiki>“d=KOHA-OAI-TEST:<!-- TMPL_VAR NAME="biblionumber" -->”</nowiki>** is the dc.Record Identifier for this record