The IMu OAI-PMH web service

The IMu OAI-PMH web service implements the OAI-PMH and uses an instance of the EMu Collections Management System (CMS) as its data store. Collectively, the web service and the EMu installation act as an OAI-PMH repository. The web service is implemented in the PHP programming language and uses the IMu toolset to harvest data from the EMu installation.

The IMu OAI-PMH web service uses the PHP programming language. The service requires:

  • PHP version 5.3.0 or later.
  • The libxml PHP extension. The extension is usually available by default with the required PHP version, although some systems may maintain it separately.
  • The XMLWriter extension. The extension is usually available by default with the required PHP version, although some systems may maintain it separately.

Using the -m switch with the command line interface to PHP displays a list of the available extensions. This list should include libxml and xmlwriter (some output has been omitted for brevity):

$ php -m
[PHP Modules]
Core
…
libxml
…
xmlwriter
…

PHP configuration

The following PHP configuration options should be set in the PHP configuration file (php.ini) for the service to run correctly:

Name Description

date.timezone

Specifies the default time zone used by all PHP date / time functions. The OAI-PMH web service has to generate and parse a number of dates and times as part of its regular operation. For example: date.timezone = Australia/Melbourne

default_socket_timeout

Specifies the default timeout (in seconds) for socket based streams. The OAI-PMH web service uses a socket based stream to connect with the EMu Collections Management System via the IMu toolset. If the value is not large enough, the connection may be closed before a response is received. As the default value (60 seconds) may sometimes not be large enough, the value should be increased. For example: default_socket_timeout = 600

The IMu OAI-PMH web service comprises:

  • An implementation of the OAI-PMH.
  • The implementations of the metadata formats that the IMu OAI-PMH web service supports.
  • An interface to the EMu CMS via the IMu toolset.

Each of these components is configured separately.

The setup of the IMu OAI-PMH repository configuration is such that it is possible to override or add to existing configurations. There are three levels of localization:

Setting Level Description

Default (common)

Axiell provides some default configuration settings and metadata formats that are common to all clients. In practice there are not many configuration options that are useful at this level because most options are, at a minimum, client specific.

Client-specific (client)

Axiell can also provide configuration and metadata formats that are specific to each client. These are set up, maintained and distributed by Axiell with the OAI-PMH repository code for the client. Settings at this level override those at the common level.

Site-specific (local)

Configurations at this level are set up and maintained by the customer. This allows customers to add to or modify configurations and metadata formats supplied by Axiell. Settings at this level override those at the common and client level.

Warning

Configuration files at the common and client levels are maintained and distributed by Axiell with the IMu OAI-PMH web service. Clients must not modify these files as any changes they make will be lost when the service is upgraded. Changes or additions to the service not made by Axiell should be maintained at the local level. Files maintained here will be preserved when the service is upgraded.

Configuration files for the implementation of the OAI-PMH and for the interface to the EMu Collections Management System are located under the config directory:

Setting Level Location

Default (common)

oai-pmh/ws/common/config

Client-specific (client)

oai-pmh/ws/client/config

Site-specific (local)

oai-pmh/ws/local/config

Configuration files are specified in the INI file format. The allowed configuration files under the config directory are:

  • ws.ini
  • oai.ini
  • filter.ini
  • sets.ini

Web service settings are specified in the ws.ini file. This file has options for the interface to the EMu Collections Management System and options related to the web service that are not specifically related to the OAI-PMH. The options are:

Name Description Default Value Mandatory Multiple Allowed

dateFormat

The date format used by the EMu CMS.

d#m#Y

No

No

fetchLimit

The maximum number of records returned at one time by the EMu CMS.

1000

No

No

host

The host name of the server running the IMu server.

localhost

No

No

port

The port number (main-port) used by the IMu server.

40000

No

No

setMode

Specifies the repository support for sets. See Sets.

off

No

No

supportedFormats

The metadata formats, other than oai_dc that this EMu OAI-PMH service supports. See Metadata formats.

oai_dc

No

Yes

timeFormat

The time format used by the EMu CMS.

H#i

No

No

traceFile

The path to a file for writing trace (debugging) information. The file must already exist and have permissions such that it can be written to by the web server (e.g. apache) process.

(None)

No

No

traceLevel

The level of detail to put in trace (debugging) information. The higher the number, the more detail.

1

No

No

version

The version of the Axiell IMu OAI-PMH web service library files to use. Currently only version 2.0 is supported.

2.0

No

No

OAI-PMH settings are specified in the oai.ini file. This file has options related to the OAI-PMH itself. The options are:

Name Description Default Value Mandatory Multiple Allowed

adminEmail

The email address of an administrator of the repository. Part of the response to the Identify request.

(None)

Yes

Yes

earliestDatestamp

A UTC datetime that is the guaranteed lower limit of all date stamps recording changes, modifications or deletions in the repository. Part of the response to the Identify request.

1970-01-01T00:00:00Z

No

No

identifierPrefix

The leading part of the identifier value returned with an OAI-PMH headerClosed The part of certain OAI-PMH responses that contains information that can be used for selective harvesting response.

Unknown interpreted text role "term".

(None)

Yes

No

repositoryName

A human readable name for the repository. Part of the response to the Identify request.

KE OAI-PMH Repository

No

No

With filters it is possible to globally restrict the records returned from the EMu CMS. Filters are specified in the filter.ini configuration file. The name of the filter, which is only used for diagnostic purposes, is specified as a section name with the other set details included in that section. Multiple sections can be specified. If multiple sections are specified, then all conditions must be met for a record to be returned. The options allowed in a section are:

Name Description Mandatory Multiple Allowed

term[]

A two part option that specifies an EMu column and a value, in that order. Only records that have the specified value in the specified column will be included with the records returned from the EMu CMS.

Yes

Required

Note

The trailing open and close square brackets [] are required for the term option.

We can, for example, specify two filters with the names department and music respectively:

[department]
term[] = "SecDepartment_tab"
term[] = "Art"

[category]
term[] = "Category_tab"
term[] = "Music"

The columns used in the filter.ini file must exist in all of the modules from which you are retrieving data. See Metadata formats.

Sets allow repository items to be partitioned arbitrarily into groups. The IMu OAI-PMH web service supports three set modes. The set mode is specified in the ws.ini configuration file. The modes are:

  • off

    The off setting disables set support. This mode should be used if a repository does not require sets. In this mode the correct response is generated for the ListSets request; the correct response is also generated with the ListIdentifiers or ListRecords requests if the set argument is included. This is the default setting.

  • on

    The on setting requires that the setSpec and setName values are stored in specialized EMu record columns, unlike the legacy mode which requires set details to be stored in a configuration file. This has a number of advantages over the legacy setting:

    • Sets can be specified across multiple modules.
    • Hierarchical sets are supported, which allows for a much finer grained specification of set membership.
    • The performance of the ListIdentifiers and ListRecords requests is improved.
    • Users can see, add or modify set membership (if they have the correct permissions) when viewing records in EMu.

Note: The on setting requires additional database support. Please contact Axiell for details.

  • legacy

    The legacy setting emulates the set support of the previous version of the IMu OAI-PMH web service. In this mode, sets are defined in the sets.ini file. The setSpec value is specified as a section name with the other set details included in that section. The options allowed in a section are:

    NameDescriptionMandatoryMultiple Allowed

    name

    A short, human-readable string naming the set.

    No

    No

    description

    A description of the set. See the Collection and Set Descriptions section of the OAI-PMH Guidelines for Repository Implementers for more details. Only the Dublin Core description element scheme is supported.

    No

    No

    module

    The name of the EMu module to which the term[] option applies. For example: module ="ecatalogue"

    Yes

    No

    term[]

    A two part option that specifies an EMu column and a value, in that order. Any EMu record in module (see above) that matches this term (i.e. where column has value) is considered part of the set.

    Note: The trailing open and close square brackets [] are required for the term option.

    Yes

    Required

We can, for example, specify two sets with a setSpec value of music and video respectively:
[music]
name = "Music Collection"
description = "Our music collection"
module = "ecatalogue"
term[] = "Category_tab"
term[] = "Music"
[video]
name = "Video Collection"
module = "ecatalogue"
term[] = "Category_tab"
term[] = "Video"

Warning

The legacy setting is deprecated and may be removed in a later version of the IMu OAI-PMH web service.