Search and list elements of Bonita Engine

Learn how to use search and list methods of the Bonita Engine APIs and how to configure word-based search.

List elements

The following example shows how to use a list method to see the archived activity instances:

List<ArchivedActivityInstance> archivedActivityInstances =
    TenantAPIAccessor.getProcessAPI(session).getArchivedActivityInstances(instance.getId(), 0, 100, ActivityInstanceCriterion.NAME_ASC);

The advantage of using list is that it is a single query, so has better performance. It is also simpler to code.

Search elements

The following example shows how to use a search method to see the archived activity instances.

SearchOptionsBuilder searchBuilder = new SearchOptionsBuilder(0, 100);
searchBuilder.sort(ArchivedActivityInstanceSearchDescriptor.NAME, Order.ASC);
SearchResult<ArchivedActivityInstance> archActivitResult = TenantAPIAccessor.getProcessAPI(session).searchArchivedActivities(searchBuilder.done());

The advantage of using search is that you can specify filters to get a more precise set of results, which can be more efficient. Several filters can be added. By default, an implicit AND clause is added when several filters are added. If the need is different, you can have an OR clause, of more complex clauses. See SearchOptionsBuilder methods for filtering that matches your needs.
The following example is a more precise search for archived activity instances, using a filter:

SearchOptionsBuilder searchBuilder = new SearchOptionsBuilder(0, 100);
// implicit AND clause between the following two filters:
searchBuilder.filter(ArchivedActivityInstanceSearchDescriptor.ROOT_PROCESS_INSTANCE_ID, processInstance.getId());
searchBuilder.filter(ArchivedActivityInstanceSearchDescriptor.ASSIGNEE_ID, myUser.getId());
searchBuilder.sort(ArchivedActivityInstanceSearchDescriptor.NAME, Order.ASC);
SearchResult<ArchivedActivityInstance> archActivitResult = TenantAPIAccessor.getProcessAPI(session).searchArchivedActivities(searchBuilder.done());

Below is another example of a more complex search filtering.

SearchOptionsBuilder sob = new SearchOptionsBuilder(0, 10);
sob.filter(HumanTaskInstanceSearchDescriptor.PROCESS_INSTANCE_ID, myProcessInstance.getId());
sob.or();
sob.differentFrom</b>(HumanTaskInstanceSearchDescriptor.ASSIGNEE_ID, myUser.getId());

Word-based search

By default, search uses a "starts by" algorithm for searching, and finds matches where the search string occurs at the start of a phrase. If word-based search is enabled, you can search for a string that is preceded by white space or is at the start of the phrase. For example:

Phrase in database	Search string	Matches with "starts with"	Matches with word-based search
Hello Charles	charles	no	yes
Hello Charles	he	yes	yes
Hello Charles	carl	no	no
Hello_Charles	ch	no	no

Phrase in database

Search string

Matches with "starts with"

Matches with word-based search

Hello Charles

charles

yes

Hello Charles

yes

Hello Charles

carl

Hello_Charles

Using word-based search has an impact on performance, so by default it is disabled. You can enable it for the platform or for a tenant. If you enable it, you can exclude any objects for which it is not useful.

To configure word-based search, using the setup tool, edit platform_engine/bonita-platform-community-custom.properties and change the value of bonita.platform.persistence.platform.enableWordSearch (for the platform) or bonita.platform.persistence.tenant.enableWordSearch (for a tenant) to true.
For each object you be excluded from word-based search, using the setup tool, edit platform_engine/bonita-platform-custom.xml add a mapping to the wordSearchExclusionMappings set. Each mapping has the following form:

   <value>org.bonitasoft.engine.identity.model.SUser</value>

Don’t forget to push your modifications using setup push command. When you restart the Engine, these settings are applied and word-based search comes into operation.