Introduction

A web service is a software component that uses open, XML-based standards and transport protocols to exchange data with calling clients. The EMu WebServices system comprises a number of standards based interfaces that provide access to data stored within EMu. These interfaces allow third party software systems to query EMu and have the results presented in a well defined XML result set. These results may then be used to present information in new and exciting ways. For example, a system may produce a map that plots latitude and longitude values for a given set of specimens.

The web services provided by EMu WebServices are:

• DiGIR (Distributed Generic Information Retrieval) - provides access to biological specimen data.
• Portal - provides querying and collation of data from multiple sources via a single source.
• Mapper - allows data from single or multiple sources to be collected and plotted on maps.
• Object Locator - allows the location of collection objects to be shown on site maps.

The EMu Mapper web service takes advantage of the excellent MapServer software to provide rendering of spatial data for web viewing. The MapServer software is installed as part of the setup of EMu WebServices if Mapper functionality is required.

A prerequisite for installing EMu WebServices is that the EMuWeb system is installed and operational. The WebServices interfaces take advantage of the low level functionality provided by  EMuWeb. EMuWeb can be installed on the local EMu server or on a remote web server. EMu WebServices must be installed on the same server as EMuWeb.

A web services component is installed as part of the EMu server-side installation. Individual clients can be configured to distribute any of the web services outlined above. By default, clients are not distributed with any web service components unless the system manager has configured the server installation bundle to distribute them. If the Mapper service is distributed, it requires the installation of the MapServer PHP extension and the unbundling of the maps. The maps are not distributed with the server install bundle due to their very large size (about 900 Mb).

The EMu WebServices software can be found in the web/webservices directory under the standard EMu installation. In the notes below, client refers to the name of the client directory for the current installation.

Requirements

• Apache, Version 1.3 or greater.
• PHP, version 5.2 or greater.
• MapServer PHP extension, version 5.2 or greater (but not 5.4.1 or 5.4.2)
  N.B. MapServer is only required if Mapper is installed.
• A C++ compiler (only required if Mapper installed).
  The Mapper installation requires the building of software on the web server machine. In order to install this software an ANSI C++ compatible compiler is required. The installation notes below have been tested with gcc and Solaris SunPRO compilers. If you do not have a compiler installed we would recommend installing gcc.

Pre-Installation Check - KE EMuWeb

Before installing and configuring EMu WebServices, EMuWeb must be installed and operational. Please refer to the EMuWeb installation instructions for details. In particular the CONFIG.php configuration file must be set up correctly.

Pre-Installation Check - Apache and PHP

Apache and PHP must be installed and operational on the web server machine before KE EMu WebServices can be installed. The PHP installation must have the sockets extension enabled. To check if the extension is accessible:

1. Log in as root on the web server machine.
2. Enter php  -m
   A list of compiled-in and loaded modules will be printed.
3. Look to see if sockets is in the list.
4. If sockets is in the list, log out and start the installation.
5. Check if sockets is installed and disabled. Enter php  -i  |  egrep  extension_dir
   A line will be printed indicating where the PHP extensions are installed.
6. Check if the directory exists and a file called php_sockets.so is present.
7. If the directory does not exist or the file is not present, you need either to build the PHP extensions (FreeBSD port lang/php5-extensions) or recompile PHP with --enable-sockets configured.
8. If the directory and file exist, you need to enable the extension. Enter php  -i  |  egrep  php.ini
   The path to the PHP initialisation file will be printed.
9. Edit the file and look for the line:
   ;extension=php_sockets.dll
   and below it add the line:
   extension=php_sockets.so
10. Restart Apache so that the extension is loaded.
11. Log out.

Pre-Installation Check - Mapper only

On Redhat the php-devel package must also be installed to provide Mapper support. To check if the php-devel is installed:

1. Log in as root on the web server machine.
2. Enter rpm  -q  -a  |  egrep  php-devel
3. If the php-devel package is not installed then install:
   Enter apt-get  install  php-devel

EMu WebServices - local UNIX Installation - Mapper only

Notes are available for PHP5.

EMu WebServices - URL Setup

Once the EMu WebServices components have been installed you can test each service to determine whether it is functioning correctly. In the URLs below, catalogue refers to the type of catalogue used in the installation  (e.g. gallery, rbg, mv, etc.). Before starting your tests please ensure that EMuWeb is functional and that the web servers are operational.

1. Log in as emu.
2. Enter client  clientname
3. Enter emuweb  start
4. Log out. 

DiGIR

