More about Declare Expression rules

Avoid direct updates to target properties

For example, if someone creates a Declare Expression rule that computes the property AverageWait, a developer tomorrow cannot save an activity that uses the Property-Set method to change the value of AverageWait.

However, if yesterday — before the Declare Expression rule was defined — someone created and saved an activity that set the value of AverageWait, then after today both the activity and the Declare Expression rule can execute to save the value. This practice is not recommended.

To reduce the risk of similar rule conflicts, you can adopt a naming convention for properties designed to be computed in Declare Expression rules, and create Declare Expression rules early, using stub or dummy expressions.

How this rule runs with forward chaining

If you select Whenever inputs change in the Compute Values field, then each time the value of any property referenced in any Declare Expression rule — or properties in other rules (such as decision trees, decision tables, or map values) referenced in the Declare Expression rule — changes, the system computes the values of the target property.

Ordinarily, code your activity to place all properties of interest on the clipboard before the activity accesses the value of a property referenced in the key of a Declare Expression rule. Your activity can create placeholder values (with Property-Set or with a data transform), or create the properties by opening instances with the Obj-Open method.

If the Declare Expression rule contains a non-blank Page Context field, the expression is evaluated at run time only when the clipboard contains a page matching that full context.

When more than one Declare Expression rule is to run, you cannot control or predetermine the order in which the multiple Declare Expression rules run.

Sample rules for backward chaining (goal seeking)

The Property-Seek-Value method uses Declare Expression rules to compute a property value on request. For an example, the standard flow action named Work-.VerifyProperty calls the standard activity Work-.VerifyProperty. If you use this flow action in a flow rule, a user can select it to cause the system to use goal-seeking to compute the value of the pyResolutionCost property.

If the backward chaining process fails, it can indicate a property with no current value that if set could aid in the computation. Your flow can then prompt a user for help or for a value that can allow the computation to complete.

Primary Page

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

Declarative Network Analysis gadget

In Dev Studio, click Configure > Case Management > Business Rules > Declarative Network to view and interact with the declarative expression rules in your application.

Alias Function Rules

The contents of the selection lists on the Expressions tab depend on property alias rules and alias function rules.

Testing and debugging Declare Expression rules

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

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 the Pega Community article How to determine which properties are tracked for declarative processing.

Like other rules, Declare Expression rules won't evaluate as expected if the RuleSets needed for correct execution are not available to the requestor at run time. For an example, see the Pega Community article Declarative rules require access to correct input property rules.

Workstation display of calculated values using AJAX

When appropriate, your application can recompute the value of target properties (presented as read-only fields) immediately as a user changes an input value on a user form or flow action form, rather than later when the form is submitted. Users can see the new value immediately.

For example, the target property can represent an order total amount for a sales order. As a user enters and revises sales details, the total changes immediately as user focus leaves an input field.

To implement this capability:

1. Use this feature on flow actions or harnesses that use the SmartFrames layout and JSP tags.
2. Include at least one input to the expression as another field or flow action. You can't place the input in the flow action form and the target in the harness form or vice versa.
3. Select the Enable Expression Calculation? box on the HTML tab of the Flow Action form or Harness form.
4. Test.

This feature uses AJAX between the browser client and the server.

Special processing for map value, decision table, and decision tree calls

Advanced debugging

Use the Tracer tool to detect that a Declare Expression rule execute when expected. For more detailed debugging help, use the Logging Level settings tool (or update the prlog4j2.xml file) to include the category shown here:

<category>
<name="Rule_Declare_Expressions">
<priority value="debug">
</category>

OnChange rules

Declare Expression rules do not evaluate during the execution of an activity of type OnChange. Such executions are typically brief.

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.