VHL Network Portal

Isis-oai-provider is a software application that provides access to ISIS databases through OAI protocol to be harvested.

The application works with PHP 5.3.x.

Setting up

Method 1 - Download files

Download the last version from Downloads link at the github repository (zip or tar gz file) and extract the file to your server.

Creating a structure and extracting application files under server /opt/ directory on a Linux server:

   $ cd /opt/
   $ mkdir bireme
   $ cd bireme
   $ wget https://github.com/bireme/isis-oai-provider/tarball/master -O isis-oai-provider.tar.gz
   $ tar xvfzp isis-oai-provider.tar.gz
   $ mv bireme-isis-oai-provider-53c0abc/ isis-oai-provider

NOTE: the term 53c0abc is automatically generated during the creation of the tar.gz file, thus being different at every execution.

Downloading the application files on a Windows server:
- access the application page available at https://github.com/bireme/isis-oai-provider
- click on the download zip button to download the application files
- unpack to the directory it is intended to

Method 2 - Clone the project git repository

The advantage of this method is that you can easily update the application later, but it is necessary that the server has the git-core package installed.

Example: Creating a structure and downloading the application from repository under /opt/ directory in the server:

   $ cd /opt/
   $ mkdir bireme
   $ cd bireme
   $ git clone git://github.com/bireme/isis-oai-provider.git

Deploy the aplication on the Web Server (ex. Apache Web Server)

Option A - Using a specific VirtualHost for the web application

   <VirtualHost *:80>
      ServerName isis-oai-provider.local
      DocumentRoot /opt/bireme/isis-oai-provider/htdocs/
      <Directory "/opt/bireme/isis-oai-provider/cgi-bin">
           Options +ExecCGI
           AllowOverride None
           Order deny,allow
      </Directory>
      ScriptAlias /cgi-bin/ /opt/bireme/isis-oai-provider/cgi-bin/
      LogLevel warn
      CustomLog /var/log/apache2/isis-oai-provider.log combined
      ServerSignature On
   </VirtualHost>

Option B - Using a existing VirtualHost

Assuming you have a website already running you will only need to find out the paths to the following components:

DocumentRoot --- the directory where static files and PHP scripts are located - usually htdocs
cgi-bin --- the directory with special permissions for executing CGI scripts - usually cgi-bin
ISIS databases --- the directory on the server where ISIS databases are located - usually bases

Then move/copy or create symbolic links to the isis-oai-provider directories:

Ex. Assuming a website with the following directory structure:

 /home/sites/
            /site1/
                   htdocs/
                   cgi-bin/
                   bases/

Follow the steps below to create symbolic link to the application directories:

 $ cd /home/sites/site1/htdocs
 $ ln -s /opt/bireme/isis-oai-provider/htdocs/isis-oai-provider/ .
 $ cd /home/sites/site1/cgi-bin
 $ ln -s /opt/bireme/isis-oai-provider/cgi-bin/isis-oai-provider/ .

Adjustments before configuring

In order that ISIS-OAI-Provider works correctly, it is mandatory to rename some directories according to the platform in use.

In case it is a Linux operating system, rename the directories as follows:
- Binary executables (WWWISIS)
  - from: cgi-bin/isis-oai-provider-linux
  - to: cgi-bin/isis-oai-provider
- Metadata translation table (oai_dc)
  - from: htdocs/isis-oai-provider/gizmo-linux
  - to: htdocs/isis-oai-provider/gizmo
In case it is a Windows operating system, rename the directories as follows:
- Binary executables (WWWISIS)
  - from: cgi-bin/isis-oai-provider-windows
  - to: cgi-bin/isis-oai-provider
- Metadata translation table (oai_dc)
  - from: htdocs/isis-oai-provider/gizmo-windows
  - to: htdocs/isis-oai-provider/gizmo

NOTES:

Be sure that all binary executable files have execute rights either in the command line, or through CGI interface;
All binary executables are 32 bits version;
There are 64 bits version files compiled only for Linux.

Configuring files

Rename the sample configuration files as follows:

 $ cd htdocs/isis-oai-provider/
 $ mv oai-config-sample.php oai-config.php
 $ mv oai-databases-sample.php oai-databases.php

Modify the oai-config.php and oai-databases.php files according to the steps below:

oai-config.php

change the variable DATABASE_PATH to the 'bases' directory of current installation

DATABASE_PATH=/home/www/my-iah/bases

change the variable NAME to a label that best identify the instance

NAME=MyIAHdb

change the variable EMAIL to the mail address of the person in charge of data

EMAIL=me@institution.org

change the variables IDPREFIX and IDDOMAIN according to the domain information of your instance

IDPREFIX=br

IDDOMAIN=bvs

set the variable EARLIESTDATESTAMP to a date close to the beginning of data recording

EARLIESTDATESTAMP=1998-12-30

oai-databases.php

Each database must be configured having in mind the following structure and mandatory elements:

[set-spec]

name=
description=
database=
mapping=
prefix=oai_date_
isis_key_length=<1660|1030>
identifier_field=<tag>
datestamp_field=<tag>

[set-spec] starts and describes a section for that database and identifies the logical name of that set. This information is presented in the verb ListSets and it is also part of the unique identifier for each document within the set.

e.g.

[lilacs]

The name variable is the label to the data set to be displayed in the ListSets verb.

e.g.

name=LILACS

the description variable is the content of description showed in the ListSets verb.

e.g.

description="LILACS Database"

the database variable has the path and the database master file name.

e.g.

database=/home/www/my-iah/bases/iah/dblil

the mapping refers to the filename format used to do the mapping of contents. (Located in map/ directory)

e.g.

mapping=lilacs-dc.pft

the prefix stands for a prefix for the date field. This should be inserted in the FST file used by the invertion process.

e.g.

prefix=oai_date_

inversion sample to be included in the LILACS.FST

93 0 |oai_date_|v93^*/

the isis_key_length specifies the minimum and maximum key length used to invert data. Pay attention to the version according to the database source (e.g.. LILACS is 1660, IAH is 1030)

e.g.

isis_key_length=1660

the identifier_field informs the tag for the unique identifier of records

e.g.

identifier_field=2

the datestamp_field informs the tag for record creation date on the record

e.g.

datestamp_field=93

Therefore, when the user needs to add new databases to the configuration file, it is only required to fullfil the fields above accordingly and append them to the file.

NOTE: provided that section name is also the database name, no database duplicates are allowed.

Testing

Test the application by opening the internet browser and accessing the domain name as: http://nome_do_servidor/isis-oai-provider/

E.g. http://isis-oai-provider.local/isis-oai-provider/

OAI documentation

http://www.openarchives.org/pmh/