DataCite DOI

This documentation relates to release candidate version of the DataCite DOI plugin, available at [1]

DataCite DOI Manager Screen

The process for registering and minting DOIs is now managed via the DataCite DOI Manager screen, available via an eprint item’s Actions tab.

Actions tab with the DataCite DOI Manager option.

The DataCite DOI Manager is only available for items in the review queue or the live archive, and only to those users with editor or administrator permissions.

Each eprint record has its own DOI that can be registered with DataCite, derived from the repository’s DataCite prefix (e.g. 10.xxx), the repository’s name, and the eprint’s ID.

An eprint in the live archive with an available DOI. Options are available to either reserve or mint the DOI.

If this DOI has not yet been registered on DataCite, it will be listed as an Available DOI, and is available either to reserve or mint:

• Reserve: The DOI is created in DataCite as a Draft DOI. The DOI is not listed in the global handle system and is not publicly findable.
• Mint: The DOI is registered with the global handle system and listed as Findable in DataCite.

Reserving DOIS

Items in the repository’s review queue may only have DOIs reserved. Not all of the mandatory metadata is required when reserving a DOI.

An item in the review queue. A DOI may be reserved adding it as a draft DOI in DataCite.

Clicking the Reserve DOI button will create a draft DOI in DataCite. This process happens instantly and the DataCite DOI Manager screen will update to show when the DOI was reserved as well as adding the DOI to the item’s DOI metadata field. Draft DOIs are not registered against the global handle system, i.e. they won’t redirect to the eprint. Once a reserved DOI has been created it can be updated with the item’s current metadata.

A reserved DOI, with the option to update the metadata associated with this DOI.

Minting DOIs

Minting a DOI adds it as a findable DOI in DataCite. There are two main approaches to minting a DOI:

1. Using the Mint DOI button for an item in the live archive, which has all of the required metadata.
2. Transferring an item with a reserved DOI and all of the required metadata, to the live archive, from the review queue.

The Mint DOI button will register the DOI with the global handle system, and the DOI will be registered as “Findable” in DataCite. This process may take a few minutes and is handled by the repository’s indexer. Upon successful completion the new DOI will be added to the eprint’s DOI metadata field.

An item in the live archive with a DOI available to mint. The option to update the previously reserved DOI is still available too.

Once a DOI has successfully been minted for an eprint, the option to Update Metadata becomes available, which will resend the eprint metadata for this DOI.

This should only be used for minor updates, e.g. correcting errors or adding additional files.

Tombstone Pages

If an item which has previously had a DOI minted for it is either retired or removed from the repository, the DataCite record is updated to point to a tombstone page for the record. This consists of the basic citation metadata that was last registered with DataCite, i.e. the data available when either of the Mint DOI or Update Metadata buttons was last used.

A tombstone page for a retired eprint, which the DOI will now redirect to, providing basic citation information.

Versioning

When creating a new version of an eprint via the New version button in the Actions tab, any existing DOI value will be copied across to the new version of the eprint.

The DataCite DOI Manager will highlight when a Current DOI redirects to an earlier version of an eprint, and will present two options when the later version is in the live archive (i.e. has a page a DOI can successfully redirect to).

1. Update Metadata & URL – this will update the current DataCite record to redirect to the new version of this eprint
2. Reserve DOI and Mint DOI – the regular options available when the Available DOI for a record has not yet been reserved or registered on DataCite.

This eprint is a later version of an existing eprint and has inherited a DOI. The metadata and URL associated with this DOI can be updated to redirect to the newer record.

DOIs registered for eprints which are earlier or later versions of other eprints, will use DataCite’s “HasVersion” and “IsVersionOf” properties to link forwards and backwards as appropriate.

External DOIs

If an eprint already has a DOI associated with it, e.g. one that has previously been provided by a journal publication, then this will be listed as the Current DOI. The DataCite DOI Manager screen will indicate where this DOI redirects to, and will still present options for an Available DOI if the DOI for this record can still be minted on DataCite.

An eprint with an external DOI set. This can be replaced with an available DOI via DataCite.

The DataCite DOI Manager will also run a search of the eprint’s title against DataCites findable records, to see if a DOI has been coined previously. If one of the records matches the eprint, the Claim DOI button will set the eprint’s DOI metadata field to the DOI already on DataCite.

Items with similar titles are already present on DataCite. If one matches the eprint, click "Claim DOI" to use the existing DOI rather than coining a new one.

Document DOIs

All of the above features are also available for documents uploaded to a repository. DOIs must resolve to a landing page about the record they identify, and as such these features are only available for repositories with document landing pages enabled.

In order to enable this functionality your repository must meet the following requirements:

1. Support document landing pages (see for further details)
2. Define a document field for storing newly minted DOIs and specify the name of this field in the DataCite DOI configuration
3. Have the document_dois configuration flag enabled.

The document_dois flag and field name can be configured in z_datacitedoi.pl.

# flag to indicate if this repository is able to coin dois for documents (off by default)
$c->{datacitedoi}{document_dois} = 1;

# which fields to use for the doi
$c->{datacitedoi}{eprintdoifield} = "id_number";
$c->{datacitedoi}{documentdoifield} = "id_number";

Similarly an id_number field can be defined in document_fields.pl or elsewhere in the repository configuration:

