Submission System Workflow

This page describes how content is transferred between the various curation stages, and how it eventually ends up in the "archived" state or is returned to the submitter's workspace. In DSpace terms, this page corresponds to the "Workflow" system.

Overview
As a data package and its associated files are processed, they travel through the workflow system. The data package always "contains" the files and they always travel together. The stages available are:
 * User workspace: Stage where a user creates an initial data package. Items return to this stage when the user creates a new version of an item, when the curator returns the submission for further editing, or when the associated article is rejected by the journal. For details, see Submission System Technology.
 * Journal review: Stage where package stays while an article is being reviewed. While a package is in this stage, it may be viewed by journal editors and/or peer reviewers using the review key.
 * Primary curation: Stage where a package is reviewed by Dryad curators. Within this stage, a package may be sitting in the "pool" waiting for a curator, or it may be "claimed" by a particular curator.
 * Publication blackout: Stage where a curator-approved package stays until the associated article is published.
 * Archived: Stage where a package is "published" and available to the public. Although the package itself is public, it may contain data files that are under embargo.

Usage
The workflow is a configuration of the underlying DSpace workflow system. Most interaction with the workflow system is performed via the GUI. In some stages, command-line tools are available to perform certain tasks (see details below). In extreme cases, the status of items may be manipulated directly in the Dryad database. See Workflow State in Database.

Overview of the Workflow System
The workflow consists of several stages. At each stage, certain activities may be performed (curation of metadata, peer review, etc.), or the data may be moved to another stage. When an item travels between stages, email messages may be generated. The workflow diagram badly needs to be updated, but it gives a general overview of the process:



Workflow Stages
For more information on how these stages are stored in the Dryad database, see Workflow State in Database.

Submitter Workspace
When a submitter creates a data package in their workspace, the first step of the Submission System determines if the submissions needs to go to the journal review stage or go to the primary curation stage. This determination is based on the Article_Status field in the metadata file for the manuscript. If Article_Status is "In Review", the package will go to journal review. Otherwise, it will go to primary curation.

Requires review (requiresReviewStep)
This stage is automated -- there is no interaction. This stage determines if the submissions needs to go to journal review or to primary curation.

A submission is directed to journal review if the article metadata has "Article_Status" set to "In Review".

This stage doesn’t send out any emails.

Journal Review (reviewStep)
In the review stage the original submitter as well as the people in the “Curators” group are granted read rights on the submission and its bitstreams.

The journal review process is set up by the DryadReviewAction class. In this class:
 * 1) a token is generated that will be used for secure access to the data package
 * 2) the token is stored in the package's metadata
 * 3) an email is sent (template: submit_datapackage_review) to alert curators, reviewers, and the submitter about the existence of the review token (e.g. http://datadryad.org/review?wfID=0000&token=abcd-efgh-ihjk-mnop)

Alternatively, reviewers may access items in review by the Data Package DOI (e.g. http://datadryad.org/review?doi=doi:10.5061/dryad.00000)

As long as the submission is in this stage the submitter may add as many data files as he sees fit, but he may not alter the submission in any other way. The restriction on edits allows the various reviewers time to all review the same information without the information being changed during the review process.

Moving items out of Journal Review
For approving/rejecting items which are in the review stage the following command can be used: ./{dspace.dir}/bin/dspace review-item -i workflow-id -a approval-status This class requires 2 parameters. The first parameter indicates the item, and can take one of two forms:
 * -i the id of the workflow item (workflow_item_id, NOT item_id)
 * -m the manuscript number associated with the item
 * WARNING: The manuscript number must be prepended with the journal's abbreviation and a hypen, like "SystBiol-1234"
 * WARNING: As of 2012-1-5, there appears to be a problem in looking up items by the manuscript number. This should be fixed in the 1.11 release.

The second parameter indicates the status of the item:
 * -a whether or not the item has been approved ("true" or "false")

This command calls org.dspace.workflow.ApproveRejectReviewItem.

Primary Curation (dryadAcceptEditReject)
While a package is in primary curation, the Dryad curators may review and modify the contents of the package.

When a package enters this stage, the submit_datapackage_task email template is sent.

Items in this stage can either be "claimed" by a particular curator, or they can be waiting in the "pool" for a curator to claim. A curator may only edit items that they have claimed.

Once curation has completed, the curators have three options:
 * 1) "reject" the data package -- it will be sent back to the user workspace, and the submit_datapackage_reject email will be sent
 * 2) "approve" the data package -- it will be sent to the archived stage
 * 3) "approve with blackout" -- it will be sent through the publication blackout steps (see ).

Either "approve" or "approve with blackout" will be highlighted based on the journal's integration settings

Publication Blackout
The purpose of the publication blackout stage is to hold items for which the journal does not want metadata to appear in the wild before the article is published. Items in blackout can only be viewed/edited by curators.

