Versions Compared

Old Version 53

changes.mady.by.user Mark H. Wood

Saved on

compared with

New Version 54

changes.mady.by.user Hrafn Malmquist

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: external mail server subchapter

...

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

...

  • [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 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 The local.cfg Configuration Properties File81952888) or using System Properties / Environment Varilables.

...

  • Configuration File Syntax/Sources: All DSpace configurations are loaded via Properties files (using the Configuration File Syntax 81952888 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 The local.cfg Configuration Properties File 81952888 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 Configuration File Syntax 81952888 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 Why are there multiple copies of some config files? 81952888 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.

...

DSpace will look up a javax.mail.Session object in JNDI and, if found, will use that to send email.  Otherwise it will create a Session using some of the properties detailed below.

Property:

mail.server

Example Value:

mail.server = smtp.my.edu

Informational Note:

The address on which your outgoing SMTP email server can be reached.

Property:

mail.server.username

Example Value:

mail.server.username = myusername

Informational Note:

SMTP mail server authentication username, if required. This property is optional.

Property:

mail.server.password

Example Value:

mail.server.password = mypassword

Informational Note:

SMTP mail server authentication password, if required. This property is optional

/

.

Property:

mail.server.port

Example Value:

mail.server.port = 25

Informational Note:

The port on which your SMTP mail server can be reached. By default, port 25 is used, port 587 is commonly used for TLS connections. Change this setting if your SMTP mailserver is running on another port. This property is optional.

Property:

mail.from.address

Example Value:

mail.from.address = dspace-noreply@myu.edu

Informational Note:

The "From" address for email. Change the 'myu.edu' to the site's host name.

Property:

feedback.recipient

Example Value:

feedback.recipient = dspace-help@myu.edu

Informational Note:

When a user clicks on the feedback link/feature, the information will be sent to the email address of choice. This configuration is currently limited to only one recipient. Since DSpace 4.0, this is also the email address displayed on the contacts page.

Property:

mail.admin

Example Value:

mail.admin = dspace-help@myu.edu

Informational Note:

Email address of the general site administrator (Webmaster)

Property:

alert.recipient

Example Value:

alert.recipient = john.doe@myu.edu

Informational Note:

Enter the recipient for server errors and alerts. This property is optional.

Property:

registration.notify

Example Value:

registration.notify = mike.smith@myu.edu

Informational Note:

Enter the recipient that will be notified when a new user registers on DSpace. This property is optional.

Property:

mail.charset

Example Value:

mail.charset = UTF-8

Informational Note:

Set the default mail character set. This may be over-ridden by providing a line inside the email template 'charset: <encoding>', otherwise this default is used.

Property:

mail.allowed.referrers

Example Value:

mail.allowed.referrers = localhost

Informational Note:

A comma separated list of hostnames that are allowed to refer browsers to email forms. Default behavior is to accept referrals only from dspace.hostname. This property is optional.

Property:

mail.extraproperties

Example Value:


Code Block
mail.extraproperties = mail.smtp.socketFactory.port=465, \
       mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory, \
       mail.smtp.socketFactory.fallback=false


Informational Note:

If you need to pass extra settings to the Java mail library. Comma separated, equals sign between the key and the value. This property is optional.

Property:

mail.server.disabled

Example Value:

mail.server.disabled = false

Informational Note:

An option is added to disable the mailserver. By default, this property is set to 'false'. By setting value to 'true', DSpace will not send out emails. It will instead log the subject of the email which should have been sent. This is especially useful for development and test environments where production data is used when testing functionality. This property is optional.

Property:

mail.session.name

Example Value:

mail.session.name = myDSpace

Informational Note:

Specifies the name of a javax.mail.Session object stored in JNDI under java:comp/env/mail.  The default value is "Session".

Property:

default.language

Example Value:

default.language = en_US

Informational Note:

If no other language is explicitly stated in the input-forms.xml, the default language will be attributed to the metadata values.

Wording of E-mail Messages

...

  • A line beginning with "#" is a comment and will not be included in the message.
  • A line beginning with "Subject: " will set the Subject: header of the message and will not be included in the body.
  • A line beginning with "Charset: " will set the character set in which the subject and single message bodypart are assumed to be encoded, will be used as the value of the charset parameter of the Content-Encoding header for the message, and will not be included in the body.   If the message has multiple bodyparts (i.e. attachments are included) then all are assumed to be encoded in US-ASCII and the "Charset: " line has no effect on them (but still affects the subject).

  • A number enclosed in braces, such as {2}, anywhere in a non-comment line, will be replaced with the corresponding parameter which was supplied to the message when the message formatter was called.   Parameter numbers are 0-based.  Refer to the comments in the template or to the code which uses it for the meaning of each parameter.

Using an external mail server

If you want to use an external mail server setting the value of mail.server to the domain name is enough if authentication is not required. Most external SMTP mail servers will however require authentication for obvious reasons. To enable TLS encryption you will typically have to set the mail.server.port to the secure default 587 and for the mail.server.username and mail.server.password to be set. In addition you will need to enable TLS by setting the following extra properties:


Code Block
mail.extraproperties = mail.smtp.auth=true, \
                       mail.smtp.starttls.enable=true


File Storage

Info

Beginning with DSpace 6, your file storage location (aka bitstore) is now defined in the [dspace]/config/spring/api/bitstore.xml Spring configuration file.  By default it is defined as the [dspace]/assetstore/.  More information on modifying your file storage location can be found at   Configuring the Bitstream Store in the Storage Layer documentation.

...

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 AuthorityControlSettings 81952888

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 AuthorityControlSettings 81952888)

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 "Defining the Indexes81952888" 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 "Defining Sort Options81952888" 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 Defining Sort Options 81952888 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 Defining Sort Options 81952888 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 Defining the Indexes 81952888).

<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

...