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 root password secret"
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.
sets
A space separated list of sets to be available in the repository (optional).
Sets can be used to group items for the purpose of selective harvesting. Each set must be defined using a unique identifier string.
Example value: "exampleSetA exampleSetB exampleSetC"
sets.<set>.name
For each set, specify a descriptive, human readable name. This will be returned as part of the OAI-PMH "ListSets" response.
Example: "sets.exampleSetA.name = Example Set A"
sets.<set>.configurations
For each set, specify a space separated list of relevant data configurations. If no further conditions are applied, all items of the relevant data configurations will be affiliated with the set.
For example, if the sets are "exampleSetA exampleSetB exampleSetC" and the data.configurations are "inv stud" where data.inv.mainObject is set to "Investigation" and data.stud.mainObject is set to "Study", one might use:
  • "sets.exampleSetA.configurations = inv stud" to say that the set "exampleSetA" shall consist of both Investigations and Studies,
  • "sets.exampleSetB.configurations = inv stud" to say that the set "exampleSetB" shall also consist of both Investigations and Studies, and
  • "sets.exampleSetC.configurations = inv" to say that the set "exampleSetC" shall consist only of Investigations.
sets.<set>.condition.<configuration>
For each set and each data configuration, optionally specify an additional condition. Only items that meet this condition will be affiliated with the set.
Conditions must be defined using regular ICAT query syntax. Use the entity variable "a" to access the attributes of the configured main object, e.g. "a.modTime", and use custom entity variables for related objects (see sets.<set>.join.* below).
For example, if the sets are "exampleSetA exampleSetB exampleSetC", the sets.exampleSetA.configurations are "inv stud", the sets.exampleSetB.configurations are "inv stud", and the sets.exampleSetC.configurations are "inv", one might use:
  • "sets.exampleSetA.condition.stud = a.modTime <= '2018-07-20 10:00:00'" to say that Studies shall only be affiliated with the set "exampleSetA" if they were modified before 2018-07-20 10:00:00.
  • "sets.exampleSetB.condition.inv = kw.name = 'Nickel' OR kw.name = 'Ni'" to say that Investigations shall only be affiliated with the set "exampleSetB" if they are related to a keyword with name "Nickel" or "Ni". In this example, it is assumed that sets.exampleSetB.join.inv is set to "JOIN a.keywords AS kw", hence the entity variable "kw" is used in the query.
  • Leave "sets.exampleSetC.condition.inv" blank to say that all Investigations shall be affiliated with the set "exampleSetC".
sets.<set>.join.<configuration>
For each set and each data configuration, optionally specify additional data objects to be joined when retrieving the items of the set.
This may be needed to be able to specify certain conditions (see sets.<set>.condition.* above).
Use the entity variable "a" to access the relations of the configured main object, e.g. "JOIN a.keywords AS kw".
For example, if the sets include "exampleSetB" and the sets.exampleSetB.configurations are "inv stud" where data.inv.mainObject is set to "Investigation" and data.stud.mainObject is set to "Study", one might use:
  • "sets.exampleSetB.join.inv = JOIN a.keywords AS kw" to say that in the query used to retrieve the Investigations related to the set "exampleSetB", the related keywords shall be joined and made accessible as entity variable "kw".
  • "sets.exampleSetB.join.stud = JOIN a.studyInvestigations AS si JOIN si.investigation AS i JOIN i.keywords AS kw" to say that in the query used to retrieve the Studies related to the set "exampleSetB", the keywords of the related studyInvestigations shall be joined and made accessible as entity variable "kw".
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 XSLT document which you want to apply to all XML responses. The browser's same-origin policy requires this file to be hosted on the same server as icat.oaipmh.
One particular use case for this would be to have the XML responses transform into HTML documents when making OAI-PMH calls from a web browser. This is particularly useful for debugging. A suitable XSLT file for this purpose can be found here.

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