JBoss jBPM gets a correlation identifier for process instances

This is a community project posting to bring some news that might have skipped your attention in the flood of work being done to get the project ready for release v6. It is a feature I have been personally looking forward to that allows you to search for and find your process instances based on an identifier, we call this a Correlation Id.

What it would be good for is for example if you want to have an exception framework to handle your process exceptions in a consistent manner and remain in the process layer of your architecture, such as done in older versions of jBPM.

A description of the problem and the solution can be found in the issue at the project site, but for posterity I have places the listed example code on how to make use of this here.

CorrelationKeyFactory factory = KieInternalServices.Factory.get().newCorrelationKeyFactory();

// create your kbase here.
// create your ksession here.

CorrelationKey key = factory.newCorrelationKey("mybusinesskey");

// start process instance.
//
ProcessInstance processInstance = ((CorrelationAwareProcessRuntime)ksession).startProcess("com.sample.bpmn.hello", getCorrelationKey(), null);

// next the process instance can be found be correlation key:
//
ProcessInstance processInstanceCopy = ((CorrelationAwareProcessRuntime)ksession).getProcessInstance(key);

// Since CorrelationKey support is introduced to internal API it requires additional 
// cast to get access to correlation based methods.
//
// The above example code shows single valued CorrelationKey but multi valued correlation 
// keys are supported as well. To create multi valued correlation key:
//
List properties = new ArrayList();
properties.add("customerid");
properties.add("orderid");
CorrelationKey multiValuedKey factory.newCorrelationKey(properties);


// Then such key can be used exactly same way as single valued key is used.
//
// CorrelationFactory is responsible for providing the right instances of 
// CorrelationKey and shall be always used to build CorrelationKey objects.
//
// CorrelationKey does not have to be stored to be able to use it later on, 
// e.g. to retrieve process instance meaning can be recreated whenever it is 
// needed. Look up is based on values. In case of multi valued keys best is to 
// keep same order of properties every time correlation key is recreated.

Many thanks to the core jBPM team for getting this in there. Sometimes the small things are what makes our lives easier! ;-)