Understanding full-text search

Pega 7 Platform incorporates a full-text search feature based on Elasticsearch. Depending on settings, developers can search for rules, data instances and work items, and application users can search for work items.

By default, the full-text search facility is enabled for rules, and is accessed by the Designer Studio search facility in the header bar.

This facility uses index files to provide full-text searching. Through settings in the Search landing page tab, you can enable or disable this facility and determine the directory where index files are stored. Indexes are updated in the background periodically, during the system pulse performed by the Pega-RULES agent — typically once a minute.

Note: When you update settings on the Search landing page tab, scroll to the bottom of the display to locate and click the Submit button. Your settings do not take effect until you submit your changes.

Configuring search

From the Search landing page tab, refer to the System Settings - Search tab help topic for more information about how to control and configure full-text searching on your system. Select Designer Studio > System > Settings > Search to access this tab.

Allowing users to search work items

Allowing application users to find work items or work item attachments 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 item.
• Full-text searches do not depend on exposed columns; all the text is 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 item or work item attachment details to users who otherwise are not permitted to open or review such work.
• Indexing (performed in the background by an agent) and searching (performed on request) can impact system performance.
  
• Full-text searching includes hits found within file attachments in Acrobat PDF format or Microsoft Office formats (Word, Excel, PowerPoint), if these attachments are stored within the PegaRULES database.

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

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

The traditional ("fixed") 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 (select Switch Work Pool > Sample Work from the application menu and start a Simple Task flow (> Run Process > Simple Task) to open the user form defined by the sample harness PegaSample-SimpleTask.New.

Building and maintaining indexes

Ordinarily, the Pega-RULES agent rebuilds indexes for Data-, Work-, and Rule- objects continuously. Using the Search landing page tab, you can stop (disable) or start (enable) activities in the PegaRULES agent that performs this processing.

Operation of the indexing engine

When enabled, the index engine component of Pega 7 Platform maintains indexes automatically for every saved rule, data instance, and work item.

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 multi-node systems, rule change information is automatically propagated to all nodes through the system pulse mechanism.

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

How class instances are stored in the search index

Assume a sample class instance with only three properties:

• .pyID = “WORK-1234”
• .pyLabel = “Search enhancement”
• .pyDescription = “Complex query”

1. All text property values, including all embedded properties, are tokenized, and the tokens (words) are stored in a field named Content in the search index for this instance, which is the field used when simple search queries are entered that are designed to match any text value in an instance:
   • Content: WORK-1234
   • Content: search
   • Content: enhancement
   • Content: complex
   • Content: query
2. In addition, each top-level scalar property is also filterable. That is, its value is tokenized, and the tokens for that property are stored in a separate field that supports search queries specific to that property, like pyLabel contains enhancement:
   • Content: WORK-1234
   • Content: search
   • Content: enhancement
   • Content: complex
   • Content: query
   • pyID: WORK-1234
   • pyLabel: search
   • pyLabel: enhancement
   • pyDescription: complex
   • pyDescription: query

   The tokenized values of embedded properties can also be filter-enabled, if specified in a Data-CustomProperties-Search instance.

3. A subset of top-level scalar properties is also returnable. That is, the entire text value is also stored in the index, so that it can be returned in search results if desired:
   • Content: WORK-1234
   • Content: search
   • Content: enhancement
   • Content: complex
   • Content: query
   • pyID: WORK-1234
   • pyLabel: search
   • pyLabel: enhancement
   • pyDescription: complex
   • pyDescription: query
   • pyLabel = “Search enhancement”

   The list of returnable properties is also modifiable by specifying a Data-CustomProperties-Search instance.

   The default list of returnable properties for each index type is given below. It corresponds to the default list of exposed and indexed properties in these class types:

   • Returnable properties for all index types (Rule, Data, Work): pzInsKey, pxInsName, pxObjclass, pxCreateOperator, pxUpdateOperator, pxCreateDateTime, pxUpdateDateTime
   • Additional returnable properties for Work- classes: pyID, pyLabel, pyStatusWork, pyOrigUserID, pxUpdateOpName, pyResolvedTimestamp
   • Additional returnable properties for Data- classes: pyClassName
   • Additional returnable properties for Rule- classes: pyRuleSet, pyRuleSetVersion, pyRuleName, pyClassName, pyRuleAvailable, pxInstanceLockedBy

Related information

Open topic with navigation