Configurable Workflows are an optional feature that may be enabled for use only within DSpace XMLUI.
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.
For more information, see the Configurable Workflow Introductory Video
Please note that enabling the Configurable Reviewer Workflow makes changes to the structure of your database that are currently irreversible in any graceful manner, so please backup your database in advance to allow you to restore to that point should you wish to do so. It should also be noted that only the XMLUI has been changed to cope with the database changes. The JSPUI will no longer work if the Configurable Reviewer Workflow is enabled. |
The submission aspect has been split up into muliple aspects: one submission aspect for the submission process, one workflow aspect containing the code for the original workflow and one xmlworkflow aspect containing the code for the new XML configurable workflow framework. In order to enable one of the two aspects, either the workflow or xmlworkflow aspect should be enabled in the [dspace]/config/xmlui.xconf configuration file. This means that the xmlui.xconf configuration for the original workflow is the following:
<aspect name="Submission and Workflow" path="resource://aspects/Submission/" /> <aspect name="Original Workflow" path="resource://aspects/Workflow/" /> |
And the xmlui.xconf configuration for the new XML configurable workflow is the following:
<aspect name="Submission and Workflow" path="resource://aspects/Submission/" /> <aspect name="XMLWorkflow" path="resource://aspects/XMLWorkflow/" /> |
Besides that, a workflow configuration file has been created that specifies the workflow that will be used in the back-end of the DSpace code. It is important that the option selected in this configuration file matches the aspect that was enabled. The workflow configuration file is available in [dspace]/config/modules/workflow.cfg. This configuration file has been added because it is important that a CLI import process uses the correct workflow and this should not depend on the UI configuration. The workflow.cfg configration file contains the following property:
# Original Workflow #workflow.framework: originalworkflow #XML configurable workflow workflow.framework: xmlworkflow |
You will also need to follow the Data Migration Procedure below. |
Please note that enabling the Configurable Reviewer Workflow makes changes to the structure of your database that are currently irreversible in any graceful manner, so please backup your database in advance to allow you to restore to that point should you wish to do so. It should also be noted that only the XMLUI has been changed to cope with the database changes. The JSPUI will no longer work if the Configurable Reviewer Workflow is enabled. |
Depending on the workflow that is used by a DSpace installation, different scripts can be used when migrating to the new workflow.
Automatic migration can be used when the out of the box original workflow framework is used by your DSpace installation. This means that your DSpace installation uses the workflow steps and roles that are available out of the box. The automated migration will migrate the policies, roles, tasks and workflowitems from the original workflow to the new workflow framework.
This process will occur automatically by simply restarting Tomcat (or your servlet container) after enabling "xmlworkflow" in the workflow.cfg.
You can also choose to manually kick off this migration by simply running:
[dspace]/bin/dspace database migrate |
For more information on the "database migrate" command, please see Database Utilities.
In case your DSpace installation uses a customized version of the workflow, the migration script might not work properly and a different approach is recommended. Therefore, an additional Java based script has been created that restarts the workflow for all the workflowitems that exist in the original workflow framework. The script will take all the existing workflowitems and place them in the first step of the XML configurable workflow framework thereby taking into account the XML configuration that exists at that time for the collection to which the item has been submitted. This script can also be used to restart the workflow for workflowitems in the original workflow but not to restart the workflow for items in the XML configurable workflow.
To execute the script, run the following CLI command:
[dspace]/bin/dspace dsrun org.dspace.xmlworkflow.migration.RestartWorkflow -e admin@myrespository.org |
The following arguments can be specified when running the script:
The workflow configuration file is available in [dspace]/config/modules/workflow.cfg. This configuration file has been added because it is important that a CLI import process uses the correct workflow and this should not depend on the UI configuration. The workflow.cfg configration file contains the following property:
# Original Workflow #workflow.framework: originalworkflow #XML configurable workflow workflow.framework: xmlworkflow |
The workflow main configuration can be found in the workflow.xml file, located in [dspace]/config/workflow.xml. An example of this workflow configuration file can be found bellow.
<?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>
|
The workflow map contains a mapping between collections in DSpace and a workflow configuration. Similar to the configuration of the submission process, the mapping can be done based on the handle of the collection. The mapping with "default" as the value for the collection mapping, will be used for the collections not occurring in other mapping tags. Each mapping is defined by a "name-map" tag with two attributes:
The workflow element is a repeatable XML element and the configuration between two "workflow" tags represents one workflow process. It requires the following 2 attributes:
Each workflow process has a number of roles defined between the "roles" tags. A role represents one or more DSpace EPersons or Groups and can be used to assign them to one or more steps in the workflow process. One role is represented by one "role" tag and has the following attributes:
<roles>
<role id="{unique.role.id} description="{role.description}" scope="{role.scope}" name="{role.name}" internal="true/false"/>
</roles>
|
The step element represents one step in the workflow process. A step represents a number of actions that must be executed by one specified role. In case no role attribute is specified, the workflow framework assumes that the DSpace system is responsible for the execution of the step and that no user interface will be available for each of the actions in this step. The step element has the following attributes in order to further configure 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>
|
Each step contains a number of actions that the workflow item will go through. In case the action has a user interface, the users responsible for the exectution of this step will have to execute these actions before the workflow item can proceed to the next action or the end of the step.
There is also an optional subsection that can be defined for a step part called "alternativeOutcome". This can be used to define outcomes for the step that differ from the one specified in the nextStep attribute. Each action returns an integer depending on the result of the action. The default value is "0" and will make the workflow item proceed to the next action or to the end of the step.
In case an action returns a different outcome than the default "0", the alternative outcomes will be used to lookup the next step. The alternativeOutcome element contains a number of steps, each having a status attribute. This status attribute defines the return value of an action. The value of the element will be used to lookup the next step the workflow item will go through in case an action returns that specified status.
The workflow actions configuration is located in the [dspace]/config/spring/api/ directory and is named "workflow-actions.xml". This configuration file describes the different Action Java classes that are used by the workflow framework. Because the workflow framework uses Spring framework for loading these action classes, this configuration file contains Spring configuration.
This file contains the beans for the actions and user selection methods referred to in the workflow.xml. In order for the workflow framework to work properly, each of the required actions must be part of this configuration.
<?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 the class identifiers come the declarations for out actions/userSelectionMethods -->
<!-- Use class workflowActionConfig for an action -->
<bean id="{action.id}" class="oorg.dspace.xmlworkflow.state.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.xmlworkflow.state.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> |
Two types of actions are configured in this Spring configuration file:
Each user selection action that is used in the workflow config refers to a bean definition in this workflow-actions.xml configuration. In order to create a new user selection action bean, the following XML code is used:
<bean id="{action.api.id.2}" class="org.dspace.xmlworkflow.state.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> |
This bean defines a new UserSelectionActionConfig and the following child tags:
Processing actions are configured similar to the user selection actions. The only difference is that these processing action beans are implementations of the WorkflowActionConfig class instead of the UserSelectionActionConfig class.
The configuration file for the workflow user interface actions is located in the [dspace]/config/spring/xmlui/ and is named "workflow-actions-xmlui.xml". BEach bean defined here has an id which is the action identifier and the class is a classpath which links to the xmlui class responsible for generating the User Interface side of the workflow action. 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. The id attribute used for the beans in the configuration must correspond to the id used in the workflow configuration. In case an action requires a User Interface class, the workflow framework will look for a UI class in this configuration 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">
<bean id="{action.id}" class="{classpath}" scope="prototype"/>
<bean id="{action.id.2}" class="{classpath}" scope="prototype"/>
</beans>
|
Currently, the authorizations are always granted and revoked based on the tasks that are available for certain users and groups. The types of authorization policies that is granted for each of these is always the same:
The workflow uses a separate metadata schema named workflow. The fields this schema contains can be found in the [dspace]/config/registries directory and in the file workflow-types.xml. This schema is only used when using the score reviewing system at the moment, but one could always use this schema if metadata is required for custom workflow steps.
The following tables have been added to the DSpace database. All tables are prefixed with 'cwf_' to avoid any confusion with the existing workflow related database tables:
The cwf_workflowitem table contains the different workflowitems in the workflow. This table has the following columns:
The cwf_collectionrole table represents a workflow role for one collection. This type of role is the same as the roles that existed in the original workflow meaning that for each collection a separate group is defined to described the role. The cwf_collectionrole table has the following columns:
The cwf_workflowitemrole table represents roles that are defined at the level of an item. These roles are temporary roles and only exist during the execution of the workflow for that specific item. Once the item is archived, the workflowitemrole is deleted. Multiple rows can exist for one workflowitem with e.g. one row containing a group and a few containing epersons. All these rows together make up the workflowitemrole The cwf_workflowitemrole table has the following columns:
The cwf_pooltask table represents the different task pools that exist for a workflowitem. These task pools can be available at the beginning of a step and contain all the users that are allowed to claim a task in this step. Multiple rows can exist for one task pool containing multiple groups and epersons. The cwf_pooltask table has the following columns:
The cwf_claimtask table represents a task that has been claimed by a user. Claimed tasks can be assigned to users or can be the result of a claim from the task pool. Because a step can contain multiple actions, the claimed task defines the action at which the user has arrived in a particular step. This makes it possible to stop working halfway the step and continue later. The cwf_claimtask table contains the following columns:
The cwf_in_progess_user table keeps track of the different users that are performing a certain step. This table is used because some steps might require multiple users to perform the step before the workflowitem can proceed. The cwf_in_progress_user table contains the following columns:
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.
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.
minimumAcceptanceScore property passed to evaluationactionAPI in config/spring/api/workflow-actions.xml.)A new features has been added to the XML based workflow that resembles the features available in the JSPUI of DSpace that allows administrators to abort workflowitems. The feature added to the XMLUI allows administrators to look at the status of the different workflowitems and look for workflowitems based on the collection to which they have been submitted. Besides that, the administrator has the ability to permanently delete the workflowitem or send the item back to the submitter.
The DSpace 1.7 version of the curation system integration into the original DSpace workflow only exists in the WorkflowManager.advance() method. Before advancing to the next workflow step or archiving the Item, a check is performed to see whether any curation tasks need to be executed/scheduled. The problem is that this check is based on the hardcoded workflow steps that exist in the original workflow. These hardcoded checks are done in the WorkflowCurator and will need to be changed.