As of October 4, 2013, Publication Blackout is implemented as an alternate set of steps/actions after primary curation, based on the action the curator chooses. These steps affect the visibility of the items metadata in its DOI registration.

Publication Blackout settings default are configured in the DryadJournalSubmission.properties file, but at Primary Curation (dryadAcceptEditReject), curators have the option to send an item to blackout, or send it directly to the archive.

If the journal is not integrated, or if the journal is integrated and publicationBlackout=true the publicationBlackout setting is true, the Primary Curation UI will suggest the publication blackout option and indicate why.

When a curator chooses Archive, the item is not sent through the publication blackout steps. It passes through the final payment steps and actions and is archived.

When a curator chooses publication blackout, the item passes through the same payment actions as if they had chosen archive. The actions reauthorize payment if necessary. These actions are documented in the [payment system]. Publication blackout uses alternate Payment steps to drive these actions, but the only difference is that the items are routed to registerPendingPublicationStep at the end of the payment check.



dryadAcceptEditRejectAction (EditMetadataAction.java)
When archive is selected, this action adds provenance metadata to the data package to indicate that it was approved for entry into the archive. The action returns OUTCOME_COMPLETE (0) to indicate the step is complete. At this point, the workflow routes the item to finalPaymentStep and it will be archived after payment is checked.

When blackout is selected, this action adds provenance metadata to the item and its data files to indicate that it has entered publication blackout. The action returns OUTCOME_BLACKOUT (1) to indicate that the item should follow the blackout payment steps.

registerPendingPublicationStep
This step has no user actions and immediately invokes the registerPendingPublicationAction on the item.

registerPendingPublicationAction
The DOI for the item is registered with dummy values (:tba) and a a destination of http://datadryad.org/publicationBlackout. This way, we register the DOI early and ensure that once the publication is live, visiting the DOI will not yield a 404. DOIs are registered for the data package as well as the files.

After registering the DOI, the item is sent to pendingPublicationStep

pendingPublicationStep
After registration, items are parked in pendingPublicationStep. This step is simply a holding area for items in blackout. When the associated article has been published, the curator will claim it from this step, and perform the afterPublicationAction

afterPublicationAction
This action has a simple UI explaining that the item is in publication blackout, and the curator has the singular option to move the item from publication blackout to the archive. When the curator invokes the action, provenance metadata is added to indicate the item was approved for entry to the archive, and full metadata is registered for the DOI. The URL is updated to the item's doi resource page.

Pending deletion (pendingDeletion)
NOTE: This stage may be inactivated.... need to check if it is still used, or if items are just going back to the user workspace.

A submission will come here if it has been rejected by the review stage.

This step will send out no emails to anybody. However the submitter will be able to view when the submission will be completely deleted on the submission page.

When the submission is in this stage for one month it will be completely removed from the system.

This is checked by the “org.dspace.workflow.CheckPendingDeletions” class which requires no parameters to run, and should be run on a daily basis.

Email Templates
Email sent from the submission system uses templates from dryad/dspace/config/emails. The following templates are currently used:
 * submit_datapackage_confirm:
 * triggered when: a data package moves from the submission stage into the workflow system
 * sent to: submitter
 * template must contain: package title, datafile titles, package DOI
 * submit_datapackage_review:
 * sent to: submitter, Curators group, email list from the journals's notifyOnReview in DryadJournalSubmission.properties
 * Triggered when a data package enters the review stage
 * submit_article_approve:
 * (doesn't currently exist???? or is the code using a different template now???)
 * triggered when: a data package moves from the journal review stage into primary curation
 * sent to: submitter
 * submit_article_reject:
 * triggered when: a data package moves from the review stage back to the submitters workspace.
 * sent to: submitter
 * submit_datapackage_task:
 * triggered when: a data package moves into the primary curation
 * sent to: Curators group
 * submit_datapackage_reject:
 * triggered when: in the primary curation stage, a curator decides to return the submission to the submitter -- this may be due to serious problems with the submission, or it may be at the request of the submitter, so we keep the language in the template very neutral
 * sent to: submitter
 * submit_datapackage_archive:
 * triggered when: in the primary curation stage, a curator approves the submission
 * sent to: submitter, email list from the journals's notifyOnArchive in DryadJournalSubmission.properties

Configuration

 * config/workflow.xml contains the steps and the relationships between them
 * config/workflow-actions.xml maps workflow actions to Java classes that process the actions
 * config/workflow-actions-xmlui.xml maps workflow actions to Java classes that render the appropriate submission system pages

For more detail, see the DSpace Configurable Reviewer Workflow documentation.

Relation to DSpace
The workflow system is built on top of DSpace's Configurable Reviewer Workflow.