org.dspace.workflow

Class WorkflowManager

java.lang.Object

org.dspace.workflow.WorkflowManager

public class WorkflowManager
extends java.lang.Object

Workflow state machine.

Notes:

Determining item status from the database:

• When an item has not been submitted yet, it is in the user's personal workspace (there is a row in PersonalWorkspace pointing to it.)
• When an item is submitted and is somewhere in a workflow, it has a row in the WorkflowItem table pointing to it. The state of the workflow can be determined by looking at WorkflowItem.getState()
• When a submission is complete, the WorkflowItem pointing to the item is destroyed and the archive(org.dspace.core.Context, org.dspace.workflow.WorkflowItem) method is called, which hooks the item up to the archive.

Notification: When an item enters a state that requires notification, (WFSTATE_STEP1POOL, WFSTATE_STEP2POOL, WFSTATE_STEP3POOL,) the workflow needs to notify the appropriate groups that they have a pending task to claim.

Revealing lists of approvers, editors, and reviewers. A method could be added to do this, but it isn't strictly necessary. (say public List getStateEPeople( WorkflowItem wi, int state ) could return people affected by the item's current state.

Field Summary

Fields

Modifier and Type	Field and Description
static int	WFSTATE_ARCHIVE
static int	WFSTATE_STEP1
static int	WFSTATE_STEP1POOL
static int	WFSTATE_STEP2
static int	WFSTATE_STEP2POOL
static int	WFSTATE_STEP3
static int	WFSTATE_STEP3POOL
static int	WFSTATE_SUBMIT

Constructor Summary

Constructors

Constructor and Description
WorkflowManager()

Method Summary

Methods

