Querying Process Instance Details

The ProcessInstanceQuery class is provided for building queries on process instances. The following section describes example use cases.

Querying Process Instances filtered by a Field in a Structured Data

This example demonstrates how to query process instances filtered by a field in a structured data.

Use Case Definition

Let us assume we have a process definition with the id StockDividend which uses a structured process date named CorporateAction having a field of type String with the id ISIN.

We like to search for all StockDividend process instances, where the ISIN field in the data CorporateAction has a specific value.

Example API

The following code example implements such a search. It queries for all StockDividend process instances with value US0378331005 in the ISIN field in the data CorporateAction.

The findForProcess method limits the query to a specific process definition. The DataFilter then limits the result to process instances having the data with the specified value.

If you use a process data for such queries then you should consider making it a descriptor. Process data (fields) that are used as descriptors are stored in an index. Therefore queries filtered by descriptors are way more efficient than queries using regular process data (fields).

For details on how to declare a descriptor, refer to section Setting Descriptors of chapter Working with Data Paths.

package test;
import java.util.Iterator;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.eclipse.stardust.engine.api.query.DataFilter;
import org.eclipse.stardust.engine.api.query.DescriptorPolicy;
import org.eclipse.stardust.engine.api.query.ProcessInstanceQuery;
import org.eclipse.stardust.engine.api.query.ProcessInstances;
import org.eclipse.stardust.engine.api.runtime.ProcessInstance;
import org.eclipse.stardust.engine.api.runtime.QueryService;
import org.eclipse.stardust.engine.api.runtime.ServiceFactory;
import org.eclipse.stardust.engine.api.runtime.ServiceFactoryLocator;
import org.eclipse.stardust.engine.api.dto.ProcessInstanceDetails;
public class QueryTest {
	public static final Logger log = LoggerFactory.getLogger(QueryTest.class);
	public static void main(String[] args) {
		ServiceFactory sf = ServiceFactoryLocator.get("motu", "motu");
		QueryService qys = sf.getQueryService();
		ProcessInstanceQuery piQuery = ProcessInstanceQuery.findForProcess("StockDividend");
		piQuery.where(DataFilter.isEqual("CorporateAction","ISIN", "US0378331005"));
		ProcessInstances pis = qys.getAllProcessInstances(piQuery);
		for (Iterator iterator = pis.iterator(); iterator.hasNext();) {
			ProcessInstance pi = (ProcessInstance) iterator.next();
			ProcessInstanceDetails details = (ProcessInstanceDetails)pi;
			log.info("PI:" + pi.getOID() + " ISIN:" + details.getDescriptorValue("ISIN"));

For details on the API used in the code refer to the according Javadoc:

Querying Process Instance Details including Historical Data

To query for process instance details including historical data, use the HistoricalDataPolicy and set it to INCLUDE_HISTORICAL_DATA as in the following example:

ProcessInstanceQuery piQuery = ProcessInstanceQuery.findAll();


ProcessInstances pis = sf.getQueryService().getAllProcessInstances(piQuery);

List<Serializable> historicValues = CollectionUtils.newList();

for (ProcessInstance pi : pis)
   if (pi.getOID() == this.piOid)
      List<HistoricalData> histDataList = ((ProcessInstanceDetails) pi).getHistoricalData();
      for (HistoricalData histData : histDataList)

Note that historical data is only written to the historical database in case the property Stardust.Engine.Data.WriteHistoricalDataToDb is set to true in your carnot.properties file.

Additionally you can set the prefetch batch size for the historical data through property Carnot.Engine.Tuning.Query.HistoricalDataPrefetchBatchSize. The default value is 400.

Please refer to section AuditTrail / Schema of chapter Server Side Properties for details on these properties.