Some tips for using the TWSEARCH JAVASCRIPT API in IBM® BPM 8.6

Body

Many times users may need to retrieve and display information that is related to Process or Task instances via the TWSearch object and it's related objects. The data that you can retrieve are same as those which you can retrieve using a Saved Search from the BPM Process Portal.

We do the test of "process-search-engine-count-optimization" by adding the following setting into 100Custom.xml.

<server merge="mergeChildren">
<process-search-engine-count-optimization merge="replace">5</process-search-engine-count-optimization>
</server>

------------------
C:\IBM\BPM\profiles\Dmgr01\config\cells\ackbdv1fCell\clusters\BPMCluster\process-center\config\100Custom.xml
C:\IBM\BPM\profiles\ProcCtr01\config\cells\ackbdv1fCell\clusters\BPMCluster\process-center\config\100Custom.xml
------------------

According to below statement in "IBM Knowledge Center - Tuning Process Portal searches", user had thought that this property should be applied to TWSearch API.

------------------

The number of entries that is returned for a saved search is controlled by the value of the process-search-engine-count-optimization property in the 99Local.xml file. 

------------------

So the number of returned entries should be 5. 

But, in real test, TWSearch API returned over 6 results. 

What's wrong? What is determined by this property "process-search-engine-count-optimization"?

The documentation for process-search-engine-count-optimization in "IBM Knowledge Center - Tuning Process Portal searches" is not up to date, DOC APAR JR59500 will fix the KC in BPM 8600 2018.06 CF. 

The value of property "process-search-engine-count-optimization" does not control the number of entries returned from saved search. The process-search-engine-count-optimization property is used to determine the displayed values for the task summary and task statistics counts (On Track, At Risk, Overdue) in the Process Portal Work and saved search dashboards. For example, with the default property value of 500, if you save a search that returns 600 tasks, the summary count shows 500+. The task statistics include only the first 500 tasks in the task list, so Process Portal users might see the following counts for the task categories: 100+ On Track, 200+ At Risk, 200+ Overdue. 

Whether there is upper limit for TWSearch API?

In our tests, we found that over 1000 results were returned by TWSearch, and seems there is no upper limit for TWSearch API. If this is true, when users have a large result set, they might receive an Out Of Memory error.

How to resolve this concern?

When TWSearch API is used for saved search, the max rows can be specified in the parameter of this API, for example:
       var search = new TWSearch();
       var results = search.execute("user1", 2); <-- second parameter is the max number of rows returned by search, current API only allow you to specify the max number rows as second parameter, the first parameter of is user or group.

       var search = new TWSearch();
       var results = search.execute(); <-- the max number of rows is read from config flag javascript-search-max-hits.

If the max number of rows is not specified in search API, a fix JR53130 is available for IBM BPM V8.0.1.2 that enables TWSearch to limit the search result to the value of the javascript-search-max-hits configuration parameter.  When the maxRows parameter is set, this configuration parameter is ignored.

BPM uses the value specified in javascript-search-max-hits property, the default is MAX_VALUE of integer, users can overwrite it in 100Custom.xml by adding the following section into the properties attribute:
    <common>
      <search-execution>
          <javascript-search-max-hits merge="replace">3</javascript-search-max-hits>
      </search-execution>
    </common>

Specify an appropriate value for javascript-search-max-hits.

There are some other useful TWSearch related knownledge documents for your reference as below and hope this article give you some help when you have some troubles with TWSearch API usage.

NullPointerException using TWSearch

How do I use TWSearch to retrieve Process and Task Instance Data?

Can BPM Saved Search acceleration tools improve the performance of JScript TWSearch() API?