is an application designed to allow deployment of data using the TAPIR protocol.
This Guide is split into three parts:
- Before you install – dealing with the way in which you need to prepare for TapirLink. This requires appropriate hardware, software and some configuration to be performed. This step will likely require your database administrator and Information Technology (IT) support group to be involved.
- Installation – dealing with how to install the TapirLink software. This is relatively easy, but requires particular access privileges to the web server and will likely need some involvement from an IT support group.
- Configuration – not highly technical. Requires knowledge of the database, its fields and values. You will also need to have access to the setup pages on the web server in the TapirLink installation previously completed.
Before you Install
Installation of TapirLink
is relatively easy, however, you need to have your data and infrastructure prepared before you can deploy your data over the web.
To create a functional data provider using TapirLink
, your organization will need to have a physical web server outside of the corporate firewall which your IT support group will allow you to install software on. This server requires a web server package, such as Apache
. Additionally, you will need PHP
(make sure to use version 4.2.3 or higher) with the PHP mbstring module
enabled and another PHP module to allow connection to the specific database package that you are planning to use. Currently, TapirLink
can only expose data that is stored in a relational database. Please check if your database is supported before installing: http://phplens.com/adodb/supported.databases.html
has been initially used by specimen/observation data providers, it is a general purpose package that can be used to serve any kind of data. Since TAPIR has been designed for federated networks, each data provider needs to choose one or more data sharing standards to use. Those currently available for specimen/observation data providers include:
There are several ways to approach the database package on the web server:
- Expose your production database to the web server to allow for a direct connection to the production database,
- Construct a “mirror” database to be a direct copy of the production database, and then perform more complex mapping of the fields to the data sharing standard chosen in TapirLink’s configuration (described in the Post-Installation section), or
- Construct a “mirror” of the production database so that the fields match the data sharing standard you will use in TapirLink, and then perform the translation from your Production Database data to this standard when you upload data, making mapping easier in TapirLink.
Each option has its advantages and drawbacks, so the decision should be on a case by case basis.
There are two ways to download and install TapirLink
- Download the latest release package. Choose the zip file if you are installing on a Windows platform, or the tarball for the other platforms. Extract the file after downloading. This is the easiest and most common way of downloading, but it does not offer any facilities to upgrade to newer versions in the future.
- Check out the TapirLink code from the Subversion repository. This option will probably take more time because you will need a Subversion client software. However, it will be easier to upgrade whenever necessary. You can find more information about this installation option here. When using the Subversion client, you will need to indicate the TapirLink repository address: https://digir.svn.sourceforge.net/svnroot/digir/tapirlink/trunk. If you want to avoid downloading an unstable version, you can specify the corresponding revision number of the latest stable release. This can be found in the latest version of the ChangeLog file.
After downloading TapirLink
, configure your web server to expose the admin and www directories. The admin directory must be password protected and behind a secure connection if possible. For example, extract the TapirLink
archive to a location on your web server outside of the document root. Create Apache aliases to the www and admin directories called tapir and tapiradmin respectively. If using IIS configure the two directories for web sharing with appropriate aliases.
All directories must be readable by the web server user and the config, log, cache and statistics directories must be writable (but not exposed to the web).
Check your installation by navigating to http://your_server/your_admin_alias/check.php and you will see a page entitled TapirLink
Navigate to http://your_server/your_admin_alias/configurator.php to set up your first resource.
The resource is setup in six stages. As you progress through the process, you will be presented with a separate page for each stage. Each step has solid documentation on what should be in each field. Once you’ve finished the process, you can access the pages again via the configurator page (shown on the right) whenever you need to make any changes.
- Stage 1 – Descriptive metadata regarding your data source.
- Stage 2 – The connection details, driver, username, and password for your database.
- Stage 3 – Defines the database tables that you will serve information from, including joins between the fields.
- Stage 4 – Set up simple filter criteria to enable you to prevent particular records from being available.
- Stage 5 – Select the data standard that you chose earlier to map your data to (see below).
- Stage 6 – Configure items such as maximum number of records and case sensitivity.
During Stage 5 of the configuration, you will need to map your fields in the database to the fields in your chosen data sharing standard. Depending on how your database was implemented in the pre-installation section, this will either be a direct mapping of fields, or a process where you need to perform some conversions.
Mapping of the fields in your database is performed via the configurator page, as shown on the left. Each field in the chosen data standard needs to be mapped to particular fields in your database, and can be done as single columns, server variables or via fixed values.
The key fields are marked with asterisks, and any other fields may or may not be mapped.
The aim of this mapping is to map as much of the data sharing standard as possible. If your database was originally designed with this in mind, all fields will be present. However, many legacy databases will not have all the fields and the mapping will not be complete for TapirLink
Having completed the configuration click the save new resource button. You can test the resource by navigating to http://your_server/your_www_alias/tapir_client.php. Using this client you can experiment with the different requests that TapirLink
Your final step should be to reference the new TapirLink
implementation with the appropriate data portal service, such as GBIF
Data Sharing Standards:
Web server software: