Installation
Compatibility
This plugin will work with an ICAT version of 4.9.0 or greater.
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