Action Requests are one of the core functions of the Kuali Enterprise Workflow (KEW) system. An Action Request is a call from KEW to a person or group to take action on a document. Action Requests are created when the system or a person routes (sends) a document to another user and ask that user to do something with the document. You might ask someone to approve an expense, for example, or to acknowledge that he or she received a copy of an expense report.
Once an Action Request has been created in KEW, the associated document is sent to the appropriate users’ action lists. A user can open his or her Action List and from there, view information about the document, open the document, and/or take the requested action. If a user takes an action, for example, approves or disapproves a document, that is called an Action Taken.
The path that the document takes from its starting point to final approval is called its route. Each point along that path where a person needs to do something with the document (approve, acknowledge, etc.) is called a node on the route.
Each action request has one row on your Action List. There are five types of Action Requests:
Table 3.1.
| Action Requested | Description | Stops Document Until Action is Taken? |
|---|---|---|
| Complete | You need to Complete the document. You may cancel a document when you have a Complete action request on it. | Yes |
| Approve | You should verify the document and either Approve or Disapprove it. You may cancel a document when you have an Approve action request on it. | Yes |
| Acknowledge | You need to acknowledge (agree) that you have seen the document | No If there are no other requests, the document changes to Processed status even if there are outstanding Acknowledge requests. |
| FYI | You have been told about this document and you need to Clear the FYI on it | No If there are no other requests, the document changes to Final status even if there are outstanding FYI requests. |
| You need to print this document and take some action with it, such as mailing it to a vendor. |
You can only Disapprove or Cancel a document if you have a Complete or Approve request.
Complete and Approve are essentially the same: A Complete action satisfies an Approve request, and an Approve action satisfies a Complete request.
When you Clear an FYI request, that action is not recorded on the Route Log (history of where the document has been and what has been done on it) for that document.
There are other actions that you can take in addition to Action Requests. We will look at those in the Action Taken section below.
Every action request has a recipient. The recipient is the individual or group of individuals whose action is requested on the document. There are three types of recipients:
Person: An individual
Group: A group of users who are members of a KIM Group
Role: A group of users who are members of a KIM Role
Roles are groups of users or KIM Groups associated with a document.
The first user in a Group to take action on a request satisfies (completes) that request. Role requests can be set up to work the same way as Group requests or to require that everyone in that Role approves the document before the request is satisfied.
In certain situations, you can use roles for action requests and you can delegate action requests. You can think of these as trees or as a parent action request that has children action requests.
Roles are groups of Principals or Groups that KEW creates based on rules your institution sets up. Since KEW can only create an action request for a single person or group but a role may have several people or groups in it, KEW creates an action request for the role (a parent request), and that action request creates child action requests that go to each person or group in that role.
The parent role request can have any number of children requests that are each either a user request or a group request.
In KEW, you may delegate, or give, your request authority to other people. For example, if Joe is the fiscal officer for an account but he doesn't actually approve documents, he may delegate his approval authority to Jane. Both Joe and Jane can now take actions on Joe’s action requests
If Jane approves a document as Joe’s delegate, Joe's action request is satisfied. If Joe approves the document, Jane's action request is satisfied.
You can combine a role request with a delegation. In fact, in the previous example, the action request that is sent to Joe as a fiscal officer is really a role request. The action request tree for that scenario is:
This tree is three levels deep and shows a role delegating to a user. You can also have a role delegate to another role.
When action requests are created, they are in the Initialized state. They stay in this state until KEW determines that they need to be Activated. When a request becomes Activated, it appears in the user's Action List.
When action requests are created, they can be set to ignore previous actions or not.
If Ignore Previous is true, the activation process will not consider previous actions that the user has taken.
If Ignore Previous is false, the activation process will consider previous actions by the user and may even consider the action request satisfied by previous user actions. (This is sometimes referred to as a request being "auto-approved.")
During request activation, if the Ignore Previous flag is false and KEW determines that a previous action satisfies the current request, it will Deactivate the request instead of Activating it. Activation begins at a root request, but Deactivation begins at the request where KEW finds that a satisfying action has occurred if that request is set to not ignore previous actions.
Note
Action request structures can be hierarchical. Activation of requests always starts at the parent request and works down the tree, activating each level of the tree in turn.
Roles can have an All Approve policy. All Approve means that all members of a role must approve the docusment before the entire request is deactivated. (See Deactivation below.)
When a user takes action on a document, that action may start the deactivation of other action requests on the document. For example, if Joe has a pending request and he takes an Approve action on it, his request is deactivated. Request deactivation changes the status of the request from Initialized or Activated to Deactivated.
If Joe’s action taken causes other action requests to be Deactivated, his action taken is associated with all of the requests that it Deactivates.
Unlike Activation, Deactivation always starts at the request that was satisfied by the action taken. For example, if Joe is delegating to Jane and Jane issues an Approve action on her request, Deactivation starts at Jane's request. However, if Joe issues the Approve action, Deactivation starts at the parent.
If there are no roles set to "All Approve" on an action request, one action can Deactivate the entire request tree. This is because KEW works up and down the tree, Deactivating requests as it goes.
However, when there is an "All Approve" role, requests for all parties within the role must be Deactivated before the parent role request is Deactivated. For example, if we have an "All Approve" role request with three children requests, when one of the users takes action, their request is Deactivated, but since there are two other requests that still need to be satisfied, the Deactivation cannot go back to the parent role request. When the last of the three users has taken action, the parent role request is Deactivated.
Actions are how a user interacts with KEW. Actions can be performed in response to an Action Request (such as an Approve action) or they can be user-initiated (such as the routing of a document). Most, but not all, actions create Action Takens. The Action Taken is recorded on the Route Log and associated with a satisfied action request, where appropriate.
The KEW Action library contains these Actions, explained below:
Acknowledge
Approve
Blanket Approve
Cancel
Clear FYI
Complete
Create Document
Disapprove
Log Document
Move Document
Return to Previous Node
Route Document
Save
Superuser Actions
Superuser Approve Document
Superuser Approve Node
Superuser Approve Request
Superuser Cancel
Superuser Disapprove
Use this action to satisfy an Acknowledge action request. When you take an Acknowledge action, it usually means that you have examined the document. Acknowledgement provides no real authority over the document; you can only take the Acknowledge action on this document.
When you take an Acknowledge action, KEW finds all pending acknowledge requests for that document that are routed to you and Deactivates them. It then records an Acknowledge Action Taken and associates it with the Deactivated requests. You may take an Acknowledge action even if you have no Acknowledge Action Requests.
Use this action to satisfy an Approve or Complete action request. When you use an Approve action, it means that you have looked at the document and approve that transaction.
When you use the Approve action, KEW Deactivates all pending approve or complete requests that have been routed to you for this document. You may take an Approve action even if you have no Approve or Complete action requests.
Use the Blanket Approve action to force a document to complete a set of action requests. This allows certain users to "push" a document through its routing. To take this action, you must have the appropriate KIM Permission (or be in the Blanket Approve Group which is set in the Document Type, but that is a deprecated feature). Unless you select a specific node (point in the document’s routing path) when you take a Blanket Approve Action, KEW finds all pending Approve or Complete requests at the current level in the request tree and Deactivates them. It records a Blanket Approve Action Taken and associates it with each of the Deactivated requests.
Then, KEW sends Acknowledge action requests to each person whose action request was satisfied by the Blanket Approve. It does this for all levels in the request tree until it reaches the end point set in the Blanket Approve Action or it reaches the end of the request tree.
Use this action when a document is no longer valid and you need to cancel it. You must have a pending Approve or Complete action request on the document before you can Cancel it. Cancelling a document is similar to Disapproving it except that the Cancel action does not send out notifications.
When you take a Cancel action, KEW finds all pending requests on the document and Deactivates them. It records a Cancel Action Taken and associates it with the Deactivated requests. Then it sets the document's status to CANCELLED and the document is effectively dead.
Use this action to satisfy an FYI action request. You usually get an FYI just to notify you about a document. You don’t need to take any action on an FYI request, but if you want to remove that FYI and document from your Action List, take the Clear FYI action.
When you take the Clear FYI action KEW locates all pending FYI requests on this document that are routed to you and Deactivates them. It then records an FYI Action Taken. You must have a pending FYI request on a document to use the Clear FYI action.
Use this action to satisfy an Approve or Complete action request. When you use a Complete, it means that you have looked at the document and completed any of the necessary information on the document so it can proceed. Complete action requests are typically created as the result of a Save action or in response to an Exception Routing request.
When you use the Complete action KEW finds all pending Approve or Complete requests that are routed to you and Deactivates them. If the document is in the Exception state, it changes it back to Enroute. It then records a Complete Action Taken. You may take a Complete action even if you have no Complete or Approve action requests.
This action creates a new document in KEW of the chosen Document Type. This action does not record an Action Taken of any sort but simply begins a new document and assigns a document ID to it. The document begins in Initiated status. The Document type determines how the document is routed and what must be done for it. For example, an expense report might be routed (sent) to two or three different people for approval before it is paid.
When you have an Approve action request, you use a Disapprove action if the document does not meet the approval criteria. You must have a pending Approve or Complete request on the document before you can Disapprove it. Disapproving a document is similar to Cancelling it, except that Disapproval sends out notifications.
When you Disapprove a document, KEW finds all pending requests on the document and Deactivates them. Next, it creates Acknowledge notification requests to all users that had Approve or Complete action requests at the current node and all previous nodes. It also sends an Acknowledge notification request to the initiator of the document. Then the document's status is set to Disapproved and the document is effectively dead.
This action simply enters a message on the document. It records an Action Taken but it is never associated with any action requests. This action displays a message on the document in the Route Log.
This action moves a document either backward in the route path or forward. Moving the document backward works like the Return to Previous Node action and moving the document forward works like a Blanket Approve action. The difference between these is that the Action Taken is recorded as a Move action.
Use this action to move a document to a previous node in the route. You must have a pending Approve or Complete request on the document before you can use this action.
When you use this action, KEW Deactivates all pending requests on the document and sets the current node on the document to the previous node that you requested (this is called the target node). It records a Return to Previous Node Action Taken and associates it with the Deactivated requests. Any requests on nodes between the current node and the target node are removed, effectively erasing them. KEW then sends the document through again to recreate requests on the target node. This way a document is "returned" to a previous node, rolling it back to its previous state at that point in the route.
Use the Route Document action to route an Initialized or Saved document to other users. Only the initiator of the document can take this action unless the user has an "Initiate Document" KIM permission (or initiator_must_route policy is set to false in the Document Type, although this feature is deprecated). The Action Taken for a Route Document action is Complete.
When you use the Route Document action, it Deactivates all pending requests for the initiator of the document and it associates a Complete Action Taken with the Deactivated requests. The document’s state is then set to Enroute.
Use this action to put a newly created document in the Action List of the document’s initiator. You can only use this action on a document in an Initiated status. When you use this action, KEW creates and Activates a Complete action request for the document’s initiator and then changes the document’s status to Saved.
Superuser actions let you move a document past workflow nodes where it may be held up because another user is unavailable to take action on it or due to a system problem. Superuser actions are an administrative tool and safety net. Superusers are designated with a KIM Permission (or they are listed in the Document Type, but this feature is deprecated).
To use the Superuser functions, go to Document Search (it is a link in the left menu) and click the Superuser Search link.
Now, do a normal document search for the document on which you need to perform a Superuser action. When you find the document, click the Document/Notification Id link. If you are authorized to perform a Superuser action on this document, this takes you to the Superuser page. Otherwise, KEW displays a message that you are not authorized to take Superuser action on this document.
This action fully approves a document, Deactivating all remaining routing requests. KEW also records a Superuser Approve Action Taken and associates it with the Deactivated requests. The document's state changes to Approved and the document is scheduled for processing. The document status automatically changes to Final when it goes into the Workflow Engine.
This action approves the document through all nodes up to (but not including) a specified node. When the document gets to the specified node, requests are created as usual. This action is exactly the same as Blanket Approve except that no notification requests are created from the Superuser Approve Node action.
This action approves a single pending Approve or Complete action request. This works the same way as a standard Approve action except that the Superuser is acting in place of the responsible user.
This action cancels the document. This action works exactly the same way as the standard Cancel action except that the Superuser does not need to have a pending request to Cancel a document.
This action disapproves the document. This action works the same way as the standard Disapprove action except that the Superuser does not need to have a pending request to perform the action. Also, on a Superuser disapprove, KEW does not send notification requests.