This guide provides information on administering a Kuali Enterprise Workflow (KEW) installation. Out of the box, KEW comes with a default setup that works well in development and test environments. However, when moving to a production environment, this setup requires adjustments. This document discusses basic administration as well as instructions for working with some of KEW’s administration tools.
You configure KEW primarily through the workflow.xml file. Please see the KEW Configuration Parameters guide for more information on initial configuration of a KEW installation.
Application Constants are the configuration elements in KEW. Each constant is modifiable at system runtime; any changes take effect immediately in KEW. Application Constants are stored in a cluster-safe cache and propagated across all machines when change occurs. For more information about Application Constants, please refer to Application Constants.
When rolling KEW out into a production environment, there are application constants which you may need to change:
ActionList.sendEmailNotification - This is usually set to false in test environments so emails aren’t generated during testing. Usually, this is set this to true in a production environment to allow email notifications. You also need to ensure that your email service is configured properly to allow KEW to send notifications.
ApplicationContext - In a production environment, this is usually something like en-prd. You must set this value correctly so that KEW’s email notifications contain valid links.
Backdoor.ShowbackDoorLogin - The backdoor login allows users to masquerade as other users for testing purposes. It is recommended that you set this value to false in a production environment.
RouteManagerPool.numWorkers – The appropriate value for this depends on the capabilities of your production hardware. If it's set too high, KEW may use so much of the CPU that other applications running on the same machine are adversely impacted.
RouteManagerQueue.waitTime - In test environments, users tend to be more sensitive to immediate feedback since they may be testing processes over the course of a couple minutes that, in practice, occur over a number of days. In test environments, it is recommended that you keep this value low. In a production environment, you can reasonably increase this value without affecting the speed at which documents are routed. This reduces thrashing on the route queue.
RouteQueue.isRoutingByIPNumber - If you are running your production KEW system in a clustered environment, set this value to false. This allows processing of documents in the queue to be distributed across the entire cluster, which enhances routing performance and facilitates load balancing.
RouteQueue.maxRetryAttempts - As with the RouteManagerQueue.waitTime constant, in a test environment it is important to find out as quickly as possible if a document is going to go into exception routing (usually indicating a problem in that document's routing setup). In a production environment, it may make sense to allow a longer period before a document goes into exception routing. This constant, in combination with the RouteQueue.timeIncrement constant, determines how long it takes a document to be put into exception routing.
RouteQueue.timeIncrement - Increasing this value results in a longer time before a document goes into exception routing.
KEW relies on XML for data population and routing configuration. XML Ingester is available from the Administrator channel in the portal. This allows import of various KEW components from XML, such as DocumentTypes, RuleAttributes, Rules, Workgroups, and more.
The Route Queue is the main scheduling mechanism in KEW. You use it to schedule documents for asynchronous routing and to queue arbitrary units of work. The database polls for new entries depending on the value set for the RouteQueue.waitTime constant. When KEW places a document into exception routing, it may become stuck after a series of failed attempts. You can use the Route Queue UI to resolve this issue, as well as to fix new entries, if needed.
The main Route Queue screen:
Examining this sample screen, we see there are five entries in the route queue, one on each row. The columns display information about each entry:
Route Queue Id - The primary key of this route queue entry in the data store
Route Header Id - The identifier of the document that is being processed by this entry. If this value is -1, it means the entry doesn't pertain to a specific document.
Queue Priority - The priority of the entry in the queue, where entries with the lowest number are processed first
Queue Status – The entry can be in a state of QUEUED, ROUTING, or EXCEPTION:
A QUEUED entry is waiting for a worker thread to pick it up.
A ROUTING entry currently has a worker working on it.
An EXCEPTION entry has a problem and the route manager cannot access it. An administrator manually sets an EXCEPTION status to suspend a route queue entry until a problem can be diagnosed.
Queue Date - The date that KEW should process this queue entry. If the queue checker runs and discovers the queue date for an entry is equal to or earlier than the current time, it processes that entry.
Retry Count - The number of times KEW has attempted to process the entry
IP Number - The IP address of the machine on which the entry was created. In the environment pictured, we have three machines in our cluster. The IP number shows from which machine each entry was queued up.
Processor Class Name - The name of the Route Queue processor with which this entry will be processed. If empty, this defaults to the Route Queue processor that submits the document to the Routing Engine for processing.
Processor Value - The parameters to be passed to the Route Queue processor
Action - The Edit link in the Action column allows you to edit the route queue entry.
Once a queue entry has been successfully processed, it is deleted from the queue.
In the screen shot above, we see two entries with special Processors. One of these special Processors is sending daily email reminders. The other one is sending weekly email reminders. When these entries are picked up from the queue, they do their work and then queue themselves back up for a day (or a week) later. Therefore, these entries never really leave the queue.
Of the other three entries, we can see that two have a status of ROUTING while one has a status of QUEUED. What this means is that, at the instant that this screen shot was taken, the two that are ROUTING have been picked up by the route manager and are being processed. The one that is QUEUED will be picked up the next time that the route manager checks the queue.
Sometimes it is necessary to manually edit a route queue entry that is halted inside of the queue. This situation might happen when:
KEW encounters an error trying to put the document into exception routing. This could occur if there is a database error or the document's PostProcessor throws an exception when it's notified of a status change
KEW is improperly shut down in the middle of an entry being processed
The database goes down while an entry is being processed
In all cases, the status of the entry is ROUTING, but there is no longer a worker thread processing the entry. Currently, KEW doesn't implement any auto-detection of failure cases. To put one of these entries in a state where it can be picked up by the route manager again, simply click the Edit link and set the entry’s status back to QUEUED. Here's a screen shot of the Route Queue Entry - Edit screen:
Use the Queue Status dropdown list to change the status of the entry. You may also want to set the Retry Count to zero to allow you to diagnose the problem before the document goes into exception routing.