Difference between revisions of "DOIPluginsDocumentation"

From PKP Wiki
Jump to: navigation, search
(Assigning DOIs)
(DOI Registration: Introduction)
Line 96: Line 96:
  
 
= DOI Registration =
 
= DOI Registration =
 +
Even when a DOI has been assigned to an object in OJS it is not automatically known to the registration agency and the corresponding URL at http://dx.doi.org/ will not yet be resolved. You'll have to register the DOI with one of the DOI registration agencies before. At the time of writing OJS supports registration with CrossRef, mEDRA and DataCite out-of-the-box. This documentation describes the mEDRA and DataCite options.
 +
 
== Export vs. Registration ==
 
== Export vs. Registration ==
Before registering DOI for the first time with mEDRA or DataCite you'll have to decide whether you want to use the registration connectors in "manual export" or "automatic registration" mode. This depends above all on your relation with the registration agency.
+
Before registering DOIs for the first time with mEDRA or DataCite you'll have to decide whether you want to use the registration connector 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 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.

Revision as of 09:56, 2 January 2012

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.

Installation Requirements

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.

Read the "Export vs. Registration" paragraph below if you're unsure what features you'll need.

Assigning DOIs to Publication Objects

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.

When are DOIs being assigned? (Important - Please Read!)

It is important that you understand when DOIs will be assigned because DOI assignment is irreversible. Once an article or issue is published there is no way from impeding automatic DOI assignment to the corresponding objects (issues, articles, galleys and supplementary files). This is due to the nature of permanent IDs: They are meant to be assigned once and only once and then never change again. This means that as soon as any public user got the chance to access a DOI it may never be changed after.

The DOI of the object is generated automatically during the first public access to the object. Public access to a publication object is assumed whenever the object is viewed for the first time on the public web site of the journal or whenever the object was exported to a file format that contains and supports DOIs (e.g. PubMed format, native OJS export format, CrossRef, DataCite, mEDRA formats, etc.).

The assignment logic is slightly different for the different suffix generation strategies:

  • In case of pattern based suffix generation (custom or default patterns) DOIs will always be generated according to the currently configured pattern on first public access. This also means that changing a pattern will not change already assigned DOIs. It will only have effect on DOIs being generated from that moment on. Be careful when changing patterns that the new pattern does not share its namespace with the previous pattern. Otherwise duplicate DOIs may result which will lead to problems when trying to register these IDs.
  • In case of DOI suffixes being generated from custom IDs / URL suffixes the DOI will also always be generated on first public access. If no custom ID / URL suffix has been entered for the object then a DOI will be generated based on the default OJS URL suffix. This DOI will not change even if you enter a URL suffix later. There is no way to change your DOI once it has been assigned so be sure to enter a URL suffix before you publicly access an object for the first time!
  • If you configured OJS to use individual DOI suffixes then the logic is slightly different to support selective DOI assignment. In this case a DOI will not be assigned even for already published objects if a DOI suffix has not been entered for that object. This allows the journal to offer DOIs to the authors as an optional (and potentially paid) service on a one-by-one basis. The individual suffix can be changed as long as no DOI has been assigned by public access to the object. Once the object has been accessed publicly with an individual suffix assigned, the suffix cannot be changed any more!

Whatever suffix generation strategy you choose, you'll be able to preview the DOI on the object's meta-data page without actually assigning a DOI provided that the object has not yet been published. The meta-data pages for the different object types are:

  • Issues: The issue data page that can be reached through the issue lists available to the editor role.
  • Articles: The article meta-data page available through the article's summary page available to all editorial roles.
  • Galleys and Supplementary Files: The galley meta-data page available through the corresponding article's "Editing" page. Click on the "Edit" link corresponding to the file in the "Layout" section of the page.

These pages will be referred to as "meta-data pages" throughout this documentation.

Pattern-Based DOI Generation

Once you configured the pattern for DOI suffix generation in the DOI plug-in you'll not have to do anything special for an object to get a DOI assigned. As soon as the object is published and has been accessed publicly for the first time a DOI will be assigned based on the corresponding pattern.

Custom ID / URL suffix

Please don't forget to enable "custom IDs" for the objects you want to assign DOIs to in journal setup step 4 when you chose this suffix generation method in the DOI plug-in. Otherwise you'll not be able to enter custom URL suffixes for the different object types.

Once you correctly configured OJS to generate DOIs based on custom IDs / URL suffixes and you enabled the custom ID option for the objects you'll see URL entry fields on the meta-data pages of issues, galleys and supplementary files. URL suffixes for articles can NOT be entered on the article meta-data page but must be entered into the issue "table of content". Please select the issue from the editor's issues lists and select the issues "Table of Contents" page. If you correctly configured OJS then you'll find a URL entry field for every article there.

Individual DOI suffixes

As long as no DOI has been assigned to the object (see "When are DOIs being assigned?" above), you'll find a DOI suffix entry field on the objects meta-data page.

See the following example of the DOI suffix field for issues:

DOI assignment - issue.png

You can change this field as long as no DOI has been assigned to the object. Leaving the field empty or deleting its contents and saving the form means that the object will not get a DOI assigned, even if it is publicly accessed.

DOI Registration

Even when a DOI has been assigned to an object in OJS it is not automatically known to the registration agency and the corresponding URL at http://dx.doi.org/ will not yet be resolved. You'll have to register the DOI with one of the DOI registration agencies before. At the time of writing OJS supports registration with CrossRef, mEDRA and DataCite out-of-the-box. This documentation describes the mEDRA and DataCite options.

Export vs. Registration

Before registering DOIs for the first time with mEDRA or DataCite you'll have to decide whether you want to use the registration connector 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 (mEDRA only)

If you want to register DOIs with mEDRA then you'll have to do some basic configuration independent of the chosen export mode (manual vs. automatic, see previous paragraph). As a Journal Manager you find the configuration page by navigating from your home page to "Import/Export Data->mEDRA Export/Registration Plugin" and then click the "configure" link.

You should see the following form fields:

MEDRA basic config.png

Please enter the institution that registered the DOI prefix you are using. This is your own institution if you have an account with the registration agency yourself (automatic registration mode) or the institution of the registration account owner you are sending your XML files to (manual export mode).

The three technical contact fields should contain your own contact information. If you are the registration agency account holder then you'll repeat your institution's name here.

The email field is of special importance: mEDRA will send registration reports to the email address you enter here. These emails are important because they are the most convenient way for you to be informed whether your registration was successful or not. Every file uploaded to mEDRA (manually or via OJS automatic registration) will result in a corresponding email. The email you enter here should belong to a person with Journal Manager rights so that the person is able to correct export errors and re-export corrected registration data.

The mEDRA format requires a "country of publication" which cannot be unambiguously deduced from the OJS configuration. According to the O4DOI specification this is "the country where the serial work is published".

If you assign DOIs to journal issues then you'll have to decide whether you want to export issues as "work" or "manifestation". Please follow the links on the configuration page for an explanation of the distinction. If you do not assign DOIs to journal issues then you can leave the default configuration untouched.

Manual Export

Export XML

Send or Upload the XML file

Automatic Registration

Apply for your mEDRA/DataCite account

Configure your account credentials

Check Export Format (Optional, Advanced Users Only)

Register new DOIs

Update DOI meta-data

Reset DOI state (mEDRA only)