Programmatically Querying the status of BPEL process-instances

During a recent presentation I did on the NL-JUG J-Spring Conference (the Dutch Java User Group) on the interaction between Oracle BPEL PM and Java applications, I got asked how we can inspect the status of a BPEL Process instance from our own application, i.e. programmatically. Of course I knew it had to be possible, as the BPEL PM Console is doing exactly that, but I did not yet know the exact API for doing this. During ODTUG 2006 I briefly discussed it with Clemens Utschig and just few minutes ago I came across the perfect blog article addressing this question: Querying BPEL Process Instances by Matt Wright – who has an excellent blog on Oracle BPEL PM.

The context for this particular question was the following: customers register for certain services from a Tele-communications service provider, via a website. Each registration would initiate a BPEL Process instance, that may run for several hours or even days, depending on the actual request. The TelCo service provider wants to allow its customers to monitor the progress of their request via the same website they used to submit it. A tailor-made BPEL console you can say.
Using the programmatic interface described by Matt Wright, this is fairly easy to achieve.

Queries against the BPEL API are turned into queries against the Dehydration Store – the Oracle Lite (default) or other relation database that sits underneath the Oracle BPEL PM. Queries typically are performed in two steps:

1. locate the process instance – using fairly straightforward where-clauses on status, Process_Id, Revision_Tag, Priority. Furthermore we can index-values – user defined identifiers to find process instances by, such as Invoice Number, Customer Identification etc. The index is set within the BPEL Process Instance (using a piece of embedded Java with the Java Embed Task at the start of the process to call the setIndex API to set the index value based on a value in the initial message: setIndex(1,((com.collaxa.cube.xml.dom.CubeDOMText) getVariableData(“input”, “payload”, “/auto:loanApplication/auto:customerName/text()”)).getText());

2. query the process instance for its status and the values of process variables, using code like: Element loanApplicationElement = (Element) instanceHandle.getField(“LoanApplicationSummary”);. This will return a DOM (Document Object Model) representing the XML contained within the process variable. You can use the actual DOM API to parse and manipulate the XML content.

While Matt’s article provides the perfect answer to my question, I am not overjoyed with the actual implementation. I would have liked to be able to search process instances for the values of their variables. For example: find me all loan applications for amounts over $100.000. The only way to achieve that it seems is by embedding the indexes into the process itself, which feels like cluttering up the BPEL Process definitions. Then again, it gives me the functionality I desire, so let’s just be grateful! Thanks Matt!

By the way, the JavaDoc for the Oracle BPEL PM Client classes is located at: http://download-uk.oracle.com/docs/cd/B14099_19/integrate.1012/b25709/toc.htm