7.3.3. Correlation Keys

A common requirement when working with processes is ability to assign a given process instance some sort of business identifier that can be later on referenced without knowing the actual (generated) id of the process instance. To provide such capabilities, jBPM allows to use CorrelationKey that is composed of CorrelationProperties. CorrelationKey can have either single property describing it (which is in most cases) but it can be represented as multi valued properties set.

Correlation capabilities are provided as part of interface

CorrelationAwareProcessRuntime

that exposes following methods:

  /**
  * Start a new process instance.  The process (definition) that should
  * be used is referenced by the given process id.  Parameters can be passed
  * to the process instance (as name-value pairs), and these will be set
  * as variables of the process instance.
  *
  * @param processId  the id of the process that should be started
  * @param correlationKey custom correlation key that can be used to identify process instance
  * @param parameters  the process variables that should be set when starting the process instance
  * @return the ProcessInstance that represents the instance of the process that was started
  */
  ProcessInstance startProcess(String processId, CorrelationKey correlationKey, Map<String, Object> parameters);

  /**
  * Creates a new process instance (but does not yet start it).  The process
  * (definition) that should be used is referenced by the given process id.
  * Parameters can be passed to the process instance (as name-value pairs),
  * and these will be set as variables of the process instance.  You should only
  * use this method if you need a reference to the process instance before actually
  * starting it.  Otherwise, use startProcess.
  *
  * @param processId  the id of the process that should be started
  * @param correlationKey custom correlation key that can be used to identify process instance
  * @param parameters  the process variables that should be set when creating the process instance
  * @return the ProcessInstance that represents the instance of the process that was created (but not yet started)
  */
  ProcessInstance createProcessInstance(String processId, CorrelationKey correlationKey, Map<String, Object> parameters);

  /**
  * Returns the process instance with the given correlationKey.  Note that only active process instances
  * will be returned.  If a process instance has been completed already, this method will return
  * null.
  *
  * @param correlationKey the custom correlation key assigned when process instance was created
  * @return the process instance with the given id or null if it cannot be found
  */
  ProcessInstance getProcessInstance(CorrelationKey correlationKey);

Correlation is usually used with long running processes and thus require persistence to be enabled to be able to permanently store correlation information.