Installing isis-oai-provider

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 -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:

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://

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
      ScriptAlias /cgi-bin/ /opt/bireme/isis-oai-provider/cgi-bin/
      LogLevel warn
      CustomLog /var/log/apache2/isis-oai-provider.log combined
      ServerSignature On

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:


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.

  1. 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
  2. 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


  1. Be sure that all binary executable files have execute rights either in the command line, or through CGI interface;
  2. All binary executables are 32 bits version;
  3. 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:


  • change the variable DATABASE_PATH to the 'bases' directory of current installation
  • change the variable NAME to a label that best identify the instance
  • change the variable EMAIL to the mail address of the person in charge of data
  • change the variables IDPREFIX and IDDOMAIN according to the domain information of your instance
  • set the variable EARLIESTDATESTAMP to a date close to the beginning of data recording


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

  • [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.


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


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


description="LILACS Database"
  • the database variable has the path and the database master file name.


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



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



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)


  • the identifier_field informs the tag for the unique identifier of records


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



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.


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