Querying Queues and Displaying Query Results

All work items for a particular step in a workflow definition reside in a queue — typically either a User queue (holds work items waiting to be processed by a specific user) or a Work queue (holds work items that can be completed by any one of a group of users or by an automated process). A required operation of any User Inbox (User Tasks Page) is to retrieve the work items for a user or Tracker by querying the queue that holds those work items (or several queues; there may be more than one).

The work items in a queue for a workflow step include Queue Elements (each Queue Element contains system fields that describe the work item and its state at a point in time), Step Elements (records consisting of helper data and user-defined parameters), and 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). For User Inbox queries, you will most typically query for Queue Elements to display the work items to the user. You may also query for Step Elements. In most cases, you will only query for Work Objects when you need to get all the data associated with the work item and then expose only those fields you are interested in.

This topic describes how to query queues for Queue Elements, Step Elements, or work objects, provides some tips to help you optimize your queries, and an example QueueQueryDisplay class that illustrates how to query a queue to retrieve a QueueElement object.

Subtopics include:

Querying a Queue - What To Do

To query a queue for Queue Elements, 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 Queries below).
  5. If appropriate, use the VWQueueQuery.next() method to call for the next VWQueueElement, VWStepElement, or VWWorkObject.
  6. Display the queue query results; for example, use the displayQueueContents() method as illustrated in the QueueHelper API sample. For example:

    displayQueueContents(VWQueue vwQueue);

Tips for Queries

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

Example QueueQueryDisplay Class

The following example QueueQueryDisplay class illustrates how to query a queue to retrieve VWQueueElement objects and then display them. It also illustrates creating QueueHelper, Logger, and SessionHelper objects (e.g., using the QueueHelper and SessionHelper API sample helper classes) and instantiating the example QueueQueryDisplay class.

// --------------------------------------------------------------------------
// QueueQueryDisplay.java
// --------------------------------------------------------------------------

import filenet.vw.api.*;

/*
* This sample QueueQueryDisplay class illustrates how to query queues
* and display queue results using the VWQueueElement class.

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

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

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

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

            // get the requested queue
            vwQueue = queueHelper.getQueue(queueName);
            if (vwQueue != null)
            {
                // get a Queue Element
                vwQueueElement = queueHelper.getQueueElement(vwQueue);
                if (vwQueueElement != null)
                {

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

                    // display the Queue Element information
                    logger.displayQueueElementInfo(vwQueueElement);

                }
                {
                  // display the queue contents
                  displayQueueContents(VWQueue vwQueue);
                }
                    }
                }
                catch(Exception ex)
                {
                if (logger != null)
                    logger.log(ex);
            else
                ex.printStackTrace();
                }
                finally
                {
                if (logger != null)
                    logger.logAndDisplay("~ QueueQueryDisplay execution complete.\n");
                }
        }

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

            try
            {
                // did the user supply enough arguments?
            if (args.length < 4 || (args.length > 0 && args[0].compareTo("?") == 0))
                {
                    System.out.println("Usage:  QueueQueryDisplay 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("QueueQueryDisplay.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 QueueQueryDisplay(vwSession, logger, args[3]);
                }
            }
            catch (Exception ex)
            {
                if (logger != null)
                    logger.log(ex);
            else
                ex.printStackTrace();
        }
        finally
        {
                // logoff
               if (sessionHelper != null)
                    sessionHelper.logoff();
        }
    }
}