DOIPluginsDocumentation

From PKP Wiki
Revision as of 09:44, 31 December 2011 by Jerico.dev (Talk | contribs)

Jump to: navigation, search

The DOI system

What are DOIs?

A "Digital Object Identifier" (DOI) is a globally unique identifier for digital objects. In the OJS context such objects are journals, journal issues, journal articles and supplementary files. DOIs are used for global and persistent identification of such objects, e.g. in citations. To this end the DOI is always associated with one or several URLs that can be resolved through a persistent URL at a global re-direction domain ([1]). Additional meta-data about certain types of digital objects can be stored in databases of specialized DOI registration agencies. This enables discovery of these objects through the web sites of the registration agencies or their partners (e.g. scientific search engines).

What are mEDRA and DataCite?

DOIs can be used for a very broad range of digital objects. The only common denominator of such objects is that they have a URL assigned through which they can be located. The DOI system therefore does not impose a single meta-data format. Digital objects can have specialized meta-data assigned that is specific to the content and format of that object. That's where DOI registration agencies like mEDRA or DataCite come in. These specialized registration agencies accept only certain types of digital objects and define mandatory and optional meta-data fields to be delivered when registering a DOI. DOI agencies require that meta-data be delivered in well-defined meta-data formats. Usually the agency defines their own meta-data format or adapt an existing standard to their purpose.

mEDRA is the multilingual European DOI Registration Agency. It registers documents of many European Union institutions but is also open to private and public institutions world-wide for registration of serial publications, serial publication issues and serial articles.

DataCite is an international not-for-profit association of several research institutions. DataCite was originally founded to make DOI registration available for primary research data. Nowadays DataCite registers a broad range of publication objects. In the OJS context these are journal issues, articles, galleys and supplementary files.

How does the DOI system work

DOIs are composed of a prefix and a suffix which are separated by a slash (e.g. "10.1234/cdb2011-01-bio234"). Organizations that want to participate in the DOI system have to apply for an account at a registration agency which will assign a unique DOI prefix to the organization (e.g. "10.1234"). The organization can then assign arbitrary suffixes to their digital objects as long as they guarantee that no suffix will be repeated (e.g. "cdb2011-01-bio234" in the above example). Sometimes several organizations share a DOI prefix to reduce the cost of DOI registration.

Once a prefix has been obtained and a suffix assigned to a publication object, the DOI composed of prefix and suffix has to be registered with the registration agency. The publishing organization formats meta-data corresponding to the publication object into the meta-data format specific to the registration agency. The resulting XML file will then be transmitted to the registration agency together with the DOI and the corresponding URL of the publication object.

The format and exact registration procedure are different for the registration agencies:

mEDRA uses a special configuration of the ONIX format called ONIX for DOI (O4DOI). This is a simplified version of the ONIX for Serials format with additional fields specific to the DOI registration use case. Detailed documentation of the format can be found on the mEDRA home page. mEDRA supports registration of OJS issues, articles and galleys but not supplementary files. mEDRA provides an asynchronous web service for automated DOI registration that is integrated into OJS. The asynchronous nature of the mEDRA registration service means that registration success or error messages are delivered via email. This means that in the unlikely case of a registration failure, some manual work is necessary to synchronize the OJS registration state with that of the mEDRA database. This is described in detail in the present document.

DataCite developed their own XML format for DOI registration that is loosely coupled to the Dublin Core format but imposes a stronger specification than the DC format. The format is relatively easy to read for non-technical users. DataCite offers a synchronous web service for automated DOI registration that is integrated into OJS. The synchronous nature of the DataCite registration service means that the OJS registration state can easily be kept in sync with the DataCite database. Other than in the case of mEDRA, manual synchronization of the registration state in OJS is therefore not necessary.

OJS' implementation of the O4DOI and DataCite formats has been optimized for maximum information transfer and data quality. OJS has co-operated directly with both registration agencies to make sure that their formats and protocols are correctly implemented and that the agencies can make best use of OJS data.

DOI registration in OJS

DOI support in OJS

OJS implements mEDRA and DataCite connectors as system plug-ins in the "Import/Export" plug-in category. These plug-ins rely on OJS' generic "DOI plug-in" which provides the user interface for DOI administration and assignment to publication objects.

Configuration of the DOI plug-in

Configuration of the DOI plug-in is a task to be performed by the Journal Manager. The DOI plug-in's setting page can be found by navigating to the Journal Manager's user home page -> System Plugins -> Generic Plugins -> DOI plug-in -> Settings:

DOI configuration.png

First select the OJS object types that you want DOIs to be assigned to. Selecting this option does not mean that all objects of the selected type need to get a DOI assigned. Depending on the chosen DOI suffix generation method you can selectively assign DOIs if you like. Selecting an object type makes the DOI configuration fields available on the corresponding object-specific meta-data entry pages. Please be aware that not all registration agencies support all object types for DOI registration. While DataCite is able to support all object types, mEDRA will not register supplementary files.

