Contribute to the DSpace Development Fund

The newly established DSpace Development Fund supports the development of new features prioritized by DSpace Governance. For a list of planned features see the fund wiki page.

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

Introduction

Configurable Reviewer Workflows are a contribution forthcoming from @mire and will provide the following features for DSpace Reviewer Workflows

The current DSpace Reviewer Workflow System hardcodes a fixed set of 3 steps, of which the order is determined beforehand, and only the authenticated users (epersons) assigned to each of these workflow steps may participate in the workflow tasks that get assigned. In various use cases, the 3 simple steps for approving, rejecting, and editing the metadata of an submission, executed by the first person who claims the task from a predefined group (pool) of users, have proved to be quite insufficient when institutions have significantly more complex needs for mediating the review of DSpace submissions.
To resolve several of the shortcomings, @mire has implemented a "Configurable DSpace Workflow System", planned for contribution to DSpace 1.8. This system is a generalization of a solution implemented and deployed in the production environment for certain clients.

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.

Overall Design

Understanding/Configuring the workflow configuration files

DSpace.cfg Settings

TODO add DSpace Cfg details

Main workflow configuration

The workflows main configuration can be found in the workflow.xml file which is located in {dspace.dir}/config. In this xml file the workflow steps and the flow of the workflow are defined.
Before even attempting to change to the workflow it might be best to send all current items in the workflow back to the workspace since not doing this and changing the workflow might result in the loss of some workflow items. You can send all the workflow items back to the workflow by using the following command: {dspace.dir}/bin/dsrun org.dspace.workflow.util.WorkflowItemConverter (no arguments are required).

The workflow.xml file has the following layout, this layout should always be maintained.

<?xml version="1.0" encoding="UTF-8"?>
<wf-config>
    <workflow-map>
        <!-- collection to workflow mapping -->
        <name-map collection="default" workflow="{workflow.id}"/>
        <name-map collection="123456789/0" workflow="{workflow.id2}"/>
    </workflow-map>

    <workflow start="{start.step.id}" id="{workflow.id}">
        <roles>
         <!-- Roles used in the workflow -->
        </roles>

            <!-- Steps come here-->
            <step id="ExampleStep1" nextStep="ExampleStep2" userSelectionMethod="{UserSelectionActionId}">
            <!-- Step1 config-->
            </step>
        <step id="ExampleStep2" userSelectionMethod="{UserSelectionActionId}">

        </step>
    </workflow>
    <workflow start="{start.step.id2}" id="{workflow.id}">
     <!-- Another workflow configuration-->
    </workflow>
</wf-config>

workflow-map

