All Versions
- DSpace 7.x (Current Release)
- DSpace 8.x (Unreleased)
- DSpace 6.x (EOL)
- DSpace 5.x (EOL)
- More Versions...
Page History
| Table of Contents |
|---|
Persistent Identifier
It is good practice to use Persistent Identifiers to address items in a digital repository. There are many different systems for Persistent Identifiers: Handle, DOI, urn:nbn, purl and many more. It is far out of the scope of this document to discuss the differences of all these systems. For several reasons the handle system is deeply integrated in DSpace and DSpace makes intensive use of it. With DSpace 3.0 the Identifier Service was introduced that makes it possible to use external identifier services within DSpace.
DOIs are Persistent Identifiers like handles are, but as many big publishing companies use DOIs they are quite well-known to scientists. Some journals ask for DOIs to link supplemental material whenever an article is submitted. Beginning with DSpace 4.0 it is possible to use DOIs in parallel to the handle system within DSpace. By using DOIs we mean automatic generation, reservation and registration of DOIs for every item that gets published.
DOI Registration Agencies
To register a DOI one has to enter into a contract with a DOI registration agency which is a member of the International DOI Foundation. Several such agencies exist. Different DOI registration agencies have different policies. Some of them offer DOI registration especially or only for academic institutions, others only for publishing companies. Most of the registration agencies charge fees for registering DOIs, and all of them have different rules describing for what kind of item a DOI can be registered. To make it quite clear: to register DOIs with DSpace you have to enter into a contract with a DOI registration agency.
DataCite is an international initiative to promote science and research and a member of the International DOI Foundation. The members of DataCite act as registration agencies for DOIs. Some DataCite members provide their own APIs to reserve and register DOIs, others let their clients use the DataCite API directly. Starting with version 4.0 DSpace supports the administration of DOIs by using the DataCite API directly or by using the API from EZID (which is a service of the University of California Digital Library). This means you can administrate DOIs with DSpace if your registration agency allows you to use the DataCite API directly or if your registration agency is EZID.
Configure DSpace to use the DataCite API
If you use a DOI registration agency that lets you use the DataCite API directly, you can follow the instructions below to configure DSpace. In case EZID is your registration agency the configuration of DSpace is documented here: Configure DSpace to use EZID service for registration of DOIs.
To use DOIs within DSpace you have to configure several parts of DSpace:
- enter your DOI prefix and the credentials to use the API from DataCite in dspace.cfg,
- configure the script which generates some metadata,
- activate the DOI mechanism within DSpace,
- configure a cron job which transmits the information about new and changed DOIs to the registration agency.
dspace.cfg
After you enter into a contract with a DOI registration agency, they'll provide you with user credentials and a DOI prefix. You have to enter these in the dspace cfg. Here is a list of DOI configuration options in dspace.cfg:
| Configuration File: | [dspace]/config/dspace.cfg | ||
|---|---|---|---|
| Property: | identifier.doi.user | ||
| Example Value: |
| ||
| Informational Note: | Username to login into the API of the DOI registration agency. You'll get it from your DOI registration agency. | ||
| Property: | identifier.doi.password | ||
| Example Value: |
| ||
| Informational Note: | Password to login into the API of the DOI registration agency. You'll get it from your DOI registration agency. | ||
| Property: | identifier.doi.prefix | ||
| Example Value: |
| ||
| Informational Note: | The prefix you got from the DOI registration agency. All your DOIs start with this prefix, followed by a slash and a suffix generated from DSpace. The prefix can be compared with a namespace within the DOI system. | ||
| Property: | identifier.doi.namespaceseparator | ||
| Example Value: |
| ||
| Informational Note: | This property is optional. If you want to use the same DOI prefix in several DSpace installations or with other tools that generate and register DOIs it is necessary to use a namespace separator. All the DOIs that DSpace generates will start with the DOI prefix, followed by a slash, the namespace separator and some number generated by DSpace. For example, if your prefix is 10.5072 and you want all DOIs generated by DSpace to look like 10.5072/dspace-1023 you have to set this as in the example value above. |
Metadata conversion
To reserve or register a DOI, DataCite requires that metadata be supplied that describes the object the DOI addresses. The file [dspace]/config/crosswalks/DIM2DataCite.xsl controls the conversion of metadata from the DSpace internal format into the DataCite format. You have to add the name of your institution into this file:
...
If you want to know more about the DataCite Scheme, have a look at the documentation. If you change this file in a way that is not compatible with the DataCite schema, you won't be able to reserve and register DOIs anymore. Do not change anything if you're not sure what you're doing.
Identifier Service
The Identifier Service manages the generation, reservation and registration of identifiers within DSpace. You can configure it using the config file located in [dspace]/config/spring/api/identifier-service.xml. In the file you should already find the code to configure DSpace to register DOIs. Just read the comments and remove the comment signs around the two appropriate beans.
...
| Code Block | ||
|---|---|---|
| ||
event.dispatcher.default.consumers = versioning, discovery, eperson, harvester, doi |
Command Line Interface
To make DSpace resistant to outages of DataCite we decided to separate the DOI support in two parts. When a DOI should be generated, reserved or minted, DSpace does this in its own database. To perform registration and/or reservation against the DOI registration agency a job has to be started using the command line. Obviously this should be done by a cron job periodically. In this section we describe the command line interface, in case you ever want to use it manually. In the next section you'll see the cron job that transfers all DOIs designated for reservation and/or registration.
...
Currently you cannot generate new DOIs with this tool. You can only send information about changes in your local DSpace database to the registration agency.
'cron' job for asynchronous reservation/registration
When a DOI should be reserved, registered, deleted or its metadata needs to be updated, DSpace just writes this information into its local database. A command line interface is supplied to send the necessary information to the registration agency. This behavior makes it easier to react to outages or errors while using the API. As this information should be sent regularly, so it is a good idea to set up a cron job instead of doing it manually.
...
| Code Block | ||
|---|---|---|
| ||
# Send information about new and changed DOIs to the DOI registration agency: 0 1,13 * * * [dspace]/bin/dspace doi-organiser -u -q ; [dspace]/bin/dspace doi-organiser -s -q ; [dspace]/bin/dspace doi-organiser -r -q ; [dspace]/bin/dspace doi-organiser -d -q |
Limitations of DOI support
| Warning |
|---|
| Every DSpace installation expects to be the only application that generates DOIs which start with the prefix and the namespace separator you configured. DSpace does not check whether a DOI it generates is reserved or registered already. |
...
DSpace currently generates DOIs for items only. There is no support to generate DOIs for Communities and collections yet.
Configure DSpace to use EZID service for registration of DOIs
Sorry, this part is not documented yet. Please feel free to add information about how to configure DSpace to work together with EZID.
Adding support for other Registration Agencies
If you want DSpace to support other registration agencies you just have to write a java class that implements the interface DOIConnector ([dspace-source]/dspace-api/src/main/java/org/dspace/identifier/doi/DOIConnector.java). You might use the DataCiteConnector ([dspace-source]/dspace-api/src/main/java/org/dspace/identifier/doi/DataCiteConnector.java) as an example. After developing your own DOIConnector you configure DSpace as if you were using the DataCite API directly. Just use your DOIConnector when configuring the IdentifierService instead of the DataCiteConnector.
...
Overview
Content Tools