Modifier and Type	Method and Description
static void	abort(Context c, WorkflowItem wi, EPerson e) abort() aborts a workflow, completely deleting it (administrator do this) (it will basically do a reject from any state - the item ends up back in the user's PersonalWorkspace
static void	advance(Context c, WorkflowItem wi, EPerson e) advance() sends an item forward in the workflow (reviewers, approvers, and editors all do an 'approve' to move the item forward) if the item arrives at the submit state, then remove the WorkflowItem and call the archive() method to put it in the archive, and email notify the submitter of a successful submission
static boolean	advance(Context c, WorkflowItem wi, EPerson e, boolean curate, boolean record) advance() sends an item forward in the workflow.
protected static void	assignToReviewer(Context context, WorkflowItem workflowItem, int step, EPerson newowner) Assign this workflow item to a reviewer.
static void	claim(Context c, WorkflowItem wi, EPerson e) claim() claims a workflow task for an EPerson
static java.lang.String	getItemTitle(WorkflowItem wi) get the title of the item in this workflow
static java.util.List<WorkflowItem>	getOwnedTasks(Context c, EPerson e) getOwnedTasks() returns a List of WorkflowItems containing the tasks claimed and owned by an EPerson.
static java.util.List<WorkflowItem>	getPooledTasks(Context c, EPerson e) getPooledTasks() returns a List of WorkflowItems an EPerson could claim (as a reviewer, etc.) for display on a user's MyDSpace page.
static java.lang.String	getSubmitterName(WorkflowItem wi) get the name of the eperson who started this workflow
static int	getWorkflowID(java.lang.String state) Translate symbolic name of workflow state into number.
static java.lang.String	getWorkflowText(int state) Get the text representing the given workflow state
protected static void	grantReviewerPolicies(Context context, WorkflowItem wfi, EPerson reviewer) This method grants the appropriate permissions to reviewers so that they can read and edit metadata and read files and edit files if allowed by configuration.
static void	notifyOfCuration(Context c, WorkflowItem wi, EPerson[] epa, java.lang.String taskName, java.lang.String action, java.lang.String message)
protected static boolean	pool(Context context, WorkflowItem workflowItem, int step) Helper method that manages state, policies, owner, notifies, task list items and so on whenever a WorkflowItem should be added to a workflow step pool.
static WorkspaceItem	reject(Context c, WorkflowItem wi, EPerson e, java.lang.String rejection_message) rejects an item - rejection means undoing a submit - WorkspaceItem is created, and the WorkflowItem is removed, user is emailed rejection_message.
protected static void	revokeReviewerPolicies(Context context, Item item) This method revokes any permission granted by the basic workflow system on the item specified as attribute.
static WorkflowItem	start(Context c, WorkspaceItem wsi) startWorkflow() begins a workflow - in a single transaction do away with the PersonalWorkspace entry and turn it into a WorkflowItem.
static WorkflowItem	startWithoutNotify(Context c, WorkspaceItem wsi) startWithoutNotify() starts the workflow normally, but disables notifications (useful for large imports,) for the first workflow step - subsequent notifications happen normally
static void	unclaim(Context c, WorkflowItem wi, EPerson e) returns an owned task/item to the pool

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

WFSTATE_SUBMIT

public static final int WFSTATE_SUBMIT

See Also:

Constant Field Values

WFSTATE_STEP1POOL

public static final int WFSTATE_STEP1POOL

See Also:

Constant Field Values

WFSTATE_STEP1

public static final int WFSTATE_STEP1

See Also:

Constant Field Values

WFSTATE_STEP2POOL

public static final int WFSTATE_STEP2POOL

See Also:

Constant Field Values

WFSTATE_STEP2

public static final int WFSTATE_STEP2

See Also:

Constant Field Values

WFSTATE_STEP3POOL

public static final int WFSTATE_STEP3POOL

See Also:

Constant Field Values

WFSTATE_STEP3

public static final int WFSTATE_STEP3

See Also:

Constant Field Values

WFSTATE_ARCHIVE

public static final int WFSTATE_ARCHIVE

See Also:

Constant Field Values

Constructor Detail

WorkflowManager

public WorkflowManager()

Method Detail

getWorkflowID

public static int getWorkflowID(java.lang.String state)

Translate symbolic name of workflow state into number. The name is case-insensitive. Returns -1 when name cannot be matched.

Parameters:

state - symbolic name of workflow state, must be one of the elements of workflowText array.

Returns:

numeric workflow state or -1 for error.

start

public static WorkflowItem start(Context c,
                 WorkspaceItem wsi)
                          throws java.sql.SQLException,
                                 AuthorizeException,
                                 java.io.IOException

startWorkflow() begins a workflow - in a single transaction do away with the PersonalWorkspace entry and turn it into a WorkflowItem.

Parameters:

c - Context

wsi - The WorkspaceItem to convert to a workflow item

Returns:

The resulting workflow item

Throws:

java.sql.SQLException - passed through.

AuthorizeException - passed through.

java.io.IOException - passed through.

startWithoutNotify

public static WorkflowItem startWithoutNotify(Context c,
                              WorkspaceItem wsi)
                                       throws java.sql.SQLException,
                                              AuthorizeException,
                                              java.io.IOException

startWithoutNotify() starts the workflow normally, but disables notifications (useful for large imports,) for the first workflow step - subsequent notifications happen normally

Throws:

java.sql.SQLException

AuthorizeException

java.io.IOException

getOwnedTasks

public static java.util.List<WorkflowItem> getOwnedTasks(Context c,
                                         EPerson e)
                                                  throws java.sql.SQLException

getOwnedTasks() returns a List of WorkflowItems containing the tasks claimed and owned by an EPerson. The GUI displays this info on the MyDSpace page.

Parameters:

e - The EPerson we want to fetch owned tasks for.

Throws:

java.sql.SQLException

getPooledTasks

public static java.util.List<WorkflowItem> getPooledTasks(Context c,
                                          EPerson e)
                                                   throws java.sql.SQLException

getPooledTasks() returns a List of WorkflowItems an EPerson could claim (as a reviewer, etc.) for display on a user's MyDSpace page.

Parameters:

e - The Eperson we want to fetch the pooled tasks for.

Throws:

java.sql.SQLException

claim

public static void claim(Context c,
         WorkflowItem wi,
         EPerson e)
                  throws java.sql.SQLException,
                         java.io.IOException,
                         AuthorizeException

claim() claims a workflow task for an EPerson

Parameters:

c - Current user context.

wi - WorkflowItem to do the claim on

e - The EPerson doing the claim

Throws:

java.sql.SQLException - passed through.

java.io.IOException - passed through.

AuthorizeException - passed through.

advance

public static void advance(Context c,
           WorkflowItem wi,
           EPerson e)
                    throws java.sql.SQLException,
                           java.io.IOException,
                           AuthorizeException

advance() sends an item forward in the workflow (reviewers, approvers, and editors all do an 'approve' to move the item forward) if the item arrives at the submit state, then remove the WorkflowItem and call the archive() method to put it in the archive, and email notify the submitter of a successful submission

Parameters:

c - Context

wi - WorkflowItem do do the approval on

e - EPerson doing the approval

Throws:

java.sql.SQLException - passed through.

java.io.IOException - passed through.

AuthorizeException - passed through.

advance

public static boolean advance(Context c,
              WorkflowItem wi,
              EPerson e,
              boolean curate,
              boolean record)
                       throws java.sql.SQLException,
                              java.io.IOException,
                              AuthorizeException

advance() sends an item forward in the workflow. Reviewers, approvers, and editors all do an 'approve' to move the item forward. If the item arrives at the submit state, then remove the WorkflowItem, call the archive(org.dspace.core.Context, org.dspace.workflow.WorkflowItem) method to put it in the archive, and email notify the submitter of a successful submission.

Parameters:

c - Context

wi - WorkflowItem do do the approval on

e - EPerson doing the approval

curate - boolean indicating whether curation tasks should be done

record - boolean indicating whether to record action

Returns:

true if the state was advanced.

Throws:

java.sql.SQLException - passed through.

java.io.IOException - passed through.

AuthorizeException - passed through.

unclaim

public static void unclaim(Context c,
           WorkflowItem wi,
           EPerson e)
                    throws java.sql.SQLException,
                           java.io.IOException,
                           AuthorizeException

returns an owned task/item to the pool

Parameters:

c - Context

wi - WorkflowItem to operate on

e - EPerson doing the operation

Throws:

java.sql.SQLException - passed through.

java.io.IOException - passed through.

AuthorizeException - passed through.

abort

public static void abort(Context c,
         WorkflowItem wi,
         EPerson e)
                  throws java.sql.SQLException,
                         AuthorizeException,
                         java.io.IOException

abort() aborts a workflow, completely deleting it (administrator do this) (it will basically do a reject from any state - the item ends up back in the user's PersonalWorkspace

Parameters:

c - Context

wi - WorkflowItem to operate on

e - EPerson doing the operation

Throws:

java.sql.SQLException

AuthorizeException

java.io.IOException

assignToReviewer

protected static void assignToReviewer(Context context,
                    WorkflowItem workflowItem,
                    int step,
                    EPerson newowner)
                                throws AuthorizeException,
                                       java.sql.SQLException

Assign this workflow item to a reviewer.

Parameters:

context - current DSpace context.

workflowItem - the item to be assigned.

step - review step.

newowner - the reviewer to be assigned.

Throws:

AuthorizeException - passed through.

java.sql.SQLException - passed through.

java.lang.IllegalArgumentException - if step is unknown.

pool

protected static boolean pool(Context context,
           WorkflowItem workflowItem,
           int step)
                       throws java.sql.SQLException,
                              AuthorizeException,
                              java.io.IOException

Helper method that manages state, policies, owner, notifies, task list items and so on whenever a WorkflowItem should be added to a workflow step pool. Don't use this method directly. Either use unclaim(Context, WorkflowItem, EPerson) if the item is claimed, start(Context, WorkspaceItem) to start the workflow, or advance(Context, WorkflowItem, EPerson) to move an item to the next state.

Parameters:

context - DSpace context object.

workflowItem - the item to be pooled.

step - the step (1-3) of the pool the item should be put into.

Returns:

true if the item was archived because no reviewers were assigned to any of the following workflow steps, false otherwise.

Throws:

java.sql.SQLException - passed through.

AuthorizeException - passed through.

java.io.IOException - passed through.

java.lang.IllegalArgumentException - if step has another value than either 1, 2, or 3.

getWorkflowText

public static java.lang.String getWorkflowText(int state)

Get the text representing the given workflow state

Parameters:

state - the workflow state

Returns:

the text representation

reject

public static WorkspaceItem reject(Context c,
                   WorkflowItem wi,
                   EPerson e,
                   java.lang.String rejection_message)
                            throws java.sql.SQLException,
                                   AuthorizeException,
                                   java.io.IOException

rejects an item - rejection means undoing a submit - WorkspaceItem is created, and the WorkflowItem is removed, user is emailed rejection_message.

Parameters:

c - Context

wi - WorkflowItem to operate on

e - EPerson doing the operation

rejection_message - message to email to user

Throws:

java.sql.SQLException

AuthorizeException

java.io.IOException

notifyOfCuration

public static void notifyOfCuration(Context c,
                    WorkflowItem wi,
                    EPerson[] epa,
                    java.lang.String taskName,
                    java.lang.String action,
                    java.lang.String message)
                             throws java.sql.SQLException,
                                    java.io.IOException

Throws:

java.sql.SQLException

java.io.IOException

getItemTitle

public static java.lang.String getItemTitle(WorkflowItem wi)
                                     throws java.sql.SQLException

get the title of the item in this workflow

Parameters:

wi - the workflow item object

Throws:

java.sql.SQLException

getSubmitterName

public static java.lang.String getSubmitterName(WorkflowItem wi)
                                         throws java.sql.SQLException

get the name of the eperson who started this workflow

Parameters:

wi - the workflow item

Returns:

"user name (email@address)"

Throws:

java.sql.SQLException - passed through.

grantReviewerPolicies

protected static void grantReviewerPolicies(Context context,
                         WorkflowItem wfi,
                         EPerson reviewer)
                                     throws java.sql.SQLException,
                                            AuthorizeException

This method grants the appropriate permissions to reviewers so that they can read and edit metadata and read files and edit files if allowed by configuration.

In most cases this method must be called within a try-finally-block that temporarily disables the authentication system. That is not done by this method as it should be done carefully and only in contexts in which granting the permissions is authorized by some previous checks.

Parameters:

context -

wfi - While all policies are granted on item, bundle or bitstream level, this method takes a WorkflowItem for convenience and uses wfi.getItem() to get the actual item.

reviewer - EPerson to grant the rights to.

Throws:

java.sql.SQLException

AuthorizeException

revokeReviewerPolicies

protected static void revokeReviewerPolicies(Context context,
                          Item item)
                                      throws java.sql.SQLException,
                                             AuthorizeException

This method revokes any permission granted by the basic workflow system on the item specified as attribute. At time of writing this method these permissions will all be granted by #grantReviewerPolicies(org.dspace.core.Context, org.dspace.workflowbasic.BasicWorkflowItem, org.dspace.eperson.EPerson).

In most cases this method must be called within a try-finally-block that temporarily disables the authentication system. That is not done by this method as it should be done carefully and only in contexts in which revoking the permissions is authorized by some previous checks.

Parameters:

context -

item -

Throws:

java.sql.SQLException - passed through.

AuthorizeException - passed through.