Versions Compared

Old Version 54

changes.mady.by.user Hrafn Malmquist

Saved on

compared with

New Version 55

changes.mady.by.user Tim Donohue

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

For ease of use, the Configuration documentation is broken into several parts:

...

Table of Contents
minLevel2
outlinetrue
stylenone

General Configuration

...


Warning
titleMany configuration names/keys have changed!

If you are upgrading from an earlier version of DSpace, you will need to

...

DSpace provides a number of textual configuration files which may be used to configure your site based on local needs. These include:

...

be aware that many configuration names/keys have changed. Because Apache Commons Configuration allows for auto-overriding of configurations, all configuration names/keys in different *.cfg files MUST be uniquely named (otherwise accidental, unintended overriding may occur).

In order to compensate for this, all

modules/*.cfg files had their configurations renamed to be prepended with the module name.  As a basic example, all the configuration settings within the modules/oai.cfg configuration now start with "oai.".

Additionally, while the local.cfg may look similar to the old build.properties, many of its configurations have slightly different names. So, simply copying your build.properties into a local.cfg will NOT work.

This means that DSpace 5.x (or below) configurations are NOT compatible with the Enhanced Configuration Scheme.  While you obviously can use your old configurations as a reference, you will need to start with fresh copy of all configuration files, and reapply any necessary configuration changes (this has always been the recommended procedure). However, as you'll see in the next section, you'll likely want to do that anyways in order to take full advantage of the new local.cfg file.

General Configuration

In the following sections you will learn about the different configuration files that you will need to edit so that you may make your DSpace installation work.

DSpace provides a number of textual configuration files which may be used to configure your site based on local needs. These include:

  • [dspace]/config/dspace.cfg : The primary configuration file, which contains the main configurations for DSpace.
  • [dspace]/config/modules/*.cfg : Module configuration files, which are specific to various modules/features within DSpace.
  • [dspace]/config/local.cfg : A (optional, but highly recommended) localized copy of configurations/settings specific to your DSpace (see The local.cfg Configuration Properties File below)
  • Additional feature-specific configuration files also exist under [dspace]/config/, some of these include:
    • default.license : the default deposit license used by DSpace during the submission process (see Submission User Interface documentation)
    • hibernate.cfg.xml : The
    • : Module configuration files, which are specific to various modules/features within DSpace.
  • [dspace]/config/local.cfg : A (optional, but highly recommended) localized copy of configurations/settings specific to your DSpace (see 81952888 below)
  • Additional feature-specific configuration files also exist under [dspace]/config/, some of these include:

...

Additionally, DSpace provides the ability to easily override default configuration settings (in dspace.cfg or modules/*.cfg) using a local.cfg file (see 81952888The local.cfg Configuration Properties File) or using System Properties / Environment Varilables.

...

  • Configuration File Syntax/Sources: All DSpace configurations are loaded via Properties files (using the 81952888 Configuration File Syntax detailed above)
    • Note: Apache Commons Configuration does support other configuration sources such as XML configurations or database configurations (see its Overview documentation).  At this time, DSpace does not utilize these other sorts of configurations by default. However, it would be possible to customize your local config-definition.xml to load settings from other locations.
  • Configuration Files/Sources: By default, only two configuration files are loaded into Apache Commons Configuration for DSpace:
    • local.cfg (see 81952888 The local.cfg Configuration Properties File documentation below)
    • dspace.cfg (NOTE: all modules/*.cfg are loaded by dspace.cfg via "include=" statements at the end of that configuration file. They are essentially treated as sub-configs which are embedded/included into the dspace.cfg)
  • Configuration Override Scheme: The configuration override scheme is defined as follows. Configurations specified in earlier locations will automatically override any later values:
    • System Properties (-D[setting]=[value]) override all other options
    • Environment Variables
    • local.cfg
    • dspace.cfg (and all modules/*.cfg files) contain the default values for all settings.
  • Configuration Auto-Reload: By default, all configuration files are automatically checked every 5 seconds for changes. If they have changed, they are automatically reloaded.

...

  • Override any default configurations: Any setting in your local.cfg will automatically OVERRIDE a setting of the same name in the dspace.cfg or any modules/*.cfg file.  This also means that you can copy ANY configuration (from dspace.cfg or any modules/*.cfg file) into your local.cfg to specify a new value.
    • For example, specifying dspace.url in local.cfg will override the default value of  dspace.url in dspace.cfg.
    • Also, specifying oai.solr.url in local.cfg will override the default value of oai.solr.url in config/modules/oai.cfg
  • Configuration Syntax: The local.cfg file uses the Apache Commons Configuration Property file syntax (like all *.cfg files) . For more information see the section on 81952888 Configuration File Syntax above.
    • This means the local.cfg also supports enhanced features like the ability to include other config files (via "include=" statements).
  • Override local.cfg via System Properties: As needed, you also are able to OVERRIDE settings in your local.cfg by specifying them as System Properties or Environment Variables.
    • For example, if you wanted to change your dspace.dir in development/staging environment, you could specify it as a System Property (e.g. -Ddspace.dir=[new-location]). This new value will override any value in both local.cfg and dspace.cfg.

When you build DSpace (e.g. mvn package), this local.cfg file will be automatically copied to [dspace]/config/local.cfg.  Similar to the dspace.cfg, the "runtime" configuration (used by DSpace) is the one in [dspace]/config/local.cfg. See the 81952888 Why are there multiple copies of some config files? question above for more details on the runtime vs source configuration.

...

Info
titleAny dspace.cfg setting can be overridden in your local.cfg

Remember, any of the below dspace.cfg settings can be copied into your local.cfg configuration file and overridden. So, rather than editing the dspace.cfg (or any of the modules/*.cfg), it's recommended to simply override the default values in your local.cfg. That way, your local.cfg can serve as the record of which configurations you have actually tweaked in your DSpace, which may help to simplify future upgrades.

...

Property:

webui.submission.sherparomeo-policy-enabled

Example Value:

webui.submission.sherparomeo-policy-enabled = true

Informational Note:

Controls whether or not the UI submission should try to use the Sherpa/RoMEO Publishers Policy Database Integration (default true)

Property:

sherpa.romeo.url

Example Value:

sherpa.romeo.url = http://www.sherpa.ac.uk/romeo/api29.php

Informational Note:

The Sherpa/RoMEO endpoint. Shared with the authority control feauture for Journal Title autocomplete see 81952888 AuthorityControlSettings

Property:

sherpa.romeo.apikey

Example Value:
sherpa.romeo.apikey = YOUR-API-KEY
Informational Note:

Allow to use a specific API key to raise the usage limit (500 calls/day for unregistred user).

You can register for a free api access key at http://www.sherpa.ac.uk/news/romeoapikeys.htm

The functionality rely on understanding to which Journal (ISSN) is related the submitting item. This is done out of box looking to some item metadata but a different strategy can be used as for example look to a metadata authority in the case that the Sherpa/RoMEO autocomplete for Journal is used (see 81952888 AuthorityControlSettings)

The strategy used to discover the Journal related to the submission item is defined in the spring file /config/spring/api/sherpa.xml

...

Property:

webui.browse.index.<n>

Example Value:

webui.browse.index.1 = dateissued:item:dateissued
webui.browse.index.2 = author:metadata:dc.contributor.*,dc.creator:text

Informational Note:

This is an example of how one "Defines the Indexes". See "81952888Defining the Indexes" in the next sub-section.

Property:

webui.itemlist.sort-option.<n>

Example Value:

webui.itemlist.sort-option.1 = title:dc.title:title

Informational Note:

This is an example of how one "Defines the Sort Options". See "81952888Defining Sort Options" in the following sub-section.

...

Element

Definition and Options (if available)

webui.browse.index.<n>

n is the index number. The index numbers must start from 1 and increment continuously by 1 thereafter. Deviation from this will cause an error during install or a configuration update. So anytime you add a new browse index, remember to increase the number. (Commented out index numbers may be used over again).

<index-name>

The name by which the index will be identified. In order for the DSpace UI to display human-friendly description for this index, you'll need to update either your Messages.properties (JSPUI) or messages.xml (XMLUI) with new message keys referencing this <index-name>.

JSPUI Example (Messages.properties):

  • browse.type.metadata.<index-name> = My New Field

XMLUI Example (messages.xml):

  • <message key= "xmlui.ArtifactBrowser.Navigation.browse_<index-name>" >My New Fields</message>
  • <message key= "xmlui.ArtifactBrowser.ConfigurableBrowse.title.metadata.<index-name>" >Browsing { 0 } by My New Field { 1 }</message>
  • <message key= "xmlui.ArtifactBrowser.ConfigurableBrowse.trail.metadata.<index-name>" >Browsing { 0 } by My New Field</message>
  • <message key= "xmlui.ArtifactBrowser.ConfigurableBrowse.<index-name>.column_heading" >My New Field</message>

(metadata|item)

Only two options are available: "metadata" or "item"

  • "metadata" indexes allow you to index all items based on one or more metadata fields. The list of fields should be provided as part of the "metadata" configuration. Only items which have values for these fields will appear in this index (e.g. if you have a "metadata" index for "dc.subject.*", an item will not appear in that browse/search if it doesn't have a "dc.subject.*" value). The browse index will have to parts: first it lists all values of the specified metadata fields. If the user select one of these values the index lists all items in which the specified metadata field is assigned with the selected value.
    • Note: If you set a <sort-type> to be used, this sort type is not used on the values of the metadata fields but on the order of the items when listing all items that have a specific value of the metadata field.
  • "item" indexes provide you with a browseable list of ALL items in the site, sorted by a particular metadata field. The field this index is sorted by is referenced by <sort-option-name> (which should refer to a corresponding "webui.itemlist.sort-option.<n>" setting... see 81952888 Defining Sort Options below for more information)

<schema-prefix>

(Only for "metadata" indexes) The schema used for the field to be index. The default is dc (for Dublin Core).

<element>

(Only for "metadata" indexes) The schema element. In Dublin Core, for example, the author element is referred to as "Contributor". The user should consult the default Dublin Core Metadata Registry table in Appendix A.

<qualifier>

(Only for "metadata" indexes) This is the qualifier to the <element> component. The user has two choices: an asterisk "" or a proper qualifier of the element. The asterisk is a wildcard and causes DSpace to index all types of the schema element. For example, if you have the element "contributor" and the qualifier "" then you would index all contributor data regardless of the qualifier. Another example, you have the element "subject" and the qualifier "lcsh" would cause the indexing of only those fields that have the qualifier "lcsh". (This means you would only index Library of Congress Subject Headings and not all data elements that are subjects.

<sort-type>

(Optional, should be set for "item" indexes) This refers to the sort type / data type of the field:

  • date the index type will be treated as a date object and sorted as such
  • text the index type will be treated as plain text and sorted as such
  • (any other value refers to a custom <sort-type> which should be defined in a corresponding webui.itemlist.sort-option.<n> setting. See 81952888 Defining Sort Options below for more information.)

<sort-order>

(Optional) The default sort order. Choose asc (ascending) or desc (descending).  Ascending is the default value, but descending may be useful for date-based indexes (e.g. to display most recent submissions first)

...

Element

Definition and Options (if available)

webui.itemlist.sort-option.<n>

n is an arbitrary number you choose.

<sort-type-name>

The name by which the sort option will be identified. This is the name by which it is referred in the "webui.browse.index" settings (see 81952888 Defining the Indexes).

<schema-prefix>

The schema used for the field to be sorted on in the index. The default is dc (for Dublin Core).

<element>

The schema element. In Dublin Core, for example, the author element is referred to as "Contributor". The user should consult the default Dublin Core Metadata Registry table in Appendix A.

<qualifier>

This is the qualifier to the <element> component. The user has two choices: an asterisk "*" or a proper qualifier of the element.

<datatype>

This refers to the datatype of the field:
date the sort field will be treated as a date object
text the sort field will be treated as plain text.
title the sort field will be treated like a title, which will include a link to the item page

...

Property:

plugin.named.org.dspace.content.authority.ChoiceAuthority

Example Value:


Code Block
plugin.named.org.dspace.content.authority.ChoiceAuthority = \
	org.dspace.content.authority.SampleAuthority = Sample, \
 	org.dspace.content.authority.LCNameAuthority = LCNameAuthority, \
 	org.dspace.content.authority.SHERPARoMEOPublisher = SRPublisher, \
 	org.dspace.content.authority.SHERPARoMEOJournalTitle = SRJournalTitle


Informational Note:

--

Property:

plugin.selfnamed.org.dspace.content.authority.ChoiceAuthority

Example Value:


Code Block
plugin.selfnamed.org.dspace.content.authority.ChoiceAuthority = \
	org.dspace.content.authority.DCInputAuthority


Property:

lcname.url

Example Value:

lcname.url = http://alcme.oclc.org/srw/search/lcnaf_

The Linked Data Service at the Library of Congress might be a better, and more stable, option: http://id.loc.gov/authorities/names.html

Informational Note:

Location (URL) of the Library of Congress Name Service

Property:

sherpa.romeo.url / sherpa.romeo.apikey

Informational Note:

Please refers to the Sherpa/RoMEO Publishers Policy Database Integration section for details about such properties. See Configuring the Sherpa/RoMEO Publishers Policy Database Integration

Property:

orcid.api.url

Example Value:orcid.api.url = https://pub.orcid.org/v2.1

Informational Note:

Location (URL) of the ORCID v2 Public API

Property:

authority.minconfidence

Example Value:

authority.minconfidence = ambiguous

Informational Note:

This sets the default lowest confidence level at which a metadata value is included in an authority-controlled browse (and search) index. It is a symbolic keyword, one of the following values (listed in descending order): accepted, uncertain, ambiguous, notfound, failed, rejected, novalue, unset. See org.dspace.content.authority.Choices source for descriptions.

Property:

xmlui.lookup.select.size

Example Value:

xmlui.lookup.select.size = 12

Informational Note:

This property sets the number of selectable choices in the Choices lookup popup

...

In the spiders directory you will also find two subdirectories.  agents contains files filled with regular expressions, one per line.  An incoming request's User-Agent header is tested with each expression found in any of these files until an expression matches.  If there is a match, the request is marked as being from a spider, otherwise not.  domains similarly contains files filled with regular expressions which are used to test the domain name from which the request comes.  You may add your own files of regular expressions to either directory if you wish to test requests with patterns of your own devising.

webui.itemdisplay.label.restricted.bitstreams 

Many configuration names/keys have changed!

...

If you are upgrading from an earlier version of DSpace, you will need to be aware that many configuration names/keys have changed. Because Apache Commons Configuration allows for auto-overriding of configurations, all configuration names/keys in different *.cfg files MUST be uniquely named (otherwise accidental, unintended overriding may occur).

...

.

...

Additionally, while the local.cfg may look similar to the old build.properties, many of its configurations have slightly different names. So, simply copying your build.properties into a local.cfg will NOT work.

This means that DSpace 5.x (or below) configurations are NOT compatible with the Enhanced Configuration Scheme.  While you obviously can use your old configurations as a reference, you will need to start with fresh copy of all configuration files, and reapply any necessary configuration changes (this has always been the recommended procedure). However, as you'll see in the next section, you'll likely want to do that anyways in order to take full advantage of the new local.cfg file.

[dspace]/config/config-definition.xml


Command-line Access to Configuration Properties

...