How to requeue failed agent items with the Broken Queue Items report
Summary
Broken Queue Items report.
Suggested Approach
When an agent wakes up, the system checks that agent’s queue for entries; if entries are there, the system begins processing the first entry. The agent activity is run for that entry; if the processing succeeds, the changes are saved; if it fails, all the changes are rolled back. (See Overview of agent processing)
Most agent processing involves work objects. As part of the background queue functionality, the agent attempts to obtain a lock on the work object being processed before making any changes to it.
Agent processing can fail for two main reasons:
- The agent cannot obtain the lock on the work object (often because a requestor already holds a lock on it)
- The agent acquires the lock, but the processing fails for some other reason, and the changes are rolled back
In V5.4+, for both of these situations, this task remains in the agent’s queue with a status of Broken-Process.
IMPORTANT: As stated in How agent queues work, tasks are left in the agent queue only if the Agent Queue Manager (AQM) is enabled
If the AQM is disabled, then as soon as a task is retrieved from an agent queue for processing, it is removed from that queue. If the processing fails for any reason, that task is lost. Therefore, it is best practice to leave AQM enabled.
Repairing broken queue items:
A system administrator can in some cases, repair individual queue entries whose status is Broken-Process, by resetting them using the Broken Queue Items report.
1. On PRPC 6.1 and lower, from the View menu, choose System > Broken Queue Items.
NOTE: This menu choice requires the user to hold a "sysadm4"-level access role.
On PRPC6.1 and higher, click Pega button . This menu selection runs the standard list view report System-Queue-.BrokenItems.All. Users who hold the @baseclass.ReconcileBrokenQueueItems privilege can resubmit or delete broken queue items.
A list of all classes which inherit from the System-Queue- class appears:
2. Click one radio button to select the class where the broken queue entries you wish to process are defined, and click Execute View. The Broken System Queue Items report appears with information about each broken queue item.
The following buttons appear at the top right of the window:
Button | Purpose |
|---|---|
Refresh | Refreshes this list (in case other agents have run and added Broken Process entries to the list).Click to see whether additional items have been added to the list since you last displayed it. |
Select All | Selects all entries in the list. Click to process all entries at once, instead of processing them one at a time. |
Deselect All | Deselects all entries in the list. |
Requeue | Changes the Item Status of the selected entries from Broken-Process to Scheduled. Click to reenter items you selected into the agent’s queue, so the agent may try again to process them. |
Delete | Removes the selected items from the queue. Clicking to delete all the tasks you selected. If you choose to clear these “broken” tasks out of the system, the processing they request will not be retried by the agent. |
3. Determine how you wish to repair the broken item, and then use the buttons to either requeue the tasks or delete them.