More about Declare Index rules

Primary page

During execution of a Declare Index rule, the page on which the rule operates becomes the primary page. The page keyword PRIMARY and the results of the tools.getPrimaryPage() PublicAPI method reflect this change. When the Declare Index rule execution completes, the primary page of the calling activity resumes as primary.

Where referenced

No other rules explicitly reference Declare Index rules. After you save a Declare Index rule, it is run immediately and as needed.

You can use an index to improve access to a property that is not an exposed column in the database table supporting the source class, or to access embedded values that may appear more than once in the instances of the source class.

Processing

After you define an index through this rule, the system maintains index data automatically using forward chaining.

Index processing occurs at every database commit operation. Index processing automatically deletes old indexes that are no longer accurate, updates existing indexes, and adds new index instances, as required, to match current values of the source instance. When a data object is deleted (typically by an Obj-Delete method followed by a Commit method) the system examines all associated indexes and deletes them as appropriate.

Normally, the system updates indexes automatically during the Commit method that completes an earlier Obj-Save or Obj-Delete method. Index processing occurs only if any of the Source Class Property values (entered on the Index tab) have changed from their previous values.

The pyIndexCount value, a system-derived integer value, is included in as part of the key of every Index- instance, and makes the key unique.

PEGA0034 Alert

When a work item or other instance is committed, multiple Declare Index rules may automatically run to create and delete index instances. If such processing causes more than 100 indexes to be created, an alert is added to the Alert log, to draw attention to a possible design or performance issue.

For an example, see the Pega Community article PEGA0034 alert: The number of declare indexes from a single interaction exceeds a threshold.

Reporting

After you implement a declarative index, reports can use the indexed property value as a selection criteria. For example, if an array of embedded Universal Product Code (UPC) codes in a work item is indexed, you can report on all work items containing a specific UPC code. Reference the index class on the Contents and Join tabs of the report definition form.

Debugging

To produce detailed output from the inference engine, use the Set Logging Level tool to set logging for the following class to DEBUG :

com.pega.pegarules.engine.database.Indexer

Benefits

Through planning and coordination with a database administrator, application developers can define indexes that greatly aid in user productivity. However, indexing introduces redundant data and extra processing. Be careful to avoid defining indexes that are not truly needed or that negatively affect performance.

Indexing can improve performance by allowing quick lookup of certain properties based on a property value that is not exposed in database table supporting the original instance, or that has multiple values (and so cannot be exposed).

For example, using appropriately defined indexes, you can quickly identify all work items that contain a customer who resides in a specified Zip code.

Reindexing with the expose option of the prpcUtils command line facility

System administrators can recompute Index- instances for some or all instances of the underlying class using the expose option of the prpcUtils scripts: prpcUtils.bat for Windows or prpcUtils.sh for UNIX/Linux systems. You can set the expose.reindex property even when no database columns need to be populated.

If the index instances in your system are incomplete or become corrupted or suspect, you can recreate them by running prpcUtils with the expose option set to true to regenerate declarative index contents. For example, expose.reindex=true.

Forced reindexing upon commit

You can force re-indexing to occur upon commit even if no tracked properties are changed. To do this, add the property @baseclass.pzReindex with a value of "true" to the page containing the object before saving and committing the object. This property causes the system to skip change tracking and recompute indexes for this object from scratch. Because of added overhead, use this technique only in testing, debugging, or low-volume situations.

Rule forms based on FormBuilder

When you save a rule form, Operator ID form, or other form defined through the FormBuilder tool and saved as instances of the Rule-File-Form class, Declare Index rules for that class are not activated. (However, property changes made to such instances through activities do cause Declare Index rules to execute.)

As a best practice, use Declare Trigger rules, not Declare Index rules, to monitor property changes in classes that have a FormBuilder form defined.