com.netscape.pm.model
Interface IWorkItem

public interface IWorkItem

Defines the interface for a work item, or the smallest unit of work definable in the Process Manager world. A work item that belongs to an active process instance exists at a particular node at a particular point in time. Once the work required of the node has been completed, the work item is removed and another work item is created at another node; work items are created and removed in this manner until the process instance has completed at an exit point.

The work item interface is the focus of user interactions both from the Express UI and from the API. The work item is used to access the process instance, modify the assignee list, alter the expiration properties and alert the engine as to how to complete and route the item itself.

The work item object that implements this interface may not be instantiated manually, rather the IPMApplication and IFinder interfaces may be used to obtain a handle on a work item object.

 // The localName is the name of the application, "myApp" for instance.
 //
 javax.naming.Context cxt = new javax.naming.InitialContext();
 String jndiName = "java:comp/env/" + IPMApplication.DEFAULT_JNDI_ROOT
                 + "/" + localName;
 IPMApplicationHome home = (IPMApplicationHome) cxt.lookup( jndiName );
 IPMApplication app = home.create();

 // Fetch a handle to a work item for update
 //
 IWorkItemPK pk = WorkItemPKFactory.create( 100, "0", "Activity1" );
 pk.setEditable( true );
 IWorkItem wi = app.findWorkItem( pk );
 

See Also:

IFinder, IPMApplication, IProcessInstance

Field Summary

static java.lang.String	DEFAULT_FORK_ID The default fork id value for a newly created work item.
static int	STATE_ACTIVE State value for a work item that is assigned to a single user and is currently being worked upon.
static int	STATE_COMPLETED State value for a work item that has just been completed.
static int	STATE_RUNNING State value for a work item that has been assigned to a single user but has not been started yet.
static int	STATE_RUNNING_TO_GROUP State value for a work item that has been assigned to a group of users but has not been accepted by a member of that group yet.
static int	STATE_SUSPENDED State value for a work item that has been suspended.
static int	STATE_TERMINATED State value for a work item that has just been terminated.

Method Summary

void	addAssignee(IParticipant user) Adds the specified user onto the list of current assignees for this work item.
void	addAssignee(IRole role) Adds the specified role onto the list of current assignees for this work item.
java.util.Enumeration	assignees() Returns an enumeration of the current assignees for this work item.
void	deleteSiblings() Deletes all of a work item's sibling work items.
void	expire() Expires the work item by seting the expiration flag of the work item to true and executing the expiration handler script associated with the node the work item is currently positioned at.
void	extend(java.util.Date newDate) Sets a new expiration date for the work item and resets the work item's expiration flag to false.
java.lang.String	getApplicationName() Returns the common name of the application this work item belongs to.
IProcessInstancePK	getChildPrimaryKey() Returns the primary key of the child process instance that this work item spawned.
java.lang.String	getClusterName() Returns the name of the cluster this work item belongs to.
java.lang.String	getComment() Returns the history comment as specified by the user.
ITransition	getConclusion() Returns the current transition being used to complete the work item.
java.util.Date	getCreationDate() Returns the creation date of this work item.
java.lang.String	getErrorMessage() Returns the attached error message as specified by the user from a completion script.
java.util.Date	getExpirationDate() Returns the current expiration date of the work item, or null if the work item does not have an expiration date.
INodeElement	getNode() Returns the node element that the work item is currently positioned at.
IWorkItemPK	getPrimaryKey() Returns the primary key for this work item.
IProcessInstance	getProcessInstance() Returns the process instance this work item belongs to.
java.lang.String	getRedirectionURL() Returns the attached redirection URL as specified by the user from a completion script.
int	getState() Returns the state of the work item.
INodeElement	getTargetNode() Returns the original node the exception occurred at.
boolean	hasExpired() Returns true if the work item has already been expired, that is if the work item's expiration flag has been set to true.
boolean	hasSiblings() Returns true if the work item has sibling work items that have not completed yet.
boolean	isAutomated() Returns true if the node the work item is currently positioned at is automated.
boolean	isExceptionWorkItem() Returns true if the work item is positioned at an exception node.
boolean	isUserAssignee(IParticipant p) Returns true is the given corporate directory user is in the list of assignees for this work item.
void	release(boolean commit) Commit/rollback the work item changes to the back-end store.
void	removeAssignees() Removes the current list of assignees for this work item.
void	resume() Resumes a suspended work item.
void	save() Save the work item and its associated process instance.
void	setComment(java.lang.String comment) Sets the history comment specified by the user.
void	setConclusion(ITransition action) Specifies the transition to use to complete the work item.
void	setExpirationDate(java.util.Date expDate) Sets a new expiration date for the work item but does not reset the work item's expiration flag.
void	suspend() Suspends the work item - no actions can be performed on the work item until it is resumed.

