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());

Case sensitivity

All Search requests done using search terms are case-insensitive but filtering IS case-sensitive.

Phrase in database Search string Matches

Phrase in database	Search string	Matches
Hello Charles	`searchBuilder.filter("name", "Hello Charles")`	yes
Hello Charles	`searchBuilder.filter("name", "hello charles")`	no
Hello Charles	`searchBuilder.searchTerm("Hello Charles")`	yes
Hello Charles	`searchBuilder.searchTerm("hello charles")`	yes

Hello Charles

searchBuilder.filter("name", "Hello Charles")

yes

Hello Charles

searchBuilder.filter("name", "hello charles")

Hello Charles

searchBuilder.searchTerm("Hello Charles")

yes

Hello Charles

searchBuilder.searchTerm("hello charles")

yes

On Oracle database, search is case-sensitive.

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

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

Hello Charles

charles

yes

Hello Charles

he

yes

Hello Charles

carl

Hello_Charles

ch

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.