Package org.kuali.rice.kew.api.action

Interface WorkflowDocumentActionsService

public interface WorkflowDocumentActionsService
This service defines various operations which are used to perform actions against a workflow Document. These actions include creation, routing, approval, acknowledgment, saving, updating document data, etc.

It also includes operations that allow for loading of information about which actions a given principal is permitted to execute against a given document (ValidActions), as well as providing information about what actions a particular principal has been requested to execute against a given document (RequestedActions).

This service can be used in conjunction with the WorkflowDocumentService which provides additional operations that relate to documents (but not document actions).

Unless otherwise specified, all parameters to all methods must not be null. If the argument is a string value it must also not be "blank" (either the empty string or a string of only whitespace). In the cases where this is violated, a RiceIllegalArgumentException will be thrown. Additionally, unless otherwise specified, all methods will return non-null return values. In the case of collections, an empty collection will be returned in preference to a null collection value. All collections which are returned from methods on this service will be unmodifiable collections.

Many of the actions trigger processing by the workflow engine. Unless otherwise specified, any method on this service which performs an action against the document will also submit the document to the workflow engine after performing the action. This may trigger the workflow document to transition to the next node in the workflow process or activate additional action requests depending on what the current state of the active node instance(s) is on the document.

Workflow engine processing may happen either asynchronously or synchronously depending on configuration and capabilities of the back end workflow engine implementation. However, asynchronous operation is suggested for most use cases. This means that when operating in asynchronous mode, after an action is submitted against the document there may be a delay in state changes to the document. For example, if a principal submits an approve against a document that triggers transition to the next node in the workflow process (generating new action requests in the process) those new actions requests will not be represented in the information returned in the DocumentActionResult result object. Though future invocations of determineRequestedActions(String, String) and similar methods may yield such information, though it may do so after an non-deterministic amount of time since the workflow engine makes no guarantees about how quickly it will complete processing. Additionally, asynchronous workflow processing is scheduled in a work queue and therefore it may not be picked up for processing immediately depending on system load and other factors.

If there is an error during asynchronous workflow processing then the document will be put into exception routing (which can be executed in various ways depending on how the document type defines it's exception policy). Regardless of the exact process that gets triggered during exception routing, the end result is a set of ActionRequestType.COMPLETE requests to those principals who are capable of resolving the exception scenario as well as the document's status being transitioned to DocumentStatus.EXCEPTION. Once they have resolved any barriers to successful processing of the document, they can take the complete(DocumentActionParameters) action against the document in order to satisfy the outstanding exception request(s) and send the document back through the workflow engine.

In contrast, when operating the workflow engine in synchronous mode, processing will happen immediately and control will not be returned to the caller until all outstanding processing has completed. As a result, the information returned in the DocumentActionResult will always be in a consistent state after each action is performed. When operating in synchronous mode, the process of exception routing does not occur when failures are encountered during workflow engine processing, rather any exceptions that are raised during processing will instead be thrown back to the calling code.

Implementations of this service are required to be thread-safe and should be able to be invoked either locally or remotely.

Author:
Kuali Rice Team (rice.collab@kuali.org)
See Also: