Using Indexed Properties to Perform Extended Queries with ActiveBPEL Designer

Introduction

ActiveBPEL Designer provides an extended query mechanism by which specific process instances may be selected using the Administration Console. To use this query capability, indexed properties must be defined during deployment as part of the Process Deployment Descriptor construction.

Once deployed, processes with indexed properties can be selected using the Additional query filtering capability in the Active Process screen of the Administration Console. This can be useful when the administrator wishes to select, say, all faulted process instances that have a certain message part value (e.g., purchase order total >= $1000.00, etc.). Further operations can be performed on the filtered list of active processes, in conjunction with ActiveBPEL Server's process administration functions.

This sample demonstrates the definition of an indexed property during creation of the PDD, and shows how to use the Active Processes filtering capability to perform extended queries using this property. This simple example can be extended in order to provide complex filtering capability using multiple indexed properties across multiple processes.

Objectives

• Define an indexed property while deploying two different processes.
• Perform extended queries in the ActiveBPEL Server Administration Console to locate process instances using this indexed property.

Getting Set Up

The files provided with this sample are contained in the example archive. You may extract this archive into a directory of your choosing. The archive contains numerous directories with an ActiveBPEL Designer project containing various support files.

In ActiveBPEL Designer, select File / Import / Existing project into workspace and navigate to the following project directory

/extended_query

This will open a project called extended_query, with various supporting directories. The project contains the .bpel, supporting WSDL and completed versions of the .pdd files that are produced in this example.

Deploying The Loan Risk Assessment Application

This example comprises two BPEL processes, which are deployed as web services in order to create a 'loan risk assessment' application. The first process - extended_query.bpel - will invoke the second - eq_smallloanapproval.bpel - to determine whether a loan is approved or not depending upon the amount requested.  If you've worked with the "Invoke with Inline Fault Handler" example, these two processes should be familiar to you. If not, you can review that example or open the two .bpel files in Designer to see how they work. The function of these processes is not terribly important to our use of indexed properties, however. Either way, if you have the processes from the "Invoke with Inline Fault Handler" deployed, you should un-deploy them to prevent any confusion.

To deploy these two processes to ActiveBPEL Server as web services, we need to create a Process Deployment Descriptor for each.  It is in this Descriptor that we will define the indexed property we want to use to do our extended queries later on.

In Designer, locate the extended_query.bpel file in the Navigator view. Right click on this file and select New / Deployment Descriptor. The New Deployment Descriptor Wizard appears. On the first page, select ActiveBPEL Enterprise (note: this functionality is not available in the ActiveBPEL® Engine) and click Next. On the next page, click Next to accept the default storage and versioning selections.

On the Partner Links page, select the riskAssessmentLinkType Partner Link and change the Service down under My Role to riskAssessmentService. Leave the Binding set to Message. Then select the smallLoanApprovalLinkType Partner Link and select an Endpoint Type of static down under Partner Role. The Endpoint Reference definition information appears automatically. Click Next.

The Indexed Properties page appears. Click the Add... button. Here we can define any name we wish. We'll be filtering on the loan request amount, so enter Amount for the Name. For Type, select double. For Variable Path, select /process/variables/variable[@name='creditInformationMessage'] (enlarge the dialog by dragging its edges, if necessary, to see the full selections) and for Part, select amount. Leave the Query blank and click OK. Click Finish to create the PDD, which should appear as follows:

Note that you may need to modify the "http://localhost:8080" reference if your server is located on a different host/port.

The indexedProperties section holds our indexed property definition: Amount. If you're not using Designer to create your PDD, you can use a text editor to create the above file (or see extended_query_complete.pdd for the completed PDD). Note that although the amount part type is defined as xsd:integer, it is necessary to promote it to a double here for querying purposes, since there is no "integer" type provided.

Perform these same steps to create a PDD for the eq_smallloanapproval.bpel process. On the Partner Links page select the approver Partner Link, select an RPC Binding under My Role and leave the Service as approverService. The Indexed Property definition will be the same (e.g., Name = Amount, Type = double, Part = amount), except that you'll select the /process/variables/variable[@name='request'] Variable Path. See eq_smallloanapproval_complete.pdd for the completed PDD.

Finally, deploy both of these processes to your server by right-clicking on the PDD, selecting Export... and then Business Process Archive, etc. For detailed information on Process Deployment, see the ActiveBPEL Designer tutorial in the Online Help. For information on manual construction and deployment of the business process archive, see Deploying a BPEL Process.

Invoking the Process(es) and Querying

The support/data folder of the extended_query project contains a test message: testInvoke.xml.

You can submit this message to the riskAssessmentService using the soapUI web service client application. Use a WSDL URL of http://localhost:8080/active-bpel/services/riskAssessmentService?wsdl (adjust hostname or port to match your server) and copy the above values to the request message. Click the green Send Request button to send the message. You should see the following reply:

If you don't see this, troubleshoot the problem before moving on.

Open a browser and navigate to the ActiveBPEL Server Administration Console at http://localhost:8080/BpelAdmin/ (adjust host and port if necessary to match your server). Select the Active Processes menu item to view the full set of process instances that have completed, faulted or are still running. You can use the Selection Filter to narrow the process instances displayed, and this is where Extended Queries come in to play.

To locate the process instance(s) for the request we just submitted, click the "..." button below the Additional query textbox.  The Expression Builder appears. Note that our Indexed Property - Amount - appears under Indexed Properties.  Double-click on Amount. The text " getIndexedPropertyValue("Amount") " appears in the Query textbox. This is the XPath 2.0 function extension used to access the Amount property. To complete the query, type "= 500" (without the quotes). The finished query will be:

 getIndexedPropertyValue("Amount") = 500   

This is our extended query. Click OK, and then click Submit. After a moment the list of process instances refreshes and we see instances of smallLoanApprovalProcess and InvokeWithCatch - the process names for the two processes we deployed above. You can click on the Process Name or ID to bring up an instance's Process Details to verify the value.

Go back to soapUI and modify the request message. Change 500 to 1000. Submit the request.

Return to the Active Process screen and submit the query again (without changing it). The same two process instances appear. Now change '500' to '1000' in the Additional query textbox. Two different process instances (note the ID values) appear. Now change '= 1000' to '>= 500' and click Submit.  All four of the process instances appear, as their amount values match that expression.

You can experiment further by adding new indexed properties and re-deploying your process(es) or modifying the Additional query as well as the other Selection Filter criteria to fine-tune the filtering of the Active Processes list to suit your needs.

Copyright © 2004–2007 Active Endpoints, Inc.