The DOI prefix is mandatory. As described above you'll receive your organization's prefix from the DOI registration agency. The exact process for application is described on the agencies' web pages.

There are several suffix generation strategies available:

When you choose one of the pattern-based generation methods then a DOI will be generated for all objects. You are not obliged to register all these DOIs with the registration agencies, though. The DOI registration agency connectors allow for selective registration.

When you enter custom patterns then it is your responsibility to create patterns that result in unique DOI suffixes for your prefix. You have to enter a combination of journal, issue and object-specific identifiers to make sure that DOIs cannot be duplicated. A galley-suffix for example, that does not contain the journal ID can be duplicated among several journals if the same prefix is used for those journals. The same can happen if you generate DOIs for articles and issues without using the issue ID in the article suffix (e.g. when generating the DOI for the issue with the internal ID 1 and the article with internal ID 1). Look at the standard patterns for examples.

If you use custom identifiers (custom URL suffixes) to improve your URLs (see journal configuration step 4) you can use those same identifiers as DOI suffixes. Again you are responsible to not assign the same custom identifier to several objects. This is also true across object categories: You cannot assign the same URL suffix to articles and corresponding galleys for example. While this would still result in unique URLs due to the differing OJS URL prefix per object type it would mean duplicated DOI suffixes as the DOI prefix is common to all object types. OJS will check uniqueness of URL suffixes when you enter suffixes and will present you with a form error when you try to enter the same suffix twice.

Choosing the individual DOI suffix option will allow you to enter suffixes completely independent from the OJS URL of the object. Use this option if none of the other suffix generation strategies fulfill your needs, e.g. when your organization has global rules for suffix generation different from what can be implemented with custom patterns.

The "Reassign DOIs" button deletes all currently assigned DOIs but not your individually assigned URL or DOI suffixes. This is an advanced action. Please use it with utmost care and make sure you understand its exact action first, e.g. within a test environment. All DOIs will be re-generated based on the patterns or custom identifiers you entered. This means that if you change the patterns or custom identifiers after you already assigned DOIs then previously assigned DOIs will be completely lost and the same object will receive a different DOI. This should be avoided in most cases as it means double-registration of the same object with two different DOIs which is contrary to the purpose of DOIs in the first place. In any case you should make a database backup before you delete all assigned DOIs.

Installation

All plug-ins necessary for DOI assignment and registration with mEDRA and DataCite are part of the default OJS installation and do not have to be installed separately.

Some features of the mEDRA and DataCite connectors have additional installation requirements, though:

  • If you want to register DOIs directly with the mEDRA or DataCite registration agencies via their web services then you need the PHP curl extension installed. Please consult the PHP manual for details.
  • If you want to export several objects at the same time into files you'll need the tar tool available on your system. You'll also have to configure the path to the tar binary in your config.inc.php file, see the file's inline documentation.

Export vs. Registration

Before using the DOI connectors for the first time you'll have to decide whether you want to use the plug-in in "manual export" or "automatic registration" mode. This depends above all on your relation with the registration agency.

If you have (or intend to have) your own account at the registration agency then automatic registration will most probably be your preferred choice. Automatic registration means that you do not have to export meta-data into the registration agency's XML format or upload files to the registration agency manually. You can register DOIs and meta-data directly from within OJS with a few mouse clicks.

If you do not have access to account credentials yourself then you'll have to export XML files for the objects to be registered. The XML can then be sent to the account owner (e.g. as an email attachment) who'll have to upload the files to the agency's registration site. This is still much better than sending unformatted meta-data by email. The OJS-implementation of the XML format has been explicitly certified by the registration agencies for maximum information content, standardization and data quality. Manual transfer errors can be avoided and the account owner will have much less work in uploading a ready-made XML rather than manually entering meta-data on the agency's site or composing a compliant XML message from scratch.

While, in principle, it is possible to mix both modes of operation, you should not usually do so. If, for example, you configure the DOI connectors for automatic registration and then upload a file manually to the registration agency you'll end up in a situation where the OJS registration database is out of sync with the registration agencies' database. This can lead to registration errors when trying to update meta-data of an object that has been registered manually before. This is especially important when you work with mEDRA as the mEDRA XML format (O4DOI) differs for initial registration and meta-data update.

It is unproblematic, though, to use the XML export feature for local inspection of XML data that will be transferred to the registration agency via OJS later. As long as the actual registration is done in OJS, the local and remote registration databases will not get out of sync.

Basic Configuration

Enable and configure the DOI plug-in

Configure the DOI connector (mEDRA only)

Manual Registration

Export XML

Send or Upload the XML file

Automatic Registration

Apply for your mEDRA/DataCite account

Configure your account credentials

Register new DOIs

Update DOI meta-data

Reset DOI state (mEDRA only)