The workflow map will contain which collection will use which workflow, it can contain a configuration for each collection and one default (the default will be used if a certain collection isn't configured in this map).
A workflow map can only contain xml elements which are named "name-map", each name map represents a link between a collection and a workflow. This workflow map element contains 2 attributes namely:

  • collection: can either be a collection handle or "default"
  • workflow: the workflow id must be the idenfitier of a workflow defined below in this xml

workflow

This is a repeatable element in the xml and each of these represents one workflow.
It requires the following 2 attributes:

  • id: a unique identifier which identifies this workflow and can be used in the workflow collection mapper
  • start: the identifier of the first step of the workflow, this will be the entry point of your workflow
    The workflow element can contain 2 sub element types "roles" and "step" these will be discussed in detail below.

roles

The roles element contains the role elements which can be used in the workflow steps of this workflow. These roles can be used to determine which people need to do

<roles>
    <role id="{unique.role.id} description="{role.description}" scope="{role.scope}" name="{role.name}" internal="true/false"/>
</roles>
  • id: a unique identifier for the role
  • description: optional attribute to describe the role
  • scope: optional attrbiute that is used to find our group and must have one of the following values:
    • collection: The group will be resolved on a collection level, it will look for a group with the specified name attached to the collection. Also this is the default value if no scope is given
    • repository: The group will be a general DSpace group
    • item: This will look for a workflow item role, this is currently not used in the NESCent workflow since it needs to be implemented in of the step classes.
  • name: the name of role will be used to look up the group, this should be equal to the group name in your DSpace system
  • internal: optional attribute which isn't really used at the moment, false by default

step

The step element represents one step in the workflow process the steps must be intertwined so for each step that is defined there must be a certain path to reach it.

<step id="{step.id}" nextStep="{next.step.id}" userSelectionMethod="{user.selection.bean.id}" role="{role.id}" >
<!-- optional alternate outcomes, depending on the outcome of the actions you can alter the next step here -->
<alternativeOutcome>
     <step status="{integer}">{alternate.step.id}</step>
</alternativeOutcome>
<action id="{action.bean.id}"/>
<action id="{action.bean.id.1}"/>
</step>
  • id: a unique identifier for the step, this id will be used to that other steps can refer to it
  • nextStep: attribute to indicate which step will follow once this step has been completed, if this attribute isn't present this means that we have reached our last step and the item will be archived
  • userSelectionMethod: the selection method identifier which will be used to determine which users will be granted access to the step, this id must refer to a bean in the workflow-actions.xml but this will be explained later.
  • role: optional attribute that must link to a role.id specified above, this role can then be used in the userSelectionMethod class defined
    Each step must can also contain one or more actions which the item will have to go through to complete the step. The elements all require just one attribute and that is an id, this id must be an id of a bean that is used in "workflow-actions.xml" file.

There is also an optional subsection section that can be defined in the step xml part named "alternativeOutcome". This can be used to define alternative outcomes, each action returns an integer depending on the user actions this is 0 by default which means go to the next action and if there isn't a next action then go the next step.
But an action can also return another integer then just 0, if this is the case you might want to send the item to a different part of the workflow. An alternativeOutcome can contain different step elements which have a status element which represent the outcome integer and as content it will be the step the item will be sent to.

Workflow actions configuration

The workflow actions configuration file can be just like the workflow.xml file be found in the {dspace.dir}/config directory and is named "workflow-actions.xml".

This file contains the beans for the actions and user selection methods refered to in the workflow.xml. So each action and userSelectionMethod identifier must occur in this file.

<?xml version="1.0" encoding="UTF-8"?>
<beans
    xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:util="http://www.springframework.org/schema/util"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
                           http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-2.0.xsd">

    <!-- At the top are our bean class identifiers --->
    <bean id="{action.api.id}" class="{class.path}" scope="prototype"/>
    <bean id="{action.api.id.2}" class="{class.path}" scope="prototype"/>

 <!-- Below our class identifiers come the declarations for out actions/userSelectionMethods -->

 <!-- Use class workflowActionConfig for an action -->
 <bean id="{action.id}" class="org.dspace.workflow.actions.WorkflowActionConfig" scope="prototype">
     <constructor-arg type="java.lang.String" value="{action.id}"/>

     <property name="processingAction" ref="{action.api.id}"/>
     <property name="requiresUI" value="{true/false}"/>
 </bean>

 <!-- Use class UserSelectionActionConfig for a user selection method -->
 <!--User selection actions-->
 <bean id="{action.api.id.2}" class="org.dspace.workflow.actions.UserSelectionActionConfig" scope="prototype">
     <constructor-arg type="java.lang.String" value="{action.api.id.2}"/>

     <property name="processingAction" ref="{user.selection.bean.id}"/>
     <property name="requiresUI" value="{true/false}"/>
 </bean>
</beans>

Each action or user selection method refered to in the workflow.xml file must be defined here. The processingAction attribute defined above must link to a classpath as this will be class that will be processed.

User Selection Action

If we want to create a new userSelection class this class must extend the //org.dspace.workflow.actions.userassignment.UserSelectionAction// class and the class attribute in the bean definition must be //org.dspace.workflow.actions.UserSelectionActionConfig//.

Processing Action

If we want to create a new Action for use in our steps this new class would need to extend the //org.dspace.workflow.actions.processingaction.ProcessingAction// class and the class attribute of the bean must be set to set to //org.dspace.workflow.actions.WorkflowActionConfig//.

The requiresUI attribute indicates if the action has a user interface if it hasn't the action will be executed immanently upon arriving at this action and will go the next action. If this attribute is set to true there must also be an entry in the "workflow-actions-xmlui.xml" which will be described below.

Workflow actions User Interface

The configuration file for the workflow user interface actions is located in the {dspace.dir}/config and is named "workflow-actions-xmlui.xml". Below is the general layout of the xml which is pretty straightforward. Each bean defined here has an id which is the action identifier and the class is a classpath which links to the xmlui class. Each of the class defined here must extend the //org.dspace.app.xmlui.aspect.submission.workflow.AbstractXMLUIAction// class, this class contains some basic settings for an action and has a method called //addWorkflowItemInformation()// which will render the given item with a show full link so you don't have to write the same code in each of your actions if you want to display the item.

<?xml version="1.0" encoding="UTF-8"?>
<beans
    xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:util="http://www.springframework.org/schema/util"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
                           http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-2.0.xsd">

    <bean id="{action.id}" class="{classpath}" scope="prototype"/>
    <bean id="{action.id.2}" class="{classpath}" scope="prototype"/>
</beans>

Alterations to Existing DSpace Classes and DB Schema

Database changes

The changes made to the database can always be found in the {dspace.src.dir}/etc directory in the file //collection-workflow-changes.sql//.
The workflow uses a separate database schema named //workflow// the fields this schema contains can found in the {dspace.dir}/registries directory and in the file //workflow-types.xml//.

The tables //collectionrole//, //workflowitemrole// where created and are used by the workflow system for the roles (the roles have been described above).
The //tasklistitem// table was altered to contain the step and the action identifiers so that the workflow system knows where in the workflow the item is.
The table //taskowner// was created so that multiple user can claim one item (this was not possible in the old workflow, there the owning user was a field in the workflowitem table).

  • No labels

All content on the LYRASIS Wiki is licensed under the CC BY (Attribution) license, unless otherwise noted.