http://yourserver/emuwebclientname/webservices/digir.php 

The output of the above command is an XML document containing information about the DiGIR data source (you may need to View Page Source in your browser to have the XML displayed correctly). The information shown is contained in the file web/webservices/digir/catalogue/DigirProviderFactory.php and may need to be updated. See the KE EMu help for details on how to tailor KE EMu WebServices.

http://yourserver/emuwebclientname/webservices/digir/catalogue/DigirProviderFactory.php?test=true

provides a useful test interface that allows you to query the DiGIR data source and view results. The Show EMu Fields option provides a useful mechanism to test that the field mappings from Darwin Core to EMu are specified correctly.

Portal 

http://yourserver/emuwebclientname/webservices/portal.php?queryScreen=true&stylesheet=portal/
style/portal_queryscreen.xsl

will display a simple query screen that can be used to query via the Portal. The available data sources are displayed at the top of the query area. The default installation will only enable the test data source DummyDummy. If you have a DiGIR source installed on the Portal server, you can configure which Portal to use by editing the file web/webservices/portal/fetchers/DefaultDigir.php and changing the line:

var $enabled = false;

to

var $enabled = true;

External data sources require a fetcher to be configured that describes how to interact with the data source. A sample fetcher can be found in web/webservices/portal/fetchers/SourceDigir.php.sample. For details on configuring new data sources see the EMu help. 

Mapper

http://yourserver/emuwebclientname/webservices/mapper.php?queryScreen=true&stylesheet=portal/
style/portal_queryscreen.xsl

will display a query screen very similar to the Portal's. When a search is performed the results are displayed on a map of the world. If plotting maps for a local data source, you must enable the web/webservices/portal/fetchers/DefaultDigir.php fetcher. 

Object Locator

http://yourserver/emuwebclientname/webservices/objectlocator.php?irn=nnn

where nnn is the irn of a catalogue record for which you want to show the location. For details on configuring the Object Locator please refer to the EMu help.

EMu WebServices - Report Setup

Both the Mapper and Object Locator web services can be configured to be report types in EMu. Once installed they appear as a Web Map Report and Object Locator Report respectively. To install the reports:

1. Log in as emu.
2. Enter client  clientname
3. Enter cd  utils
4. Enter reportsupdate
5. Log out.

If a remote UNIX installation has been performed, that is, Apache is running on another server from the EMu server, you need to set a configuration variable with the hostname of the server on which EMu WebServices is located:

1. Log in as emu on the EMu server.
2. Enter client  clientname
3. Enter cd  etc
4. Enter vi  config
5. Locate the line containing EMUWEBSERVICESERVER. The value for EMUWEBSERVICESERVER is the leading part of a URL used to communicate with the Apache server. Modify the setting to:  EMUWEBSERVICESERVER=http://hostname
   where hostname is the name of the host containing the Apache web server.
6. Save the file and exit the editor.
7. Log out. 

Mapper Report 

In order to display a map of a matching set of catalogue records you need to design a report that contains as a minimum the latitude, longitude and some other identity string (e.g. Scientific Name or Genus, etc.). More than one identity string can be included. As the Mapper works with Darwin Core based XML a mapping is required to transform the XML produced by the EMu report into a form acceptable to the Mapper. The mapping can be found in web/webservices/translator/catalogue/TranslatorFactory.php

An example definition is:

var $translations = array (
    'atom[name=IdeQualifiedName]' => 'ScientificName',
    'atom[name=DetCentroidLatitude]' => 'latitude',
    'atom[name=DetCentroidLongitude]' => 'longitude',
    'atom[name=IdeFiledAsClass]' => 'Class',
    'atom[name=IdeFiledAsFamily]' => 'Family',
    'atom[name=IdeFiledAsGenus]' => 'Genus',
    'atom[name=IdeFiledAsSpecies]' => 'Species',
    'atom[name=IdeFiledAsSubSpecies]' => 'SubSpecies',
    'atom[name=IdeFiledAsTypeStatus]' => 'TypeStatus',
);

The table defines a catalogue field (shown in bold above) mapped to the standard DiGIR XML name (shown in italics). The fields used in defining a report must appear in the translation table. The mapped latitude and longitude fields must always appear in the report (DetCentroidLatitude and DetCentroidLongitude respectively). Once the report is invoked your web browser will start and the map will be displayed. 

Object Locator Report 

When designing a report in KE EMu to interface to the Object Locator web service, the report should contain one field only, namely irn. When the report is invoked your web browser will start and display the location map.