$c->{fields}->{document} = [
    {
        name => "id_number",
        type => "text",
        render_value => 'EPrints::Extras::render_possible_doi',
    },
];

The document "test.pdf" attached to this eprint can also have a DOI reserved or coined.

Document Landing Pages

The DataCite DOI plugin supports minting DOIs for documents uploaded to eprint records, however all DOIs must resolve to a landing page however and so in order to enable this your repository needs to support document landing pages. The following code snippets illustrate how to implement document landing pages in EPrints.

First we need a URL rewrite trigger to catch the URLs which should resolve to the landing page. The following needs to be added to the eprints or archives' configuration files, e.g. lib/cfg.d/doc_landing_pages.pl. We can also define a flag here for plugins to check to see if document landing pages are enabled on this repository.

# configuration flag used to check if document landing pages are enabled on this repository
$c->{doc_landing_pages_enabled} = 1;

$c->add_trigger( EP_TRIGGER_URL_REWRITE, sub
{
    my( %args ) = @_;

    my( $uri, $rc, $request ) = @args{ qw( uri return_code request ) };

    # matches https://myrepo.ac.uk/document/<doc_id>
    if( defined $uri && ($uri =~ m#^/document/(.*)$# ) )
    {
        $request->handler('perl-script');
        $request->set_handlers(PerlResponseHandler => [ 'EPrints::Apache::Document' ] );
        ${$rc} = EPrints::Const::OK;
    }

    return EP_TRIGGER_OK;

}, priority => 100 );

This trigger uses a Document handler we need to implement, e.g. perl_lib/EPrints/Apache/Document.pm

######################################################################
#
# EPrints::Apache::Document
#
######################################################################

package EPrints::Apache::Document;

use strict;

use EPrints;
use EPrints::Apache::AnApache;

sub handler
{
    my( $r ) = @_;

    my $uri = $r->uri;

    if( $uri =~ m#^/document/(.*)$# )
    {
        my $repository = $EPrints::HANDLE->current_repository;
        return DECLINED if( !defined $repository );

        # Document landing pages enabled for this repository?
        return DECLINED unless( $repository->config( "doc_landing_pages_enabled" ) );

        my $doc_id = $1;

        my $doc_ds = $repository->dataset( "document" );
        my $doc = $doc_ds->dataobj( $doc_id );

        if( defined $doc )
        {
            EPrints::ScreenProcessor->process(
                session => $repository,
                screenid => "Document",
                document => $doc,
            );
            return OK;
        }
    }

    return DECLINED;
}

1;

The handler calls on an EPrints screen to generate the content for the landing page, e.g. perl_lib/EPrints/Plugin/Screen/Document.pm

=head1 NAME

EPrints::Plugin::Screen::Document

=cut#

package EPrints::Plugin::Screen::Document;

use EPrints::Plugin::Screen;

@ISA = ( 'EPrints::Plugin::Screen' );

use strict;

sub new
{
    my( $class, %params ) = @_;

    my $self = $class->SUPER::new(%params);

    return $self;
}

sub properties_from
{
    my( $self ) = @_;

    $self->{processor}->{eprint} = $self->{processor}->{document}->get_eprint;

    $self->SUPER::properties_from;
}

sub render_title
{
    my( $self ) = @_;

    my $session = $self->{session};

    my $f = $self->{session}->make_doc_fragment;

    my $eprint = $self->{processor}->{eprint};
    my $doc = $self->{processor}->{document};

    $f->appendChild( $self->{processor}->{eprint}->render_citation( "screen" ) );

    $f->appendChild( $self->{session}->html_phrase( "document_join" ) );

    $f->appendChild( $self->{processor}->{document}->render_citation( "screen" ) );

    return $f;
}

sub render
{
    my( $self ) = @_;

    my $repo = $self->{repository};
    my $doc =  $self->{processor}->{document};

    my $page = $repo->make_doc_fragment;

    my $div = $repo->make_element( "div", class => "doc_citation" );

    $div->appendChild( $doc->render_citation( "landing_page", eprint => $self->{processor}->{eprint} ) );

    return( $div );
}

1;

And finally, the screen uses a citation file to display the document landing page content in an easily customisable fashion, e.g. lib/defaultcfg/citations/document/landing_page.xml

<?xml version="1.0" ?>

<!--
    Full "abstract page" (or splash page or summary page, depending on your jargon) for an eprint.
-->

<cite:citation xmlns="http://www.w3.org/1999/xhtml" xmlns:epc="http://eprints.org/ep3/control" xmlns:cite="http://eprints.org/ep3/citation" >

    <!-- Display the parent eprint citation -->
    <epc:print expr="$eprint.citation_link('default')" />

    <!-- Display the document details in a similar fashion to eprint summary pages -->
    <table>
        <tr>
            <td valign="top" align="right"><epc:print expr="$item.icon( 'HoverPreview', 'noNewWindow' )" /></td>
            <td valign="top">
                <epc:print expr="$item.citation('default')" /><br />
                <a href="{$item.url()}" class="ep_document_link"><epc:phrase ref="summary_page:download"/> (<epc:print expr="$item.doc_size().human_filesize()" />)</a>
            </td>
          </tr>
      </table>

</cite:citation>