hazza/DSpace
1
0
Fork 0
mirror of https://github.com/DSpace/DSpace.git synced 2025-10-07 18:14:26 +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;
/**
* A workflow step.
* Linkage between a workflow step and some {@link org.dspace.curate.CurationTask}s.
*/
public class FlowStep {
public final String step;
@@ -20,10 +20,14 @@ public class FlowStep {
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 queue name of the step's associated queue (if any).
* @param name name of the workflow step.
* @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) {
this.step = name;
@@ -31,8 +35,8 @@ public class FlowStep {
}
/**
* Associate a task with this step.
* @param task a task to be applied in this step.
* Associate a curation task with the linked workflow step.
* @param task a curation task configuration to be applied in this step.
*/
public void addTask(@NotNull Task 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;
/**
* 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 final String name;
@@ -22,26 +31,29 @@ public class Task {
public final Map<String, List<String>> contacts = new HashMap<>();
/**
* Create a task with a given name.
* @param name the task's name.
* Create an instance of an association with a given curation task.
* @param name the name of a curation task to be attached to some workflow.
*/
public Task(@NotNull String name) {
this.name = name;
}
/**
* Add a task power to this task.
* @param power the given power. TODO should use schema-generated {@code enum}?
* Empower this attachment to affect a workflow in some way.
* @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) {
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 contact the associated contact.
* @param status an exit status of the curation task.
* 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) {
List<String> sContacts = contacts.get(status);
@@ -53,8 +65,11 @@ public class Task {
}
/**
* Get the collection of contacts for a given status.
* @param status the given status. TODO should use schema-generated {@code enum}?
* Get the collection of contacts for a given status such as
* {@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.
*/
@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;
/**
* 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 final String name;
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 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:documentation>
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
first step of workflow, place a 'task' element in the
'step1' flowstep.
workflow step 'edit', place a 'task' element in the
'edit' flowstep.
You may define from one to four flowstep elements in a
taskset, since DSpace provides three workflow steps,
and the flowstep action occurs before each step: use
'step1' for tasks prior to step1, 'step2' for tasks
before step2, 'step3' before step3 and 'archive'
before the item is installed in archive.
You may define a flowstep element in a taskset for each
step in the workflow, since the flowstep action occurs
before its workflow step. Use 'archive' for tasks to run
just before the item is installed in archive.
Each flowstep also allows an optional 'queue'
attribute, which controls whether and where the tasks
are placed on a queue for deferred performance. If the
attribute is not present, the tasks are all performed
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.
</xsd:documentation>
@@ -158,7 +156,7 @@
<xsd:complexType name='task-type'>
<xsd:annotation>
<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
must match the plugin manager name given the task in
dspace.cfg.

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

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