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 collating 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, clientname refers to the name of the client directory for the current installation.

Requirements

• Microsoft IIS, version 5.0 or greater.
• PHP, version 4.3.11 or greater.
• MapServer PHP extension, version 4.8 or greater (only required if Mapper installed).

Pre-Installation Check - 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.

EMu WebServices - local IIS Installation - Mapper only

Follow the notes in this section if IIS is running on the same machine as the one on which EMu server is installed:

1. Log in to the Windows machine as emu.
2. Start up your web browser and download the maps file maps.tar.gz. The maps should be saved in the SFU temporary directory (typically C:\SFU\tmp). The download will take some time as the map files are very large (about 900 Mb).
3. Start a Korn Shell (Start>Programs>Windows Services for UNIX>Korn Shell).
4. Enter client  clientname
5. Enter tar  xvzf  /tmp/maps.tar.gz. The maps will be extracted into the web/webservices/mapper/maps directory.
6. Enter rm  -f  /tmp/maps.tar.gz
7. Enter exit to close the Korn Shell window.
8. Log out of Windows.
9. Continue with EMu WebServices - MapServer Installation.

EMu WebServices - remote IIS Installation - Mapper only

Follow the notes in this section if IIS is running on a different machine to the one on which EMu server is installed:

1. Log in as local Administrator on the IIS Web Server machine.
2. Start up your web browser and download the maps file maps.zip. The maps should be saved in the Windows temporary directory (typically C:\WINDOWS\temp). The download will take some time as the map files are very large (about 900 Mb).
3. Start Windows Explorer.
4. Navigate to the location you saved the downloaded maps file.
5. Right-click the file and select Extract All...
6. Extract the files into the directory in which the EMu Web files are located (typically C:\Inetpub\wwwroot).
7. Remove the downloaded maps.zip file to regain space.
8. Continue with EMu WebServices - MapServer Installation.

EMu WebServices - MapServer Installation - Mapper only

Once the maps are installed the MapServer PHP extension must be added:

1. Log in as local Administrator on the IIS Web Server machine.
2. Start up your web browser and download the MapServer PHP extension file phpmapscript.zip. The file should be saved in the Windows temporary directory (typically C:\Windows\Temp).
3. Start Windows Explorer.
4. Navigate to the location you saved the downloaded MapServer PHP extension file.
5. Right-click the file and select Extract All...
6. Extract the files into the directory in which PHP is installed on your machine (typically C:\php).
7. Open the Control Panel (Start>Programs>Control Panel).
8. Double-click the System icon.
9. Select the Advanced tab and click the Environment Variables button.
10. In the System Variables list, highlight the Path entry.
11. Click the Edit button.
12. The dll directory under the directory where PHP is installed (typically C:\php\dll) must be added to the Variable value: list if it does not already appear. Remember that the semi-colon character is used as a separator between directories.
13. Click the OK button to save the change.
14. Click OK to close the Environment Variable dialog box.
15. Click OK to close the System Properties dialog box.
16. Navigate with Windows Explorer to the directory that contains the php.ini file (typically C:\WINDOWS).
17. Edit the php.ini file with Wordpad or your preferred editor application.
18. Locate the area where the PHP extensions are defined. Add the following lines (if they do not already exist):
    extension=php_sockets.dll
    extension=php_mapscript_48.dll
19. Save the file and close the editor application.
20. Close Windows Exploror.
21. Log out of Windows.

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 to the Windows machine as emu on the EMu server.
2. Start a Korn Shell (Start>Programs>Windows Services for UNIX>Korn Shell).
3. Enter client  clientname
4. Enter emuweb start
5. Enter exit to close the Korn Shell window.

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 EMu help for details on how to tailor 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 similar query screen 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 to the Windows machine as emu on the EMu server.
2. Start a Korn Shell (Start>Programs>Windows Services for UNIX>Korn Shell).
3. Enter client  clientname
4. Enter cd  utils
5. Enter reportsupdate
6. Enter exit to close the Korn Shell window.
7. Log out of Windows.

If a remote IIS installation has been performed, that is IIS 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. On the EMu server, log in to the Windows machine as emu.
2. Start a Korn Shell (Start>Programs>Windows Services for UNIX>Korn Shell).
3. Enter client  clientname
4. Enter cd  etc
5. Enter vi config
6. Locate the line containing EMUWEBSERVICESERVER. The value for EMUWEBSERVICESERVER is the leading part of a URL used to communicate with the IIS server. Modify the setting to:
   EMUWEBSERVICESERVER=http://hostname
   where hostname is the name of the host containing the IIS Web server.
7. Save the file and exit the editor.
8. Enter exit to close the Korn Shell window.
9. Log out of Windows.

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