Date: Tue, 19 Mar 2024 03:17:51 -0400 (EDT) Message-ID: <1962235885.8675.1710832671458@lyrasis1-roc-mp1> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_8674_2140347821.1710832671458" ------=_Part_8674_2140347821.1710832671458 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
Configurable Workflows are an optional feature that may be enabled for u= se 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 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.
For more information, see the Configurable Workflow Introductory V= ideo
Please note that enabling the Configurable Reviewer Workflow makes chang= es to the structure of your database that are currently irreversible in any= graceful manner, so please backup your database in advanc= e 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 databa= se changes. The JSPUI will no longer work if the Configurable Reviewer Work= flow is enabled.
The submission aspect has been split up into muliple aspects: one submis=
sion aspect for the submission process, one workflow aspect containing the =
code for the original workflow and one xmlworkflow aspect containing the co=
de for the new XML configurable workflow framework. In order to enable one =
of the two aspects, either the workflow or xmlworkflow aspect should be ena=
bled in the [dspace]/config/xmlui.xconf
configuration file. Th=
is means that the xmlui.xconf configuration for the original workflow is th=
e following:
<asp= ect name=3D"Submission and Workflow" path=3D"resource://aspects/Submission/= " /> <aspect name=3D"Original Workflow" path=3D"resource://aspects/Workflow/"= />
And the xmlui.xconf configuration for the new XML configurable workflow = is the following:
<asp= ect name=3D"Submission and Workflow" path=3D"resource://aspects/Submission/= " /> <aspect name=3D"XMLWorkflow" path=3D"resource://aspects/XMLWorkflow/" /&= gt;
Besides that, a workflow configuration file has been created that specif= ies the workflow that will be used in the back-end of the DSpace code. It i= s important that the option selected in this configuration file matches the= aspect that was enabled. The workflow configuration file is available in <= code>[dspace]/config/modules/workflow.cfg. This configuration file h= as been added because it is important that a CLI import process uses the co= rrect workflow and this should not depend on the UI configuration. The work= flow.cfg configration file contains the following property:
# Origi= nal Workflow #workflow.framework: originalworkflow #XML configurable workflow workflow.framework: xmlworkflow
Workflow Data Migration
If you have existing workflow data in your DSpace instance, you will als= o need to follow the Data Migration Procedure below.
Please note that enabling the Configurable Reviewer Workflow makes chang= es to the structure of your database that are currently irreversible in any= graceful manner, so please backup your database in advanc= e 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 databa= se changes. The JSPUI will no longer work if the Configurable Reviewer Work= flow is enabled.
Depending on the workflow that is used by a DSpace installation, differe= nt scripts can be used when migrating to the new workflow.
SQL based migration can be used when the out of the box original workflo= w framework is used by your DSpace installation. This means that your DSpac= e installation uses the workflow steps and roles that are available out of = the box. The migration script will migrate the policies, roles, tasks and w= orkflowitems from the original workflow to the new workflow framework. The = following SQL scripts are available depending on the database that is used = by the DSpace installation:
[dspace]
/etc/oracle/xmlworkflow/workflow_migration.sql[dspace]
/etc/postgres/xmlworkflow/workflow_migration.sql=
li>
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 = dsrun org.dspace.xmlworkflow.migration.RestartWorkflow -e admin@myresposito= ry.org
The following arguments can be specified when running the script:
The workflow configuration file is available in [dspa=
ce]/config/modules/workflow.cfg
. This configuration file ha=
s been added because it is important that a CLI import process uses the cor=
rect workflow and this should not depend on the UI configuration. The workf=
low.cfg configration file contains the following property:
# Origi= nal Workflow #workflow.framework: originalworkflow #XML configurable workflow workflow.framework: xmlworkflow
The workflow main configuration can be found in the workflow.xml file, l=
ocated in [dspace]/config/workflow.xml
. An ex=
ample of this workflow configuration file 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]/conf=
ig/spring/api/
directory and is named "workflow-actions.xml". This c=
onfiguration file describes the different Action Java classes that are used=
by the workflow framework. Because the workflow framework uses Spring fram=
ework for loading these action classes, this configuration file contains Sp=
ring 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 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]/config/spring/xmlui/
and is named "workflow-=
actions-xmlui.xml". BEach bean defined here has an id which is the action i=
dentifier and the class is a classpath which links to the xmlui class respo=
nsible 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 addWorkflow=
ItemInformation()
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 yo=
u want to display the item. The id attribute used for the beans in the conf=
iguration 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.
<?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 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 mom=
ent, but one could always use this schema if metadata is required for custo=
m workflow steps.
The changes made to the database can always be found in the [dspac=
e]/etc/[database-type]/xmlworkflow/
directory in the file xml_=
workflow.sql
. The following tables have been added to the DSpace dat=
abase. 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 w= orkflow. This table has the following columns:
The cwf_collectionrole table represents a workflow role for one collecti= on. 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 d= escribed the role. The cwf_collectionrole table has the following columns:<= /p>
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 archive= d, the workflowitemrole is deleted. Multiple rows can exist for one workflo= witem with e.g. one row containing a group and a few containing epersons. A= ll these rows together make up the workflowitemrole The cwf_workflowitemrol= e table has the following columns:
The cwf_pooltask table represents the different task pools that exist fo= r a workflowitem. These task pools can be available at the beginning of a s= tep 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 use= r. Claimed tasks can be assigned to users or can be the result of a claim f= rom 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 late= r. The cwf_claimtask table contains the following columns:
The cwf_in_progess_user table keeps track of the different users that ar= e performing a certain step. This table is used because some steps might re= quire multiple users to perform the step before the workflowitem can procee= d. The cwf_in_progress_user table contains the following columns:
This workflow makes it possible to assign a single user to review an ite= m. This workflow configuration skips the task pool option meaning that the = assigned reviewer no longer needs to claim the task. The configuration cons= ists of the following 2 steps.
The score review system allows reviewers to give the reviewed item a rat= ing. Depending on the results of the rating, the item will be approved to g= o to the next workflow step or will be sent to an alternative step. The scr= ore review workflow consists of the following 2 steps.
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.