hazza/DSpace
1
0
Fork 0
mirror of https://github.com/DSpace/DSpace.git synced 2025-10-10 03:23:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

[DS-2058] Clarify doc commentary.

Browse Source
This commit is contained in:
Mark H. Wood
2021-05-11 17:48:52 -04:00
parent 88966a34e2
commit 37668dccc8
7 changed files with 114 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
dspace-api/src/main/java/org/dspace/workflow/FlowStep.java
View File

@@ -12,7 +12,7 @@ import java.util.List;
import javax.validation.constraints.NotNull; import javax.validation.constraints.NotNull;
/** /**
* A workflow step. * Linkage between a workflow step and some {@link org.dspace.curate.CurationTask}s.
*/ */
public class FlowStep { public class FlowStep {
public final String step; public final String step;
@@ -20,10 +20,14 @@ public class FlowStep {
public final List<Task> tasks = new ArrayList<>(); public final List<Task> tasks = new ArrayList<>();
/** /**
* Create a workflow step. * Create a set of curation tasks to be linked to a named workflow step.
* If the name of a curation task queue is supplied, the tasks will be queued;
* otherwise they will execute as the workflow item is passing through the
* linked workflow step.
* *
* @param name name of the step. * @param name name of the workflow step.
* @param queue name of the step's associated queue (if any). * @param queue name of the associated curation queue in which tasks will run,
* or {@code null} if these tasks should execute immediately.
*/ */
public FlowStep(@NotNull String name, String queue) { public FlowStep(@NotNull String name, String queue) {
this.step = name; this.step = name;
@@ -31,8 +35,8 @@ public class FlowStep {
} }
/** /**
* Associate a task with this step. * Associate a curation task with the linked workflow step.
* @param task a task to be applied in this step. * @param task a curation task configuration to be applied in this step.
*/ */
public void addTask(@NotNull Task task) { public void addTask(@NotNull Task task) {
tasks.add(task); tasks.add(task);

35
dspace-api/src/main/java/org/dspace/workflow/Task.java
View File

@@ -14,7 +14,16 @@ import java.util.Map;
import javax.validation.constraints.NotNull; import javax.validation.constraints.NotNull;
/** /**
* A workflow task. * An association between a {@link org.dspace.curate.CurationTask curation task}
* and the workflow system. A single curation task may be associated with more
* than one workflow, and each association may be configured differently.
*
* <p>A curation task can be given {@link addPower "powers"} to affect the
* progress of a workflow. For example, a curation task can cause a workflow
* item to be rejected if it fails.
*
* <p>A curation task can be associated with {@link addContact "contacts"}
* (email addresses) to be notified when the curation task returns a given status.
*/ */
public class Task { public class Task {
public final String name; public final String name;
@@ -22,26 +31,29 @@ public class Task {
public final Map<String, List<String>> contacts = new HashMap<>(); public final Map<String, List<String>> contacts = new HashMap<>();
/** /**
* Create a task with a given name. * Create an instance of an association with a given curation task.
* @param name the task's name. * @param name the name of a curation task to be attached to some workflow.
*/ */
public Task(@NotNull String name) { public Task(@NotNull String name) {
this.name = name; this.name = name;
} }
/** /**
* Add a task power to this task. * Empower this attachment to affect a workflow in some way.
* @param power the given power. TODO should use schema-generated {@code enum}? * @param power the given power. See {@link org.dspace.curate.XmlWorkflowCuratorServiceImpl#curate}.
* TODO should use schema-generated {@code enum}?
*/ */
public void addPower(@NotNull String power) { public void addPower(@NotNull String power) {
powers.add(power); powers.add(power);
} }
/** /**
* Associate a contact with a given status. * Associate a contact with a given curation status such as
* {@link org.dspace.curate.Curator#CURATE_ERROR}.
* *
* @param status the given status. TODO should use schema-generated {@code enum}? * @param status an exit status of the curation task.
* @param contact the associated contact. * TODO should use schema-generated {@code enum}?
* @param contact an address to be notified of this status.
*/ */
public void addContact(@NotNull String status, @NotNull String contact) { public void addContact(@NotNull String status, @NotNull String contact) {
List<String> sContacts = contacts.get(status); List<String> sContacts = contacts.get(status);
@@ -53,8 +65,11 @@ public class Task {
} }
/** /**
* Get the collection of contacts for a given status. * Get the collection of contacts for a given status such as
* @param status the given status. TODO should use schema-generated {@code enum}? * {@link org.dspace.curate.Curator#CURATE_SUCCESS}.
*
* @param status the given status.
* TODO should use schema-generated {@code enum}?
* @return contacts associated with this status. * @return contacts associated with this status.
*/ */
@NotNull @NotNull

5
dspace-api/src/main/java/org/dspace/workflow/TaskSet.java
View File

@@ -11,14 +11,15 @@ import java.util.List;
import javax.validation.constraints.NotNull; import javax.validation.constraints.NotNull;
/** /**
* A collection of workflow tasks. * A collection of {@link org.dspace.curate.CurationTask curation tasks} to be
* attached to a workflow.
*/ */
public class TaskSet { public class TaskSet {
public final String name; public final String name;
public final List<FlowStep> steps; public final List<FlowStep> steps;
/** /**
* Create a TaskSet. * Create a name for a collection of {@link FlowStep}s.
* *
* @param name name of this task set. * @param name name of this task set.
* @param steps workflow steps in this task set. * @param steps workflow steps in this task set.

20
dspace-api/src/main/java/org/dspace/workflow/package-info.java Normal file
View File

@@ -0,0 +1,20 @@
/**
* DSpace has a simple workflow system, which models the workflows
* as named steps: SUBMIT, arbitrary named steps that you define, and ARCHIVE.
* When an item is submitted to DSpace, it is in the SUBMIT state. If there
* are no intermediate states defined, then it proceeds directly to ARCHIVE and
* is put into the main DSpace archive.
*
* <p>
* EPerson groups may be assigned to the intermediate steps, where they are
* expected to act on the item at those steps. For example, if a Collection's
* owners desire a review step, they would create a Group of reviewers, and
* assign that Group to a step having a review action. The members of that
* step's Group will receive emails asking them to review the submission, and
* will need to perform an action on the item before it can be rejected
* back to the submitter or advanced to the next step.
*
* @author dstuve
*/
package org.dspace.workflow;

41
dspace-api/src/main/java/org/dspace/workflow/package.html
View File

@@ -1,41 +0,0 @@
<!--
The contents of this file are subject to the license and copyright
detailed in the LICENSE and NOTICE files at the root of the source
tree and available online at
http://www.dspace.org/license/
-->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!--
Author: dstuve
Version: $Id$
Date: $Date$
-->
</head>
<body bgcolor="white">
<p>DSpace's workflow system</p>
<p>
DSpace has a simple workflow system, which models the workflows
as 5 steps: SUBMIT, three intermediate steps (STEP1, STEP2, STEP3), and ARCHIVE.
When an item is submitted to DSpace, it is in the SUBMIT state. If there
are no intermediate states defined, then it proceeds directly to ARCHIVE and
is put into the main DSpace archive.
</p>
<p>
EPerson groups may be assigned to the three possible intermediate steps,
where they are expected to act on the item at those steps. For example,
if a Collection's owners desire a review step, they would create a Group
of reviewers, and assign that Group to step 1. The members of step 1's
Group will receive emails asking them to review the submission, and
will need to perform an action on the item before it can be rejected
back to the submitter or placed in the archive.
</p>
</body>
</html>

20
dspace-api/src/main/resources/org/dspace/workflow/workflow-curation.xsd
View File

@@ -120,24 +120,22 @@
<xsd:annotation> <xsd:annotation>
<xsd:documentation> <xsd:documentation>
Tasksets are organized into elements called Tasksets are organized into elements called
'flowsteps' which correspond to DSpace workflow 'flowsteps' which correspond by name to DSpace workflow
steps. Thus, to cause a task to be performed in the steps. Thus, to cause a task to be performed in the
first step of workflow, place a 'task' element in the workflow step 'edit', place a 'task' element in the
'step1' flowstep. 'edit' flowstep.
You may define from one to four flowstep elements in a You may define a flowstep element in a taskset for each
taskset, since DSpace provides three workflow steps, step in the workflow, since the flowstep action occurs
and the flowstep action occurs before each step: use before its workflow step. Use 'archive' for tasks to run
'step1' for tasks prior to step1, 'step2' for tasks just before the item is installed in archive.
before step2, 'step3' before step3 and 'archive'
before the item is installed in archive.
Each flowstep also allows an optional 'queue' Each flowstep also allows an optional 'queue'
attribute, which controls whether and where the tasks attribute, which controls whether and where the tasks
are placed on a queue for deferred performance. If the are placed on a queue for deferred performance. If the
attribute is not present, the tasks are all performed attribute is not present, the tasks are all performed
immediately. Otherwise, the tasks are placed on a immediately. Otherwise, the tasks are placed on a
queue named by the attribute value. queue named by the attribute's value.
You may add any number of tasks to a flowstep. You may add any number of tasks to a flowstep.
</xsd:documentation> </xsd:documentation>
@@ -158,7 +156,7 @@
<xsd:complexType name='task-type'> <xsd:complexType name='task-type'>
<xsd:annotation> <xsd:annotation>
<xsd:documentation> <xsd:documentation>
Each task element has a mandatory name attribute and 2 Each task element has a mandatory name attribute and two
optional, repeatable children. The task name attribute optional, repeatable children. The task name attribute
must match the plugin manager name given the task in must match the plugin manager name given the task in
dspace.cfg. dspace.cfg.

82
dspace/config/workflow-curation.xml
View File

@@ -1,49 +1,61 @@
<?xml version="1.0" encoding="UTF-8" ?> <?xml version="1.0" encoding="UTF-8" ?>
<workflow-curation> <workflow-curation>
<!-- workflow-curation enables curation tasks to be assigned to DSpace --> <!-- workflow-curation assigns Curation Tasks to DSpace workflow steps. -->
<!-- workflow steps. The taskset-map element maps collection handles to -->
<!-- tasksets enumerated in the 'tasksets' element. The special literal --> <!-- The taskset-map element maps collection handles to tasksets enumerated -->
<!-- key 'default' is applied when a collection is not otherwise mapped. --> <!-- in the 'tasksets' element. The special collection handle 'default' is -->
<!-- The special literal value 'none' indicates no taskset to perform. --> <!-- matched when a collection is not otherwise mapped. The special -->
<!-- taskset name 'none' indicates that there is no taskset to perform. -->
<taskset-map> <taskset-map>
<mapping collection-handle="default" taskset="none" /> <mapping collection-handle="default" taskset="none" />
</taskset-map> </taskset-map>
<!-- Tasksets specify tasks to be automatically performed at specific --> <!-- Tasksets specify curation tasks to be automatically performed at -->
<!-- stages of workflow. The taskset 'name' attribute should match the --> <!-- specific stages of workflow. The taskset 'name' attribute should match -->
<!-- 'taskset' attribute in the task-set mapping above. Sets are organized --> <!-- the 'taskset' attribute in the task-set mapping above. -->
<!-- into elements called 'flowsteps' which correspond to DSpace workflow -->
<!-- steps. Thus, to cause a task to be performed in the first step of --> <!-- Tasksets are organized into elements called 'flowsteps' which -->
<!-- workflow, place a 'task' element in the 'step1' flowstep. You may --> <!-- correspond by name to DSpace workflow steps. Thus, to cause a task to -->
<!-- define from one to four flowstep elements in a taskset, since DSpace --> <!-- be performed in the workflow step 'edit', place a 'task' element in -->
<!-- provides three workflow steps, and the flowstep action occurs before --> <!-- the 'edit' flowstep. -->
<!-- each step: use 'step1' for tasks prior to step1, 'step2' for tasks --> <!-- -->
<!-- before step2, 'step3' before step3 and 'archive' before the item is --> <!-- You may define a flowstep element in a taskset for each step in the -->
<!-- installed in archive. Each flowstep also allows an optional 'queue' --> <!-- workflow, since the flowstep action occurs before its workflow step. -->
<!-- attribute, which controls whether and where the tasks are placed --> <!-- Use 'archive' for tasks to run just before the item is installed in -->
<!-- on a queue for deferred performance. If the attribute is not present, --> <!-- archive. -->
<!-- the tasks are all performed immediately. Otherwise, the --> <!-- -->
<!-- tasks are placed on a queue named by the attribute value. --> <!-- Each flowstep also allows an optional 'queue' attribute, which -->
<!-- You may add any number of tasks to a flowstep. Each task --> <!-- controls whether and where the tasks are placed on a queue for -->
<!-- element has a mandatory name attribute and 2 optional, repeatable --> <!-- deferred performance. If the attribute is not present, the tasks are -->
<!-- properties. The task name attribute must match the plugin --> <!-- all performed immediately. Otherwise, the tasks are placed on a queue -->
<!-- manager name given the task in dspace.cfg. The 'workflow' element --> <!-- named by the attribute value. -->
<!-- describes what workflow actions can be taken upon completion of the --> <!-- -->
<!-- task. In the example below, the vscan (virus scan) task has been given --> <!-- You may add any number of tasks to a flowstep.-->
<!-- the power to 'reject': meaning that if the task fails - viz. a virus -->
<!-- is detected - the item will be rejected like a reviewer would reject --> <!-- Each task element has a mandatory name attribute and two optional, -->
<!-- it. The other 'workflow' value is 'approve', which skips any further --> <!-- repeatable children. The task name attribute must match the plugin -->
<!-- tasks and advances the item. The 'notify' element allows you use --> <!-- manager name given the task in dspace.cfg. -->
<!-- the workflow system of notifications (email) whenever a task is --> <!-- -->
<!-- performed and returns the designated status code (in the 'on' --> <!-- The 'workflow' element describes what workflow actions can be taken -->
<!-- attribute): 'fail', 'success' or 'error'. The values these elements --> <!-- upon completion of the task. In the example below, the vscan (virus -->
<!-- can have must be one of the following types: --> <!-- scan) task has been given the power to 'reject': meaning that if the -->
<!-- task fails - viz. a virus is detected - the item will be rejected like -->
<!-- a reviewer would reject it. -->
<!-- The other 'workflow' value is 'approve', which skips any further tasks -->
<!-- and advances the item. -->
<!-- -->
<!-- The 'notify' element allows you use the workflow system of -->
<!-- notifications (email) whenever a task is performed and returns the -->
<!-- designated status code (in the 'on' attribute): 'fail', 'success' or -->
<!-- 'error'. -->
<!-- The content of these elements must be one of the following types: -->
<!-- an eperson name, an eperson group, or one of the special literals: --> <!-- an eperson name, an eperson group, or one of the special literals: -->
<!-- '$flowgroup' = the workflow group of the step (if any). --> <!-- '$flowgroup' = the workflow group of the step (if any). -->
<!-- '$colladmin' = the collection administrator's group (if any) --> <!-- '$colladmin' = the collection administrator's group (if any) -->
<!-- '$siteadmin' = the site administrator --> <!-- '$siteadmin' = the site administrator -->
<!-- Thus, a recap of the sample taskset below would be: run a virus scan --> <!-- Thus, a recap of the sample taskset below would be: run a virus scan -->
<!-- on every submitted item, reject infected submissions, notify the --> <!-- on every submitted item, reject infected submissions, notify the -->
<!-- reviewer's group and collection administrators of same, or the site --> <!-- reviewer's group and collection administrators of same, or the site -->
@@ -62,7 +74,7 @@
</flowstep> </flowstep>
</taskset> </taskset>
<!-- We require an empty taskset to match "none" mappings --> <!-- We require an empty taskset to match "none" mappings. DO NOT REMOVE! -->
<taskset name='none'/> <taskset name='none'/>
</tasksets> </tasksets>