|Unix: Installing EMu WebServices|
|EMu 4.0 Install/Upgrade Notes|
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:
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.
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:
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:
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.
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.
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.
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;
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.
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.
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:
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:
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 (
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.
|Last Updated on Wednesday, 27 January 2010 13:07|