Querying for Step Elements or Work Objects

All work items for a particular workflow step reside in a queue, typically either a User queue and/or a Work queue. A required operation of any Step Processor is to retrieve the work items for the step by querying the queue (or queues) that holds the work items.

See About Queues for general information about Process Engine queues.

Querying a Queue

To query a queue for Step elements or WorkObject elements, at a minimum you should do the following:

  1. If you do not already have a VWSession object, you must log in to the Process Engine server and establish a Process session using VWSession.
  2. Get the desired queue by calling VWSession.getQueue().

    Alternatively, you may 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().

    When using VWQueue.createQuery(), you can specify the index name to optimize your query. An index name is assigned to a queue using the Configuration Console). The index must be the name of an exposed field, such as a user-defined field. For greater efficiency, you can also set the QUERY_LOCK_OBJECTS flag in the queryFlags parameter of the createQuery() method to lock the work items returned. In this case, you could skip the next step.

  4. Lock the retrieved Step and/or WorkObject element as soon as it is retrieved, 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 do this is to use the sample helper class QueueHelper.displayQueueContents().

Optimizing Queries

To help optimize your queries on queues:

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 related to querying a queue are in bolded.

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();
        }
    }
}