Process Instance Search

This article illustrates how to search for all the Process Instances that fulfill certain specific criteria. For example, you may search for the IDs of all the Process Instances with a specific attribute.

FNZ Studio Script Language offers predicate search over Process Instances, as well as predicate search over Users. A predicate search over Process Instances is faster than iterating over all Process Instances.

Introduction

Predicate search generates less network traffic and is faster than first retrieving all User objects and then iterating over them. The same reasoning applies to predicate search over Process Instances.

To find, say, the IDs of all persistent Process Instances with a given attribute, you can write:

Copy 
ProcessInstancePredicate $pip := new ProcessInstancePredicate();
$pip.setPersistent();
$pip.setProcessInstanceAttribute('attributeName', 'attributeValue');
Indexed String $processInstanceIds := ProcessInstanceIds($pip);
// do something with the process-instance IDs

In this snippet, a ProcessInstancePredicate object is created, and then the search criteria ("all persistent Process Instances" and "all Process Instances with an attribute with name attributeName and value attributeValue") are set on the predicate. Finally, the search is performed by calling ProcessInstanceIds with the predicate parameter.

This snippet executes a distributed search, collecting the IDs of all Process Instances that meet the predicate criteria locally on all cluster nodes. Only the IDs of the matching Process Instances are then sent back to the node making the call.

ProcessInstancePredicate Functions

The following two Script Functions provide predicate search over Process Instances:

  • ProcessInstanceIds(ProcessInstancePredicate)
  • LocalProcessInstanceIds(ProcessInstancePredicate)

The first function, ProcessInstanceIds, returns the IDs of all Process Instances that fulfill the criteria defined in the given predicate object.

The second function, LocalProcessInstanceIds, does the same predicate search, but only over those Process Instances that are managed by the node on which the function is called. (More precisely: LocalProcessInstanceIds goes only over those data objects representing Process Instances in the respective distributed map that are managed by the cluster node on which the function is called).

Both functions can also be invoked without a parameter. Doing so returns all, or all locally owned Process Instances, respectively.

The ProcessInstancePredicate Class The built-in ProcessInstancePredicate class provides the following functions to set search criteria:

  • addStatus(String) Add a status. This function can be called more than once. If this is done, the predicate is fulfilled by all Process Instances with any of the added statuses.
  • setPersistent() The predicate is fulfilled by all persistent Process Instances.
  • setSessionId(String) The predicate is fulfilled by all Process Instances with the given session ID.
  • setValueStoreId(String) The predicate is fulfilled by all Process Instances with the given value store ID.
  • setTokenId(String) The predicate is fulfilled by the Process Instance with the token with the given ID.
  • addQueueName(String) Add a queue name. The predicate is fulfilled by all Process Instances waiting for any of the added queue names (user, group, or role name).
  • setProcessInstanceAttribute(String, String) The predicate is fulfilled by all Process Instances with the given name-value pair as one of their attributes. If the second parameter is null, the predicate is fulfilled by all Process Instances with an attribute with the given name (and any value).
  • setProcessId(String) The predicate is fulfilled by all Process Instances with the given Process ID."p

If the predicate has more than one criterion set, the predicate as a whole is fulfilled by Process Instances meeting all criteria.