Field Detail

STATE_RUNNING

public static final int STATE_RUNNING

State value for a work item that has been assigned to a single user but has not been started yet.

See Also:

getState()

Since:

NPM 1.0

STATE_RUNNING_TO_GROUP

public static final int STATE_RUNNING_TO_GROUP

State value for a work item that has been assigned to a group of users but has not been accepted by a member of that group yet. Once a member of the group accepts the work item, the state will change to STATE_ACTIVE.

See Also:

STATE_RUNNING, getState()

Since:

NPM 1.0

STATE_ACTIVE

public static final int STATE_ACTIVE

State value for a work item that is assigned to a single user and is currently being worked upon. By default, the Process Manager engine will set the state of a work item assigned to a single user to this value rather than STATE_RUNNING.

See Also:

STATE_RUNNING, STATE_RUNNING_TO_GROUP, getState()

Since:

NPM 1.0

STATE_SUSPENDED

public static final int STATE_SUSPENDED

State value for a work item that has been suspended. Assignees of this work item cannot modify this work item until it has been returned to the running or active state.

See Also:

getState(), suspend()

Since:

NPM 1.0

STATE_COMPLETED

public static final int STATE_COMPLETED

State value for a work item that has just been completed. A work item that has this state is in a transient state and will not be saved with this state value. Completed work items in the Process Manager engine are removed; this state value is used internally to track work items that should be removed from the system.

See Also:

getState()

Since:

NPM 1.0

STATE_TERMINATED

public static final int STATE_TERMINATED

State value for a work item that has just been terminated. A work item that has this state is in a transient state and will not be saved with this state value. Terminated work items in the Process Manager engine are removed; this state value is used internally to track work items that should be removed from the system.

See Also:

getState()

Since:

NPM 1.0

DEFAULT_FORK_ID

public static final java.lang.String DEFAULT_FORK_ID

The default fork id value for a newly created work item. This value is the fork id value assigned to work items not positioned at a node within a parallel block.

See Also:

IWorkItemPK.getForkId()

Since:

PAE 4.0

Method Detail

getPrimaryKey

public IWorkItemPK getPrimaryKey()

Returns the primary key for this work item. The primary key contains the instance id of the process instance, the fork id of the work item (which is used to determine which parallel block the work item currently part of), and the name of the node the work item is currently positioned at. The primary key also indicates whether the work item has been fetched for update or read-only.

Returns:

the primary key for this work item.

Since:

PM 6.0

See Also:

IWorkItemPK

getProcessInstance

public IProcessInstance getProcessInstance()
                                    throws PMException

Returns the process instance this work item belongs to. If this work item has been loaded for update, the process instance is also loaded for update.

Returns:

the process instance this work item belongs to.

Throws:

PMException - if there is a problem loading the process instance.

Since:

NPM 1.0

See Also:

IProcessInstance

getCreationDate

public java.util.Date getCreationDate()

Returns the creation date of this work item.

Returns:

the creation date of this work item.

Since:

NPM 1.0

isUserAssignee

public boolean isUserAssignee(IParticipant p)
                       throws PMException

Returns true is the given corporate directory user is in the list of assignees for this work item.

Parameters:

p - a corporate directory user

Returns:

true if the given user has been assigned the work item; false otherwise.

Throws:

PMException - if there is problem resolving the assignee list for this work item.

Since:

NPM 1.1

See Also:

IParticipant

assignees

public java.util.Enumeration assignees()
                                throws PMException

Returns an enumeration of the current assignees for this work item. The returned list will contain both IParticipant and IRole objects.

 for( Enumeration as = wi.assignees(); as.hasMoreElements(); )
 {
     Object o = as.nextElement();
     if( o instanceof IParticipant )
         System.out.println( "User: " + ((IParticipant) o).getUserId() );
     else if( o instanceof IRole )
         System.out.println( "Role: " + ((IRole) o).getName() );
 }
 

