WorkflowDocumentActionsService

Name WorkflowDocumentActions
Version
Included Services  
Java Package org.kuali.rice.kew.api.action

This service defines various operations which are used to perform actions against a workflow
{@link 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 ({@link ValidActions}), as well as
providing information about what actions a particular principal has been requested to execute
against a given document ({@link RequestedActions}).


This service can be used in conjunction with the {@link 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 {@link 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 {@link DocumentActionResult} result object. Though future invocations of
{@link #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 {@link ActionRequestType#COMPLETE} requests to
those principals who are capable of resolving the exception scenario as well as the document's
status being transitioned to {@link DocumentStatus#EXCEPTION}. Once they have resolved any
barriers to successful processing of the document, they can take the
{@link #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 {@link 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.

Operations
Main Message Structures

Method create
Description Creates a new document instance from the given document type. The initiator of the resulting
document will be the same as the initiator that is passed to this method. Optional
{@link DocumentUpdate} and {@link DocumentContentUpdate} parameters can be supplied in order
to create the document with these additional pieces of data already set.


By default, if neither the {@link DocumentUpdate} or {@link DocumentContentUpdate} is passed
to this method, the document that is created and returned from this operation will have the
following initial state:



      {@code status} set to {@link DocumentStatus#INITIATED}


      {@code createDate} and {@code dateLastModified} set to the current date and time


      {@code current} set to 'true'


      {@code documentContent} set to the default and empty content




Additionally, the initial {@link org.kuali.rice.kew.api.document.node.RouteNodeInstance} for the workflow process on the document
will be created and linked to the document as it's initial node. Once the document is
created, the {@link #route(DocumentActionParameters)} operation must be invoked in order to
submit it to the workflow engine for initial processing.


In certain situations, the given principal may not be permitted to initiate documents of the
given type. In these cases an {@link InvalidActionTakenException} will be thrown.
Parameters String documentTypeName the name of the document type from which to create this document
String initiatorPrincipalId the id of the principal who is initiating this document
DocumentUpdate documentUpdate specifies additional document to set on the document upon creation,
this is optional and if null is passed then the document will be created with the
default document state
DocumentContentUpdate documentContentUpdate defines what the initial document content for the document
should be, this is optional if null is passed then the document will be created with
the default empty document content
Return Document the document that was created
Errors RiceIllegalArgumentException if {@code principalId} is null or blank
IllegalDocumentTypeException if the specified document type is not active
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method determineValidActions
Description Determines which actions against the document with the given id are valid for the principal
with the given id.
Parameters String documentId the id of the document for which to determine valid actions
String principalId the id of the principal for which to determine valid actions against the
given document
Return ValidActions a {@link ValidActions} object which contains the valid actions for the given
principal against the given document
Errors RiceIllegalArgumentException if {@code documentId} is null or blank

Back to Operations

Method determineRequestedActions
Description Determines which actions are requested against the document with the given id for the
principal with the given id. These are generally derived based on action requests that are
currently pending against the document.


This method is distinguished from {@link #determineValidActions(String, String)} in that fact
that valid actions are the actions that the principal is permitted to take, while requested
actions are those that the principal is specifically being asked to take. Note that the
actions that are requested are used when assembling valid actions but are not necessarily the
only authoritative source for determination of valid actions for the principal, as
permissions and other configuration can also come into play.
Parameters String documentId the id of the document for which to determine requested actions
String principalId the id of the principal for which to determine requested actions against
the given document
Return RequestedActions a {@link RequestedActions} object which contains the actions that are being requested
from the given principal against the given document
Errors RiceIllegalArgumentException if {@code documentId} is null or blank

Back to Operations

Method acknowledge
Description Executes an {@link ActionType#ACKNOWLEDGE} action for the given principal and document
specified in the supplied parameters. When a principal acknowledges a document, any of the
principal's pending action requests at or below the acknowledge level (which includes fyi
requests as well) will be satisfied by the principal's action. The principal's action should
be recorded with the document as an {@link ActionTaken}.


Depending on document type policy, a pending action request at or below the acknowledge level
may have to exist on the document in order for the principal to take this action. Otherwise
an {@link InvalidActionTakenException} may be thrown. In order to determine if an acknowledge
action is valid, the {@link ValidActions} or {@link RequestedActions} for the document can be
checked.
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method approve
Description Executes an {@link ActionType#APPROVE} action for the given principal and document specified
in the supplied parameters. When a principal approves a document, any of the principal's
pending action requests at or below the approve level (which includes complete, acknowledge,
and fyi requests as well) will be satisfied by the principal's action. The principal's action
should be recorded with the document as an {@link ActionTaken}.


Depending on document type policy, a pending action request at or below the approve level may
have to exist on the document in order for the principal to take this action. Otherwise an
{@link InvalidActionTakenException} may be thrown. In order to determine if an approve action
is valid, the {@link ValidActions} or {@link RequestedActions} for the document can be
checked.
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method adHocToPrincipal
Description Executes an {@link ActionType#ADHOC_REQUEST} action for the given principal and document
specified in the supplied parameters to create an ad hoc action request to the target
principal specified in the {@code AdHocToPrincipal}.


Operates as per {@link #adHocToGroup(DocumentActionParameters, AdHocToGroup)} with the
exception that this method is used to send an adhoc request to principal instead of a group.


Besides this difference, the same rules that are in play for sending ad hoc requests to group
apply for sending ad hoc requests to principals.
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
AdHocToPrincipal adHocToPrincipal defines various pieces of information that informs what type of ad
hoc request should be created
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method adHocToGroup
Description Executes an {@link ActionType#ADHOC_REQUEST} action for the given group and document
specified in the supplied parameters to create an ad hoc action request to the target group
specified in the {@code AdHocToGroup}. The {@code AdHocToGroup} contains additional
information on how the ad hoc action request should be created, including the type of request
to generate, at which node it should generated, etc.


The policy for how ad hoc actions handle request generation and interact with the workflow
engine is different depending on the state of the document when the request to generate the
ad hoc is submitted. There are also different scenarios under which certain types of ad hoc
actions are allowed to be executed (throwing {@link InvalidActionTakenException} in
situations where the actions are not permitted). The rules are defined as follows:


  1. If the status of the document is {@link DocumentStatus#INITIATED} then the action request
    will be generated with a status of {@link ActionRequestStatus#INITIALIZED} and no processing
    directives will be submitted to the workflow engine. When the document is routed, these ad
    hoc requests will get activated

  2. If the ad hoc request being created is an {@link ActionRequestType#COMPLETE} or
    {@link ActionRequestType#APPROVE} and the document is in a "terminal" state (either
    {@link DocumentStatus#CANCELED}, {@link DocumentStatus#DISAPPROVED},
    {@link DocumentStatus#PROCESSED}, {@link DocumentStatus#FINAL}) or is in
    {@link DocumentStatus#EXCEPTION} status, then an {@link InvalidActionTakenException} will be
    thrown. This is because submitting such an action with a document in that state would result
    in creation of an illegal action request.

  3. If the document is in a "terminal" state (see above for definition) then the request will
    be immediately (and synchronously) activated.

  4. Otherwise, after creating the ad hoc request it will be in the
    {@link ActionRequestStatus#INITIALIZED} status, and the document will be immediately
    forwarded to the workflow engine for processing at which point the ad hoc request will
    activated at the appropriate time.




Unlink other actions, ad hoc actions don't result in the recording of an {@link ActionTaken}
against the document. Instead, only the requested ad hoc {@link ActionRequest} is created.
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
AdHocToGroup adHocToGroup defines various pieces of information that informs what type of ad hoc
request should be created
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principals i is not allowed to execute
this action

Back to Operations

Method revokeAdHocRequestById
Description Executes an {@link ActionType#ADHOC_REQUEST_REVOKE} action for the given principal and
document specified in the supplied parameters against the action request with the given id.
The process of revoking an ad hoc request simply deactivates the request associating the
generated {@link ActionTaken} of the revoke action with the deactivated request (this allows
for it to be determined what caused the ad hoc request to be deactivated). As with other
actions, this action taken is then recorded with the document.
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
String actionRequestId the id of the action request to revoke
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method revokeAdHocRequests
Description Executes an {@link ActionType#ADHOC_REQUEST_REVOKE} action which revokes all pending ad hoc
action requests that match the supplied {@link AdHocRevoke} criteria for the given principal
and document specified in the supplied parameters. The process of revoking an ad hoc requests
simply deactivates all ad hoc requests that match the given {@code AdHocRevoke} criteria,
associating the generated {@link ActionTaken} of the revoke action with the deactivated
requests (this allows for it to be determined what caused the ad hoc request to be
deactivated). As with other actions, this action taken is then recorded with the document.


It's possible that the given ad hoc revoke command will match no action requests on the
document, in which case this method will complete successfully but no requests will be
deactivated.
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
AdHocRevoke revoke the criteria for matching ad hoc action requests on the specified document that
should be revoked
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method revokeAllAdHocRequests
Description Executes an {@link ActionType#ADHOC_REQUEST_REVOKE} action which revokes all pending ad hoc
action requests for the given principal and document specified in the supplied parameters.
This process of revoking all ad hoc requests will simply deactivate all ad hoc requests on
the specified document, associating the generated {@link ActionTaken} of the revoke action
with the deactivated requests (this allows for it to be determined what caused the ad hoc
request to be deactivated). As with other actions, this action taken is then recorded with
the document.


It's possible that the specified document will have no pending adhoc requests, in which case
this method will complete successfully but no requests will be deactivated.
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method cancel
Description Executes a {@link ActionType#CANCEL} action for the given principal and document specified in
the supplied parameters. When a principal cancels a document, all pending action requests on
the document are deactivated and the the principal's action will be recorded on the document
as an {@link ActionTaken}. Additionally, the document will be (synchronously) transitioned to
the {@link DocumentStatus#CANCELED} status.


In order to cancel a document, the principal must have permission to cancel documents of the
appropriate type, and one of the following must hold true:


  1. The document must have a status of {@link DocumentStatus#INITIATED} or

  2. The document must have a status of {@link DocumentStatus#SAVED} or

  3. The principal must have a pending "complete" or "approve" request on the document.
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method recall
Description Executes a {@link ActionType#RECALL} action for the given principal and document specified in
the supplied parameters. When a principal cancels a document, all pending action requests on
the document are deactivated and the the principal's action will be recorded on the document
as an {@link ActionTaken}. Additionally, the document will be (synchronously) transitioned to
the {@link DocumentStatus#RECALLED} status.

TODO: FILL IN DOCS FOR RECALL ACTION


In order to cancel a document, the principal must have permission to cancel documents of the
appropriate type, and one of the following must hold true:


  1. The document must have a status of {@link DocumentStatus#INITIATED} or

  2. The document must have a status of {@link DocumentStatus#SAVED} or

  3. The principal must have a pending "complete" or "approve" request on the document.
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
boolean cancel whether to recall & cancel or recall & return to action list
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method clearFyi
Description Executes an {@link ActionType#FYI} action for the given principal and document specified in
the supplied parameters. When a principal clears fyis on a document, any of the principal's
pending fyis will be satisfied by the principal's action. The principal's action should be
recorded with the document as an {@link ActionTaken}.


Depending on document type policy, a pending fyi request may have to exist on the document in
order for the principal to take this action. Otherwise an {@link InvalidActionTakenException}
may be thrown. In order to determine if an fyi action is valid, the {@link ValidActions} or
{@link RequestedActions} for the document can be checked.
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method complete
Description Executes an {@link ActionType#COMPLETE} action for the given principal and document specified
in the supplied parameters. When a principal completes a document, any of the principal's
pending action requests at or below the complete level (which includes approve, acknowledge,
and fyi requests as well) will be satisfied by the principal's action. The principal's action
should be recorded with the document as an {@link ActionTaken}.


Depending on document type policy, a pending action request at or below the complete level
may have to exist on the document in order for the principal to take this action. Otherwise
an {@link InvalidActionTakenException} may be thrown. In order to determine if an complete
action is valid, the {@link ValidActions} or {@link RequestedActions} for the document can be
checked.
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method disapprove
Description Executes a {@link ActionType#DISAPPROVE} action for the given principal and document
specified in the supplied parameters. When a principal disapproves a document, all pending
action requests on the document are deactivated and the the principal's action will be
recorded on the document as an {@link ActionTaken}. Additionally, the document will be
(synchronously) transitioned to the {@link DocumentStatus#DISAPPROVED} status.


Depending on document type policy and configuration, notifications may be sent to past
approvers of the document. By default, an "acknowledge" request will be sent to each
principal who took an "approve" or "complete" action on the document previously.


In order to disapprove a document, the principal must have a pending approve or complete
request on the document.
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method route
Description Submits a document that is in either the "initiated" or "saved" state to the workflow engine
for processing. The route action triggers the beginning of the routing process and
(synchronously) switches the status of the document to {@link DocumentStatus#ENROUTE}. It
then queues up a request to the workflow engine to process the document.


When the route action is executed, an {@link ActionType#COMPLETE} action is recorded on the
document for the principal who executed the route action. At this point in time, any action
requests that are currently on the document in an "initialized" state will be activated.
Requests of this nature can commonly exist if ad hoc requests have been attached to the
document prior to execution of the route action.


By default, the principal who initiated the document is the same principal who must submit
the route command. However, a document type policy can be set which will relax this
constraint.


The route action should ideally only ever be executed once for a given document. Depending on
document type policy, attempting to execute a "route" action against a document which is
already enroute or in a terminal state may result in an {@link InvalidActionTakenException}
being thrown.
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method blanketApprove
Description Triggers the execution of a full {@link ActionType#BLANKET_APPROVE} action for the given
principal and document specified in the supplied parameters. Blanket approval will
orchestrate a document from it's current node all the way to the end of the document's
workflow process. During this process, it will automatically act on all "approve" and
"complete" requests, effectively bypassing them. When it does this, it will notify the
original recipients of these requests by routing acknowledge requests to them.


Blanket approve processing is handled by a special mode of the workflow engine which runs the
document through it's full processing lifecycle, ensuring that it makes it's way to the end
of it's route path (by bypassing any steps that would cause the process to halt, such as
approval requests). Because of this nature, blanket approve processing behavior is governed
by the same configuration as the rest of the workflow engine. So depending on whether the
engine is configured or synchronous or asynchronous operation, the blanket approve processing
will behave in the same manner.


In order to execute a blanket approve operation, the principal must have permissions to do
so.
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method blanketApproveToNodes
Description Triggers the execution of a {@link ActionType#BLANKET_APPROVE} action which orchestrates the
document to the given set of node names for the given principal and document specified in the
supplied parameters. This method functions the same as
{@link #blanketApprove(DocumentActionParameters)} with the exception that the blanket approve
process will be halted once all node names in the given set have been reached.


If null or an empty set is passed for {@code nodeNames} on this method, it's behavior will be
equivalent to {@link #blanketApprove(DocumentActionParameters)}.
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
StringList nodeNames a set of node names to which to blanket approve the given document
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method returnToPreviousNode
Description Triggers the execution of a {@link ActionType#RETURN_TO_PREVIOUS} action for the given
principal and document specified in the supplied parameters. Return a document to a previous
node will allow for the document to be pushed back to an earlier node in the process based on
the criteria present in the {@link ReturnPoint} that is passed to this method.


The document is synchronously returned to the suggested return point (assuming the desired
return point can be identified for the given document), and then the document will be
submitted to the engine for further processing (effectively, re-establishing the flow of the
document from the target return point).


Return the document to the first node in the document is treated as a special case and,
rather then transitioning the document back to the "initiated" status, will route a
"complete" request to the initiator of the document. The effectively enacts a return to the
document initiator in these cases.
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
ReturnPoint returnPoint ???
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method move
Description Triggers the execution of a {@link ActionType#MOVE} action for the given
principal and document specified in the supplied parameters. Move a document to a
node will allow for the document to be pushed to a different node in the process based on
the criteria present in the {@link MovePoint} that is passed to this method.


The document is synchronously moved to the suggested move point (assuming the desired
move point can be identified for the given document), and then the document will be
submitted to the engine for further processing (effectively, re-establishing the flow of the
document from the target return point).
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
MovePoint movePoint the point to move the document
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method takeGroupAuthority
Description Triggers the execution of a {@link ActionType#TAKE_GROUP_AUTHORITY} action for the given
principal and document specified in the supplied parameters. Takes authority of a group by a
member of that group.
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
String groupId the group id to take authority of
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method releaseGroupAuthority
Description Triggers the execution of a {@link ActionType#RELEASE_GROUP_AUTHORITY} action for the given
principal and document specified in the supplied parameters. Releases authority of a group by a
member of that group.
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
String groupId the group id to take authority of
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method save
Description Triggers the execution of a {@link ActionType#SAVE} action for the given
principal and document specified in the supplied parameters. Saves a document to a
at the current point.
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method saveDocumentData
Description Triggers the execution of a {@link ActionType#SAVE} action for the given
principal and document specified in the supplied parameters. Saves the current document data for
the document. Note that passing an annotation to this will have no effect because it is not
recorded in the route log
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method delete
Description Deletes the document.
Parameters String documentId the unique id of the document to delete
String principalId ???
Return Document the document that was removed from the system
Errors RiceIllegalArgumentException if {@code documentId} is null
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method logAnnotation
Description Records the non-routed document action. - Checks to make sure the document status
allows the action. Records the action.
Parameters String documentId the unique id of the document to delete
String principalId ???
String annotation ???
Return void the document that was removed from the system
Errors RiceIllegalArgumentException if {@code documentId} is null
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method initiateIndexing
Description ???
Parameters String documentId the unique id of the document to delete
Return void ???
Errors RiceIllegalArgumentException if {@code documentId} is null

Back to Operations

Method superUserBlanketApprove
Description Triggers the execution of a {@link ActionType#SU_BLANKET_APPROVE} action for the given
principal and document specified in the supplied parameters. Does a blanket approve for a super user
and runs post-processing depending on {@code executePostProcessor}
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
boolean executePostProcessor boolean value determining if the post-processor should be run or not
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method superUserNodeApprove
Description Triggers the execution of a {@link ActionType#SU_APPROVE} action for the given
principal and document specified in the supplied parameters. Does an approve for a super user
on a node and runs post-processing depending on {@code executePostProcessor}
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
boolean executePostProcessor boolean value determining if the post-processor should be run or not
String nodeName ???
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method superUserTakeRequestedAction
Description Triggers the execution of a {@link ActionType#SU_APPROVE} action for the given
actionRequestId and principal and document specified in the supplied parameters. Does an approve for a super user
on a node and runs post-processing depending on {@code executePostProcessor}
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
boolean executePostProcessor boolean value determining if the post-processor should be run or not
String actionRequestId unique Id of an action request to take action on
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method superUserDisapprove
Description Triggers the execution of a {@link ActionType#SU_DISAPPROVE} action for the given
principal and document specified in the supplied parameters. Does a disapprove for a super user
on a node and runs post-processing depending on {@code executePostProcessor}
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
boolean executePostProcessor boolean value determining if the post-processor should be run or not
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method superUserCancel
Description Triggers the execution of a {@link ActionType#SU_CANCEL} action for the given
principal and document specified in the supplied parameters. Does an cancel for a super user
on a node and runs post-processing depending on {@code executePostProcessor}
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
boolean executePostProcessor boolean value determining if the post-processor should be run or not
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method superUserReturnToPreviousNode
Description Triggers the execution of a {@link ActionType#SU_RETURN_TO_PREVIOUS} action for the given
principal and document specified in the supplied parameters. Returns the document to the
previous node for a super user on a node and runs post-processing depending on {@code executePostProcessor}
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
boolean executePostProcessor boolean value determining if the post-processor should be run or not
ReturnPoint returnPoint point to return to
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method placeInExceptionRouting
Description Places a document in exception routing or the given principal and document specified in the supplied parameters.
Parameters DocumentActionParameters parameters the parameters which indicate which principal is executing the action
against which document, as well as additional operations to take against the document,
such as updating document data
Return DocumentActionResult the result of executing the action, including a view on the updated state of the
document and related actions
Errors RiceIllegalArgumentException if {@code parameters} is null
InvalidDocumentContentException if the document content on the
{@link DocumentContentUpdate} supplied with the {@code parameters} is invalid.
InvalidActionTakenException if the supplied principal is not allowed to execute this
action

Back to Operations

Method validateWorkflowAttributeDefinition
Description Validates a workflow attribute definition and returns a list of validation errors
Parameters WorkflowAttributeDefinition definition WorkflowAttributeDefinition to validate
Return RemotableAttributeErrorList a list of RemotableAttributeErrors caused by validation of the passed in {@code definition}
Errors RiceIllegalArgumentException if {@code parameters} is null

Back to Operations

Method isUserInRouteLog
Description Determines if a passed in user exists in a document's route log or future route depending on the passed in
{@code lookFuture} value
Parameters String documentId unique Id of document
String principalId unique Id of Principal to look for in document's route log
boolean lookFuture boolean value determines whether or not to look at the future route log
Return boolean boolean value representing if a principal exists in a Document's route log
Errors RiceIllegalArgumentException if {@code documentId} is null

Back to Operations

Method isUserInRouteLogWithOptionalFlattening
Description Determines if a passed in user exists in a document's route log or future route depending on the passed in
{@code lookFuture} value and {@code flattenNodes}
Parameters String documentId unique Id of document
String principalId unique Id of Principal to look for in document's route log
boolean lookFuture boolean value determines whether or not to look at the future route log
boolean flattenNodes ???
Return boolean boolean value representing if a principal exists in a Document's route log
Errors RiceIllegalArgumentException if {@code documentId} is null

Back to Operations

Method reResolveRoleByDocTypeName
Description Re-resolves the given role for all documents for the given document type (including children).
Parameters String documentTypeName documentTypeName of DocuemntType for role
String roleName name of Role to reresolve
String qualifiedRoleNameLabel qualified role name label
Return void ???
Errors RiceIllegalArgumentException if {@code documentTypeName} is null

Back to Operations

Method reResolveRoleByDocumentId
Description Re-resolves the given role for all documents for the given document id (including children).
Parameters String documentId documentId of Docuemnt for role
String roleName name of Role to reresolve
String qualifiedRoleNameLabel qualified role name label
Return void ???
Errors RiceIllegalArgumentException if {@code documentTypeName} is null

Back to Operations

Method executeSimulation
Description Executes a simulation of a document to get all previous and future route information
Parameters RoutingReportCriteria reportCriteria criteria for the simulation to follow
Return DocumentDetail DocumentDetail object representing the results of the simulation
Errors RiceIllegalArgumentException if {@code reportCriteria} is null

Back to Operations

Method isFinalApprover
Description Determines if a passed in user is the final approver for a document
Parameters String documentId unique Id of the document
String principalId unique Id of Principal to look for in document's route log
Return boolean boolean value representing if a principal is the final approver for a document
Errors RiceIllegalArgumentException if {@code documentId} is null

Back to Operations

Method isLastApproverAtNode
Description Determines if a passed in user is the last approver at a specified route node
Parameters String documentId unique Id of the document
String principalId unique Id of Principal to look for in document's route log
String nodeName name of route node to determine last approver for
Return boolean boolean value representing if a principal is the last approver at the specified route node
Errors RiceIllegalArgumentException if {@code documentId} is null

Back to Operations

Method routeNodeHasApproverActionRequest
Description Determines if a route node has an 'approve action' request
Parameters String docType document type of document
String docContent string representing content of document
String nodeName name of route node to determine if approve action request exists
Return boolean boolean value representing if a route node has an 'approve action' request
Errors RiceIllegalArgumentException if {@code docType} is null

Back to Operations

Method documentWillHaveAtLeastOneActionRequest
Description Determines if a document has at least one action request
Parameters RoutingReportCriteria reportCriteria criteria for routing report
StringList actionRequestedCodes list of action request codes to see if they exist for the document
boolean ignoreCurrentActionRequests boolean value to determine if current action requests should be ignored
Return boolean boolean value representing if a document will have at least one action request
Errors RiceIllegalArgumentException if {@code docType} is null

Back to Operations

Method getPrincipalIdsInRouteLog
Description Returns a list of principal Ids that exist in a route log
Parameters String documentId unique id of the document to get the route log for
boolean lookFuture boolean value that determines if the method should look at future action requests
Return StringList list of principal ids that exist in a route log
Errors RiceIllegalArgumentException if {@code documentId} is null

Back to Operations