Installation

Compatibility

This plugin will work with an ICAT version of 4.9.0 or greater.

Prerequisites

Summary of steps

  1. Please follow the generic installation instructions
  2. Check that it works.

The setup.properties file

container
Values must be chosen from: TargetServer Though only Glassfish is working properly at the moment.
home
is the top level of the container installation. For Glassfish it must contain "glassfish/domains" and for JBoss (wildfly) it must contain jboss-modules.jar.
port
is the administration port of the container which is typically 4848 for Glassfish and 9990 for JBoss.
secure
must be set to true or false. If true then only https and not http connections will be allowed.

The logback.xml file

If you wish to modify the provided logging levels then rename logback.xml.example to logback.xml and edit it to suit your needs.

The run.properties file

Note: When you are using non-ASCII characters for one or more properties (e.g. for the repositoryName), the run.properties file must either be encoded as ISO 8859-1 (Latin-1), or non-ASCII characters must be represented using Unicode escapes (e.g. \u00fc for the character ü).

icat.url
The url of the machine hosting the icat service. It should normally just have the scheme, the hostname and the port.
Example value: "https://example.org:443"
icat.auth
Space separated icat plugin name and credentials for a user permitted to read all the ICAT tables that are of interest.
Example value: "simple username nick password 123456"
repositoryName
A human readable name for the repository. The name will be returned as part of the OAI-PMH "Identify" response.
Example value: "Example experimental data repository"
adminEmails
A space separated list of e-mail addresses of the repository administrator. The email addresses will be returned as part of the OAI-PMH "Identify" response.
Example value: "someone@example.org another@example.org"
requestUrl
The Base URL of the OAI-PMH interface. Must be a well-formed URL. This will be returned as part of the OAI-PMH "Identify" response, and is being used for the unique identifiers of records.
Example value: "https://www.example.org/oaipmh/request"
maxResults
The maximum number of results per page for incomplete responses. Must be an integer greater than 0.
Example value: "50"
icatDateTimeFormat
A pattern for the Java DateTimeFormatter.
Example values: "yyyy-MM-dd HH:mm:ss Z" or "MM/dd/yyyy HH:mm.ss Z"
This will be used to format date/time values when querying ICAT (see icatDateTimeZone below for details).
icatDateTimeZone
A zoneId (or time zone offset) for the of(String zoneId) method of the Java ZoneId.
Example values: "Z" or "Europe/Berlin" or "+02:00"
This will be used to format date/time values when querying ICAT. Make sure both the icatDateTimeFormat and the icatDateTimeZone match with the way date/time values are stored in your ICAT.
For example, when a harvester requests the records from 2018-08-31 07:45:20 (UTC),
  • if icatDateTimeFormat is set to "MM/dd/yyyy HH:mm.ss Z", and icatDateTimeZone is set to "+02:00", the query sent to ICAT by icat.oaipmh would use the following condition:
    "WHERE a.modTime >= '08/31/2018 09:45.20 +0200'".
  • if icatDateTimeFormat is set to "yyyy-MM-dd HH:mm:ss Z", and icatDateTimeZone is set to "Z", the query sent to ICAT by icat.oaipmh would use the following condition:
    "WHERE a.modTime >= '2018-08-31 07:45:20 +0000'".
metadataPrefixes
A space separated list of metadata formats to be supported.
At minimum, support for the Dublin Core format ("oai_dc") is required.
Example value: "oai_dc oai_datacite"
<metadataPrefix>.xslt
For each metadata format, specify the absolute path to an XSLT definition. This XSLT file must be able to transform metadata from the generic XML format (as defined by the data.* properties below) into some other well defined metadata format (such as Dublin Core).
For more information, see the example files located at "src/main/config/".
Example: "oai_dc.xslt = /home/icat/xslt/dublin_core.xsl"
<metadataPrefix>.namespace
For each metadata format, specify the namespace.
Example (official Dublin Core namespace): "oai_dc.namespace = http://www.openarchives.org/OAI/2.0/oai_dc/"
<metadataPrefix>.schema
For each metadata format, specify the link to a schema definition.
Example (official Dublin Core schema definition): "oai_dc.schema = http://www.openarchives.org/OAI/2.0/oai_dc.xsd"
data.configurations
A space separated list of identifiers for the configuration of metadata to be retrieved from ICAT.
Each listed data configuration must use a unique identifier. It is recommended to use short human readable identifiers, such as 'inv' for the data object Investigation, or 'stud' for Study.
Example value: "inv stud"
data.<configuration>.metadataPrefixes
For each data configuration, specify a space separated list of supported metadata formats (as defined in the list of metadataPrefixes above).
At minimum, support for the Dublin Core format ("oai_dc") is required.
For example, if the metadataPrefixes are "oai_dc oai_datacite", and the data.configurations are "inv stud", one might use:
  • "data.inv.metadataPrefixes = oai_dc oai_datacite", and
  • "data.stud.metadataPrefixes = oai_dc"
data.<configuration>.mainObject
For each data configuration, specify the ICAT object (from the ICAT metadata schema) which will be the main source of information when retrieving metadata from ICAT.
For example, if the data.configurations are "inv stud", one might use:
  • "data.inv.mainObject = Investigation", and
  • "data.stud.mainObject = Study"
data.<configuration>.<icatObject>.subPropertyLists
A space separated list of ICAT sub-objects which are to be included in the property hierarchy below the <icatObject> for the respective <configuration>.
For example, if the data.configurations include "inv", and data.inv.mainObject is set to "Investigation", one might use:
  • "data.inv.subPropertyLists = datasets" to include the datasets as part an investigation, and
  • "data.inv.datasets.subPropertyLists = datafiles parameters" to include the datafiles and parameters as part of a dataset.
data.<configuration>.<icatObject>.<dataTypeProperties>
A space separated list of ICAT properties to be retrieved from ICAT for the <icatObject> when retrieving metadata from ICAT.
Possible <dataTypeProperties> are: "stringProperties", "numericProperties", or "dateProperties", depending on the data type within ICAT.
For example, if the data.configurations include "inv", data.inv.mainObject is set to "Investigation", data.inv.subPropertyLists is set to "investigationUsers", and data.inv.investigationUsers.subPropertyLists is set to "user", one might use:
  • "data.inv.stringProperties = doi title summary" and "data.inv.dateProperties = startDate endDate" as properties for the investigation,
  • "data.inv.investigationUsers.stringProperties = role" as properties for the investigationUser, and
  • "data.inv.investigationUsers.user.stringProperties = fullName orcidId" as properties for the user.
responseDebug
If this (optional) parameter is included and set to "true", the metadata received when making OAI-PMH calls won't be transformed into another format.
This means, the metadata will stay in the generic XML format (as defined by the data.* properties above), and the defined metadataPrefixes properties are ignored.
This is particularly helpful for the development of custom XSLT files, in order to understand the structure of the generic XML format before attempting to transform it into some other metadata format.
responseStyle
Set this (optional) parameter to the URL of an XSL document which you want to apply to all XML responses.
One particular use for this would be to have the XML responses transform into HTML documents when making OAI-PMH calls from a web browser.

Check that icat.oaipmh works

A simple standalone test is to run:

curl -k https://localhost:8181/oaipmh/request?verb=Identify -w "\n" which should return the OAI-PMH Identify response