Returns:

a java.util.Enumeration of IParticipant and IRole objects.

Throws:

PMException - if there is a problem resolving the assignee list for this work item.

Since:

PAE 4.0

See Also:

IParticipant, IRole

addAssignee

public void addAssignee(IParticipant user)
                 throws PMException

Adds the specified user onto the list of current assignees for this work item. If the user is already on the current assignee list, calling this method is a noop.

Parameters:

user - a corporate directory user

Throws:

PMException - if there is a problem resolving the assignee list for this work item.

Since:

PM 6.0

See Also:

addAssignee( IRole ), IParticipant

addAssignee

public void addAssignee(IRole role)
                 throws PMException

Adds the specified role onto the list of current assignees for this work item. If this role is already on the current assignee list, calling this method is a noop.

By adding the specified role onto the current assignees list, all of the current members of the given role are assigned the work item. This is not the same however, as assigning the work item to each member of the role using addAssignee( IParticipant ) since assigning to a role will properly resolve a role with a dynamic membership list. For instance, if group A initially contains users x and y, and user z is added after the work item has been assigned to group A, user z will be assigned the work item. Whereas explicitly assigning the work item to users x and y will not assign the work item to user z later on.

Parameters:

role - a role defined in the current application

Throws:

PMException - if there is a problem resolving the assignee list for this work item.

Since:

PM 6.0

See Also:

addAssignee( IParticipant ), IRole

removeAssignees

public void removeAssignees()
                     throws PMException

Removes the current list of assignees for this work item.

Throws:

PMException - if there is a problem resolving the assignee list for this work item.

Since:

PAE 4.0

expire

public void expire()
            throws PMException

Expires the work item by seting the expiration flag of the work item to true and executing the expiration handler script associated with the node the work item is currently positioned at. If the work item has already been expired, calling this method is a noop.

Throws:

PMException - if there is problem with invoking the expiration handler script of the node.

Since:

NPM 1.0

See Also:

extend

extend

public void extend(java.util.Date newDate)

Sets a new expiration date for the work item and resets the work item's expiration flag to false. If the given extension date is not later than the current time and date, the expiration date for the work item is not reset.

This method may be invoked before a work item is expired. In this case, the work item's expiration date is set to a date further in the future.

Parameters:

newDate - the work item's new expiration date

Since:

NPM 1.0

See Also:

expire

setExpirationDate

public void setExpirationDate(java.util.Date expDate)

Sets a new expiration date for the work item but does not reset the work item's expiration flag.

Parameters:

expDate - the work's item new expiration date

Since:

NPM 1.0

See Also:

expire(), extend(java.util.Date)

getExpirationDate

public java.util.Date getExpirationDate()

Returns the current expiration date of the work item, or null if the work item does not have an expiration date.

Returns:

the current expiration date for the work item.

Since:

NPM 1.0

See Also:

setExpirationDate(java.util.Date)

hasExpired

public boolean hasExpired()

Returns true if the work item has already been expired, that is if the work item's expiration flag has been set to true. A return value of true indicates that the expire method has been invoked on the current work item, as this method is the only means of changing a work item's expiration flag to true.

Returns:

true if the work item has already been expired; false otherwise.

Since:

NPM 1.0

See Also:

getExpirationDate(), expire()

getChildPrimaryKey

public IProcessInstancePK getChildPrimaryKey()

Returns the primary key of the child process instance that this work item spawned. This method is only relevant if this work item is positioned at a subprocess node. If this work item does not have a child process instance key, null is returned.

Returns:

the primary key of the child process instance this work item spawned.

Since:

PM 6.0

See Also:

IProcessInstancePK, IProcessInstance.getParentPrimaryKey()

suspend

public void suspend()

Suspends the work item - no actions can be performed on the work item until it is resumed.

There is no effect by calling this method if the work item is already suspended.

Since:

NPM 1.0

See Also:

STATE_SUSPENDED, resume()

resume

public void resume()
            throws PMException

Resumes a suspended work item. The assignees of the work item will be able to perform any actions on the work item if this call succeeds.

