Resolved for 6.0, here comes a simple code snippet that illustrates the usage:
CorrelationKeyFactory factory = KieInternalServices.Factory.get().newCorrelationKeyFactory();
// create your kbase
// create your ksession
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<String> properties = new ArrayList<String>();
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. Lookup is based on values. In case of multi valued keys best is to keep same order of properties every time correlation key is recreated.