More about Declare Expression rules

This topic provides additional information about declare expression rules.

Avoid direct updates to target properties

CAUTION:
Do not change the value of a property computed by a Declare Expression rule through the Property-Set method, application of a data transform, or user input into a form. As you develop your application, the Pega Platform attempts to detect and prohibit such situations.

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.

CAUTION:
At run time, the system neither detects nor prevents the value of a target property from changing through user input, through the Property-Set method, or by data transforms. If the value changes through these or other direct means, the target property value can temporarily not equal the last computed expression value. This situation is corrected the next time any input values for the expression change.

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

Select Designer Studio > Processes & Rules > 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 PDN 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 PDN 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.

Note: This feature can improve user productivity and accuracy, while also reducing the number of server interactions and HTTP traffic required to complete a valid input form. Consider whether and where such interactive operation can simplify the user's task of completing complex input forms in your application.

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

When a Declare Expression rule has Result of decision table, Result of decision tree or Result of map value for the Set Property To field, special processing occurs at run time when a property referenced in that decision rule is not present on the clipboard. Ordinarily such decision rules fail with an error message; in this case the system returns the Otherwise value instead. For details, see the PDN article Troubleshooting: Declarative Expression does not execute when a decision rule provides no return value.

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.

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