Page History

Introduction

Workflows can be used to define how documents should be reviewed or edited after being submitted and/or imported into DSpace. The primary focus of the workflow framework is to create a more flexible solution for the administrator to configure, and even to allow an application developer to implement custom steps, which may be configured in the workflow for the collection through a simple configuration file. Each workflow can be compared to an action that is performed on an item between its submission to the repository and the moment it is archived and published in the repository. The concept behind this approach was modeled on the configurable submission system already present in DSpace.

How to Configure your Workflows

Every submission to DSpace goes through a workflow before it is published in the repository.  A workflow consists of a series of steps, each of which is an opportunity for a reviewer, editor or collection administrator to modify and/or approve/reject the submission.  A step may also begin by running a {Curation Task} over the submission.

Each collection is associated with a workflow.  If no explicit association is made, the collection is assigned the default workflow.  These associations are configured in config/spring/api/workflow.xml using the workflowMapping property of the XmlWorkflowFactory bean.  To make an explicit association, add an entry to the list with the collection's Handle as the 'key' and the 'name' of a Workflow bean as the 'value-ref'.

Each step in a workflow is associated with a "role" which defines who can perform that step.  Role members will be notified when a new submission needs their attention.  Roles are defined by DSpace user groups.  If you wish to have reviewers interact with incoming submissions, you must create and fill the necessary groups.  See below for details.

WORKFLOWS

To create a new workflow, add another bean with the 'class' 'org.dspace.xmlworkflow.state.Workflow' and a unique 'name'.  Give it a 'steps' property containing a list of the steps that should be entered in sequence, and a 'firstStep' property which names the step to be entered first.  See the default workflow for an example.  An existing step may be re-used if appropriate, or you can create one to suit.

STEPS

Aside from its name, a step has a "user selection method", a "role", "actions" and "outcomes".

A step's 'userSelectionMethod' is the name of an "action" of the user-selection type.  A step may, for example, let itself be claimed (for a given submission) by a single user, or it may combine the actions of multiple users.  A step has exactly one 'userSelectionMethod'.  See more on actions below.

A step's role defines the set of users who may perform actions on a submission that has entered that step.  See more on roles below.

A step's actions are the types of work that are done in the step.  See more on actions below.  More than one action may be listed.

A step's outcomes connect the role members' decisions with the next step to be performed.  For example, this allows a role member to accept a submission and skip subsequent steps by going directly to the final step in the workflow.

To create a new step, add a bean with 'class' org.dspace.xmlworkflow.state.Step and the necessary properties, as discussed above.  See the existing steps in workflow.xml for examples.

ROLES

You may re-use existing roles, or add your own.  A role has a 'name', a 'scope', and optionally a 'description'.  There are three kinds of roles:

• A COLLECTION role refers to a user group associated with a specific collection.  It will be named {collectionID}_{roleName}.  For example, a role 'editor' with COLLECTION scope, applied to collection 123, will refer to the user group named 'editor_123', while the same role applied to collection 456 will refer to the user group 'editor_456'.
• A REPOSITORY role refers to a fixed user group, whose name is the role's name.  A REPOSITORY role named 'fred' will always refer to the user group 'fred'.
• An ITEM role is assigned by a previous action in the workflow.  [NEEDS MORE EXPLANATION]

To create a new role, add a bean with 'class' org.dspace.xmlworkflow.Role, the appropriate 'scope', and a unique 'name'.  Be sure that the related groups exist.

ACTIONS

Actions are defined separately in 'config/spring/api/workflow-actions.xml'.

A number of actions are already defined, and these should serve most needs.  Actions are implemented in Java code, so if you need a new one then you will need to write some Java in addition to configuring it here.

There are two kinds of actions:  user assignment and processing.  A user assignment action selects one or more role members to execute a step.  A processing action modifies the state of the submission.

To configure a new Action, create a bean with a unique 'id', 'class' equal to the fully qualified name of the Java class which implements the action, and 'scope' "prototype".  Add properties, constructor arguments, etc. as required by the code.

CURATION

To attach a Curation Task to a workflow step, see Curation System.  Tasks are executed at the beginning of a step, before role members are notified.

HOW IT WORKS

For details of how these concepts are implemented (for example, to create new actions) see the Workflow page under DSpace Development.

Data Migration

As of DSpace 7, Configurable Workflow is the only workflow system available in DSpace.  It has fully replaced the older "traditional/basic workflow" system. One major difference is that Configurable Workflow is dynamic – if a user is added to a workflow approval task after a workflow has already begun, they will immediately get access to any existing items in workflow.  Previously, this was not possible in the "traditional" workflow system.

The primary focus of the workflow framework is to create a more flexible solution for the administrator to configure, and even to allow an application developer to implement custom steps, which may be configured in the workflow for the collection through a simple configuration file. The concept behind this approach was modeled on the configurable submission system already present in DSpace.

Data Migration

in workflow.  Previously, this was not possible in the "traditional" workflow system.

Workflowitem conversion/migration scripts

...

• in_progress_user_id: The identifier of the in progress user and the primary key of this table
• workflowitem_id: The identifier of the workflowitem for which the user is performing or has performed the step.
• user_id: The identifier of the eperson that is performing or has performe the task
• finished: Keeps track of the fact that the user has finished the step or is still in progress of the execution

...

• the step or is still in progress of the execution

Additional workflow steps/actions and features

These optional steps are only supported in 7.5 and later.

These optional workflow steps are pre-defined in the "workflow.xml" but are not used by default.

Optional workflow steps: Select single reviewer workflow

This workflow makes it possible to assign a single user to review an item. This workflow configuration skips the task pool option meaning that the assigned reviewer no longer needs to claim the task. The configuration consists of  the following 2 steps.

• AssignStepselectReviewerStep: During the assignstepthis step, a user has the ability to select a responsible user to review the workflowitem. This means that for each workflowitem, a different user can be selected. Because a user is assigned, the task pool is no longer required.different user can be selected. Because a user is assigned, the task pool is no longer required.
  • The available users to select from are defined in the "action.selectrevieweraction.group" setting in workflow.cfg. This setting must list the name of a group of reviewers to select from (default value = "Reviewers" group).
• singleUserReviewStepReviewStep: The start of the reviewstep is different than the typical task pool. Instead of having a task pool, the user will be automatically assigned to the task. However, the user still has the option to reject the task (in case he or she is not responsible for the assigned task) or review the item. In case the user rejects the task, the workflowitem will be sent to the another step in the workflow as an alternative to the default outcome.

...

The score review system allows reviewers to give the reviewed item a rating. Depending on the results of the rating, the item will be approved to go to the next workflow step or will be sent to an alternative step. The scrore review workflow consists of the following 2 steps.

• ScoreReviewStepscoreReviewStep: The group of responsible users for the score reviewing will be able to claim the task from the taskpool. Dependingn Depending on the configuration, a different number of users can be required to execute the task (default is requiredusers=2). This means that the task will be available in the task pool until the required number of users has at least claimed the task. Once everyone of them has finished the task, the next (automatic) processing step is activated.
• EvaluationStepevaluationStep: During the evaluationstep, no user interface is required. The workflow system will automatically execute the step that evaluates the different scores (which corresponds to a rating from 1-5). In case the average score is more than a configurable percentagegreater than the average "minimumAcceptanceScore", the item is approved, otherwise it is rejected.  (The minimum average score is set by adjusting the minimumAcceptanceScore property passed to evaluationactionAPI in config/spring/api/workflow-actions.xml.)

...