Difference between revisions of "DOIPluginsDocumentation"

From PKP Wiki
Jump to: navigation, search
m (clarification)
m (typo)
Line 178: Line 178:
That's all. Most users will probably be able to do all their DOI registration like this. If you do not intend to update meta-data after registration then this is all you'll ever do.
That's all. Most users will probably be able to do all their DOI registration like this. If you do not intend to update meta-data after registration then this is all you'll ever do.
If you want to register specific objects selectively than you can do so in any of the lists you can access through the connector's home page. You can either register objects by clicking on their corresponding "Register" link or by checking several objects manually and clicking the "Register" button at the bottom of the list.
If you want to register specific objects selectively then you can do so in any of the lists you can access through the connector's home page. You can either register objects by clicking on their corresponding "Register" link or by checking several objects manually and clicking the "Register" button at the bottom of the list.
Objects that have been registered will disappear from the "Export all unregistered..." list.
Objects that have been registered will disappear from the "Export all unregistered..." list.

Revision as of 13:10, 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 (http://dx.doi.org/some-doi). 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. In OJS language these are journal issues, articles and galleys.

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. 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, see "Reset DOI registration state" below.

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 content 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 your 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. There you should see something like:

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, see "When are DOIs being assigned?" below. 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 independently 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, or if you do not want to generate DOIs for all objects by default.

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 publicly accessed for the first time a DOI will be assigned based on the corresponding pattern.

Custom ID / URL suffix

Once you correctly configured OJS to generate DOIs based on custom IDs / URL suffixes and you enabled the custom ID option in journal setup step 4 for the same object types 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's "table of content". If you correctly configured OJS then you'll find a URL entry field for every article there.

NB: If you forget to enable "custom IDs" for the objects you want to assign DOIs to in journal setup step 4 then you'll not be able to enter DOI suffixes and you DOI suffixes will be generated based on the OJS default URL suffix.

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 object's meta-data page. See "When are DOIs being assigned?" for a list of these meta-data pages.

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 with mEDRA or DataCite for the first time 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

This paragraph is only relevant if you decided to use the mEDRA/DataCite connector in "manual export" mode. If you want to use the connector in "automatic registration mode" you can jump directly to the "Automatic Registration" paragraph below.

If you want to export mEDRA/DataCite XML manually then you do not have to configure a username or password on the connector's configuration page. Leaving the username/password fields empty will disable automatic registration in the connector's user interface. This means that you'll see no "Register", "Update" or "Reset" buttons, just an "Export" button for all objects.

Export XML

As a Journal Manager navigate to the plug-ins home page:

  • For mEDRA export: Import/Export Data -> mEDRA Export/Registration Plugin
  • For DataCite export: Import/Export Data -> DataCite Export/Registration Plugin

If you work in manual export mode then you can probably ignore the "Export all unregistered ..." link. OJS cannot maintain any registration information in manual export mode so all objects will appear "unregistered" which means that the list of unregistered objects is very long and of no real use.

To register an object manually navigate to the corresponding object list from the connector's home page and find the object there. If you already know one of OJS' export plug-ins then these lists will be familiar to you. They work exactly the same way as for other export plug-ins.

To generate the export file for a single object you can click the "Export" button behind the object. To export several objects at once you can check the objects to be exported and click the "Export" button to the bottom of the page. Please be aware that exporting several objects at once may require you to install and configure the "tar" utility on your OJS server. Please see the "Installation requirements" paragraph above. You may also have to install a tar extraction utility on your local computer if you want to view the generated files before sending them to the registration agency account holder or the registration agency itself.

As soon as you click the "Export" button, the generated XML file or tar archive should trigger your browser's usual download mechanism. Please save the file to your disk where you can find it later for sending or inspection.

Send or Upload the XML file

Once you generated the XML or tar file you can attach it to an email and send it to the registration agency account holder or upload it manually on the registration agency's home page. Please check with the account holder / registration agency how this works in detail. If you send the file to an account holder then please make sure that they upload the XML unchanged. The OJS DOI export formats have been accredited by the registration agencies and are optimized for best data quality and information content.

Automatic Registration

This paragraph is only relevant if you decided to register DOIs directly from within OJS. Access to an account with the registration agency is required.

Apply for your mEDRA/DataCite account

As a Journal Manager please navigate to the agency's connector home page:

  • For mEDRA: Import/Export Data -> mEDRA Export/Registration Plugin
  • For DataCite: Import/Export Data -> DataCite Export/Registration Plugin

There you'll find a short introductory notice about how to apply for your own registration account. Please follow the instructions and links there.

Configure your account credentials

Once you received your username and password from the registration agency you'll have to follow the "configure" link on the connector's home page. You can enter your credentials there. The user interface elements required for automatic registration will only appear after you have configured your credentials. If you do not see the "Register", "Update" or "Reset" buttons mentioned in the following paragraphs then please double-check the configuration page.

Check Export Format (Optional, Advanced Users Only)

Most users can skip this paragraph and jump directly to the next one. If, however, you are an advanced user who knows the O4DOI or DataCite formats and you want to check what exactly is being exported to the registration agency then you can have a look at the generated XML before you register it.

To do so go to the connector's home page and select one of the lists with exportable objects. When you click the "Export" button for a single object or you select a number of objects and click the "Export" button at the end of the list then you can download the XML format exactly as it will be exported to the registration agency. If you select more than one object at a time you might have to install the "tar" utility on your OJS server and a tar extraction utility on your local computer, see "Installation Requirements" above for details.

Exporting the file will not change the object's registration state. You can look at the XML at any time. In the case of the "mEDRA" connector you'll see the "registration" notification format when the object has not been registered before. After the first registration you'll see the "update" notification format. In the case of the "DataCite" connector the "registration" and "update" formats are the same.

Register new DOIs

The fast track for automatic registration is:

  • Open the "Export all unregistered ..." link on the connector's home page,
  • check the list of unregistered objects and make sure that all objects have been selected by default,
  • click the "Register" button at the bottom of the list and
  • wait for the "Registration Successful!" message.

That's all. Most users will probably be able to do all their DOI registration like this. If you do not intend to update meta-data after registration then this is all you'll ever do.

If you want to register specific objects selectively then you can do so in any of the lists you can access through the connector's home page. You can either register objects by clicking on their corresponding "Register" link or by checking several objects manually and clicking the "Register" button at the bottom of the list.

Objects that have been registered will disappear from the "Export all unregistered..." list.

Update DOI meta-data

This paragraph describes how you update the meta-data for an existing DOI, not how you assign a new DOI to an already existing object. OJS does not currently support changing the DOI for an already registered object. Assigning a new DOI is only recommended when the content of the corresponding object changed considerably. In the case of OJS this probably triggers another round of internal or external review, layout, proofreading or other editorial tasks. Therefore, if you want to re-register a publication object with a different DOI then you'll have to create a new issue, article, galley or supplementary file and register it as a new object.

Once you registered an object for the first time, it disappears from the list of unregistered objects of the registration agency connector. It will, however, continue to be listed on the object-specific pages. The button corresponding to the object will have changed to "Update" rather than "Register". This is how you can recognize objects that OJS considers "registered". Clicking the "Update" button will update the meta-data of the object in the registration agency's database corresponding to the meta-data saved in OJS. This means that changes in OJS meta-data will not be transferred to the registration agency automatically.

NB: In the case of mEDRA it may happen that an object appears as "registered" in OJS although you received an error message via email after clicking the "Register" button for the first time. This is due to the asynchronous nature of the mEDRA registration service: Successful upload of a mEDRA meta-data file does not always mean acceptance of that file into the mEDRA database. Please do NOT click the "Update" button to recover from an error after first registration. Follow the directions in "Reset DOI state" below, instead. You can use the "Update" button to recover from a failed update, though. Please correct the error condition described in the email you received from the mEDRA registration service and then click the "Update" button for the failed object again. If you use the DataCite connector then OJS registration state should always correspond 100% to the real registration state as long as you do not mix automatic and manual registration.

Reset DOI registration state (mEDRA only)

In the case of mEDRA the registration state of an object in OJS can become out of sync with the real registration state in the mEDRA database. This happens when mEDRA acknowledges a successful upload first but later rejects the file due to error conditions not being checked during upload. The mEDRA XML format for first registration differs from the XML format for update. Therefore, you cannot use the "Update" button to recover from the error as it will just lead to another failed upload. This is what the "Reset" button is meant for. It appears for all objects that have already been registered. Clicking it removes all registration information for the object from the OJS database such that the object appears to OJS as if it had never been registered before.

Of course you should not click the "Reset" button if the object was successfully registered as it will then delete valid registration information. If you happen to click the "Reset" button by accident then you'll have to re-register the object which will lead to an error message from mEDRA (which you can safely ignore in that case) but will correct the registration state in OJS.

NB: Do not use the "Reset" button to recover from update errors! If you receive an error message via email after clicking the "Update" button then just click the "Update" button again after correcting the problems mentioned in the mEDRA error message.