mirror of
https://github.com/DSpace/DSpace.git
synced 2025-10-07 01:54:22 +00:00
36e5885630
========= (Andrea Bollini) - SF Patch #1687815 Search function for select eperson JSPUI (Richard Jones) - SF Patch #1659868 Improved database level debugging - SF Patch #1659901 Import community and collection structure - SF Patch #1659837 ItemIterator now deals with item ids also - SF Patch #1659796 Create administrator wtih command line options - SF Patch #1659841 Add option to clear context object cache (Stuart Lewis) - SF Patch #1641678 [dspace]/bin scripts for import and export - SF Patch #1642336 Restrict domains of self-registered users - SF Patch #1587225 Google and html sitemap generator (Monika Mevenkamp) - SF Patch #1654466 dsprop convenience script (Dorothea Salo) - SF Patch #1557948 Link subjects and authors on item pages git-svn-id: http://scm.dspace.org/svn/repo/branches/dspace-1_4_x@1781 9c30dcfa-912a-0410-8fc2-9e0234be79fd
1379 lines
86 KiB
HTML
1379 lines
86 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd"><html>
|
|
<head>
|
|
<title>DSpace System Documentation: Configuration and Customization</title>
|
|
<link rel="StyleSheet" href="style.css" type="text/css">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
|
|
</head>
|
|
|
|
<body>
|
|
<h1>DSpace System Documentation: Configuration and Customization</h1>
|
|
|
|
<p><a href="index.html">Back to contents</a></p>
|
|
|
|
<p>There are a number of ways in which DSpace can be configured and/or customized:</p>
|
|
|
|
<ul>
|
|
<li>Altering the configuration files in <code><i>[dspace]</i>/config</code></li>
|
|
|
|
<li>Creating modified versions of the JSPs; these can be placed separately from and override the default installed JSPs, so that future updates of the code won't overwrite your changes</li>
|
|
|
|
<li>Implementing a custom 'plug-in' class -- for example, an 'authenticator' class, so that user authentication in the Web UI can be adapted and integrated with any existing mechanisms your organization might use, or a 'media filter' to generate thumbnails or extract full text from a new file format</li>
|
|
|
|
<li>Editing the source code</li>
|
|
</ul>
|
|
|
|
<p>Of these methods, only the last is likely to cause any headaches; if you update the DSpace source code directly, particularly core class files in <code>org.dspace.*</code> or <code>org.dspace.storage.*</code>, it may make applying future updates difficult. Before doing this, it is strongly recommended that you <a href="http://wiki.dspace.org/DspaceResources">e-mail the DSpace developer community</a> to find out the best way to proceed, and hte best way to implement your change in a way that can be <A href="http://wiki.dspace.org/HowToContribute">contributed back to DSpace</a> for everyone's benefit (and saving you from having sole responsibility to maintain the code).</p>
|
|
|
|
<h2><a name="dspacecfg" id="dspacecfg">The <code>dspace.cfg</code> Configuration Properties File</a></h2>
|
|
|
|
<p>The primary way of configuring DSpace is to edit the <code>dspace.cfg</code>. You'll definitely have to do this before you can operate DSpace properly. <code>dspace.cfg</code> contains basic information about a DSpace installation, including system path information, network host information, and other things like site name.</p>
|
|
|
|
<p>The default <code>dspace.cfg</code> is a good source of information, and contains comments for all properties. It's a basic Java properties file, where lines are either comments, starting with a '<code>#</code>', blank lines, or property/value pairs of the form:</p>
|
|
<pre>
|
|
property.name = property value
|
|
</pre>
|
|
|
|
<p>The <cite>property value</cite> may contain <em>references</em> to other
|
|
configuration properties, in the form
|
|
<code><b>${</b></code><cite>property.name</cite><code><b>}</b></code>.
|
|
This follows the <code>ant</code> convention of allowing references
|
|
in property files. A property may not refer to itself. Examples:
|
|
<pre>
|
|
property.name = word1 ${other.property.name} more words
|
|
property2.name = ${dspace.dir}/rest/of/path
|
|
</pre>
|
|
|
|
<p>Due to time constraints, this document does not contain an exhaustive list of properties; they are all listed in the supplied <code>dspace.cfg</code>. Below are some particularly relevant properties with notes for their use:</p>
|
|
|
|
<table>
|
|
<caption>
|
|
<code>dspace.cfg</code> Main Properties (Not Complete)
|
|
</caption>
|
|
|
|
<tbody>
|
|
<tr>
|
|
<th>Property</th>
|
|
|
|
<th>Example Values</th>
|
|
|
|
<th>Notes</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>dspace.dir</code></td>
|
|
|
|
<td><code>/dspace</code></td>
|
|
|
|
<td>Root directory of DSpace installation. Omit the trailing '/'. Note that if you change this, there are several other parameters you will probably want to change to match, e.g. <code>assetstore.dir</code>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>dspace.url</code></td>
|
|
|
|
<td><code>http://dspace.myu.edu</code><br>
|
|
<code>http://dspacetest.myu.edu:8080</code></td>
|
|
|
|
<td>Main URL at which DSpace Web UI webapp is deployed. Include any port number, but do not include a trailing '/'</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>dspace.hostname</code></td>
|
|
|
|
<td><code>dspace.myu.edu</code></td>
|
|
|
|
<td>Fully qualified hostname; do not include port number</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>dspace.name</code></td>
|
|
|
|
<td><code>DSpace at My University</code></td>
|
|
|
|
<td>Short and sweet site name, used throughout Web UI, e-mails and elsewhere (such as OAI protocol)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>config.template.foo</code></td>
|
|
|
|
<td><code>/opt/othertool/cfg/foo</code></td>
|
|
|
|
<td>When <code>install-configs</code> is run, the file <code><i>[dspace]</i>/config/templates/foo</code> file will be filled out with values from <code>dspace.cfg</code> and copied to the value of this property, in this example <code>/opt/othertool/cfg/foo</code>. <a href="#templates">See here for more information.</a></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>plugin.sequence.org.dspace<br>.eperson.AuthenticationMethod</code></td>
|
|
|
|
<td><code>org.dspace.eperson<br>.X509Authentication, org.dspace.eperson<br>.PasswordAuthentication</code></td>
|
|
|
|
<td>Comma-separated list of classes implementing the <code>org.dspace.eperson.AuthenticationMethod</code> interface, which make up the <a href="#authenticate">authentication stack</a>. Authentication methods are called on in the order listed.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>authentication.x509.keystore.path</code></td>
|
|
|
|
<td><code>/tomcat/conf/keystore</code></td>
|
|
|
|
<td>Path to Java keystore containing Client CA's certificiate for client X.509 certificates (Optional; only needed if X.509 user authentication is used.)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>authentication.x509.keystore.password</code></td>
|
|
|
|
<td><code>changeit</code></td>
|
|
|
|
<td>Password to Java keystore configured above in <code>authentication.x509.keystore.path</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>handle.prefix</code></td>
|
|
|
|
<td><code>1721.1234</code></td>
|
|
|
|
<td>The Handle prefix for your site, <a href="install.html#handles">see the Handle section</a></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>assetstore.dir</code></td>
|
|
|
|
<td><code>/bigdisk/store</code></td>
|
|
|
|
<td>The location in the file system for asset (bitstream) store number zero. This should be a directory for the sole use of DSpace.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>assetstore.dir.n</code></td>
|
|
|
|
<td><code>/anotherdisk/store1</code></td>
|
|
|
|
<td>The location in the file system of asset (bitstream) store number <code>n</code>. When adding additional stores, start with 1 (<code>assetstore.dir.1</code> and count upwards. Always leave asset store zero (<code>assetstore.dir</code>). For more details, see <a href="storage.html#bitstreams">the Bitstream Storage section</a>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>assetstore.incoming</code></td>
|
|
|
|
<td><code>1</code></td>
|
|
|
|
<td>The asset store number to use for storing new bitstreams. For example, if <code>assetstore.dir.1</code> is <code>/anotherdisk/store1</code>, and <code>assetstore.incoming</code> is <code>1</code>, new bitstreams will be stored under <code>/anotherdisk/store1</code>. A value of <code>0</code> (zero) corresponds to <code>assetstore.dir</code>. For more details, see <a href="storage.html#bitstreams">the Bitstream Storage section</a>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><span style="font-family: monospace;">srb.xxx</span><br style="font-family: monospace;">
|
|
<span style="font-family: monospace;">srb.xxx.n</span><br></td>
|
|
|
|
<td><span style="font-family: monospace;">/zone/home/user.domain</span><br></td>
|
|
|
|
<td>The sets of SRB access parameters (see <span style="font-family: monospace;">dspace.cfg</span>) if one or more SRB accounts are used. The <span style="font-family: monospace;">srb.xxx</span> set would correspond to asset (bitstream) store number zero. The <span style="font-family: monospace;">srb.xxx.n</span> set would correspond to asset (bitstream) store number <span style="font-family: monospace;">n</span>. For more details, see <a href="storage.html#bitstreams">the Bitstream Storage section</a>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>webui.submit.enable-cc</code></td>
|
|
|
|
<td><code>true</code></td>
|
|
|
|
<td>Enable the Creative Commons license step in the submission process. Submitters are given an opportunity to select a Creative Commons license to accompany the Item. Creative Commons licenses govern the use of the content. For more details, see <a href="http://creativecommons.org">the Creative Commons website</a>.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p>Property values can include other, previously defined values, by enclosing the property name in ${...}. For example, if your dspace.cfg contains: -</p>
|
|
|
|
<pre>
|
|
dspace.dir = /dspace
|
|
dspace.history = ${dspace.dir}/history
|
|
</pre>
|
|
|
|
<p>Then the value of the <code>dspace.history</code> property is expanded to be <code>/dspace/history</code>. This method is especially useful for handling commonly used file paths.</p>
|
|
|
|
<p>Whenever you edit <code>dspace.cfg</code>, you should then run <code><i>[dspace]</i>/bin/install-configs</code> so that any changes you may have made are reflected in the configuration files of other applications, for example Apache. You may then need to restart those applications, depending on what you changed.</p>
|
|
|
|
<h2><a name="email" id="email">Wording of E-mail Messages</a></h2>
|
|
|
|
<p>Sometimes DSpace automatically sends e-mail messages to users, for example to inform them of a new workflow task, or as a subscription e-mail alert.
|
|
The wording of emails can be changed by editing the relevant file in <code><i>[dspace]</i>/config/emails</code>.
|
|
Each file is commented. Be careful to keep the right number 'placeholders' (e.g.<code>{2}</code>).<br />
|
|
<strong>Note:</strong> You should replace the contact-information "<code>dspace-help@myu.edu or call us at xxx-555-xxxx</code>" with your own contact details in:
|
|
<ul>
|
|
<li><code>config/emails/change_password</code></li>
|
|
<li><code>config/emails/register</code></li>
|
|
</ul>
|
|
|
|
</p>
|
|
|
|
<h2><a name="registries" id="registries">The Metadata and Bitstream Format Registries</a></h2>
|
|
|
|
<p>
|
|
The <code><i>[dspace]</i>/config/registries</code> directory contains two XML files.
|
|
These are used to load the <em>initial</em> contents of the <a href="appendix.html#dublincoreregistry">Dublin Core Metadata registry</a>
|
|
and <a href="appendix.html#bitstreamformatregistry">Bitstream Format registry</a>.
|
|
After the initial loading (performed by <code>ant fresh_install</code> above),
|
|
the registries reside in the database; the XML files are not updated.
|
|
</p>
|
|
|
|
<p>
|
|
In order to change the registries, you may adjust the XML files before the first installation of DSpace.
|
|
On an allready running instance it is recommended to change the registries via DSpace admin UI.
|
|
The changes made via admin UI are not reflected in the XML files.
|
|
</p>
|
|
|
|
<h3>Metadata Format Registries</h3>
|
|
|
|
<p>
|
|
The default metadata schema is Dublin Core, so DSpace is distributed with a default Dublin Core Metadata Registry.
|
|
Currently, the system requires that every item have a Dublin Core record.<br/>
|
|
Via the DSpace admin UI you may define new Metadata Schemas, edit existing schemas and move elements between schemas.<br/>
|
|
There is a set of Dublin Core Elements, which is used by the system and should not be removed or moved to another schema,
|
|
see <a href="appendix.html#dublincoreregistry">Appendix: Default Dublin Core Metadata registry</a>.<br/>
|
|
<strong>Note</strong>: altering a Metadata Registry has no effect on corresponding parts, e.g. item submission interface, item display,
|
|
item import and vice versa. Every metadata element used in submission interface or item import must be registered before using it.<br />
|
|
<strong>Note</strong> also that deleting a metadata element will delete all its corresponding values.
|
|
</p>
|
|
|
|
<h3>Bitstream Format Registry</h3>
|
|
<p>
|
|
The bitstream formats recognized by the system and levels of support are similarly stored in the bitstream format registry.
|
|
This can also be edited at install-time via <code><i>[dspace]</i>/config/registries/bitstream-formats.xml</code> or by the administation Web UI.
|
|
The contents of the bitstream format registry are entirely up to you, though the system requires that the following two formats are present:
|
|
<ul>
|
|
<li><code>Unknown</code></li>
|
|
<li><code>License</code></li>
|
|
</ul>
|
|
<strong>Note:</strong> Deleting a format will cause any existing bitstreams of this format to be reverted to the unknown bitstream format.
|
|
</p>
|
|
|
|
<h2><a name="license" id="license">The Default Submission License</a></h2>
|
|
<p>For each submitted item, a license must be granted. The license will be stored along with the item in the bundle LICENSE in order to keep the information under which terms an items has been published.</p>
|
|
<p>You may define a license for each collection seperately, when creating/editing a collection. If no collection specific license is defined, the default license is used.</p>
|
|
<p>The default license can be found in <code><i>[dspace]</i>/config/default.license</code> and can be edited via the dspace-admin interface.</p>
|
|
<p>DSpace comes with a demo license, which you must adopt to your institutional needs and the legal regulations of your country.</p>
|
|
<p>If in doubt, contact the law department of your institution.</p>
|
|
<h3>Possible Points in a License </h3>
|
|
<it>Note, that this is no legal advice, just some starting thoughts for creating you own license.</it>
|
|
<ul>
|
|
<li>Non-exclusive or exclusive right to</li>
|
|
<ul>
|
|
<li>capture and store</li>
|
|
<li>distribute</li>
|
|
<ul>
|
|
<li>worldwide</li>
|
|
<li>restricted (e.g. institutional wide</li>
|
|
</ul>
|
|
<li>translate</li>
|
|
<li>transform to other formats or mediums</li>
|
|
without changing the content
|
|
</ul>
|
|
<li>Make sure no rights (copyright or any other) are violated by this publication</li>
|
|
<li>In case the type of submission (e.g. thesis) needs approval, make sure it is the final and approved version.</li>
|
|
<li>Distinguish between the document itself and the metadata</li>
|
|
<li>Point out that the license granted and the information who granted it will be stored.</li>
|
|
</ul>
|
|
|
|
<h2><a name="crosswalks" id="crosswalks">Activating Additional OAI-PMH Crosswalks</a></h2>
|
|
|
|
<p>DSpace comes with an unqualified DC Crosswalk used in the default OAI-PMH data provider. There are also other Crosswalks bundled with the DSpace distribution which can be activated by editing one or more configuration files. How to do this for each available Crosswalk is described below.</p>
|
|
|
|
<h3>METS</h3>
|
|
<p>The old DSpace 1.3 METS Crosswalk can be activated as follows:</p>
|
|
<ol>
|
|
<li>Uncomment the METS Crosswalk entry from the <code>config/templates/oaicat.properties</code> file</li>
|
|
<li>Run the <code>bin/install-configs</code> script</li>
|
|
<li>Restart Tomcat</li>
|
|
<li>Verify the Crosswalk is activated by accessing a URL such as <code>http://mydspace/dspace-oai/request?verb=ListRecords&metadataPrefix=mets</code></li>
|
|
</ol>
|
|
<h3>Crosswalk Plugins</h3>
|
|
<p>OAI-PMH crosswalks based on Crosswalk Plugins, including the new (DSpace 1.4) METS crosswalk, are activated as follows:</p>
|
|
<ol>
|
|
<li>Ensure the crosswalk plugin has a <em>lower-case</em> name (possibly
|
|
in addition to its upper-case name) in the plugin configuration.</li>
|
|
<li>Add a line to the file <code>config/templates/oaicat.properties</code> of
|
|
the form:<br>
|
|
<code>Crosswalks.</code><i>plugin_name</i><code>=org.dspace.app.oai.PluginCrosswalk</code><br>
|
|
substituting the plugin's name, e.g. <code>"mets"</code> or <code>"qdc"</code>for <i>plugin_name</i>.</li>
|
|
<li>Run the <code>bin/install-configs</code> script</li>
|
|
<li>Restart your servlet container, e.g. Tomcat, for the change to take effect.</li>
|
|
</ol>
|
|
|
|
The DSpace 1.4 source includes the following crosswalk plugins available
|
|
for use with OAI-PMH:
|
|
<ul>
|
|
<li><b><code>mets</code></b> - The manifest document from a DSpace METS SIP.</li>
|
|
<li><b><code>mods</code></b> - MODS metadata, produced by the <a href="#mods">table-driven MODS dissemination crosswalk</a>.</li>
|
|
<li><b><code>qdc</code></b> - Qualfied Dublin Core, produced by the <a href="#qdc">configurable QDC crosswalk</a>.
|
|
Note that this QDC does <em>not</em> include all of the
|
|
DSpace "dublin core"
|
|
metadata fields, since the XML standard for QDC is
|
|
defined for a different set of elements and qualifiers.</li>
|
|
</ul>
|
|
|
|
<h3>DIDL</h3>
|
|
<p>By activating the DIDL provider, DSpace items are represented as MPEG-21 DIDL objects. These DIDL objects are XML documents that wrap both the Dublin Core metadata that describes the DSpace item and its actual bitstreams. A bitstream is provided inline in the DIDL object in a base64 encoded manner, and/or by means of a pointer to the bitstream. The data provider exposes DIDL objects via the metadataPrefix didl.</p>
|
|
<p>The crosswalk does not deal with special characters and purposely skips dissemination of the <code>license.txt</code> file awaiting a better understanding on how to map DSpace rights information to MPEG21-DIDL.</p>
|
|
|
|
<p>The DIDL Crosswalk can be activated as follows:</p>
|
|
<ul>
|
|
<li>Uncomment the <code>oai.didl.maxresponse</code> item in <code>dspace.cfg</code></li>
|
|
<li>Uncomment the DIDL Crosswalk entry from the <code>config/templates/oaicat.properties</code> file</li>
|
|
<li>Run the <code>bin/install-configs</code> script</li>
|
|
<li>Restart Tomcat</li>
|
|
<li>Verify the Crosswalk is activated by accessing a URL such as <code>http://mydspace/dspace-oai/request?verb=ListRecords&metadataPrefix=didl</code></li>
|
|
</ul>
|
|
|
|
<h2><a name="templates" id="templates">Configuration Files for Other Applications</a></h2>
|
|
|
|
<p>To ease the hassle of keeping configuration files for other applications involved in running a DSpace site, for example Apache, in sync, the DSpace system can automatically update them for you when the main DSpace configuration is changed. This feature of the DSpace system is entirely optional, but we found it useful.</p>
|
|
|
|
<p>The way this is done is by placing the configuration files for those applications in <code><i>[dspace]</i>/config/templates</code>, and inserting special values in the configuration file that will be filled out with appropriate DSpace configuration properties. Then, tell DSpace where to put filled-out, 'live' version of the configuration by adding an appropriate property to <code>dspace.cfg</code>, and run <code><i>[dspace]</i>/bin/install-configs</code>.</p>
|
|
|
|
<p>Take the <code>apache13.conf</code> file as an example. This contains plenty of Apache-specific stuff, but where it uses a value that should be kept in sync across DSpace and associated applications, a 'placeholder' value is written. For example, the host name:</p>
|
|
<pre>
|
|
ServerName @@dspace.hostname@@
|
|
</pre>
|
|
|
|
<p>The text <code>@@dspace.hostname@@</code> will be filled out with the value of the <code>dspace.hostname</code> property in <code>dspace.cfg</code>. Then we decide where we want the 'live' version, that is, the version actually read in by Apache when it starts up, will go.</p>
|
|
|
|
<p>Let's say we want the live version to be located at <code>/opt/apache/conf/dspace-httpd.conf</code>. To do this, we add the following property to <code>dspace.cfg</code> so DSpace knows where to put it:</p>
|
|
<pre>
|
|
config.template.apache13.conf = /opt/apache/conf/dspace-httpd.conf
|
|
</pre>
|
|
|
|
<p>Now, we run <code><i>[dspace]</i>/bin/install-configs</code>. This reads in <code><i>[dspace]</i>/config/templates/apache13.conf</code>, and places a copy at <code>/opt/apache/conf/dspace-httpd.conf</code> with the placeholders filled out.</p>
|
|
|
|
<p>So, in <code>/opt/apache/conf/dspace-httpd.conf</code>, there will be a line like:</p>
|
|
<pre>
|
|
ServerName dspace.myu.edu
|
|
</pre>
|
|
|
|
<p>The advantage of this approach is that if a property like the hostname changes, you can just change it in <code>dspace.cfg</code> and run <code>install-configs</code>, and all of your tools' configuration files will be updated.</p>
|
|
|
|
<p>However, take care to make all your edits to the versions in <code><i>[dspace]</i>/config/templates</code>! It's a wise idea to put a big reminder at the top of each file, since someone might unwittingly edit a 'live' configuration file which would later be overwritten.</p>
|
|
|
|
<h2><a name="customui" id="customui">Customizing the Web User Interface</a></h2>
|
|
|
|
<p>The Web UI is implemented using Java Servlets which handle the business logic, and JavaServer Pages (JSPs) which produce the HTML pages sent to an end-user. Since the JSPs are much closer to HTML than Java code, altering the look and feel of DSpace is relatively easy.</p>
|
|
|
|
<p>To make it even easier, DSpace allows you to 'override' the JSPs included in the source distribution with modified versions, that are stored in a separate place, so when it comes to updating your site with a new DSpace release, your modified versions will not be overwritten. It should be possible to dramatically change the look of DSpace to suit your organization by just changing the CSS style file and the site 'skin' or 'layout' JSPs in <code>jsp/layout</code>; if possible, it is recommended you limit local customizations to these files to make future upgrades easier.</p>
|
|
|
|
<p>You can also easily edit the text that appears on each JSP page by editing the dictionary file. However, note that unless you change the entry in all of the different language message files, users of other languages will still see the default text for their language. See <A HREF="application.html#i18n">internationalization</A>.</P>
|
|
|
|
<p>Note that the data (attributes) passed from an underlying Servlet to the JSP may change between versions, so you may have to modify your customized JSP to deal with the new data.</p>
|
|
|
|
<p>Thus, if possible, it is recommeded you limit your changes to the 'layout' JSPs and the stylesheet.</P>
|
|
|
|
<p>The JSPs are stored in <code><i>[dspace-source]</i>/jsp</code>. Place your edited version of a JSP in the <code><i>[dspace-source]</i>/jsp/local</code> directory, with the same path as the original. If they exist, these will be used in preference to the distributed versions in <code><i>[dspace-source]</i>/jsp</code>. For example:</p>
|
|
|
|
<table>
|
|
<tbody>
|
|
<tr>
|
|
<th>DSpace default</th>
|
|
|
|
<th>Locally-modified version</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code><i>[dspace-source]</i>/jsp/community-list.jsp</code></td>
|
|
|
|
<td><code><i>[dspace-source]</i>/jsp/local/community-list.jsp</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code><i>[dspace-source]</i>/jsp/mydspace/main.jsp</code></td>
|
|
|
|
<td><code><i>[dspace-source]</i>/jsp/local/mydspace/main.jsp</code></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p>Heavy use is made of a style sheet, in <code><i>[dspace-source]</i>/jsp/styles.css.jsp</code>. If you make edits, call the local version <code><i>[dspace-source]</i>/jsp/local/styles.css.jsp</code>, and it will be used automatically in preference to the default, as described above.</p>
|
|
|
|
<p>Fonts and colors can be easily changed using the stylesheet. The stylesheet is a JSP so that the user's browser version can be detected and the stylesheet tweaked accordingly.</p>
|
|
|
|
<p>The 'layout' of each page, that is, the top and bottom banners and the navigation bar, are determined by the JSPs <code><i>[dspace-source]</i>/jsp/layout/header-*.jsp</code> and <code><i>[dspace-source]</i>/jsp/layout/footer-*.jsp</code>. You can provide modified versions of these (in <code><i>[dspace-source]</i>/jsp/local/layout</code>, or define more styles and apply them to pages by using the "style" attribute of the <code>dspace:layout</code> tag.</p>
|
|
|
|
<p>After you've customized your JSPs, <strong>you must rebuild the DSpace Web application</strong>. If you haven't already built and installed it, follow the <a href="install.html">install</a> directions. Otherwise, follow the steps below:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>Rebuild the <code>dspace.war</code> file by running the following command from your <code><i>[dspace-source]</i></code> directory:</p>
|
|
<pre>
|
|
ant -Dconfig=<i>[dspace]</i>/config/dspace.cfg build_wars
|
|
</pre>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Shut down Tomcat, and delete the existing <i>[tomcat]</i>/webapps/dspace directory.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Copy the new .war file to the Tomcat webapps directory:</p>
|
|
<pre>
|
|
cp <i>[dspace-source]</i>/build/dspace.war <i>[tomcat]</i>/webapps
|
|
</pre>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>When you restart the web server you should see your customized JSPs.</p>
|
|
|
|
<h2><a name="customsimpleitem" id="customsimpleitem">Customizing the Simple Item Display Metadata</a></h2>
|
|
|
|
<h3>Customizing the Default Simple Item Display Metadata</h3>
|
|
|
|
<p>In <code>dspace.cfg</code> create a <code>webui.itemdisplay.default</code> item specifying a comma-separated list of metadata fields to display. For example,</p>
|
|
|
|
<pre>webui.itemdisplay.default = dc.title, dc.date.issued(date), dc.identifier.uri(link), dc.description.*</pre>
|
|
|
|
<p> will set the default simple item display to show the Dublin Core title, issue date (in date format), handle URI (rendered as a link) and all DC description metadata. If no <code>webui.itemdisplay.default</code> is present, the default defers to a preset list hard-coded in DSpace. If an item has no value for a particular field, it won't be displayed.</p>
|
|
|
|
<p>Add entries to the <code>Messages.properties</code> file as required. The name of the field for display will be drawn from the current UI dictionary, using the key <code>metadata.<metadata field></code>. For example <code>metadata.dc.title = Title</code>
|
|
|
|
<p>The metadata in <code>dspace.cfg</code> can be specified in the form <code><schema prefix>.<element>[.<qualifier>|.*][(date)|(link)], ...</code>. For example,</p>
|
|
<ul>
|
|
<li><code>dc.title</code> refers to unqualifed Dublin Core (DC) 'title' element</li>
|
|
<li><code>dc.title.alternative</code> refers to the qualified DC element 'title.alternative'</li>
|
|
<li><code>dc.title.*</code> refers to all DC 'title' elements (i.e. any or no qualifier)</li>
|
|
<li><code>dc.identifier.uri(link)</code> refers to DC 'identifier.uri' and render as a link</li>
|
|
<li><code>dc.date.issued(date)</code> refers to DC 'date.issued' and render as a date</li>
|
|
</ul>
|
|
|
|
<p>Links can be made from author and subject values to their applicable browse pages. By default
|
|
this is enabled for author names (links to browse-author) and disabled for subjects (links to browse-subject). They can be
|
|
changed by editing <code>webui.authorlinks.enable</code> and <code>webui.subjectlinks.enable</code>.
|
|
The metadata that constitutes authors and subjects is controlled by <code>webui.browse.index.author</code>
|
|
and <code>webui.browse.index.subject</code>.</p>
|
|
|
|
<h3>Customizing the Simple Item Display Metadata for Individual Collections</h3>
|
|
|
|
<p>Create <code>dspace.cfg</code> entries for each of the "styles" of item display in the same way the default layout is configured. For example,</p>
|
|
|
|
<pre>webui.itemdisplay.thesis-style = dc.contributor.*, dc.identifier.uri, dc.description.abstract</pre>
|
|
|
|
<p>
|
|
Then associate this simple item display with collections using an additional <code>dspace.cfg</code> item. For example,</p>
|
|
|
|
<pre>webui.itemdisplay.thesis-style.collections = 123456789/1, 123456789/56</pre>
|
|
<p>
|
|
Don't forget to add any required message keys to the <code>Messages.properties</code> file. In the above example, the <code>Messages.properties</code> file would need to contain something like:</p>
|
|
<pre>
|
|
metadata.dc.contributor.* = Authors
|
|
metadata.dc.identifier.uri = Citation
|
|
metadata.dc.description.abstract = Abstract</pre>
|
|
|
|
<h2><a name="mydspacegroupmembership" id="mydspacegroupmembership">MyDSpace Display of Group Memberships</a></h2>
|
|
<p>In the MyDSpace page of a user, all the groups the user is member of can be displayed by setting webui.mydspace.showgroupmemberships = true:
|
|
<pre>
|
|
### MyDSpace display of group membership
|
|
#
|
|
# default behaviour is false
|
|
#
|
|
# webui.mydspace.showgroupmemberships = false
|
|
</pre>
|
|
Setting this property to true will result in a list of all groups the user is explicitly or implicitly member of.<br />
|
|
<strong>Note: </strong>this list might not be very usable for the standard DSpace user as it displays the group names.<br />
|
|
If omitted the default behaviour is false.
|
|
</p>
|
|
<h2><a name="authenticate" id="authenticate">Custom Authentication Code</a></h2>
|
|
|
|
<p>Since many institutions and organizations have exisiting
|
|
authentication systems, DSpace has been designed to allow these to
|
|
be easily integrated into an existing authentication infrastructure.
|
|
It keeps a series, or "stack", of <em>authentication methods</em>, so
|
|
each one can be tried in turn. This makes it easy to add new
|
|
authentication methods or rearrange the order without changing any
|
|
existing code. You can also share authentication code with other sites.</p>
|
|
|
|
<p>The configuration property
|
|
<code>plugin.sequence.org.dspace.eperson.AuthenticationMethod</code>
|
|
defines the authentication stack. It is a comma-separated list of
|
|
class names. Each of these classes implements a different
|
|
<em>authentication method</em>, or way of determining the identity of
|
|
the user. They are invoked in the order specified until one succeeds.
|
|
|
|
<p>An authentication method is a class that implements the
|
|
interface <code>org.dspace.eperson.AuthenticationMethod</code>.
|
|
It <em>authenticates</em> a user by evaluating the <em>credentials</em>
|
|
(e.g. username and password) he or she presents and
|
|
checking that they are valid.</p>
|
|
|
|
<p>The basic authentication procedure in the DSpace Web UI is this:</p>
|
|
|
|
<ol>
|
|
<li>A request is received from an end-user's browser that, if fulfilled, would lead to an action requiring authorization taking place.</li>
|
|
|
|
<li>If the end-user is already authenticated:
|
|
|
|
<ul>
|
|
<li>If the end-user is allowed to perform the action, the action proceeds</li>
|
|
|
|
<li>If the end-user is NOT allowed to perform the action, an authorization error is displayed.</li>
|
|
|
|
<li>If the end-user is NOT authenticated, i.e. is accessing DSpace anonymously:</li>
|
|
</ul>
|
|
|
|
<li>The parameters etc. of the request are stored</li>
|
|
|
|
<li>The Web UI's <code>startAuthentication</code> method is invoked.</li>
|
|
|
|
<li>First it tries all the authentication methods which do <em>implicit</em>
|
|
authentication (i.e. they work with just the information already
|
|
in the Web request, such as an X.509 client certificate). If one
|
|
of these succeeds, it proceeds from Step 2 above.</li>
|
|
|
|
<li>If none of the implicit methods succeed, the UI responds by putting
|
|
up a "login" page to collect credentials for one of the
|
|
<em>explicit</em> authentication methods in the stack. The servlet
|
|
processing that page then
|
|
gives the proffered credentials to each authentication method in turn
|
|
until one succeeds, at which point it
|
|
retries the original operation from Step 2 above.</li>
|
|
</ol>
|
|
|
|
<p>Please see the source files <code>AuthenticationManager.java</code> and <code>AuthenticationMethod.java</code> for more details about this mechanism.
|
|
|
|
<h3>Authentication by Password</h3>
|
|
|
|
<p>The default method <code>org.dspace.eperson.PasswordAuthentication</code> has the following properties:
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Use of inbuilt e-mail address/password-based log-in. This is achieved by forwarding a request that is attempting an action requiring authorization to the password log-in servlet, <code>/password-login</code>. The password log-in servlet (<code>org.dspace.app.webui.servlet.PasswordServlet</code> contains code that will resume the original request if authentication is successful, as per step 3. described above.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Users can register themselves (i.e. add themselves as e-people without needing approval from the administrators), and can set their own passwords when they do this</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Users are not members of any special (dynamic) e-person groups</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>LDAP Authentication</h3>
|
|
|
|
<p>As of version 1.3, the authentication method <code>org.dspace.eperson.LDAPAuthentication</code> is also supplied to support <A HREF="#ldap">LDAP authentication</A>.</P>
|
|
|
|
<h3>X.509 Certificate Authentication</h3>
|
|
|
|
<p>The X.509 authentication method uses an X.509 certificate sent by
|
|
the client to establish his/her identity. It requires the client to
|
|
have a personal Web certificate installed on their browser (or other client
|
|
software) which is issued by a Certifying Authority (CA) recognized
|
|
by the web server.</p>
|
|
|
|
<ol>
|
|
<li>See the <a href="install.html#https">HTTPS installation
|
|
instructions</a> to configure your Web server. If you are using
|
|
HTTPS with Tomcat, note that the <code><Connector></code> tag
|
|
<em>must</em> include the attribute <code><b>clientAuth="true"</b></code>
|
|
so the server requests a personal Web certificate from the client.</p>
|
|
</li>
|
|
<p><li>
|
|
Add the <code>org.dspace.eperson.X509Authentication</code> plugin
|
|
<em>first</em> to the list of stackable authentication methods in the value
|
|
of the configuration key <code>plugin.sequence.org.dspace.eperson.AuthenticationMethod</code>
|
|
<i>E.g.:</i>
|
|
</p>
|
|
<pre>
|
|
plugin.sequence.org.dspace.eperson.AuthenticationMethod = \
|
|
org.dspace.eperson.X509Authentication, \
|
|
org.dspace.eperson.PasswordAuthentication
|
|
</pre>
|
|
|
|
</li>
|
|
<p><li>
|
|
You must also configure DSpace with the same CA certificates as the
|
|
web server, so it can accept and interpret the clients' certificates.
|
|
It can share the same keystore file as the web server, or a
|
|
separate one, or a CA certificate in a file by itself.
|
|
Configure it by <em>one</em> of these methods, either the Java keystore
|
|
|
|
<pre>
|
|
authentication.x509.keystore.path = <em>path to Java keystore file</em>
|
|
authentication.x509.keystore.password = <em>password to access the keystore</em>
|
|
</pre>
|
|
|
|
...or the separate CA certificate file (in PEM or DER format):
|
|
<pre>
|
|
authentication.x509.ca.cert = <em>path to certificate file for CA whose client certs to accept.</em>
|
|
</pre>
|
|
</p>
|
|
</li>
|
|
<p><li>
|
|
<p>Choose whether to enable auto-registration: If you want users who
|
|
authenticate successfully to be automatically registered as new E-Persons
|
|
if they are not already, set the
|
|
<code>authentication.x509.autoregister</code> configuration property
|
|
to <code>true</code>.
|
|
This lets you automatically accept all users with valid
|
|
personal certificates. The default is <code>false</code>.</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<h3>Example of a Custom Authentication Method</h3>
|
|
|
|
<p>Also included in the source is an implementation of an authentication method used at MIT, <code>edu.mit.dspace.MITSpecialGroup</code>.
|
|
This does not actually authenticate a user, it <em>only</em>
|
|
adds the current user to a special (dynamic) group called 'MIT
|
|
Users' (which must be present in the system!). This allows us to
|
|
create authorization policies for MIT users without having to
|
|
manually maintain membership of the MIT users group.</p>
|
|
|
|
<p>By keeping this code in a separate method, we can customize the
|
|
authentication process for MIT by simply adding it to the stack in
|
|
the DSpace configuration. None of the code has to be touched.
|
|
|
|
<p>You can create your own custom authentication method and add it to
|
|
the stack. Use the most similar existing method as a model, e.g.
|
|
<code>org.dspace.eperson.PasswordAuthentication</code> for an "explicit"
|
|
method (with credentials entered interactively) or
|
|
<code>org.dspace.eperson.X509Authentication</code> for an implicit
|
|
method.</p>
|
|
|
|
|
|
<h2><a name="ldap" id="ldap">Configuring LDAP Authentication</a></h2>
|
|
|
|
<p>You can enable LDAP authentication by adding its method to the
|
|
stack in the DSpace configuration, e.g.</p>
|
|
<pre>plugin.sequence.org.dspace.eperson.AuthenticationMethod = org.dspace.eperson.LDAPAuthentication</pre>
|
|
|
|
<p>If LDAP is enabled in the dspace.cfg file, then new users will be able to register by entering their username and password without being sent the registration token. If users do not have a username and password, then they can still register and login with just their email address the same way they do now.</p>
|
|
|
|
<p>If you want to give any special privileges to LDAP users, create a stackable authentication method to automatically put people who have a netid into a special group. You might also want to give certain email addresses special privileges. Refer to the <a href="#authenticate">Custom Authentication Code</a> section above for more information about how to do this.</p>
|
|
|
|
<p>Here is an explanation of what each of the different configuration parameters are for:</p>
|
|
|
|
<ul>
|
|
<li><b>ldap.enable</b><br>
|
|
This setting will enable or disable LDAP authentication in DSpace. With the setting off, users will be required to register and login with their email address. With this setting on, users will be able to login and register with their LDAP user ids and passwords.</li>
|
|
|
|
<li><b>webui.ldap.autoregister</b><br>
|
|
This will turn LDAP autoregistration on or off. With this on, a new EPerson object will be created for any user who successfully authenticates against the LDAP server when they first login. With this setting off, the user must first register to get an EPerson object by entering their ldap username and password and filling out the forms.</li>
|
|
|
|
<li><b>ldap.provider_url = ldap://ldap.myu.edu/o=myu.edu</b><br>
|
|
This is the url to your institution's ldap server. You may or may not need the /o=myu.edu part at the end. Your server may also require the ldaps:// protocol.</li>
|
|
|
|
<li><b>ldap.id_field = uid</b><br>
|
|
This is the unique identifier field in the LDAP directory where the username is stored.</li>
|
|
|
|
<li><b>ldap.object_context = ou=people,o=myu.edu</b><br>
|
|
This is the object context used when authenticating the user. It is appended to the ldap.id_field and username. For example uid=username,ou=people,o=myu.edu. You will need to modify this to match your ldap configuration.</li>
|
|
|
|
<li><b>ldap.search_context = ou=people</b><br>
|
|
This is the search context used when looking up a user's ldap object to retrieve their data for autoregistering. With ldap.autoregister turned on, when a user authenticates without an EPerson object we search the ldap directory to get their name and email address so that we can create one for them. So after we have authenticated against uid=username,ou=people,o=byu.edu we now search in ou=people for filtering on [uid=username]. Often the ldap.search_context is the same as the ldap.object_context parameter. But again this depends on your ldap server configuration.</li>
|
|
|
|
<li><b>ldap.email_field = mail</b><br>
|
|
This is the ldap object field where the user's email address is stored. "mail" is the default and the most common for ldap servers. If the mail field is not found the username will be used as the email address when creating the eperson obejct.</li>
|
|
|
|
<li><b>ldap.surname_field = sn</b><br>
|
|
This is the ldap object field where the user's last name is stored. "sn" is the default and is the most common for ldap servers. If the field is not found the field will be left blank in the new eperson object.</li>
|
|
|
|
<li><b>ldap.givenname_field = givenName</b><br>
|
|
This is the ldap object field where the user's given names are stored. I'm not sure how common the givenName field is in different ldap instances. If the field is not found the field will be left blank in the new eperson object.</li>
|
|
|
|
<li><b>ldap.phone_field = telephoneNumber</b><br>
|
|
This is the field where the user's phone number is stored in the ldap directory. If the field is not found the field will be left blank in the new eperson object.</li>
|
|
</ul>
|
|
|
|
<h2><a name="search-index" id="search-index">Configuring Lucene Search Indexes</a></h2>
|
|
|
|
<p>(Available in DSpace 1.2.1+)</p>
|
|
|
|
<p>Search Indexes can be configured via the <code>dspace.cfg</code> file. This allows institutions to choose which DSpace metadata fields are indexed by Lucene. Note that as of DSpace 1.4, the schema for the element is also required.</p>
|
|
|
|
<p>For example, the following entries appear in a default DSpace installation:</p>
|
|
<pre>
|
|
search.index.1 = author:dc.contributor.*
|
|
search.index.2 = author:dc.creator.*
|
|
search.index.3 = title:dc.title.*
|
|
search.index.4 = keyword:dc.subject.*
|
|
search.index.5 = abstract:dc.description.abstract
|
|
search.index.6 = author:dc.description.statementofresponsibility
|
|
search.index.7 = series:dc.relation.ispartofseries
|
|
search.index.8 = abstract:dc.description.tableofcontents
|
|
search.index.9 = mime:dc.format.mimetype
|
|
search.index.10 = sponsor:dc.description.sponsorship
|
|
search.index.11 = id:dc.identifier.*
|
|
</pre>
|
|
|
|
<p>The form of each entry is <code>search.index.<id> = <search <schema>field>:<metadata field></code> where:</p>
|
|
<ul>
|
|
<li><code><id></code> is an incremental number to distinguish each search index entry</li>
|
|
<li><code><search field></code> is an identifier for the search field this index will correspond to</li>
|
|
<li><code><metadata field></code> is the DSpace metadata field to be indexed</li>
|
|
</ul>
|
|
<p>So in the example above, search.indexes1, 2 and 6 are configured as the <code>author</code> search field. The <code>author</code> index is created by Lucene indexing all <code>contributor</code>, <code>creator</code> and <code>description.statementofresponsibility</code> medatata fields.</p>
|
|
<p>After changing the configuration, run <code>index-all</code> to recreate the indexes.</p>
|
|
|
|
<p><strong>NOTE:</strong> While the indexes are created, this only affects the search results and has no effect on the search components of the user interface. To add new search capability (e.g. to add a new search category to the Advanced Search) requires local customisation to the user interface.</p>
|
|
|
|
<h2><a name="mediafilters" id="mediafilters">Media Filters</a></h2>
|
|
|
|
<p>Media Filters are classes used to generate derivative or alternative versions of master bitstreams. For example, the PDF Media Filter will extract textual content from PDF bitstreams, the JPEG Media Filter can create thumbnails from image bitstreams.</p>
|
|
|
|
<p>Media Filters are configured as a <a href="business.html#plugin">Sequence Plugin</a>, with each filter also having a separate config item indicating which formats it can process. The default configuration is shown below.</p>
|
|
|
|
<p><pre>#### Media Filter plugins (through PluginManager) ####
|
|
|
|
plugin.sequence.org.dspace.app.mediafilter.MediaFilter = \
|
|
org.dspace.app.mediafilter.PDFFilter, org.dspace.app.mediafilter.HTMLFilter, \
|
|
org.dspace.app.mediafilter.WordFilter, org.dspace.app.mediafilter.JPEGFilter
|
|
# to enable branded preview: remove last line above, and uncomment 2 lines below
|
|
# org.dspace.app.mediafilter.WordFilter, org.dspace.app.mediafilter.JPEGFilter, \
|
|
# org.dspace.app.mediafilter.BrandedPreviewJPEGFilter
|
|
|
|
filter.org.dspace.app.mediafilter.PDFFilter.inputFormats = Adobe PDF
|
|
filter.org.dspace.app.mediafilter.HTMLFilter.inputFormats = HTML, Text
|
|
filter.org.dspace.app.mediafilter.WordFilter.inputFormats = Microsoft Word
|
|
filter.org.dspace.app.mediafilter.JPEGFilter.inputFormats = GIF, JPEG, image/png
|
|
filter.org.dspace.app.mediafilter.BrandedPreviewJPEGFilter.inputFormats = GIF, JPEG, image/png</pre></p>
|
|
|
|
<p>To add a new Media Filter, add the new filter class to the <code>plugin.sequence.org.dspace.app.mediafilter.MediaFilter</code> config item and add a corresponding <code>filter.<i><class path></i>.inputFormats</code> config item. Note the input formats must match the <code>short_description</code> field in the <code>bitstreamformatregistry</code> table.</p>
|
|
|
|
<h2><a name="statistics" id="statistics">Configuring System Statistical Reports</a></h2>
|
|
|
|
<p>Statistics for the system can be made available at <code>http://www.mydspaceinstance.edu/statistics</code>. To use the system statistics you will have to initialise them as per the installation documentation, but before you do so you need to perform the customisations discussed here in order to ensure that the reports are generated correctly.</p>
|
|
|
|
<h3>Configuration File</h3>
|
|
|
|
<p>Configuration for the statistics system are in <code>[dspace]/config/dstat.cfg</code> and the file should guide you to correctly filling in the details required. For the most part you will not need to change this file.</p>
|
|
|
|
<h3>Customising Shell Scripts</h3>
|
|
|
|
<p>To customise the supplied perl scripts to do monthly and general report generation it is necessary to modify the scripts themselves sightly. This is because these scripts were developed to speed up the process of using DStat at Edinburgh University Library and were not particularly intended for external use. They appear here for the convenience of others and in order to bridge the gap between the report generation and the inclusion of those reports into the DSpace UI, which is currently a clunky process.</p>
|
|
|
|
<p>In order to get these scripts to work for you, open each of the following in turn:</p>
|
|
<pre>
|
|
stat-general
|
|
stat-initial
|
|
stat-monthly
|
|
stat-report-general
|
|
stat-report-initial
|
|
stat-report-monthly
|
|
</pre>
|
|
|
|
<p>scripts eding with <code>-general</code> do the work for building reports spanning the entire history of the archive; scripts ending <code>-initial</code> are to initialise the reports by doing monthly reports from some start date up to the present; scripts ending <code>-monthly</code> generate a single monthly report <em>for the current month</em>. These scripts are just designed to make life easier, and are not particularly clever or elegant.</p>
|
|
|
|
<p>In each file you will find a section:</p>
|
|
<pre>
|
|
# Details used
|
|
################################################
|
|
|
|
... some perl ...
|
|
|
|
################################################
|
|
</pre>
|
|
|
|
<p>the perl between the lines of hashes defines the variables which will be used to do all of the processing in the report. The following explains what the variables mean and what they should be set to for each of the scripts</p>
|
|
|
|
<p><strong>stat-initial:</strong><br>
|
|
<code>$out_prefix</code>: prefix to place in front of each output file.<br>
|
|
<code>$out_suffix</code>: suffix for output file. A date will be inserted between the prefix and suffix<br>
|
|
<code>$start_year</code>: year to start back-analysing monthly logs from<br>
|
|
<code>$start_month</code>: month to start back-analysing monthly logs from<br>
|
|
<code>$dsrun</code>: path to your dsrun script, usually <code>[dspace]/bin/dsrun</code><br>
|
|
<code>$out_directory</code>: directory into which to place analysis files, for example <code>[dspace]/bin/log/</code><br></p>
|
|
|
|
<p><strong>stat-monthly:</strong><br>
|
|
<code>$out_prefix</code>: prefix to place in front of each output file.<br>
|
|
<code>$out_suffix</code>: suffix for output file. A date will be inserted between the prefix and suffix<br>
|
|
<code>$dsrun</code>: path to your dsrun script, usually <code>[dspace]/bin/dsrun</code><br>
|
|
<code>$out_directory</code>: directory into which to place analysis files, for example <code>[dspace]/bin/log/</code><br></p>
|
|
|
|
<p><strong>stat-general:</strong><br>
|
|
<code>$out_prefix</code>: prefix to place in front of each output file.<br>
|
|
<code>$out_suffix</code>: suffix for output file. Today's date will be inserted between the prefix and suffix<br>
|
|
<code>$dsrun</code>: path to your dsrun script, usually <code>[dspace]/bin/dsrun</code><br>
|
|
<code>$out_directory</code>: directory into which to place analysis files, for example <code>[dspace]/bin/log/</code><br></p>
|
|
|
|
<p><strong>stat-report-initial:</strong><br>
|
|
<code>$in_prefix</code>: the prefix of the files generated by stat-initial<br>
|
|
<code>$in_suffix</code>: the suffix of the files generated by stat-initial<br>
|
|
<code>$out_prefix</code>: the report file prefix. Should be "<code>report-</code>" in order to work with DSpace UI<br>
|
|
<code>$out_suffix</code>: the report file suffix. Should be "<code>.html</code>" in order to work with DSpace UI<br>
|
|
<code>$start_year</code>: the start year used in stat-initial<br>
|
|
<code>$start_month</code>: the start month used in stat-initial<br>
|
|
<code>$dsrun</code>: path to your dsrun script, usually <code>[dspace]/bin/dsrun</code><br>
|
|
<code>$in_directory</code>: directory where analysis files were placed in stat-initial<br>
|
|
<code>$out_directory</code>: the live reports directory: <code>[dspace]/reports/</code><br></p>
|
|
|
|
<p><strong>stat-report-monthly:</strong><br>
|
|
<code>$in_prefix</code>: the prefix of the files generated by stat-monthly<br>
|
|
<code>$in_suffix</code>: the suffix of the files generated by stat-monthly<br>
|
|
<code>$out_prefix</code>: the report file prefix. Should be "<code>report-</code>" in order to work with DSpace UI<br>
|
|
<code>$out_suffix</code>: the report file suffix. Should be "<code>.html</code>" in order to work with DSpace UI<br>
|
|
<code>$dsrun</code>: path to your dsrun script, usually <code>[dspace]/bin/dsrun</code><br>
|
|
<code>$in_directory</code>: directory where analysis files were placed in stat-monthly<br>
|
|
<code>$out_directory</code>: the live reports directory: <code>[dspace]/reports/</code><br></p>
|
|
|
|
<p><strong>stat-report-general:</strong><br>
|
|
<code>$in_prefix</code>: the prefix of the files generated by stat-general<br>
|
|
<code>$in_suffix</code>: the suffix of the files generated by stat-general<br>
|
|
<code>$out_prefix</code>: the report file prefix. Should be "<code>report-general-</code>" in order to work with DSpace UI<br>
|
|
<code>$out_suffix</code>: the report file suffix. Should be "<code>.html</code>" in order to work with DSpace UI<br>
|
|
<code>$dsrun</code>: path to your dsrun script, usually <code>[dspace]/bin/dsrun</code><br>
|
|
<code>$in_directory</code>: directory where analysis files were placed in stat-general<br>
|
|
<code>$out_directory</code>: the live reports directory: <code>[dspace]/reports/</code><br></p>
|
|
|
|
<p>If you want additional customisations, you will need to modify the lines which build the command to be executed and change the parameters passed to the java processes which actually carry out the analysis. For more information on these processes either build the javadocs or run:</p>
|
|
|
|
<pre>[dspace]/bin/dsrun org.dspace.app.statistics.LogAnalyser -help
|
|
[dspace]/bin/dsrun org.dspace.app.statistics.ReportGenerator -help</pre>
|
|
|
|
<h2><a name="preview" id="preview">Displaying Image Item Preview</a></h2>
|
|
|
|
<p>For particular types of objects (currently various image formats), a preview feature can be activated. This provides a branded version of the DSpace bitstream for display on the Item Display page.</p>
|
|
<p>To activate this feature and display a preview image on the item page (all properties mentioned below
|
|
are found in <code>dspace.cfg</code>):</p>
|
|
<ol>
|
|
<li>Uncomment the lines defining the list of configured mediafilters at
|
|
<code>plugin.sequence.org.dspace.app.mediafilter.MediaFilter</code> to include <code>org.dspace.app.mediafilter.BrandedPreviewJPEGFilter</code>.</li>
|
|
<li>Set the maximum pixel dimensions for the preview image by altering the <code>webui.preview.maxwidth</code> and <code>webui.preview.maxheight</code> (default is 600) config items.</li>
|
|
<li>Set the <code>webui.preview.brand</code> to the text you want to brand the image with. The brand will appear as white text on a black background strip across the base of the image. For example you might set the text to the owning organisation. The handle is also displayed as part of the branding.</li>
|
|
<li>Set the <code>webui.preview.brand.abbrev</code>. This is an abbreviated form of the <code>webui.preview.brand</code> text and will be shown where the brand text is longer than the image width (e.g. for narrow images).</li>
|
|
<li>Set the <code>webui.preview.brand.height</code> to the height in pixels of the appended branding (default 20).</li>
|
|
<li>Set the <code>webui.preview.brand.font</code> to the font for the brand text (default is SansSerif).</li>
|
|
<li>Set the <code>webui.preview.brand.fontpoint</code> to the font size for the brand text (default is 12).</li>
|
|
<li>Run <code>[dspace]/bin/filter-media</code> to generate the preview images. These will be stored in a BRANDED_PREVIEW bundle so won't interfere with existing bundles.</li>
|
|
<li>Set <code>webui.preview.enabled = true</code>.</li>
|
|
<li>Set <code>webui.preview.dc</code> if a metadata value is to appear just below the preview. For example, to highlight item rights you might set <code>webui.preview.dc = rights</code> or to show the description as part of the preview set <code>webui.preview.dc = description.abstract</code>. This is disabled by default.</li>
|
|
<li>Restart Tomcat.</li>
|
|
</ol>
|
|
|
|
<h2><a name="webuithumbs" id="webuithumbs">Displaying Image Thumbnails</a></h2>
|
|
|
|
<h3>Browse and Search Results Page Thumbnails</h3>
|
|
|
|
<p>Image thumbnails can be enabled on the Browse and Search Results pages by setting the appropriate configuration values. To enable the display of thumbnails the following items must be set in the <code>dspace.cfg</code> file:</p>
|
|
|
|
<p><code>webui.browse.thumbnail.show = true</code></p>
|
|
|
|
<p>If set to <code>false</code> or this configuration item is missing then thumbnails will not be shown. Additionally, appropriate <A HREF="application.html#mediafilters">media filters</a> must be configured and the media filter configured to run periodically (for example, via a 'cron' job) </p>
|
|
|
|
<p>The size of the browse/search thumbnails can also be configured to a smaller size than that generated by the mediafilter. To do this set the following configuration items:</p>
|
|
|
|
<p><code>webui.browse.thumbnail.maxheight = <maxheight in pixels></code></p>
|
|
|
|
<p><code>webui.browse.thumbnail.maxwidth = <maxwidth in pixels></code></p>
|
|
|
|
<p>If these configuration items are not set, <code>thumbnail.maxheight</code> and <code>thumbnail.maxwidth</code> are used. Setting these values greater than or equal to the size of the thumbnail generated by the mediafilter (i.e. <code>thumbnail.maxheight</code> and <code>thumbnail.maxwidth</code>) will have no effect.</p>
|
|
|
|
<p><strong>Note:</strong></p>
|
|
|
|
<ul>
|
|
<li>where the primary bitstream is HTML, no thumbnail is shown;</li>
|
|
|
|
<li>where the primary bitstream has a thumbnail, its thumbnail is shown;</li>
|
|
|
|
<li>where the primary bitstream is not set, the first thumbnail found by DSpace will be shown;</li>
|
|
|
|
<li>where the user does not have read access to the thumbnail bitstream, no thumbnail is shown;</li>
|
|
|
|
<li>currently, for a thumbnail to display, a JPEG thumbnail under the current implementation rules must exist (i.e. primary bitstream name with ".jpg" suffix).</li>
|
|
</ul>
|
|
|
|
<h3>Configuring Thumbnail Link Behaviour</h3>
|
|
|
|
<p>The target of a thumbnail in the Browse and Search Results Page can be configured by setting the following configuration item:</p>
|
|
|
|
<p><code>webui.browse.thumbnail.linkbehaviour = <target page type></code></p>
|
|
|
|
<p>Currently the values <code>item</code> and <code>bitstream</code> are allowed. If this configuration item is not set, or set incorrectly, the default is <code>item</code>.</p>
|
|
|
|
<h3>Item Display Page Thumbnails</h3>
|
|
|
|
<p>Thumbnails may also be enabled or disabled on the Item Display page by setting the following configuration item in <code>dspace.cfg</code>:</p>
|
|
|
|
<p><code>webui.item.thumbnail.show = true</code></p>
|
|
|
|
<p>If set to <code>false</code> or this configuration item is missing then thumbnails will not be shown.</p>
|
|
|
|
<h2><a name="strengths" id="strengths">Displaying Community and Collection Item Counts</a></h2>
|
|
|
|
<p>To show the item count against communities and collections set the <code>webui.strengths.show</code> configuration item in the <code>dspace.cfg</code> file as follows:</p>
|
|
|
|
<p><code>webui.strengths.show = true</code></p>
|
|
|
|
<p>If this config item is missing or is set to any value other than <code>true</code> the item counts will not be shown.</p>
|
|
|
|
<h2><a name="luceneanalyzer" id="luceneanalyzer">Lucene Analyzer</a></h2>
|
|
|
|
<p>The Lucene analyzer used in searching and indexing can be configured by setting the <code>search.analyzer</code> configuration item in <code>dspace.cfg</code> to the class of the desired analzyer. If this item is not present/commented out, the default Lucene analyzer <code>org.dspace.search.DSAnalyzer</code> is used.</p>
|
|
|
|
<p>As well as those analyzers included in the Lucene distribution (see <code>lucene.jar</code>), a Chinese analyzer from the Lucene sandbox is included in <code>lucene-sandbox.jar</code>. This analyzer is yet to be included in the core Lucene distribution but can be configured by setting <code>search.analyzer = org.apache.lucene.analysis.cn.ChineseAnalyzer</code> in <code>dspace.cfg</code>.</p>
|
|
|
|
<h2><a name="formathelp" id="formathelp">On-line Help About File Formats</a></h2>
|
|
|
|
<p>Because the file format support policy is determined by each individual institution, the on-line help on this subject is intentionally left blank. The help file will, however, retrieve a list of formats and the support levels associated with them in your database and display this information to the user. We highly recommend that you edit the "Format Support Policy" section of the file <code><i>[dspace-source]</i>/jsp/help/formats.jsp</code>.</p>
|
|
|
|
<h2><a name="viewlicence" id="viewlicence">View Item Licence</a></h2>
|
|
|
|
<p>Setting <code>webui.licence_bundle = true</code> in <code>dspace.cfg</code> will result in a hyperlink being rendered on the Item View page that points to the item's licence.</p>
|
|
|
|
<h2><a name="syndication" id="syndication">Configuring RSS Syndication</a></h2>
|
|
|
|
<p>In addition to the email subscription service, recent submissions to communities and collections are also available via RSS feeds. The feed link or links appear on the community and collection
|
|
home pages, in the sidebar underneath the <em>Recent Submissions</em> citations. The content of the feed includes the community/collection handle, name, short description, and icon; for each
|
|
item it includes: the handle, title, author, date issued, description, and abstract if present. Feed behavior can be configured by setting the following properties
|
|
in <code>dspace.cfg</code>:</p>
|
|
<p><code>webui.feed.enable = true</code></p>
|
|
<p>Set the value of this property to <code>true</code> to enable RSS feeds. If <code>false</code>, feeds will not be generated, and the feed links will not appear.</p>
|
|
<p><code>webui.feed.items = 4</code></p>
|
|
<p>The value of this property governs the number of DSpace items appearing in each feed, which are the most recent <code>n</code> submissions.</p>
|
|
<p><code>webui.feed.cache.size = 100</code></p>
|
|
<p>To improve performance, generated feeds may be cached in memory. If caching is desired, set the value of this property to a positive number,
|
|
which represents the total number of feeds kept in the cache at one time, for all communities and collections. A value of <code>0</code> disables caching, and the feed is generated
|
|
on demand for each request. If the cache grows beyond the specified value, the least-requested feeds are removed to maintain its size.
|
|
To assist you in optimization, whenever cache maintenance is performed a profile of the cache is recorded in the DSpace system log,
|
|
showing its size, and the total, average, minimum, and maximum number of 'hits' against cached feeds.</p>
|
|
<p><code>webui.cache.age = 48</code></p>
|
|
<p>To ensure that the feeds in the cache remain current, requested feeds are checked after they reach a certain <em>age</em>.
|
|
This property specifies that age in hours. A value of <code>0</code> will force a check with each request, which guarantees currency, but with a performance penalty. If caching is disabled, this property is ignored.</p>
|
|
<p><code>webui.feed.formats = rss_1.0,rss_2.0</code></p>
|
|
<p>The RSS feature supports several different syndication formats. If you wish only a single format to be offered,
|
|
set the value of this property to that format, selecting only from the list of canonical names provided. If you wish multiple formats,
|
|
set the value to a comma-separated list of canonical names. Each format will appear as a distinct icon and link
|
|
in the community and collection home page, as well as an 'autodiscovery' link in the page header.</p>
|
|
<p><code>webui.feed.localresolve = false</code></p>
|
|
<p>By default, the RSS feed will return global handle server-based URLs to items, collections and communities (e.g. http://hdl.handle.net/123456789/1). This means if you have not registered your DSpace installation with the CNRI Handle Server (e.g. development or testing instance) the URLs returned by the feed will return an error if accessed. Setting <code>webui.feed.localresolve = true</code> will result in the RSS feed returning localised URLs (e.g. http://myserver.myorg/handle/123456789/1). If <code>webui.feed.localresolve</code> is set to <code>false</code> or not present the default global handle URL form is used.</p>
|
|
|
|
<p><code>webui.feed.item.title = dc.title<br/>
|
|
webui.feed.item.date = dc.date.issued</code></p>
|
|
<p>Specify which metadata field you want to be displayed as an item's title and date in the RSS feed. You can only specify a <em>single</em> metadata field for each of these properties.</p>
|
|
|
|
<p><code>webui.feed.item.description = dc.title, dc.contributor.author, \<br/>
|
|
dc.contributor.editor, dc.description.abstract, \<br/>
|
|
dc.description</code></p>
|
|
<p>Specify which metadata fields should be displayed in an item's description field in the RSS feed. You can specify as many fields as you wish here. The fields will be listed in the RSS feed in the order they appear, and will only be listed if they have values.
|
|
Similar to the item display UI, the name of the field displayed in the feed will be drawn from the current UI dictionary, using the key: <code>"metadata.<field>"</code> (e.g. <code>"metadata.dc.title"</code>, <code>"metadata.dc.contributor.author"</code>, <code>"metadata.dc.description.*"</code>)</p>
|
|
|
|
|
|
<h2><a name="suggest" id="suggest">Configuring Item Recommendations</a></h2>
|
|
<p>The 'suggest an item' service is a convenient way for DSpace users to notify others via email about
|
|
content they discover in the repository. If enabled, a link appears on the simple item display page leading
|
|
to a form where the user can enter an email address, and additional optional information. Upon completion of the form, the system transmits a pre-formatted
|
|
message about the item to that address. Item recommendation can be configured by setting the following properties
|
|
in <code>dspace.cfg</code>:</p>
|
|
<p><code>webui.suggest.enable = true</code></p>
|
|
<p>Set the value of this property to <code>true</code> to expose the link to the recommendation form. If <code>false</code>, the link will not display.</p>
|
|
<p><code>webui.suggest.sender = A DSpace user</code></p>
|
|
<p>The form includes an optional field for the name of the person making the recommendation. The value of this property will be used if the sender is not specified. Note that
|
|
if the user has been authenticated to DSpace, the e-person record will be used to set the default value of this field, and will also be used to set
|
|
the 'reply-to' email header to the e-person's address.</p>
|
|
<p><code>webui.suggest.recipient = colleague</code></p>
|
|
<p>In addition to the required destination email address, the form includes an optional field for the name of person to whom the recommendation is to be sent. The value of this property will be used if the recipient name is not specified.</p>
|
|
<p>The wording and layout of the email message is governed by the template file <code><i>[dspace]</i>/config/emails/suggest</code>. You may edit this file
|
|
to alter the language, layout, type, or amount of information contained in the email, but note that the values passed to the template are limited to those enumerated at the
|
|
top of the template file and represented in the body of the message with 'placeholders' {0}, {1}, etc. A general description of DSpace is included as
|
|
a footer to the email, which may be replaced with site-specific content.</p>
|
|
|
|
|
|
<h2><a name="controlledvocabulary" id="controlledvocabulary">Configuring Controlled Vocabularies</a></h2>
|
|
<p>
|
|
DSpace now supports controlled vocabularies to confine the set of keywords that users can use
|
|
while describing items.
|
|
</p>
|
|
<p>
|
|
The need for a limited set of keywords is important since it eliminates the
|
|
ambiguity of a free description system, consequently simplifying the task of finding specific
|
|
items of information.
|
|
</p>
|
|
<p>
|
|
The controlled vocabulary add-on allows the user to choose from a defined set of keywords organised
|
|
in an tree (taxonomy) and then use these keywords to describe items while they are being submitted.
|
|
</p>
|
|
<p>
|
|
We have also developed a small search engine that displays the classification tree (or taxonomy)
|
|
allowing the user to select the branches that best describe the information that he/she seeks.
|
|
</p>
|
|
<p>
|
|
The taxonomies are described in XML following this (very simple) structure:
|
|
</p>
|
|
|
|
<p><code>
|
|
<node id="acmccs98" label="ACMCCS98"><br/>
|
|
<isComposedBy><br/>
|
|
<node id="A." label="General Literature"><br/>
|
|
<isComposedBy><br/>
|
|
<node id="A.0" label="GENERAL"/><br/>
|
|
<node id="A.1" label="INTRODUCTORY AND SURVEY"/><br/>
|
|
...<br/>
|
|
</isComposedBy><br/>
|
|
</node><br/>
|
|
...<br/>
|
|
</isComposedBy><br/>
|
|
</node><br/>
|
|
</code></p>
|
|
<p>
|
|
Your are free to use any application you want to create your controlled vocabularies. A simple
|
|
text editor should be enough for small projects. Bigger projects will require more complex
|
|
tools. You may use Protegé to create your taxonomies, save them as OWL and then use a
|
|
XML Stylesheet (XSLT) to transform your documents to the appropriate format. Future enhancements
|
|
to this add-on should make it compatible with standard schemas such as OWL or RDF.
|
|
</p>
|
|
<p>
|
|
In order to make DSpace compatible with WAI 2.0, the add-on is <b>turned off</b> by default
|
|
(the add-on relies strongly on Javascript to function).
|
|
It can be activated by setting the following property in <code>dspace.cfg</code>:
|
|
<p>
|
|
<code>
|
|
webui.controlledvocabulary.enable = true
|
|
</code>
|
|
</p>
|
|
<p>
|
|
New vocabularies should be placed in <code><i>[dspace]/config/controlled-vocabularies/</i></code> and must be
|
|
according to the structure described. A validation XML Schema can be downloaded <a href="controlledvocabulary.xsd">here</a>.
|
|
</p>
|
|
<p>
|
|
Vocabularies need to be associated with the correspondant DC metadata fields.
|
|
Edit the file <code><i>[dspace]/config/input-forms.xml</i></code> and place
|
|
a <code>"vocabulary"</code> tag under the <code>"field"</code> element that you
|
|
want to control. Set value of the <code>"vocabulary"</code> element to
|
|
the name of the file that contains the vocabulary, leaving out the extension
|
|
(the add-on will only load files with extension "*.xml").
|
|
For example:
|
|
</p>
|
|
<p>
|
|
<code>
|
|
<field><br/>
|
|
<dc-schema>dc</dc-schema><br/>
|
|
<dc-element>subject</dc-element><br/>
|
|
<dc-qualifier></dc-qualifier><br/>
|
|
<!-- An input-type of twobox MUST be marked as repeatable --><br/>
|
|
<repeatable>true</repeatable><br/>
|
|
<label>Subject Keywords</label><br/>
|
|
<input-type>twobox</input-type><br/>
|
|
<hint> Enter appropriate subject keywords or phrases below. </hint><br/>
|
|
<required></required><br/>
|
|
<b> <vocabulary [closed="false"]>nsi</vocabulary></b><br/>
|
|
</field><br/>
|
|
</code>
|
|
</p>
|
|
<p>
|
|
The vocabulary element has an optional boolean attribute <b>closed</b> that can be used to force input only with
|
|
the javascript of controlled-vocabulary add-on.
|
|
The default behaviour (i.e. without this attribute) is as set <b>closed="false"</b>.
|
|
This allow the user also to enter the value in free way.
|
|
</p>
|
|
<p>
|
|
The following vocabularies are currently available by default:
|
|
</p>
|
|
<ul>
|
|
<!-- <li><strong>acmccs98-1.2.4</strong> - <em>acmccs98-1.2.4.xml</em> - ACM Computing Classification System</li> -->
|
|
<li><strong>nsi</strong> - <em>nsi.xml</em> - The Norwegian Science Index</li>
|
|
<li><strong>srsc</strong> - <em>srsc.xml</em> - Swedish Research Subject Categories</li>
|
|
</ul>
|
|
|
|
<h2><a name="checker">Checksum Checker</a></h2>
|
|
<p>There are three aspects of the Checksum Checker's operation that can be configured:<p>
|
|
<ol>
|
|
<li>the execution mode</li>
|
|
<li>the logging output</li>
|
|
<li>the policy for removing old checksum results from the database</li>
|
|
|
|
</ol>
|
|
|
|
<h3>Checker Execution Mode</h3>
|
|
|
|
<p>Execution mode can be configured using command line options. Information on the options can be found at any time by running <code><i>[dspace]</i>/bin/checker --help</code>. The different modes are described below; see the "Which to use" section that follows for details on the various pros and cons.</p>
|
|
|
|
<p>Unless a particular bitstream or handle is specified, the Checksum Checker will always check bitstreams in order of the least recently checked bitstream. (Note that this means that the most recently ingested bitstreams will be the last ones checked by the Checksum Checker.)</p>
|
|
|
|
<strong>Limited Count Mode</strong>
|
|
|
|
<p>To check a specific number of bitstreams, use the -c option followed by an integer number of bitstreams to check:</p>
|
|
|
|
<pre>bin/checker -c 10</pre>
|
|
|
|
|
|
<p>Limited count mode is particularly useful for checking that the checker is executing properly. The Checksum Checker's default execution mode is to check a single bitstream, as if the -c 1 option had been given.</p>
|
|
|
|
<strong>Limited Duration Mode</strong>
|
|
|
|
<p>To run the Checker for a specific period of time, use the -d option with a time argument:</p>
|
|
|
|
<pre>bin/checker -d 10m
|
|
bin/checker -d 2h</pre>
|
|
|
|
<p>Valid options for specifying duration are <code>s</code> for seconds, <code>m</code> for minutes, <code>h</code> for hours, <code>d</code> for days, <code>w</code> for weeks, and <code>y</code> for years (OK, so we're optimists).</p>
|
|
|
|
<p>The checker will keep starting new bitstream checks for the specified duration, so actual execution duration will be slightly longer than the specified duration. Bear this in mind when scheduling checks.</p>
|
|
|
|
<strong>Check Specific Bitstreams</strong>
|
|
|
|
<p>To check one or more particular bitstreams by ID, use the -b option followed by one or more bitstream IDs:</p>
|
|
|
|
<pre>bin/checker -b 1 2 3 4</pre>
|
|
|
|
<p>This mode is useful when analyzing problems reported in the logs and when verifying that a resolution has been successful.</p>
|
|
|
|
<strong>Check Specific Handles</strong>
|
|
|
|
<p>Use the -a option followed by a handle:</p>
|
|
|
|
<pre>bin/checker -a 123456/123</pre>
|
|
|
|
<p>This will check all the bitstreams inside an item, collection or community.</p>
|
|
|
|
|
|
<strong>Continuous Looping</strong>
|
|
|
|
<p>There are two looping modes:</p>
|
|
|
|
<pre>bin/checker -l # Loops once through the repository
|
|
bin/checker -L # Loops continuously through the repository</pre>
|
|
|
|
<p>The -l option can be used if your repository is relatively small and your backup strategy requires it to be completely validated at a particular point. The -L option might be useful if you have a large repository, and you don't mind (or can avoid) the IO load caused by the checker.</p>
|
|
|
|
<strong>Which to Use</strong>
|
|
|
|
<p>The Checksum Checker was designed with the idea that most sys admins will run it from the cron. For small repositories we recommend using the -l option in the cron. For larger repositories that cannot be completely checked in a couple of hours, we recommend the -d option in the cron.</p>
|
|
|
|
<h3>Checker Reporting</h3>
|
|
|
|
<p>Checksum Checker uses log4j to report its results. By default it will report to a log called <code><i>[dspace]</i>/log/checker.log</code>, and it will report only on bitstreams for which the newly calculated checksum does not match the stored checksum. To report on all bitstreams checked regardless of outcome, use the <code>-v</code> (verbose) command line option:</p>
|
|
|
|
<pre>bin/checker -l -v #Loop through the repository once and
|
|
report in detail about every bitstream checked.</pre>
|
|
|
|
<p>To change the location of the log, or to modify the prefix used on each line of output, edit the <code><i>[dspace]</i>/config/templates/log4j.properties</code> file and run <code><i>[dspace]</i>/bin/install_configs</code>. </p>
|
|
|
|
|
|
<h3>Checker Results Pruning</h3>
|
|
|
|
<p>The Checksum Checker will store the result of every check in the checksum_history table. By default, successful checksum matches that are eight weeks old or older will be deleted when the -p command line option is used (unsuccessful ones will be retained indefinitely). The amount of time for which results are retained in the checksum_history table can be modified by one of two methods: </p>
|
|
|
|
<ol>
|
|
<li>editing the retention policies in <code><i>[dspace]/</i>config/dspace.cfg</code> OR
|
|
</li>
|
|
<li>passing in a properties file containing retention policies when using the -p option. </li>
|
|
</ol>
|
|
|
|
<p>Pruning is controlled by a number of properties, each of which describes a checksum result code, and the length of time for which results with that code should be retained. The format is <code>checker.retention.[RESULT CODE]=[duration]. For example: -</p>
|
|
|
|
<pre>checker.retention.CHECKSUM_MATCH=8w</pre>
|
|
|
|
<p>indicates that successful checksum matches will be retained for eight weeks. Supported units of time are</p>
|
|
|
|
<table>
|
|
<tr>
|
|
<td>s</td>
|
|
<td>Seconds</td>
|
|
</tr>
|
|
<tr>
|
|
<td>m</td>
|
|
<td>Minutes</td>
|
|
</tr>
|
|
<tr>
|
|
<td>h</td>
|
|
<td>Hours</td>
|
|
</tr>
|
|
<tr>
|
|
<td>d</td>
|
|
<td>Days</td>
|
|
</tr>
|
|
<tr>
|
|
<td>w</td>
|
|
<td>Weeks</td>
|
|
</tr>
|
|
<tr>
|
|
<td>y</td>
|
|
<td>Years</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>(Note that these units are also used for describing durations for the <code>-d</code> limited duration mode.)</p>
|
|
|
|
<p>There is a special property, <code>checker.retention.default</code>, that is used to assign a default retention period.</p>
|
|
|
|
<p>To execute the pruning you must use the -p command line option (with or without a properties file). Checksum Checker will prune the history table before beginning new checks. We recommend that you use this option regularly, as the checksum_history table can grow very large without it.</p>
|
|
|
|
<h2><a name="packager">Configuring Packager Plugins</a></h2>
|
|
|
|
<p>Package ingester plugins are configured as <a href="business.html#plugin">named or self-named plugins</a>
|
|
for the interface <code>org.dspace.content.packager.PackageIngester</code>. Package disseminator plugins are configured as <a href="business.html#plugin">named or self-named plugins</a>
|
|
for the interface <code>org.dspace.content.packager.PackageDisseminator</code>.</p>
|
|
|
|
<p>You can add names for the existing plugins, and add new plugins, by altering these configuration properties. See the <a href="business.html#plugin">Plugin Manager</a> architecture for more information about plugins.</p>
|
|
|
|
<h2><a name="crosswalk">Configuring Crosswalk Plugins</a></h2>
|
|
<p>Ingestion crosswalk plugins are configured as <a href="business.html#plugin">named or self-named plugins</a>
|
|
for the interface <code>org.dspace.content.crosswalk.IngestionCrosswalk</code>.
|
|
Dissemination crosswalk plugins are configured as <a href="business.html#plugin">named or self-named plugins</a>
|
|
for the interface <code>org.dspace.content.crosswalk.DisseminationCrosswalk</code>.</p>
|
|
|
|
<p>You can add names for existing crosswalks, add new plugin classes, and add new configurations for the configurable crosswalks as noted below.</p>
|
|
|
|
<h3><a name="mods">Configurable MODS dissemination crosswalk</a></h3>
|
|
|
|
<p>The MODS crosswalk is a self-named plugin. To configure an instance of
|
|
the MODS crosswalk, add a property to the DSpace configuration starting
|
|
with <code>"crosswalk.mods.properties."</code>; the final word of the
|
|
property name becomes the plugin's name. For example, a property name
|
|
<code>crosswalk.mods.properties.MODS</code> defines a crosswalk plugin
|
|
named <code>"MODS"</code>.</p>
|
|
|
|
<p> The value of this property is a path to a separate properties file
|
|
containing the configuration for this crosswalk. The pathname is relative to the DSpace configuration directory, i.e. the <code>config</code> subdirectory of the DSpace install directory.
|
|
So, a line like:<pre> crosswalk.mods.properties.MODS = crosswalks/mods.properties</pre>
|
|
defines a crosswalk named <code>MODS</code> whose configuration comes from
|
|
the file <code>[dspace]/config/crosswalks/mods.properties</code>.</p>
|
|
|
|
<p>The MODS crosswalk properties file is a list of properties describing how DSpace metadata elements are to be turned into elements of the MODS XML output document. The property name is a concatenation of the metadata schema, element name, and optionally the qualifier. For example, the <code>contributor.author</code> element
|
|
in the native Dublin Core schema would be: <code>dc.contributor.author</code>. The value of the property is a line containing two segments separated by the vertical bar (<code>"|"</code>): The first part is an XML fragment
|
|
which is copied into the output document. The second is an XPath expression describing where in that fragment to put the value of the metadata element. For example, in this property:
|
|
<pre>
|
|
dc.contributor.author = <mods:name><mods:role><mods:roleTerm type="text">author</mods:roleTerm></mods:role><mods:namePart>%s</mods:namePart></mods:name> | mods:namePart/text()
|
|
</pre>
|
|
Some of the examples include the string <code>"%s"</code> in the prototype
|
|
XML where the text value is to be inserted, but don't pay any attention to
|
|
it, it is an artifact that the crosswalk ignores.
|
|
|
|
<p>For example, given an author named <em>Jack Florey</em>, the crosswalk will insert</p>
|
|
<pre><code>
|
|
<mods:name>
|
|
<mods:role>
|
|
<mods:roleTerm type="text">author</mods:roleTerm>
|
|
</mods:role>
|
|
<mods:namePart></code><em>Jack Florey</em><code></mods:namePart>
|
|
</mods:name> </code></pre>
|
|
into the output document. Read the example configuration file for more
|
|
details.
|
|
|
|
<h3><a name="qdc">Configurable Qualified Dublin Core (QDC) dissemination crosswalk</a></h3>
|
|
|
|
<p>The QDC crosswalk is a self-named plugin. To configure an instance of
|
|
the QDC crosswalk, add a property to the DSpace configuration starting
|
|
with <code>"crosswalk.qdc.properties."</code>; the final word of the
|
|
property name becomes the plugin's name. For example, a property name
|
|
<code>crosswalk.qdc.properties.QDC</code> defines a crosswalk plugin
|
|
named <code>"QDC"</code>.</p>
|
|
|
|
<p>The value of this property is a path to a separate properties file
|
|
containing the configuration for this crosswalk. The pathname is relative to the DSpace configuration directory, i.e. the <code>config</code> subdirectory of the DSpace install directory. So, a line like:<pre> crosswalk.qdc.properties.QDC = crosswalks/qdc.properties</pre> defines a crosswalk named <code>QDC</code> whose configuration comes from the file <code>[dspace]/config/crosswalks/qdc.properties</code>.</p>
|
|
|
|
<p>You'll also need to configure the namespaces and schema location strings for the XML output generated by this crosswalk. The namespaces property names are of the format: <br>
|
|
<code>crosswalk.qdc.namespace.</code><em>prefix</em> = <em>uri</em>
|
|
<br>where <em>prefix</em> is the namespace prefix and <em>uri</em> is the namespace URI.</p>
|
|
|
|
<p>For example, this shows how a crosswalk named "QDC" would be configured:
|
|
<pre>crosswalk.qdc.properties.QDC = crosswalks/QDC.properties
|
|
crosswalk.qdc.namespace.QDC.dc = http://purl.org/dc/elements/1.1/
|
|
crosswalk.qdc.namespace.QDC.dcterms = http://purl.org/dc/terms/
|
|
crosswalk.qdc.schemaLocation.QDC = \
|
|
http://purl.org/dc/terms/ http://dublincore.org/schemas/xmls/qdc/2003/04/02/qualifieddc.xsd</pre></p>
|
|
|
|
<p>The QDC crosswalk properties file is a list of properties
|
|
describing how DSpace metadata elements are to be turned into elements of the Qualified DC XML output document. The property name is a concatenation of the metadata schema, element name, and optionally
|
|
the qualifier. For example, the <code>contributor.author</code> element in the native Dublin Core schema would be: <code>dc.contributor.author</code>. The value of the property is an XML fragment, the element whose value
|
|
will be set to the value of the metadata field in the property key.</p>
|
|
|
|
<p> For example, in this property:
|
|
<pre> dc.coverage.temporal = <dcterms:temporal /></pre>
|
|
the generated XML in the output document would look like, e.g.:
|
|
<pre> <dcterms:temporal>Fall, 2005</dcterms:temporal></pre></p>
|
|
|
|
<h3>XSLT-based crosswalks</h3>
|
|
|
|
<p>The XSLT crosswalks use XSL stylesheet transformation (XSLT) to
|
|
transform an XML-based external metadata format to or from DSpace's
|
|
internal metadata. XSLT crosswalks are much more powerful and
|
|
flexible than the configurable MODS and QDC crosswalks, but they
|
|
demand some esoteric knowledge (XSL stylesheets). Given that, you can
|
|
create all the crosswalks you need just by adding stylesheets and
|
|
configuration lines, without touching any of the Java code.</p>
|
|
<p>A submission crosswalk is described by a configuration key starting with '<code>crosswalk.submission.</code>", like <pre> crosswalk.submission.<i>PluginName</i>.stylesheet = <i>path</i></pre>
|
|
The <em>PluginName</em> is, of course, the plugin's name. The <em>path</em> value is the path to the file containing the crosswalk stylesheet (relative to <code><em>dspace.dir</em>/config</code>).</p>
|
|
<p>Here is an example that configures a crosswalk named "LOM" using a stylesheet
|
|
in <code>[dspace]/config/crosswalks/d-lom.xsl</code>:
|
|
<pre> crosswalk.submission.stylesheet.LOM = crosswalks/d-lom.xsl</pre></p>
|
|
|
|
<p>A dissemination crosswalk is described by a configuration key starting with '<code>crosswalk.dissemination.</code>", like <pre> crosswalk.dissemination.<i>PluginName</i>.stylesheet = <i>path</i></pre>
|
|
The <em>PluginName</em> is, of course, the plugin's name. The <em>path</em> value is the path to the file containing
|
|
the crosswalk stylesheet (relative to <code><em>dspace.dir</em>/config</code>).</p>
|
|
|
|
<p>You can make two different plugin names point to the same crosswalk,
|
|
by adding two configuration entries with the same path, e.g.
|
|
<pre>
|
|
crosswalk.submission.MyFormat.stylesheet = crosswalks/myformat.xslt
|
|
crosswalk.submission.almost_DC.stylesheet = crosswalks/myformat.xslt
|
|
</pre></p>
|
|
|
|
<p>The dissemination crosswalk must also be configured with an XML Namespace
|
|
(including prefix and URI) and an XML Schema for its output format. This
|
|
is configured on additional properties in the DSpace Configuration, i.e.:
|
|
<pre> crosswalk.dissemination.<i>PluginName</i>.namespace.<i>Prefix</i> = <i>namespace-URI</i>
|
|
crosswalk.dissemination.<i>PluginName</i>.schemaLocation = <i>schemaLocation value</i> </pre>
|
|
For example:
|
|
<pre> crosswalk.dissemination.qdc.namespace.dc = http://purl.org/dc/elements/1.1/
|
|
crosswalk.dissemination.qdc.namespace.dcterms = http://purl.org/dc/terms/
|
|
crosswalk.dissemination.qdc.schemaLocation = \
|
|
http://purl.org/dc/elements/1.1/ http://dublincore.org/schemas/xmls/qdc/2003/04/02/qualifieddc.xsd </pre></p>
|
|
|
|
<h3>DSpace Intermediate Metadata (DIM) format</h3>
|
|
XSLT crosswalk plugins translate between the external metadata format
|
|
and an XML format called <em>DSpace Intermediate Metadata</em>,
|
|
which exists <em>only</em> for the purpose of XSLT crosswalks.
|
|
It is <em>never</em> to be exported from DSpace, since it is not an
|
|
acknowledged metadata format, it is simply an expression of the way
|
|
DSpace stores its metadata fields internally.
|
|
<p>All the elements in a DIM document are in the namespace
|
|
<code>http://www.dspace.org/xmlns/dspace/dim</code>.</p>
|
|
<p>The root element is named <code>dim</code>. It has zero or more
|
|
children, all <code>field</code> elements. It may have an
|
|
attribute <code>dspaceType</code>, which identifies the type of
|
|
object ("ITEM", "COLLECTION", or "COMMUNITY") this metadata describes. This attribute
|
|
is only guaranteed to be set for dissemination crosswalks.</p>
|
|
<p>Each <code>field</code> element may have the following attributes:
|
|
<ul>
|
|
<li><code>mdschema</code> (Required) The metadata schema, e.g. <code>"dc"</code>.</li>
|
|
<li><code>element</code> (Required) Element name, such as "contributor".</li>
|
|
<li><code>qualifier</code> Qualifier name, such as "author".</li>
|
|
<li><code>lang</code> Language code describing language of this entry.</li>
|
|
</ul>
|
|
The value of <code>field</code> is the value of that metadata field.
|
|
Fields with the same qualifiers may be repeated.
|
|
|
|
<p>Here is an example of the DIM format:
|
|
<pre> <dim:dim xmlns:dim="http://www.dspace.org/xmlns/dspace/dim" dspaceType="ITEM">
|
|
<dim:field mdschema="dc" element="title" lang="en_US">
|
|
The Endochronic Properties of Resublimated Thiotimonline
|
|
</dim:field>
|
|
<dim:field mdschema="dc" element="contributor" qualifier="author">
|
|
Isaac Asimov
|
|
</dim:field>
|
|
<dim:field mdschema="dc" element="language" qualifier="iso">
|
|
eng
|
|
</dim:field>
|
|
<dim:field mdschema="dc" element="subject" qualifier="other" lang="en_US">
|
|
time-travel scifi hoax
|
|
</dim:field>
|
|
<dim:field element="publisher">
|
|
Boston University Department of Biochemistry
|
|
</dim:field>
|
|
</dim:dim>
|
|
</pre></p>
|
|
|
|
<h3>Testing XSLT Crosswalks</h3>
|
|
The XSLT crosswalks will automatically reload an XSL stylesheet that
|
|
has been modified, so you can edit and test
|
|
stylesheets without restarting DSpace.
|
|
|
|
<p>You can test a dissemination crosswalk by hooking it up to an OAI-PMH
|
|
crosswalk and using an OAI request to get the metadata for a known item.</p>
|
|
|
|
<p>Testing the submission crosswalk is more difficult, so we have supplied
|
|
a command-line utility to help. It calls the crosswalk plugin to
|
|
translate an XML document you submit, and displays the resulting
|
|
intermediate XML (DIM). Invoke it with:
|
|
<pre><em>[dspace]</em>/bin/dsrun org.dspace.content.crosswalk.XSLTIngestionCrosswalk [-l] <em>plugin input-file</em></pre>
|
|
..where <em>plugin</em> is the name of the crosswalk plugin to test (e.g.
|
|
"LOM"), and <em>input-file</em> is a file containing an XML document
|
|
of metadata in the appropriate format.</p>
|
|
<p> Add the <code>-l</code> option to to pass the ingestion crosswalk a list of elements instead of a whole document, as if the List form of the ingest() method had been called. This is needed to test ingesters for formats like DC that get called with lists of elements instead of a root element.</p>
|
|
|
|
|
|
<hr>
|
|
|
|
<address>
|
|
Copyright © 2002-2004 MIT and Hewlett Packard
|
|
</address>
|
|
</body>
|
|
</html>
|