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:

  • Method Details

    • create

      Document create(String documentTypeName, String initiatorPrincipalId, DocumentUpdate documentUpdate, DocumentContentUpdate documentContentUpdate) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, IllegalDocumentTypeException, InvalidActionTakenException
      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 DocumentUpdate and DocumentContentUpdate parameters can be supplied in order to create the document with these additional pieces of data already set.

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

          status set to DocumentStatus.INITIATED
          createDate and dateLastModified set to the current date and time
          current set to 'true'
          documentContent set to the default and empty content

      Additionally, the initial 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 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 InvalidActionTakenException will be thrown.

      Parameters:
      documentTypeName - the name of the document type from which to create this document
      initiatorPrincipalId - the id of the principal who is initiating this document
      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 - 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
      Returns:
      the document that was created
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if principalId is null or blank
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if principalId does not identify a valid principal
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if documentTypeName is null or blank
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if documentTypeName does not identify an existing document type
      IllegalDocumentTypeException - if the specified document type is not active
      IllegalDocumentTypeException - if the specified document type does not support document creation (in other words, it's a document type that is only used as a parent)
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • determineValidActions

      ValidActions determineValidActions(String documentId, String principalId) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException
      Determines which actions against the document with the given id are valid for the principal with the given id.
      Parameters:
      documentId - the id of the document for which to determine valid actions
      principalId - the id of the principal for which to determine valid actions against the given document
      Returns:
      a ValidActions object which contains the valid actions for the given principal against the given document
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if documentId is null or blank
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if document with the given documentId does not exist
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if principalId is null or blank
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if principal with the given principalId does not exist

    • isValidAction

      boolean isValidAction(String actionTypeCode, String documentId, String principalId) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException
      Determines whether the given action is valid for the document and principal id.
      Parameters:
      actionTypeCode - type code for the action to check
      documentId - the id of the document to check action for
      principalId - the id of the principal to check permission for
      Returns:
      boolean true if the action is valid, false if not
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if actionTypeCode is null or blank
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if documentId is null or blank
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if document with the given documentId does not exist
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if principalId is null or blank
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if principal with the given principalId does not exist

    • determineRequestedActions

      RequestedActions determineRequestedActions(String documentId, String principalId) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException
      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 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:
      documentId - the id of the document for which to determine requested actions
      principalId - the id of the principal for which to determine requested actions against the given document
      Returns:
      a RequestedActions object which contains the actions that are being requested from the given principal against the given document
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if documentId is null or blank
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if document with the given documentId does not exist
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if principalId is null or blank
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if principal with the given principalId does not exist

    • acknowledge

      DocumentActionResult acknowledge(DocumentActionParameters parameters) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Executes an 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 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 InvalidActionTakenException may be thrown. In order to determine if an acknowledge action is valid, the ValidActions or RequestedActions for the document can be checked.

      Parameters:
      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
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • approve

      DocumentActionResult approve(DocumentActionParameters parameters) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Executes an 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 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 InvalidActionTakenException may be thrown. In order to determine if an approve action is valid, the ValidActions or RequestedActions for the document can be checked.

      Parameters:
      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
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • adHocToPrincipal

      DocumentActionResult adHocToPrincipal(DocumentActionParameters parameters, AdHocToPrincipal adHocToPrincipal) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Executes an 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 AdHocToPrincipal.

      Operates as per 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:
      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 - defines various pieces of information that informs what type of ad hoc request should be created
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if adHocToPrincipal is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action
      InvalidActionTakenException - if the target principal is not permitted to receive ad hoc requests on documents of this type
      InvalidActionTakenException - if the specified ad hoc request cannot be generated because the current state of the document would result in an illegal request being generated
      See Also:

    • adHocToPrincipal

      @Deprecated DocumentActionResult adHocToPrincipal(DocumentActionParameters parameters, AdHocToPrincipal_v2_1_2 adHocToPrincipal) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Deprecated.
      Executes an 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 AdHocToPrincipal.

      Operates as per 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:
      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 - defines various pieces of information that informs what type of ad hoc request should be created
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if adHocToPrincipal is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action
      InvalidActionTakenException - if the target principal is not permitted to receive ad hoc requests on documents of this type
      InvalidActionTakenException - if the specified ad hoc request cannot be generated because the current state of the document would result in an illegal request being generated
      Since:
      2.1.3
      See Also:

    • adHocToGroup

      DocumentActionResult adHocToGroup(DocumentActionParameters parameters, AdHocToGroup adHocToGroup) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Executes an 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 AdHocToGroup. The 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 InvalidActionTakenException in situations where the actions are not permitted). The rules are defined as follows:

      1. If the status of the document is DocumentStatus.INITIATED then the action request will be generated with a status of 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 ActionRequestType.COMPLETE or ActionRequestType.APPROVE and the document is in a "terminal" state (either DocumentStatus.CANCELED, DocumentStatus.DISAPPROVED, DocumentStatus.PROCESSED, DocumentStatus.FINAL) or is in DocumentStatus.EXCEPTION status, then an 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 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 ActionTaken against the document. Instead, only the requested ad hoc ActionRequest is created.

      Parameters:
      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 - defines various pieces of information that informs what type of ad hoc request should be created
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if adHocToGroup is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principals i is not allowed to execute this action
      InvalidActionTakenException - if any of the principals in the target group are not permitted to receive ad hoc requests on documents of this type
      InvalidActionTakenException - if the specified ad hoc request cannot be generated because the current state of the document would result in an illegal request being generated

    • adHocToGroup

      @Deprecated DocumentActionResult adHocToGroup(DocumentActionParameters parameters, AdHocToGroup_v2_1_2 adHocToGroup) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Deprecated.
      Executes an 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 AdHocToGroup. The 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 InvalidActionTakenException in situations where the actions are not permitted). The rules are defined as follows:

      1. If the status of the document is DocumentStatus.INITIATED then the action request will be generated with a status of 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 ActionRequestType.COMPLETE or ActionRequestType.APPROVE and the document is in a "terminal" state (either DocumentStatus.CANCELED, DocumentStatus.DISAPPROVED, DocumentStatus.PROCESSED, DocumentStatus.FINAL) or is in DocumentStatus.EXCEPTION status, then an 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 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 ActionTaken against the document. Instead, only the requested ad hoc ActionRequest is created.

      Parameters:
      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 - defines various pieces of information that informs what type of ad hoc request should be created
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if adHocToGroup is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principals i is not allowed to execute this action
      InvalidActionTakenException - if any of the principals in the target group are not permitted to receive ad hoc requests on documents of this type
      InvalidActionTakenException - if the specified ad hoc request cannot be generated because the current state of the document would result in an illegal request being generated
      Since:
      2.1.3

    • revokeAdHocRequestById

      DocumentActionResult revokeAdHocRequestById(DocumentActionParameters parameters, String actionRequestId) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Executes an 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 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:
      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
      actionRequestId - the id of the action request to revoke
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if actionRequestId is null or blank
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action
      InvalidActionTakenException - if a pending ad hoc request with the given actionRequestId does not exist on the specified document, this could mean that the action request id is invalid, or that the action request has already been deactivated and is no longer pending

    • revokeAdHocRequests

      DocumentActionResult revokeAdHocRequests(DocumentActionParameters parameters, AdHocRevoke revoke) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Executes an ActionType.ADHOC_REQUEST_REVOKE action which revokes all pending ad hoc action requests that match the supplied 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 AdHocRevoke criteria, associating the generated 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:
      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
      revoke - the criteria for matching ad hoc action requests on the specified document that should be revoked
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if revoke is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • revokeAllAdHocRequests

      DocumentActionResult revokeAllAdHocRequests(DocumentActionParameters parameters) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Executes an 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 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:
      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
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • cancel

      DocumentActionResult cancel(DocumentActionParameters parameters) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Executes a 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 ActionTaken. Additionally, the document will be (synchronously) transitioned to the 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 DocumentStatus.INITIATED or
      2. The document must have a status of DocumentStatus.SAVED or
      3. The principal must have a pending "complete" or "approve" request on the document.
      Parameters:
      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
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • recall

      DocumentActionResult recall(DocumentActionParameters parameters, boolean cancel) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Executes a 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 ActionTaken. Additionally, the document will be (synchronously) transitioned to the 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 DocumentStatus.INITIATED or
      2. The document must have a status of DocumentStatus.SAVED or
      3. The principal must have a pending "complete" or "approve" request on the document.
      Parameters:
      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
      cancel - whether to recall invalid input: '&' cancel or recall invalid input: '&' return to action list
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action
      Since:
      2.1

    • clearFyi

      DocumentActionResult clearFyi(DocumentActionParameters parameters) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Executes an 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 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 InvalidActionTakenException may be thrown. In order to determine if an fyi action is valid, the ValidActions or RequestedActions for the document can be checked.

      Parameters:
      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
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • complete

      DocumentActionResult complete(DocumentActionParameters parameters) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Executes an 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 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 InvalidActionTakenException may be thrown. In order to determine if an complete action is valid, the ValidActions or RequestedActions for the document can be checked.

      Parameters:
      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
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • disapprove

      DocumentActionResult disapprove(DocumentActionParameters parameters) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Executes a 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 ActionTaken. Additionally, the document will be (synchronously) transitioned to the 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:
      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
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • route

      DocumentActionResult route(DocumentActionParameters parameters) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      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 DocumentStatus.ENROUTE. It then queues up a request to the workflow engine to process the document.

      When the route action is executed, an 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 InvalidActionTakenException being thrown.

      Parameters:
      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
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • blanketApprove

      DocumentActionResult blanketApprove(DocumentActionParameters parameters) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Triggers the execution of a full 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:
      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
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • blanketApproveToNodes

      DocumentActionResult blanketApproveToNodes(DocumentActionParameters parameters, Set<String> nodeNames) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Triggers the execution of a 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 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 nodeNames on this method, it's behavior will be equivalent to blanketApprove(DocumentActionParameters).

      Parameters:
      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
      nodeNames - a set of node names to which to blanket approve the given document
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • returnToPreviousNode

      DocumentActionResult returnToPreviousNode(DocumentActionParameters parameters, ReturnPoint returnPoint) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Triggers the execution of a 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 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:
      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
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • move

      DocumentActionResult move(DocumentActionParameters parameters, MovePoint movePoint) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Triggers the execution of a 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 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:
      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 - the point to move the document
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • takeGroupAuthority

      DocumentActionResult takeGroupAuthority(DocumentActionParameters parameters, String groupId) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Triggers the execution of a 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:
      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
      groupId - the group id to take authority of
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • releaseGroupAuthority

      DocumentActionResult releaseGroupAuthority(DocumentActionParameters parameters, String groupId) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Triggers the execution of a 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:
      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
      groupId - the group id to take authority of
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • save

      DocumentActionResult save(DocumentActionParameters parameters) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Triggers the execution of a ActionType.SAVE action for the given principal and document specified in the supplied parameters. Saves a document to a at the current point.
      Parameters:
      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
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • saveDocumentData

      DocumentActionResult saveDocumentData(DocumentActionParameters parameters) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Triggers the execution of a 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:
      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
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • delete

      Document delete(String documentId, String principalId) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidActionTakenException
      Deletes the document.
      Parameters:
      documentId - the unique id of the document to delete
      principalId -
      Returns:
      the document that was removed from the system
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if documentId is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if principalId is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId exists
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • logAnnotation

      void logAnnotation(String documentId, String principalId, String annotation) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidActionTakenException
      Records the non-routed document action. - Checks to make sure the document status allows the action. Records the action.
      Parameters:
      documentId - the unique id of the document to delete
      principalId -
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if documentId is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if principalId is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if annotation is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId exists
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • initiateIndexing

      void initiateIndexing(String documentId) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException
      Initiates the process of document attribute indexing for the document with the given id. Calling this method does not trigger processing of the workflow engine, though it may occur asynchronously or synchronously depending on configuration of the implementation.
      Parameters:
      documentId - the unique id of the document for which to initiate indexing
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if documentId is null

    • superUserBlanketApprove

      DocumentActionResult superUserBlanketApprove(DocumentActionParameters parameters, boolean executePostProcessor) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Triggers the execution of a 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 executePostProcessor
      Parameters:
      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
      executePostProcessor - boolean value determining if the post-processor should be run or not
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • superUserNodeApprove

      DocumentActionResult superUserNodeApprove(DocumentActionParameters parameters, boolean executePostProcessor, String nodeName) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Triggers the execution of a 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 executePostProcessor
      Parameters:
      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
      executePostProcessor - boolean value determining if the post-processor should be run or not
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • superUserTakeRequestedAction

      DocumentActionResult superUserTakeRequestedAction(DocumentActionParameters parameters, boolean executePostProcessor, String actionRequestId) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Triggers the execution of a 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 executePostProcessor
      Parameters:
      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
      executePostProcessor - boolean value determining if the post-processor should be run or not
      actionRequestId - unique Id of an action request to take action on
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if (@code actionRequestId}
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • superUserDisapprove

      DocumentActionResult superUserDisapprove(DocumentActionParameters parameters, boolean executePostProcessor) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Triggers the execution of a 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 executePostProcessor
      Parameters:
      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
      executePostProcessor - boolean value determining if the post-processor should be run or not
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • superUserCancel

      DocumentActionResult superUserCancel(DocumentActionParameters parameters, boolean executePostProcessor) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Triggers the execution of a 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 executePostProcessor
      Parameters:
      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
      executePostProcessor - boolean value determining if the post-processor should be run or not
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • superUserReturnToPreviousNode

      DocumentActionResult superUserReturnToPreviousNode(DocumentActionParameters parameters, boolean executePostProcessor, ReturnPoint returnPoint) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Triggers the execution of a 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 executePostProcessor
      Parameters:
      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
      executePostProcessor - boolean value determining if the post-processor should be run or not
      returnPoint - point to return to
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • placeInExceptionRouting

      DocumentActionResult placeInExceptionRouting(DocumentActionParameters parameters) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException, InvalidDocumentContentException, InvalidActionTakenException
      Places a document in exception routing or the given principal and document specified in the supplied parameters.
      Parameters:
      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
      Returns:
      the result of executing the action, including a view on the updated state of the document and related actions
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • validateWorkflowAttributeDefinition

      List<org.kuali.rice.core.api.uif.RemotableAttributeError> validateWorkflowAttributeDefinition(WorkflowAttributeDefinition definition) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException
      Validates a workflow attribute definition and returns a list of validation errors
      Parameters:
      definition - WorkflowAttributeDefinition to validate
      Returns:
      a list of RemotableAttributeErrors caused by validation of the passed in definition
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if parameters is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists
      InvalidDocumentContentException - if the document content on the DocumentContentUpdate supplied with the parameters is invalid.
      InvalidActionTakenException - if the supplied principal is not allowed to execute this action

    • isUserInRouteLog

      boolean isUserInRouteLog(String documentId, String principalId, boolean lookFuture) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException
      Determines if a passed in user exists in a document's route log or future route depending on the passed in lookFuture value
      Parameters:
      documentId - unique Id of document
      principalId - unique Id of Principal to look for in document's route log
      lookFuture - boolean value determines whether or not to look at the future route log
      Returns:
      boolean value representing if a principal exists in a Document's route log
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if documentId is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if principalId is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists

    • isUserInRouteLogWithOptionalFlattening

      boolean isUserInRouteLogWithOptionalFlattening(String documentId, String principalId, boolean lookFuture, boolean flattenNodes) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException
      Determines if a passed in user exists in a document's route log or future route depending on the passed in lookFuture value and flattenNodes
      Parameters:
      documentId - unique Id of document
      principalId - unique Id of Principal to look for in document's route log
      lookFuture - boolean value determines whether or not to look at the future route log
      Returns:
      boolean value representing if a principal exists in a Document's route log
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if documentId is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if principalId is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no document with the documentId specified in parameters exists
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if no principal with the principalId specified in parameters exists

    • reResolveRoleByDocTypeName

      void reResolveRoleByDocTypeName(String documentTypeName, String roleName, String qualifiedRoleNameLabel) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException
      Re-resolves the given role for all documents for the given document type (including children).
      Parameters:
      documentTypeName - documentTypeName of DocuemntType for role
      roleName - name of Role to reresolve
      qualifiedRoleNameLabel - qualified role name label
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if documentTypeName is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if roleName is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if qualifiedRoleNameLable is null

    • reResolveRoleByDocumentId

      void reResolveRoleByDocumentId(String documentId, String roleName, String qualifiedRoleNameLabel) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException
      Re-resolves the given role for all documents for the given document id (including children).
      Parameters:
      documentId - documentId of Docuemnt for role
      roleName - name of Role to reresolve
      qualifiedRoleNameLabel - qualified role name label
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if documentTypeName is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if roleName is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if qualifiedRoleNameLable is null

    • executeSimulation

      DocumentDetail executeSimulation(RoutingReportCriteria reportCriteria) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException
      Executes a simulation of a document to get all previous and future route information
      Parameters:
      reportCriteria - criteria for the simulation to follow
      Returns:
      DocumentDetail object representing the results of the simulation
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if reportCriteria is null

    • isFinalApprover

      boolean isFinalApprover(String documentId, String principalId) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException
      Determines if a passed in user is the final approver for a document
      Parameters:
      documentId - unique Id of the document
      principalId - unique Id of Principal to look for in document's route log
      Returns:
      boolean value representing if a principal is the final approver for a document
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if documentId is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if principalId is null

    • isLastApproverAtNode

      boolean isLastApproverAtNode(String documentId, String principalId, String nodeName) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException
      Determines if a passed in user is the last approver at a specified route node
      Parameters:
      documentId - unique Id of the document
      principalId - unique Id of Principal to look for in document's route log
      nodeName - name of route node to determine last approver for
      Returns:
      boolean value representing if a principal is the last approver at the specified route node
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if documentId is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if principalId is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if nodeName is null

    • routeNodeHasApproverActionRequest

      boolean routeNodeHasApproverActionRequest(String docType, String docContent, String nodeName) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException
      Determines if a route node has an 'approve action' request
      Parameters:
      docType - document type of document
      docContent - string representing content of document
      nodeName - name of route node to determine if approve action request exists
      Returns:
      boolean value representing if a route node has an 'approve action' request
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if docType is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if docContent is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if nodeName is null

    • documentWillHaveAtLeastOneActionRequest

      boolean documentWillHaveAtLeastOneActionRequest(RoutingReportCriteria reportCriteria, List<String> actionRequestedCodes, boolean ignoreCurrentActionRequests) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException
      Determines if a document has at least one action request
      Parameters:
      reportCriteria - criteria for routing report
      actionRequestedCodes - list of action request codes to see if they exist for the document
      ignoreCurrentActionRequests - boolean value to determine if current action requests should be ignored
      Returns:
      boolean value representing if a document will have at least one action request
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if docType is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if docContent is null
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if nodeName is null

    • getPrincipalIdsInRouteLog

      List<String> getPrincipalIdsInRouteLog(String documentId, boolean lookFuture) throws org.kuali.rice.core.api.exception.RiceIllegalArgumentException
      Returns a list of principal Ids that exist in a route log
      Parameters:
      documentId - unique id of the document to get the route log for
      lookFuture - boolean value that determines if the method should look at future action requests
      Returns:
      list of principal ids that exist in a route log
      Throws:
      org.kuali.rice.core.api.exception.RiceIllegalArgumentException - if documentId is null