There is no effect by calling this method if the work item is not currently suspended.

Throws:

PMException - if there is a problem accessing the back-end database where the work item is stored.

Since:

NPM 1.0

See Also:

STATE_RUNNING, STATE_RUNNING_TO_GROUP, STATE_ACTIVE, STATE_SUSPENDED

getState

public int getState()

Returns the state of the work item.

Returns:

the current state of the work item.

Since:

NPM 1.0

See Also:

STATE_RUNNING, STATE_RUNNING_TO_GROUP, STATE_ACTIVE, STATE_SUSPENDED, STATE_COMPLETED, STATE_TERMINATED, #STATE_EXCEPTION

save

public void save()
          throws PMException

Save the work item and its associated process instance. As opposed to the similar method off the IProcessInstance interface, this method saves both the work item and the process instance. This method should be used when the desired effect is to save any changes made to the work item and not ask the engine to transition it to the next activity. For example, delegating a work item or just changing its state.

Throws:

PMException - if there is a problem accessing the back-end database where the work item is stored.

Since:

NPM 1.0

See Also:

IProcessInstance.save()

release

public void release(boolean commit)
             throws PMException

Commit/rollback the work item changes to the back-end store. This method must be called even if the work item has been obtained for read-only, as this method will release any back-end database connection resources acquired during the life of this object. Failing to call this method at the close of a request could lead to a shortage in available database connections for future requests. Additionally, the Process Manager engine relies upon the invocation of this method to trigger the routing of any newly created work items spawned from the completion of this work item. If the node following the current node is automated, failing to call this method at the close of the request could result in automated work items not being performed immediately by the engine.

The effect this method will have on the work item depends upon two factors: the value of the commit parameter and whether the work item has been loaded for update or read-only.

		commit
editable		T	F
	T	commit	rollback
	F	noop	noop

Note: the IProcessInstance version of this method cannot be called in lieu of this method. Calling release from IProcessInstance will simply release database resources, while this version will cause newly generated workitems to be routed internally in the engine.

Parameters:

commit - set to true if want to commit work item changes; otherwise false to rollback changes

Throws:

PMException - is a problem accessing the back-end database where the work item is stored.

Since:

PAE 4.0

See Also:

IProcessInstance.release(boolean)

getClusterName

public java.lang.String getClusterName()

Returns the name of the cluster this work item belongs to.

Returns:

the name of the cluster this work item belongs to.

Since:

iPM 6.5

See Also:

IPMApplication

getApplicationName

public java.lang.String getApplicationName()

Returns the common name of the application this work item belongs to.

Returns:

the name of the application this work item belongs to.

Since:

PAE 4.0

See Also:

IPMApplication

getNode

public INodeElement getNode()
                     throws PMException

Returns the node element that the work item is currently positioned at. If the work item is an exception work item, the current node will be an exception node. The method getTargetNode will return the node element that the work item originally failed at.

Returns:

the node that the work item is currently positioned at.

Throws:

PMException - if there is a problem accessing the application's process definition.

Since:

NPM 1.0

See Also:

getTargetNode(), INodeElement

getComment

public java.lang.String getComment()

Returns the history comment as specified by the user. The history comment is represented in the Express UI as the textarea available for assignees to enter comments that are written to the history log. The comments are available when viewing history events from the UI or from the API.

Returns:

the history comment specified by the user.

Since:

PAE 4.0

See Also:

setComment(java.lang.String), IHistoryEvent.getComment(), IProcessInstance.getHistoryEvents()

setComment

public void setComment(java.lang.String comment)

Sets the history comment specified by the user. The history comment is represented in the Express UI as the textarea available for assignees to enter comments that are written to the history log. The comments are available when viewing history events from the UI or from the API.

Parameters:

comment - a comment to include in the history log

Since:

PAE 4.0

See Also:

getComment(), IHistoryEvent.getComment(), IProcessInstance.getHistoryEvents()

getTargetNode

public INodeElement getTargetNode()
                           throws PMException

Returns the original node the exception occurred at. If an exception occurs while executing a work item, an exception work item is generated. Within the context of this exception work item, the target node is the node the original work item was positoned at when the exception occurred; the exception node is considered to be the current node of the work item.

This method only applies to work items that are in an exception state. If the work item is not in an exception state, this method will return null.

