More about Declare OnChange rules

Properties tracked by the OnChange rule

This rule tracks the following properties:

• Properties identified in the Properties to Watch field
• Properties used in the when condition rule identified in the When field
• Properties used in the decision rules referred by the when condition rule

Restrictions for OnChange activities

The activity identified on the OnChange Properties tab must have an Activity Type of OnChange. It can call or branch to other activities, but only if they too have an Activity Type of OnChange.

Your activity can examine the Value List property pyChangedProperties to discover the property that changed value. This property is on the page named pyDeclarativeContext, of class Code-Pega-DeclarativeContext. This page exists only while the activity runs.

The primary page passed to OnChange activities is the top-level page.

OnChange processing may start as the result of a user HTTP Post operation. If users complete an HTTP form that changes the value of a property tracked by a Declare OnChange processing, this change is detected.

Use care not to start an infinite processing loop within declarative rules. For example, in an OnChange activity, do not update any of the properties that caused the activity to start. You can to update other properties in the OnChange activity.

• Declare Expression rules do not evaluate during the execution of an OnChange activity. However, do not attempt in an OnChange activity to overtly set the value of a property that is the target of a Declare Expression rule.
• Similarly, constraints rules do not evaluate during the execution of an OnChange activity.

Primary page

During execution of a Declare OnChange 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 OnChange rule execution completes, the primary page of the calling activity resumes as primary.

Performance

Design the OnChange activity to execute quickly, as some properties may change values often. Remember that properties may change values (and thus cause the rule to run) during development and testing tasks, such as the preview of a harness or flow action form.

Declare OnChange rules may be expensive (computing several values) compared with Declare Trigger rules that test the same property. Consider which rule type better meets your needs. For example, if a value changes every few seconds but is part of an object that is saved only hourly on average, a Declare Trigger rule computes a new value only hourly, not in real time.

Testing and debugging Declare OnChange rules

Using the Tracer, you can watch the evaluation of a Declare OnChange rule. Start the Tracer and select a requestor session. Click Settings and check the Declare OnChange box in the Event Types to Trace section. Also check the RuleSet that contains the rule to be traced.

The statistic Tracked Property Changes on the full details page of the Performance tool shows how many property changes have occurred (for the current requestor since log-in) that are tracked for declarative rules computations. You can modify the prlog4j2.xml file to log additional details about tracked property changes. See How to identify which properties are tracked for declarative processing.

You can view the generated Java code of a rule by clicking Actions > View Java. You can use this code to debug your application or to examine how rules are implemented.