Date: Thu, 28 Mar 2024 19:12:43 -0400 (EDT) Message-ID: <607466390.29150.1711667563146@lyrasis1-roc-mp1> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_29149_547004600.1711667563145" ------=_Part_29149_547004600.1711667563145 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
Configurable Reviewer Workflows are a contribution forthcoming from @mir= e and will provide the following features for DSpace Reviewer Workflows
The current DSpace Reviewer Workflow System hardcodes a fixed set of 3 s=
teps, of which the order is determined beforehand, and only the authenticat=
ed users (epersons) assigned to each of these workflow steps may participat=
e in the workflow tasks that get assigned. In various use cases, the 3 simp=
le steps for approving, rejecting, and editing the metadata of an submissio=
n, executed by the first person who claims the task from a predefined group=
(pool) of users, have proved to be quite insufficient when institutions ha=
ve significantly more complex needs for mediating the review of DSpace subm=
issions.
To resolve several of the shortcomings, @mire has implemented a =E2=80=9DC=
onfigurable DSpace Workflow System=E2=80=9D, planned for contribution to DS=
pace 1.8. This system is a generalization of a solution implemented and dep=
loyed 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 applicat= ion developer to implement custom steps, which may be configured in the wor= kflow for the collection through a simple configuration file. The concept b= ehind this approach was modeled on the configurable submission system alrea= dy present in DSpace.
Currently, the whole workflow process is managed by the XmlWorkflowManag=
er as was the case for the previous version of the workflow. The workflow m=
anager is responsible for executing the different actions, processing their=
outcome and activating new ones. The WorkflowManager is being called from =
the user interface in order to process an action submitted by a user. In ca=
se another action follows the one executed by the user, the WorkflowManager=
will return this action and the user interface will show the new action pa=
ge.
For the DSpace XMLUI, the submission.js flowscript file is responsible for=
interacting with the WorkflowManager and will show the user the correct pa=
ge after submitting an action.
The WorkflowManager uses one Workflow object for each collection. In man= y cases, multiple collections will use the same workflow process and for th= ose, the same Workflow object will be used by the collection manager. A Wor= kflow object represents one workflow process as configured in the workflow.= xml and contains a number of workflow steps that the workflow item should g= o through. The main responsibility of the Workflow object is managing its s= teps and managing the different roles used in the workflow process. It cont= ains two mappings from identifiers used in the workflow.xml configuration t= o the actual Java objects used by the workflow framework.
A Step is a child element of the Workflow object and contains a number o= f actions that will sequentially be executed by one of the workflow roles o= nce the workflow item goes through the step. Each step has the following im= portant properties:
WorkflowActionConfig objects are the children of a Step object. The acti= ons are the different tasks that can be executed as part of one Step and wi= ll therefore be executed by the same role. There are two types of WorkflowA= ctionConfig objects that are being used in the workflow framework:
The workflow framework uses these WorkflowActionConfig object to separat= e the user interface classes from the API classes. Therefore, each Workflow= ActionConfig object contains an Action object and a property that indicates= whether the Action requires interaction with the user interface. The Actio= n object is the API part of the action and is responsible for the actual ex= ecution of the action. In case user interface interaction is required, the = action will not be automatically executed by will halt until the user inter= face interaction has been done.
An Action object is responsible for the actual execution of the task for= which it is responsible. The Action object is a part of a WorkflowActionCo= nfig object. In order to execute the task for which the Action object is re= sponsible, two methods are available:
The WorkflowFactory is responsible for managing the different workflow o= bjects that are being used by the different collections in DSpace. The Work= flowFactory contains a mapping from collection handles or the "default" opt= ions to Workflow objects. Each workflow object represents one workflow proc= ess containing a number of different steps. The WorkflowFactory contains al= l the required functions for loading the API bean classes that are required= by the workflow framework. When a workflow, a step or an action is not yet= available in the workflow cache, the WorkflowFactory will create the requi= red objects based on the Spring configuration file (config/workflow-actions= .xml).
This section shortly explains how an item moves through the workflow sta=
rting from the end of the submission process and ending at the archival in =
DSpace.
When an item enters the workflow after the submission process, the first w=
orkflow-step in the collection workflow is selected. The first action of th=
at step, the user selection action, is activated. From there, the workflow =
behaves as follows:
In case an action requires interaction with the user interface, the work= flow process halts after the activation of the action. The activation metho= d will be responsible for preparing the workflow-item for user interface in= teraction. An example for a pool task activation task is generating a task = pool. The user interface interaction will offer the users for which the poo= l has been generated the ability to claim the action. After interaction wit= h the user interface, the execute method is executed. Based on the result t= ype of this method, the workflow will proceed as explained in the transitio= n section described below.
In case an action does not require interaction with the user interface, = the execute method is executed directly after the activate method. This mak= es it possible to create automatic actions. An example of such an automatic= action might be to calculate an average of reviewer scores and decide base= d on that average to approve or reject the item. Based on the result type o= f the execute method, the workflow will proceed as explained in the transit= ion section described below.
Transitions between different actions and steps depend on the result typ= e of the execute method. The following result types are possible:
The WorkflowXMLUIFactory is responsible for creating the required UI act= ions that are used by the workflow framework. Currently, the WorkflowXMLUIF= actory only has one method that will create an instance of the required cla= ss by using the Spring configuration file (config/workflow-actions-xmlui.xm= l). The caching of the different UI actions is currently being done by the = Spring framework itself.
Each object returned by the WorkflowXMLUIFactory is an implementation of= the ActionInterface object or more specific, an implementation of Abstract= XMLUIAction. These objects are used by the WorkflowTransformer in order to = generate the different user interface pages that are used by the workflow f= ramework.
The flow control of the workflow framework at the side of the user inter= face is done in flowscript, more specific in the submission.js file. In cas= e the workflow process requires user interface interaction, tasks will be a= vailable for the user in the submission overview page in the DSpace user in= terface. Once the user starts one of these tasks, the workflow flow control= in the flowscript file is used to perform the required tasks. These can be= one of the following:
Currently, there are no workflow configuration options added to the DSpa= ce.cfg configuration file.
The workflow main configuration can be found in the workflow.xml file, l= ocated in {dspace.dir}/config. An example of this workflow configuration fi= le can be found bellow.
<?xm= l version=3D"1.0" encoding=3D"UTF-8"?> <wf-config> <workflow-map> <!-- collection to workflow mapping --> <name-map collection=3D"default" workflow=3D"{workflow.id}"/> <name-map collection=3D"123456789/0" workflow=3D"{workflow.id2}"= /> </workflow-map> <workflow start=3D"{start.step.id}" id=3D"{workflow.id}"> <roles> <!-- Roles used in the workflow --> </roles> <!-- Steps come here--> <step id=3D"ExampleStep1" nextStep=3D"ExampleStep2" userSele= ctionMethod=3D"{UserSelectionActionId}"> <!-- Step1 config--> </step> <step id=3D"ExampleStep2" userSelectionMethod=3D"{UserSelectionA= ctionId}"> </step> </workflow> <workflow start=3D"{start.step.id2}" id=3D"{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 proc= ess, the mapping can be done based on the handle of the collection. The map= ping with "default" as the value for the collection mapping, will be used f= or the collections not occurring in other mapping tags. Each mapping is def= ined by a "name-map" tag with two attributes:
The workflow element is a repeatable XML element and the configuration b= etween 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 us= ed 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:
<rol= es> <role id=3D"{unique.role.id} description=3D"{role.description}" scop= e=3D"{role.scope}" name=3D"{role.name}" internal=3D"true/false"/> </roles>
The step element represents one step in the workflow process. A step rep= resents a number of actions that must be executed by one specified role. In= case no role attribute is specified, the workflow framework assumes that t= he DSpace system is responsible for the execution of the step and that no u= ser interface will be available for each of the actions in this step. The s= tep element has the following attributes in order to further configure it:<= /p>
<ste= p id=3D"{step.id}" nextStep=3D"{next.step.id}" userSelectionMethod=3D"{user= .selection.bean.id}" role=3D"{role.id}" > <!-- optional alternate outcomes, depending on the outcome of the action= s you can alter the next step here --> <alternativeOutcome> <step status=3D"{integer}">{alternate.step.id}</step> </alternativeOutcome> <action id=3D"{action.bean.id}"/> <action id=3D"{action.bean.id.1}"/> </step>
Each step contains a number of actions that the workflow item will go th= rough. In case the action has a user interface, the users responsible for t= he exectution of this step will have to execute these actions before the wo= rkflow 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 s=
tep that differ from the one specified in the nextStep attribute. Each acti=
on returns an integer depending on the result of the action. The default va=
lue 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 al=
ternative outcomes will be used to lookup the next step. The alternativeOut=
come element contains a number of steps, each having a status attribute. Th=
is 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 thr=
ough in case an action returns that specified status.
The workflow actions configuration is located in the {dspace.dir}/config= /spring/api directory and is named "workflow-actions.xml". This configurati= on file describes the different Action Java classes that are used by the wo= rkflow framework. Because the workflow framework uses Spring framework for = loading these action classes, this configuration file contains Spring confi= guration.
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 wor= k properly, each of the required actions must be part of this configuration= .
<?xm= l version=3D"1.0" encoding=3D"UTF-8"?> <beans xmlns=3D"http://www.springframework.org/schema/beans" xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" xmlns:util=3D"http://www.springframework.org/schema/util" xsi:schemaLocation=3D"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=3D"{action.api.id}" class=3D"{class.path}" scope=3D"prototy= pe"/> <bean id=3D"{action.api.id.2}" class=3D"{class.path}" scope=3D"proto= type"/> <!-- Below the class identifiers come the declarations for out actions/= userSelectionMethods --> <!-- Use class workflowActionConfig for an action --> <bean id=3D"{action.id}" class=3D"oorg.dspace.xmlworkflow.state.actions= .WorkflowActionConfig" scope=3D"prototype"> <constructor-arg type=3D"java.lang.String" value=3D"{action.id}"/&g= t; <property name=3D"processingAction" ref=3D"{action.api.id}"/> <property name=3D"requiresUI" value=3D"{true/false}"/> </bean> <!-- Use class UserSelectionActionConfig for a user selection method --= > <!--User selection actions--> <bean id=3D"{action.api.id.2}" class=3D"org.dspace.xmlworkflow.state.ac= tions.UserSelectionActionConfig" scope=3D"prototype"> <constructor-arg type=3D"java.lang.String" value=3D"{action.api.id.= 2}"/> <property name=3D"processingAction" ref=3D"{user.selection.bean.id}= "/> <property name=3D"requiresUI" value=3D"{true/false}"/> </bean> </beans>
Two types of actions are configured in this Spring configuration file:= p>
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:
<bea= n id=3D"{action.api.id.2}" class=3D"org.dspace.xmlworkflow.state.actions.Us= erSelectionActionConfig" scope=3D"prototype"> <constructor-arg type=3D"java.lang.String" value=3D"{action.api.id.= 2}"/> <property name=3D"processingAction" ref=3D"{user.selection.bean.id}= "/> <property name=3D"requiresUI" value=3D"{true/false}"/> </bean>
This bean defines a new UserSelectionActionConfig and the following chil= d tags:
Processing actions are configured similar to the user selection actions.= The only difference is that these processing action beans are implementati= ons of the WorkflowActionConfig class instead of the UserSelectionActionCon= fig class.
The configuration file for the workflow user interface actions is locate= d in the {dspace.dir}/config/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 genera= ting the User Interface side of the workflow action. Each of the class defi= ned 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 Inte= rface class, the workflow framework will look for a UI class in this config= uration file.
<?xm= l version=3D"1.0" encoding=3D"UTF-8"?> <beans xmlns=3D"http://www.springframework.org/schema/beans" xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance" xmlns:util=3D"http://www.springframework.org/schema/util" xsi:schemaLocation=3D"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=3D"{action.id}" class=3D"{classpath}" scope=3D"prototype"/&= gt; <bean id=3D"{action.id.2}" class=3D"{classpath}" scope=3D"prototype"= /> </beans>
Currently, the authorizations are always granted and revoked based on th= e tasks that are available for certain users and groups. The types of autho= rization policies that is granted for each of these is always the same:
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 metadata schema named //workflow// the fields=
this schema contains can be found in the {dspace.dir}/registries directory=
and in the file //workflow-types.xml//.
The tables //collectionrole//, //workflowitemrole// where created and ar=
e 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 ite=
m is.
The table //taskowner// was created so that multiple user can claim one it=
em (this was not possible in the old workflow, there the owning user was a =
field in the workflowitem table).
There are a number of important database changes in order to support the= new reviewer workflow framework. The following tables have been added:
The collectionrole table stores the the groups that are assigned to one = of the collection scope roles. A new entry in this table is created when an= administrator creates a new collection role group in the Edit Collection i= nterface. The table has the following columns:
This table stores the the group or eperson that has been assigned to one= of the workflow items to perform one of the steps in the workflow. This ta= ble stores the item scope workflow roles. For one item, multiple groups or = epersons can be configured so multiple rows in this table can correspond to= the same item, step and workflow. The selection of the members of these it= em roles is performed by another action earlier in the workflow. This table= contains the following columns:
This table contains all the tasks that belong to an eperson. Entries in = this table are created when a user claims a certain task from the task pool= or can be automatically created when automated action assigns the user to = a task. The taskowner table contains the following columns:
The following tables have been added to the DSpace database. All tables = are prefixed with 'xmlwf_' to avoid any confusion with the existing workflo= w related database tables:
The xmlwf_workflowitem table contains the different workflowitems in the= workflow. This table has the following columns:
The xmlwf_collectionrole table represents a workflow role for one collec= tion. This type of role is the same as the roles that existed in the origin= al workflow meaning that for each collection a separate group is defined to= described the role. The xmlwf_collectionrole table has the following colum= ns:
The xmlwf_workflowitemrole table represents roles that are defined at th= e level of an item. These roles are temporary roles and only exist during t= he execution of the workflow for that specific item. Once the item is archi= ved, the workflowitemrole is deleted. Multiple rows can exist for one workf= lowitem with e.g. one row containing a group and a few containing epersons.= All these rows together make up the workflowitemrole The xmlwf_workflowite= mrole table has the following columns:
The xmlwf_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 st= ep. Multiple rows can exist for one task pool containing multiple groups an= d epersons. The xmlwf_pooltask table has the following columns:
The xmlwf_claimtask table represents a task that has been claimed by a u= ser. 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 claim= ed task defines the action at which the user has arrived in a particular st= ep. This makes it possible to stop working halfway the step and continue la= ter. The xmlwf_claimtask table contains the following columns:
The xmlwf_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 proc= eed. The xmlwf_in_progress_user table contains the following columns:
In order to be backwards compatible with previous versions of DSpace, a = number of changes have been made to the existing submission/workflow aspect= . The submission aspect has been split up into muliple aspects: one submiss= ion aspect for the submission process, one workflow aspect containing the c= ode for the original workflow and one xmlworkflow aspect containing the cod= e for the new XML configurable workflow framework. In order to enable one o= f the two aspects, either the workflow or xmlworkflow aspect should be enab= led in the dspace-install-dir/config= /xmlui.xconf configuration file. Besides that, a workflow configuration fil= e has been created that specifies the workflow that will be used in the bac= k-end of the DSpace code. It is important that the option selected in this = configuration file matches the aspect that was enabled. The workflow config= uration file is available in dspace-inst= all-dir/config/modules/workflow.cfg. This configuration file has been a= dded because it is important that a CLI import process uses the correct wor= kflow and this should not depend on the UI configuration. The workflow.cfg = configration file contains the following propertu:
Depending on the workflow that is used by a DSpace installation, differe= nt scripts can be used when migration to the new workflow.
SQL based migration can be used when the out of the box original workflo= wframework is used by your DSpace installation. This means that your DSpace= installation uses the workflow steps and roles that are available out of t= he box. The migration script will migrate the policies, roles, tasks and wo= rkflowitems from the original workflow to the new workflowframework. The fo= llowing SQL scripts are available depending on the database that is used by= the DSpace installation:
In case your DSpace installation uses a customized version of the workfl= ow, the migration script might not work properly and a different approach i= s recommended. Therefore, an additional Java based script has been created = that restarts the workflow for all the workflowitems that exist in the orig= inal workflow framework. The script will take all the existing workflowitem= s and place them in the first step of the XML configurable workflow framewo= rk thereby taking into account the XML configuration that exists at that ti= me 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 wor= kflow but not to restart the workflow for items in the XML configurable wor= kflow.
To execute the script, run the following CLI command: dspace(.bat) dsrun= org.dspace.xmlworkflow.migration.RestartWorkflow -e admin@myrespository.or= g
The following arguments can be specified when running the script:
Work in progress...
A new features has been added to the XML based workflow that resembles t= he features available in the JSPUI of DSpace that allows administrators to = abort workflowitems. The feature added to the XMLUI allows administrators t= o look at the status of the different workflowitems and look for workflowit= ems 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 origi= nal DSpace workflow only exists in the WorkflowManager.advance() method. Be= fore 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 tha= t exist in the original workflow. These hardcoded checks are done in the Cu= rationManager and will need to be changed.