Queue sweep troubleshooting

Attempts to process queue entries can fail. Depending on the underlying issue, the problem might or might not be fixable. In either case, failed queue entries require corrective action.

Resolving problematic queue entries

There are two types of problematic queue entries: deferrals and failures.

About this task

A deferral occurs when the sweep subsystem determines that a queue entry is not eligible for processing for a problem that can be corrected. For example, when an advanced storage area is used, a content deletion request is deferred if the content is on a storage device that is offline. A deferred queue entry is given a status of RETRY-WAIT.

A failure occurs when a queue entry cannot be processed due to an unexpected error that might or might not be correctable. For example, a content deletion request fails if the content does not exist in the storage area. A failed queue entry can have either a FAILED or RETRY-WAIT status, depending on how the MaximumFailures property is set on the queue sweep.

Finding problematic queue entries

You can find problematic queue entries by using the Queue Entries tab of a sweep. You can define a filter to view queue entries that meet specific criteria. For example, you can define a filter to view queue entries that have a status of Retry wait and a deferral count greater than or equal to 50.

In some cases, to properly troubleshoot the issue, you might need to filter the queue entries according to other properties that are not shown on the Queue Entries tab. To use more properties to filter the queue entries, perform an object store search. For example, to view deferred content deletion requests for documents that were created during the first week of September 2014, set the following criteria on the New Object Store Search > Simple View tab.

Search criteria	Value
Class	Content Deletion Queue Entry
Date Created	Greater Or Equal to 9/1/2014
Date Created	Less Or Equal to 9/7/2014
Queue Entry Status	Equal to 0
Deferral Count	Greater Or Equal to 50

Tip: To search for a specific queue entry status, use the following integer values:

Value	Status
0	Waiting
1	In progress
2	Retry wait
3	Failed

Resolving problematic queue entries

To resolve deferred queue entries, check that all required resources are available. After the queue entries become eligible for processing, the queue sweep automatically starts to process them.

The reason for a failed queue entry is stated in the entry's LastFailureReason property. If you can fix the problem for a queue entry with a RETRY-WAIT status, the queue entry will be successfully processed when it is scheduled for a retry. If you can fix the problem for a queue entry with a FAILED status, you must also reset the entry's FailureCount property to zero before processing restarts. For a few failed queue entries, you can select the queue entries on the Queue Entries tab of the sweep and click Actions > Reset Failure Count. To reset many failed queue entries, you can set up a custom sweep job.

If a queue entry failed and there is no way to fix the underlying problem, you can delete the queue entry. You can manually delete a queue entry from the Queue Entries tab of the sweep. To delete many queue entries, you can set up a disposal policy. When you create this policy, ensure that the filter expression includes the expression QueueEntryStatus=3 to identify the failed queue entries.

Tip: After the disposal policy finishes deleting the failed queue entries, delete or disable the policy. Alternatively, set an end date on the policy to prevent it from continuing to delete queue entries.

Resetting failed queue sweep entries

Thumbnail queue sweeps and custom queue sweeps stop processing failed queue entries after the number of failures exceeds a threshold. To restart the processing of failed queue entries, a property must be reset on each queue entry.

About this task

For most system implementations of queue sweeps, the maximum number of failures property is set to zero by default, meaning that the queue sweep attempts to reprocess failed queue entries an unlimited number of times. One exception is the thumbnail generation queue sweep, where the default maximum number of failures is three. Another exception applies to any user-implemented custom queue sweep where the default maximum number of failures is greater than zero. Each time a queue entry fails to process, the sweep service increments the failure count property on the queue entry. If the failure count value equals or exceeds the maximum number of failures set for the queue sweep, the queue entry property for the queue entry is set to a fail status and the queue sweep no longer processes the failed queue entry.

To restart the processing of failed queue entries, you must reset the failure count property on each queue entry. Although you can use Administration Console for Content Platform Engine to reset failed queue entries, creating a custom sweep job for this task is a faster and more convenient alternative for resetting large numbers of failed queue entries.

Procedure

To use a custom sweep job to reset the failed queue sweep entries:

Implement a sweep action handler that resets the failure count property on the failed queue entries to zero.

The following example is a simple JavaScript implementation. You might consider adding trace logging and error handling to your implementation.

importClass(java.lang.System);
importPackage(Packages.com.filenet.api.core);
importPackage(Packages.com.filenet.api.constants);
importPackage(Packages.com.filenet.api.engine);

function onSweep (sweepObject, sweepItems)
{
for (ii = 0; ii < sweepItems.length; ii++)
{
item = sweepItems[ii].getTarget();
item.set_FailureCount ( 0 );
item.save ( RefreshMode.NO_REFRESH );
sweepItems[ii].setOutcome(SweepItemOutcome.PROCESSED, "");
}
}

function onPolicySweep ( sweepObject, sweepPolicy, sweepItems) 
{
}

function getRequiredProperties() 
{
return '';
}

Create a custom sweep job.
Set the Filter expression property to the queue entries that are in a failed state.
For example: customJob.set_FilterExpression("QueueEntryStatus=3");
Set the Sweep target property to the queue sweep subclass with the failed queue entries.
For example: customJob.set_SweepTarget(Factory.ClassDefinition.getInstance(os, GuidConstants.Class_CmThumbnailRequest));