diff --git a/dspace-api/src/main/java/org/dspace/workflow/FlowStep.java b/dspace-api/src/main/java/org/dspace/workflow/FlowStep.java index 3a72b5ed63..c154538cfd 100644 --- a/dspace-api/src/main/java/org/dspace/workflow/FlowStep.java +++ b/dspace-api/src/main/java/org/dspace/workflow/FlowStep.java @@ -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 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); diff --git a/dspace-api/src/main/java/org/dspace/workflow/Task.java b/dspace-api/src/main/java/org/dspace/workflow/Task.java index 289a082723..774cda070e 100644 --- a/dspace-api/src/main/java/org/dspace/workflow/Task.java +++ b/dspace-api/src/main/java/org/dspace/workflow/Task.java @@ -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. + * + *

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. + * + *

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> 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 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 diff --git a/dspace-api/src/main/java/org/dspace/workflow/TaskSet.java b/dspace-api/src/main/java/org/dspace/workflow/TaskSet.java index 00f370ed2a..d0a49b1c77 100644 --- a/dspace-api/src/main/java/org/dspace/workflow/TaskSet.java +++ b/dspace-api/src/main/java/org/dspace/workflow/TaskSet.java @@ -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 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. diff --git a/dspace-api/src/main/java/org/dspace/workflow/package-info.java b/dspace-api/src/main/java/org/dspace/workflow/package-info.java new file mode 100644 index 0000000000..1a871dd69a --- /dev/null +++ b/dspace-api/src/main/java/org/dspace/workflow/package-info.java @@ -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. + * + *

+ * 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; diff --git a/dspace-api/src/main/java/org/dspace/workflow/package.html b/dspace-api/src/main/java/org/dspace/workflow/package.html deleted file mode 100644 index 1cc217af71..0000000000 --- a/dspace-api/src/main/java/org/dspace/workflow/package.html +++ /dev/null @@ -1,41 +0,0 @@ - - - - - - - -

DSpace's workflow system

- -

-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. -

- -

-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. -

- - - diff --git a/dspace-api/src/main/resources/org/dspace/workflow/workflow-curation.xsd b/dspace-api/src/main/resources/org/dspace/workflow/workflow-curation.xsd index 263bbf0245..0a5cfcf089 100644 --- a/dspace-api/src/main/resources/org/dspace/workflow/workflow-curation.xsd +++ b/dspace-api/src/main/resources/org/dspace/workflow/workflow-curation.xsd @@ -120,24 +120,22 @@ 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. @@ -158,7 +156,7 @@ - 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. diff --git a/dspace/config/workflow-curation.xml b/dspace/config/workflow-curation.xml index 7508925617..9779ac649e 100644 --- a/dspace/config/workflow-curation.xml +++ b/dspace/config/workflow-curation.xml @@ -1,49 +1,61 @@ - - - - - + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -62,7 +74,7 @@ - +