How Agent Queues Work
Summary
An agent queue is an ordered list of "task-driven" processing that each agent must perform.
Suggested Approach
There are two types of processing that agents perform: task-driven and schedule-driven processing. Examples of task-driven processing may include:
- correspondence: a work object generates the correspondence, and an agent sends it
- assignments: a work object generates an assignment, and an agent processes the assignment
Schedule-driven processing may include:
- running a report every morning to list yesterday's calls
- running the system cleaner (to clean up abandoned requestors)
These scheduled tasks do not require entries into an agent queue, as they are not linked to specific user work objects, but are part of overall processing.
As users do work, their work objects may generate the “task-driven” entries such as correspondence or assignments. These tasks are automatically entered into the agent queue as they occur (see How to enter items into the Agent Queue for details); the appropriate agents then process them at intervals.
Unless other time settings are configured, the entries are processed in the order in which they were created in the agent queue.
The Agents form contains two fields which hold queue information for each agent:
- Queue Mode
- Auto Queue Manager
NOTE: Neither of these two fields will be visible on the Agent Schedule form; they are only available on the Agents rule.
Queue Mode
The Queue Mode tells the system how this agent should interact with the queue when running the agent activity. Beginning in Version 5.4, agent functionality is enhanced to separate out the transactional processing (such as locking the item being processed, or doing commits or rollbacks) from the business logic processing. The system handles the transactional steps; the agent activity should only contain business processing steps.
There are three Queue Mode values:
Legacy
Standard
Advanced
Legacy
For applications upgraded from versions before Version 5.4, agents have the Queue Mode field set to Legacy.
These agents run as in prior versions: when an agent “wakes up,” it runs the activity directly, without using a queue. It is assumed that all the transactional processing steps are in the agent activity, as well as the business processing.
Agents created in Version 5.3 or earlier versions, cannot use the agent queue features unless you rewrite the agent activity. The Legacy
mode provides backward compatibility until you rewrite these activities. (See How to upgrade a Legacy agent)
When the Queue Mode is set to Legacy
, you can resave the Agents rule form to a higher version of the RuleSet; however, a warning appears at the bottom of the form:
>>Warning>>: One or more agents are in Legacy Mode. Please see “Upgrading an Existing Agent” on the PDN to upgrade these.
NOTE: This Legacy setting is not valid for agents you create in V5.4; it only appears for agents created in lower-numbered versions.
Standard
The default Queue Mode setting for agents created in V5.4 is Standard
. Standard mode assumes that the transactional processing will be handled by the agent queue functionality, and that the agent activity will contain only business logic.
When the Mode is set to Standard
, then when the agent wakes up, it immediately checks the agent queue to see if there are any entries for that agent. If there are, it processes the entries until either the Max Records number of entries have been processed, or the queue is empty – whichever comes first. After this processing, the agent stops and goes “back to sleep” for its specified interval.
Advanced
In Advanced
mode, the agent activity is again responsible for both transactional and business processing. However, unlike the Legacy mode, the agent activity in Advanced mode may still use the agent queue functionality; it just must do so explicitly (rather than the Standard mode, where the agent queue is engaged automatically). So when the agent “wakes up,” it runs the activity directly, and that activity may either call the agent queue, or just do processing without a queue.
Auto Queue Manager
This checkbox is only valid for Standard Queue Mode agents.
This box is checked by default, which enables the Queue Manager (AQM). When AQM is enabled, then when a queue entry is retrieved for processing by the agent activity, the system locks that entry until a commit or rollback occurs at the end of processing. (This allows one agent/node to have exclusive rights to that queue entry; no agent on another node can process it.) If some kind of issue occurs (like the agent can’t get a lock on the work object), the task is re-queued automatically and can be set up to try again.
If AQM is disabled, then the system immediately removes entries from the agent queue, instead of locking them and leaving them in the database table. When QM is disabled, the system performs the commits or rollbacks on the items being processed, but the queue entry does not persist in the database. If a rollback occurs, that entry is now gone and cannot be requeued.
As a best practice, leave AQM enabled for all agents in Standard
mode.