Digital Object Identifier (DOI)

Persistent Identifier

It is good practice to user Persistent Identifier 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 handles. With DSpace 3.0 the Identifier Service was introduced that makes it possible to use external identifier services within DSpace.

DOIs are Persistent Identifier like handles are. But as many big publishing companies uses DOIs they are quite well-known by scientists. Some journals asks for DOIs to link supplemented 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 that is member of the International DOI Foundation. Several such agencies exist. Different DOI registration agencies have different policies. Some of them offer DOI registration specially or only for academic institutions, others only for publishing companies. Most of the registration agencies charge fees for registering DOIs, 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 own APIs to reserve and register DOIs, others let their clients use the API from DataCite directly. Starting with version 4.0 DSpace support registering, reserving, ... DOIs using the DataCite API directly or using the API from EZID which is a service of the University of California Digital Library. So starting with DSpace 4.0 it is possible to use DOIs with all DataCite members that let you use the DataCite API directly and with EZID.

Configure DSpace to use DataCites API

If you use a DOI registration agency that let you use the API from DataCite directly, you can use the following instructions to configure DSpace. If you use EZID please look the instructions below.

To use DOIs within DSpace you have to configure several parts of DSpace. You'll have to enter your DOI prefix and the credentials to use the API from DataCite in dspace.cfg. You'll have to configure the script which generates some metadata. Then you'll have to activate the DOI mechanism within DSpace. And last you have to configure a cronjob which transmits the information about new and changed DOIs to the registration agency.

dspace.cfg

After you entered into a contract with an DOI registration agency, they provide you with 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:

identifier.doi.user

identifier.doi.user = user123

identifier.doi.password

identifier.doi.password = top-secret

identifier.doi.prefix

identifier.doi.prefix = 10.5072

identifier.doi.namespaceseparator

identifier.doi.namespaceseparator = dspace-

Meta data conversion

To reserve a DOI DataCite requests metadata from the object the DOI addresses. It is mandatory to send those metadata to reserve and register a DOI. The file [dspace]/config/crosswalks/DIM2DataCite.xsl controls the conversion of meta data from the DSpace internal format into the DataCite format. You have to add the name of you institution into this file:

<!--
    Document   : DIM2DataCite.xsl
    Created on : January 23, 2013, 1:26 PM
    Author     : pbecker, ffuerste
    Description: Converts metadata from DSpace Intermediat Format (DIM) into
                 metadata following the DataCite Schema for the Publication and
                 Citation of Research Data, Version 2.2
-->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:dspace="http://www.dspace.org/xmlns/dspace/dim"
                xmlns="http://datacite.org/schema/kernel-2.2"
                version="1.0">
    
    <!-- CONFIGURATION -->
    <!-- The content of the following variable will be used as element publisher. -->
    <xsl:variable name="publisher">My University</xsl:variable>
    <!-- The content of the following variable will be used as element contributor with contributorType datamanager. -->
    <xsl:variable name="datamanager"><xsl:value-of select="$publisher" /></xsl:variable>
    <!-- The content of the following variable will be used as element contributor with contributorType hostingInstitution. -->
    <xsl:variable name="hostinginstitution"><xsl:value-of select="$publisher" /></xsl:variable>
    <!-- Please take a look into the DataCite schema documentation if you want to know how to use these elements.
         http://schema.datacite.org -->
    
    
    <!-- DO NOT CHANGE ANYTHING BELOW THIS LINE EXCEPT YOU REALLY KNOW WHAT YOU ARE DOING! -->
...

Just change the value in the variable named "publisher".

If you want to know more about the DataCite Scheme, take a look in the documentation. If you change this file in a way that it is not compatible with the DataCite schema, you won't be able to reserve and register DOIs any more. So please do not change anything your not sure about.

Identifier Service

The Identifier Service manage 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.

After removing the comment signs the file should look something like this (I removed the comments that document this file as well, to make the listing shorter):

<!--
    Copyright (c) 2002-2010, DuraSpace.  All rights reserved
    Licensed under the DuraSpace License.

    A copy of the DuraSpace License has been included in this
    distribution and is available at: http://www.dspace.org/license
-->

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">

    <bean id="org.dspace.identifier.IdentifierService"
          class="org.dspace.identifier.IdentifierServiceImpl"
          autowire="byType"
          scope="singleton"/>

    <bean id="org.dspace.identifier.DOIIdentifierProvider"
        class="org.dspace.identifier.DOIIdentifierProvider"
        scope="singleton">
        <property name="configurationService"
            ref="org.dspace.services.ConfigurationService" />
        <property name="DOIConnector"
            ref="org.dspace.identifier.doi.DOIConnector" />
    </bean>

    <bean id="org.dspace.identifier.doi.DOIConnector"
        class="org.dspace.identifier.doi.DataCiteConnector"
        scope="singleton">
        <property name='DATACITE_SCHEME' value='https'/>
        <property name='DATACITE_HOST' value='mds.datacite.org'/>
        <property name='DATACITE_DOI_PATH' value='/mds/doi/' />
        <property name='DATACITE_METADATA_PATH' value='/mds/metadata/' />
        <property name='disseminationCrosswalkName' value="DataCite" />
    </bean>
</beans>

If you use other IdentifierProviders beside the DOIIdentifierProvider there will be more beans in this file.

Please pay attention to configure the property DATACITE_HOST. Per default it is set to the DataCite test server. To reserve real DOIs you probably will have to change it to mds.datacite.org. Ask your registration agency, if you're not sure about the correct address.

DSpace should send updates to DataCite whenever meta data of an item changes. To do so you have to change the dspace.cfg again. You should remove them comments in front of the two following properties or add them to the dspace.cfg:

event.consumer.doi.class = org.dspace.identifier.doi.DOIConsumer
event.consumer.doi.filters = Item+Modify_Metadata

Then you should add doi to the property event.dispatcher.default.consumers. After adding it, this property may look like this:

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 to 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 have to be started using the command line. The idea is, that this should be done periodically by a cron job. 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 that should be reserved and or registered at the DOI registration agency.

The command line interface in generals is documented here: Command Line Operations. The command that takes care for DOIs is doi-organiser. You can use the following options:

Currently you cannot generate new DOIs with this tool. You only can send information about changes in your local DSpace database to the registration agency.

'cron' job for asynchronous reservation/registration

Configure DSpace to use EZID service for registration of DOIs

Sorry, this part is not documented yet.

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 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.