Querying for Step Elements or Work Objects

Querying a Queue

To query a queue for Step elements or WorkObject elements, do the following actions:

1. If you do not already have a VWSession object, you must log in to the Content Platform Engine server and establish a workflow system session that uses VWSession.
2. Get the wanted queue by calling VWSession.getQueue().

   Alternatively, you might want to display a list of queues. See Displaying a List of Queues for this information.

3. Create a query on a queue by calling VWQueue.createQuery().
   Tip:

   • To help optimize query performance, you can specify a database index that is associated with a queue. For more information, see Managing workflow indexes.
   • For even greater efficiency, you can set the QUERY_LOCK_OBJECTS flag in the queryFlags parameter of the createQuery() method. Doing so locks the work items that are returned. In this case, you might skip the next step.
4. Lock the retrieved Step, WorkObject element, or both items as soon as they are retrieved by using VWStepElement.doLock() or VWWorkObject.doLock.
5. If appropriate, use VWQueueQuery.next() to call the next VWQueueElement, VWStepElement, or VWWorkObject.
6. If appropriate, display the queue query results. An efficient way to display the queue query results is to use the sample helper class QueueHelper.displayQueueContents().

Optimizing Queries

To help optimize your queries on queues:

• Use indexes and filters for more efficient queries. Indexes must be unique. Use filters for the following purposes:
  • To limit the retrieved elements to a specified range
  • To set the maximum number of objects that are to be retrieved for each fetch from the Content Platform Engine server (see VWQueue.setBufferSize)
• Minimize the amount of return data by not retrieving system fields and helper data from the work items that are returned. To do so, set one of more of the following query flags in the queryFlags parameter of VWQueue.createQuery(): QUERY_GET_NO_SYSTEM_FIELDS and QUERY_GET_NO_TRANSLATED_SYSTEM_FIELDS.

Example: Querying a Queue

The following Step Processor sample illustrates how to query a queue to retrieve a VWStepElement object. Logger and SessionHelper objects are created. Comments and code that are related to querying a queue are in bold.

This code uses the QueueHelper (helper class) sample. See also StepProcessor Sample.

import filenet.vw.api.*;

/*
* This sample Step Processor class illustrates how to retrieve,
* modify, and complete a step using the VWStepElement class.

*/
public class StepProcessorSample extends Object
{
    // declare variables

    /*
     * Constructor - performs initialization and establishes
     *  the Process session.
     */
        public StepProcessorSample(VWSession vwSession, Logger logger, String queueName)
        {
            QueueHelper     queueHelper = null;
            VWQueue         vwQueue = null;
            VWStepElement   vwStepElement = null;

                try
                {
                logger.logAndDisplay("\n~ Starting StepProcessorSample execution.");

            // create the helper class
            queueHelper = new QueueHelper(vwSession, logger);

            // get the requested queue
            vwQueue = queueHelper.getQueue(queueName);
            if (vwQueue != null)
            {
                // get a step element
                vwStepElement = queueHelper.getStepElement(vwQueue);
                if (vwStepElement != null)
                {
                    // lock the record
                    vwStepElement.doLock(true);

                    // set the comments
                    vwStepElement.setComment("This is the user's comment.");

                    // display the Step Processor information
                    logger.displayStepElementInfo(vwStepElement);

                    // complete the step
                    logger.log("Completing step: " + vwStepElement.getOperationName());
                    vwStepElement.doDispatch();
                }
                    }
                }
                catch(Exception ex)
                {
                if (logger != null)
                    logger.log(ex);
            else
                ex.printStackTrace();
                }
                finally
                {
                if (logger != null)
                    logger.logAndDisplay("~ StepProcessorSample execution complete.\n");
                }
        }

    /*
     * Creates the Logger and SessionHelper objects, then
     * instantiates the outer class.
     */
    public static void main(String args[])
        {
            String                  queueName = null;
            String                  outputFileName = null;
            Logger                  logger = null;
            SessionHelper           sessionHelper = null;
            VWSession               vwSession = null;
            StepProcessorSample     sampleClass = null;

            try
            {
                // did the user supply enough arguments?
            if (args.length < 4 || (args.length > 0 && args[0].compareTo("?") == 0))
                {
                    System.out.println("Usage:  StepProcessorSample username password router_URL queueName [output_filename]");
                    System.exit(1);
                }

                    // the file name (for output) is optional
                if (args.length > 4)
                    outputFileName = args[4];
               else
                    outputFileName = new String("StepProcessorSample.out");

                // create and initialize the logger
                logger = new Logger(outputFileName);

                // create the session and log in
                sessionHelper = new SessionHelper(args[0], args[1], args[2], logger);
                vwSession = sessionHelper.logon();
                if (vwSession != null)
                {
                    // create the sample class
                    sampleClass = new StepProcessorSample(vwSession, logger, args[3]);
                }
            }
            catch (Exception ex)
            {
                if (logger != null)
                    logger.log(ex);
            else
                ex.printStackTrace();
        }
        finally
        {
                // logoff
               if (sessionHelper != null)
                    sessionHelper.logoff();
        }
    }
}