How to enable and control the full text search facility

Using the System Management application, you can rebuild indexes completely, or consolidate and compact indexes for improved search performance.

In a multinode system, the indexes are usually maintained on only one node, to save disk space and processing; searches entered by users connected to another node are forwarded to the hosting node using Connect SOAP rules. The node containing the indexes is identified by a Dynamic System Settings data instance.

You can exclude indexing for objects of individual concrete classes derived from Work-, Rule-, or Data- by checking the Exclude this class from search? on the Advanced tab of the Class form.

Allowing application users to find work objects using full-text search (in addition to structured searches based on owner, party, or status) has advantages and costs. Consider these factors:

• Full text searches may reduce the chances that an application user enters a duplicate work object
• Full text searches do not depend on exposed columns; all properties are searched.
• Full text searches can increase operator productivity by providing faster access than structured searches
• Full text searches may produce many "hits" that require further review and qualification
• Full text searches may disclose sensitive work object details to uses who otherwise would not be permitted to open or review such work
• Indexing (performed in the background by the Pega-ProCom agent) and searching (performed on request) can impact system performance.

If you choose to provide this facility, consider which work types are to be indexed. To exclude indexing for work objects of one type, open and check the Exclude this class from search? on the Advanced tab of the Class form. (For an example, see Pega Developer Network article PRKB-25620 How to limit text search to specific class instances.)

The standard sections @baseclass.FindWork and @baseclass.SearchField supports full text search. If your application uses a composite portal, include one of theses sections (or similar custom section) in your portal.

The traditional portal WorkUser does not directly support full-text search. To provide this capability, include the standard section @baseclass.SearchField in the New harness for each work type. For an example of this approach, select the PegaSample work pool (File > Open > Work Pool > Sample Work) and start Simple Task flow (Run > Process > Simple Task) to open the work object form defined by the sample harness rule PegaSample-SimpleTask.New.

Indexing is controlled by settings in standard Dynamic System Settings data instances (Data-Admin-System-Settings class) and by a check box option on the Advanced tab of the Class form. The Dynamic System Settings are:

• Pega-RULES.indexing/dataenabled — Set to true or false to control whether searching is supported for Data- instances. Default is false.
• Pega-RULES.indexing/ruleenabled — Set to true or false to control whether searching is supported for Rule- instances. Default is true.
• Pega-RULES.indexing/workenabled — Set to true or false to control whether searching is supported for Work- instances. Default is false.
• Pega-RULES.indexing/enabled — Set to false to disable all searching. Default is true.
• Pega-RULES.indexing/explicitindexdir — If not blank, identifies a directory on the server that can hold indexes. The indexing facility places the index files it creates (with file type .cfs) in subdirectories of this directory.               
• Pega-RULES.indexing/hostid — Needed in a multinode cluster, hash node ID of the node on which the indexes reside.  (In a multinode cluster, indexing occurs on only one node; this can reduce processing workloads and disk space requirements. Through standard SOAP connector rules, search requests from other nodes are forwarded to this node.)
• Pega-RULES.SearchSOAPURI — Needed in a multinode cluster, URI of the node on which searching occurs, in the format: http://10.60.51.214/prweb/PRSOAPServlet

By default in new installations, only rule indexing is enabled. If no explicit directory name is specified, indexes are created in a subdirectories of the PegaRULES Web root directory (typically /prweb). The system creates rule indexes in a subdirectory named PegaRULEIndex.  The DataIndex and WorkIndex subdirectories contain CFS files for data instances and work objects respectively.

By default in new installations, data object indexing and work object indexing are disabled. To enable them, update the two Dynamic System Settings listed above and build initial indexes. If you enable work object indexing, make sure the SystemWorkIndexer agent activity (part of the Pega-RULES agent) is also enabled on the appropriate node.

Indexing excludes instances of any class for which the Exclude this class from search? box is selected (on the Advanced tab of the Class form. You can select this box to exclude instances of any class from indexing and searching, for example, for performance or data sensitivity reasons. Of course, when no indexes exist for a class, the resulting instances (such as work objects or data instances) do not appear in search results.

Building and maintaining indexes with the System Management application

Use the System Management application to force reindexing of rule, data, and work information after installation, after changes to Dynamic System Settings values, or when desired:

1. Start the System Management application. On the System Management window, select the node on which the index files are located.

2. Select the Administration > Index Management menu item.

3. Click one of four buttons to process indexes. Perform these one at a time; each starts processing that may require several minutes to complete. Each responds with a success message when processing is complete. Additional details and progress messages appear in the system console log.

• Click  Build PegaRULES Index   to build or rebuild indexes for rules.
• Click  Build Work Index   to build or rebuild the indexes on work objects.
• Click  Build Data Index   to build or rebuild the indexes on data instances.
• Click  Optimize PegaRULES Index   to compact index files for improved search performance. (This operation is not needed in normal system use.)

You can perform any of these four operations while a Process Commander server node is operating, but such index processing can affect system performance if the indexes are large.   As a best practice, choose a time when the server is down (that is, Process Commander is not available) or is up but less busy to perform these one-time processor-intensive operations.  

Building initial indexes naturally requires reading every rule, data instance, or work object. In some cases, a PEGA0004 alert threshold (alerts/database/interactionByteThreshold/errorMB) can cause the indexing process to fail before completing. Before building indexes on a new installation, make sure no value is set for the errorMB setting.

When enabled, the index engine component of Process Commander maintains indexes automatically for every saved rule, data instance, or work object.

To minimize any impact on user response, indexing operations occur in the background (by the Pega-RULES agent) upon the next system pulse after an object is saved. So, depending on the system pulse setting, search results may reflect slightly stale information and may be incomplete. In multinode systems, rule change information is automatically propagated to all nodes through the system pulse mechanism.

Some internal rules — instances of the Rule-System-Generated-Access class — are generated automatically as Process Commander operates. When rule indexing is enabled, these are indexed at each system pulse and rules of these types may appear in search results.