Difference between revisions of "DOIPluginsDocumentation"
|Line 49:||Line 49:|
== Installation ==
== Installation ==
== Export vs. Registration ==
== Export vs. Registration ==
== Basic Configuration ==
== Basic Configuration ==
Revision as of 09:20, 31 December 2011
- 1 The DOI system
- 2 DOI registration in OJS
- 2.1 DOI support in OJS
- 2.2 Installation
- 2.3 Export vs. Registration
- 2.4 Basic Configuration
- 2.5 Manual Registration
- 2.6 Automatic Registration
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 (). 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:
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.
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.