Returns:

the original node that the exception occurred at.

Throws:

PMException - if there is a problem accessing the application's process definition.

Since:

PM 6.0

See Also:

getNode(), INodeElement

isExceptionWorkItem

public boolean isExceptionWorkItem()

Returns true if the work item is positioned at an exception node. If an exception occurs while executing a work item, an exception work item is generated at an exception node, the target node is the node the original work item was positioned at when the exception occurred.

Returns:

true if this work item is positioned at an exception node; false otherwise.

Since:

PM 6.0

See Also:

getTargetNode()

hasSiblings

public boolean hasSiblings()
                    throws PMException

Returns true if the work item has sibling work items that have not completed yet. A sibling work item is defined as being any other work item belonging to the same process instance that is positioned within the same parallel block as the current work item. A parallel block in this definition is an imaginary construct containing the nodes between an AndSplit and AndJoin. If there are two activities A and B, each on separate threads, and there are work items positioned at both A and B, the work item at A is considered to be a sibling to the work item at B. A parallel block can be nested within another parallel block, thus if parallel block X is contained with parallel block Y, all work items contained in X are siblings to the work items in Y, but not vice versa.

Returns:

true if the work item has sibling work items; false otherwise.

Throws:

PMException - is a problem accessing the back-end database where the work item is stored.

Since:

NPM 1.1

See Also:

IWorkItemPK.getForkId()

deleteSiblings

public void deleteSiblings()
                    throws PMException

Deletes all of a work item's sibling work items. A sibling work item is defined as being any other work item belonging to the same process instance that is positioned within the same parallel block as the current work item. A parallel block in this definition is an imaginary construct containing the nodes between an AndSplit and AndJoin. If there are two activities A and B, each on separate threads, and there are work items positioned at both A and B, the work item at A is considered to be a sibling to the work item at B.

A parallel block can be nested within another parallel block, thus if parallel block X is contained with parallel block Y, all work items contained in X are siblings to the work items in Y, but not vice versa.

By removing all of a work item's siblings, the process instance will be able to exit the current parallel block once this work item is complete.

Throws:

PMException - if there is a problem accessing the back-end database where the work item is stored.

Since:

NPM 1.1

See Also:

hasSiblings()

getRedirectionURL

public java.lang.String getRedirectionURL()

Returns the attached redirection URL as specified by the user from a completion script. The redirection URL can be any valid URL that is set from a JavaScript completion script via the setRedirectionURL JavaScript method; in the Process Manager UI layer, this value is used to redirect the user's browser to the specified location.

This action is typically used for multiple screen data entry where the same person may enter data across several screens in a row (and also several user activities) within Process Manager. By doing this the process takes on a wizard like forms entry screen. To accomplish this specific example, the completion steps of each user activity needs to redirect the user's browser to the same process instance.

Returns:

the redirection URL specified from a user script.

Since:

NPM 1.1

getErrorMessage

public java.lang.String getErrorMessage()

Returns the attached error message as specified by the user from a completion script. The error message can be any valid string message that is set from a JavaScript completion script via the setErrorMessage JavaScript method; in the Process Manager UI layer, this value is used to provide additional context for error messages displayed to end-users via the browser.

Returns:

the last attached user defined error message.

Since:

PAE 4.0

setConclusion

public void setConclusion(ITransition action)

Specifies the transition to use to complete the work item. The specified transition must extend from the node the work item is currently positioned at. The target node of the transition will be the node where the next work item, following the completion of this work item, will be generated.

Parameters:

action - a transition element extending from the current node

Since:

NPM 1.1

See Also:

getConclusion(), ITransition

getConclusion

public ITransition getConclusion()

Returns the current transition being used to complete the work item.

Returns:

a transition element extending from the current node.

Since:

NPM 1.1

See Also:

setConclusion(com.netscape.pm.model.ITransition), ITransition

isAutomated

public boolean isAutomated()

Returns true if the node the work item is currently positioned at is automated. A node is considered to be automated if the entity performing the work of the node is the engine; as opposed to activity nodes where the performer is the user that is assigned to the workitem.

Returns:

true if the node the work item is positioned at is automated; false otherwise.

Since:

PAE 4.0

See Also:

INodeElement.isAutomated()