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. KE 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 KE 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 5.2 or greater. (N.B. KE has bundled a copy of PHP 5.2.5 available at php_5_2_5_windows.zip. If you are installing the Mapper, we recommend that  you install the KE packaged PHP version as it includes the MapServer dll). 
  N.B. if you decide to install MapServer via another mechanism, we recommend that you do not use production release versions 5.4.1 and 5.4.2 due to an issue they have with spatial querying.
• MapServer PHP extension, version 5.2 or greater (only required if Mapper installed).

Pre-Installation Check - EMuWeb

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

Installing the KE Bundled PHP 5.2.5 Version

KE provides a bundled version of PHP 5.2.5 that can be installed easily, and which contains the MapScript dll prebuilt for use with the Mapper.

You do not have to install this version but if you do not require an alternative PHP version this is probably the simplest way to get PHP running.

1. Log in as local Administrator on the IIS Web Server machine.
2. Start your web browser and download the PHP bundle php_5_2_5_windows.zip.
   The file should be saved to the Windows temporary directory (typically C:\WINDOWS\temp).
3. Start Windows Explorer.
4. Navigate to the location to which you saved the php_5_2_5.zip file.
5. Right-click the file and select Extract All...
6. Extract the files into the root directory C:\ 
   This will create a directory 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 C:\PHP and C:\PHP\dlls directories must be added to the Variable value: list. Remember that the semi-colon character is used as a separator between directories. 
    The Path will therefore need to have:
    ;C:\PHP;C:\PHP\dlls
    added to the end.
13. Click the OK button to save the change.
14. Click OK to close the Environment Variable dialogue box.
15. Click OK to close the System Properties dialogue box.
16. Navigate with Windows Explorer to the directory that contains the php.ini file (C:\PHP).
17. Restart the Windows computer to ensure the Path variable is re-read by all components.
18. Once the machine is rebooted, start Windows Explorer and navigate to C:\PHP.
19. Right-click C:\PHP\php.ini and select edit.
20. If there are any locally customised requirements, set them here. 
    In particular check that the following variables:  
    doc_root
    browsecap
    upload_tmp_dir
    session.save_path
    are set appropriately for your server. 
21. Save C:\PHP\php.ini.
22. In Windows Explorer, right-click C:\PHP\php.ini and select Properties from the popup menu.
    The php.ini Properties dialogue will appear.
23. Alter the file permissions so that  Everyone has Read permissions on the file.
24. Close the php.ini Properties dialogue box.
25. Close Windows Explorer.
26. Open the Windows Registry Editor by clicking Start>Run and entering RegEdit and clicking OK.
27. Click on HKEY_LOCAL_MACHINE/SOFTWARE and in the right hand panel, right-click and select New and add a new String  Value.
28. Enter the name IniFilePath for the identifier.
29. Right-click IniFilePath and select Modify and enter C:\PHP in the value field and click OK.
30. Close the Windows Registry Editor.
31. Windows 2003: Start Internet Information Services Manager (Start>Settings>Control Panel>Administrative Tools>Internet Information Services (IIS) Manager)
    -OR-
    Windows XP: Start Internet Information Services (Start>Settings>Control Panel>Administrative Tools>Internet Information Services)
    -OR-
    Windows 2000: Start Internet Service Manager (Start>Settings>Control Panel>Administrative Tools>Internet Service Manager)
32. The Management Console program will appear.
33. Find the web site that will be used to access KE EMu. The notes below assume the Default Web Site.
34. Right-click the Default Web Site and select Properties.
35. Click the Home Directory tab then press the Configuration button then the  Add button.
36. Browse using the Executable Browse button to C:\PHP and select php5isapi.dll (you may need to select *.dll file types from the drop down control if php5isapi.dll is not visible).
37. Enter an extension .php.
38. Click OK, Apply, OK as required.
39. Close IIS Manager.
40. Click Start>Run and enter NET STOP iisadmin to stop the web system.
41. Click Start>Run and enter NET START w3svc to start the system.
42. Copy the file C:\PHP\info.php to C:\inetpub\wwwroot (or the appropriate document root for your system).
43. Test the system: using a browser on that machine enter the URL:
    http://localhost/info.php
    You should get a PHP information page. Using Ctrl-F search for MapScript and check there is a section on the page with that heading.

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

NB This step is NOT required if you have installed the bundled KE PHP 5.2.5 package. Instead skip to the next step

If you are not using the KE bundled PHP version then 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 KE 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 KE EMuWeb is functional and that the web servers are operational.

1. Log in to the Windows machine as emu on the KE 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 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 KE 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 KE 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 KE EMu help.

EMu WebServices - Report Setup

Both the Mapper and Object Locator web services can be configured to be report types in KE 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 KE 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 KE EMu server, you need to set a configuration variable with the hostname of the server on which KE 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 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.