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. Thus, a required operation of any Step Processor is to retrieve the work items for that step by querying the queue that holds those work items (or several queues; there may be more than one).

This topic provides a description of Process Engine queues, describes how to specify a query on a queue for a Step Element or work object, provides some tips to help you optimize your queries and provides a sample Step Processor class that illustrates how to query a queue to retrieve a VWStepElement object.

Subtopics include:

Overview of Process Engine Queues

A Process Engine queue is a database structure that holds work items that are waiting to be completed for a specific step in the workflow. There are four types of Process Engine queues:

As indicated, all work items for a particular step in a workflow reside in either a User queue or a Work queue. The work items in a queue may be Step Elements (records consisting of helper data and user-defined parameters), Work Objects (each work object is a BLOB that consists of system fields, helper data, and user-defined fields — Note that the queue contains the actual work object BLOB), or Queue Elements (each Queue Element contains system fields that describe the work item and its state; Queue Elements are typically used to display the work item's status).

In most cases, you query a queue for Step Elements, which is the most common type of query on a step. Normally, the only circumstance under which you would query for work objects would be when you need to get all the data and expose those parts you are interested in.

Querying a Queue - What To Do

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

Note For details on these APIs, see the Process API JavaDoc documentation.

  1. If you do not already have a VWSession object, you must login to the Process Engine server and establish a Process session using the VWSession API.
  2. Get the desired queue by calling the getQueue() method to create an instance of the VWQueue class.
  3. Create a query on a queue by calling the createQuery() method to obtain a VWQueueQuery object. The VWQueue.createQuery() method takes parameters which specify which work items (and which "view" of them) will be fetched with a subsequent next() method call (see Step 6 below).

    Note Views are provided by the following API classes used to access queue work items:

  4. When using VWQueue.createQuery(), you can specify the index name (the index name is the name assigned to an index on this queue using the Configuration Console) to optimize your query. The index must be the name of an exposed field, such as a user-defined field (see Tips for Optimizing Queries below). In addition, you may wish to set the QUERY_LOCK_OBJECTS flag in the queryFlags parameter of the createQuery() method to lock the work items returned from a search (thereby eliminating the need for Step 5).
  5. Lock the retrieved Step and/or WorkObject element as soon as it is retrieved (the doLock() method is available for all API "fetch" methods). Note that using the QUERY_LOCK_OBJECTS flag with the createQuery() method (Step 4) enables you to avoid another RPC to lock or check the lock on the work item.
  6. If appropriate, use the VWQueueQuery.next() method to call for the next VWQueueElement, VWStepElement, or VWWorkObject.

Tips for Optimizing Queries

Here are some additional tips to help optimize your queries on queues:

Sample Step Processor Class Illustrating a Query

The following sample Step Processor class illustrates how to query a queue to retrieve a VWStepElement object, including creating Logger and SessionHelper objects and instantiating the example StepProcessorSample class. Comments and code related to querying a queue are bolded.

// --------------------------------------------------------------------------
// StepProcessorSample.java
// --------------------------------------------------------------------------

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