More about Declare Expression rules
This topic provides additional information 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
For more information about forward chaining, see 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.
Forward chaining does not create new embedded pages. Declare expressions that have a non-blank Page Context field and that use top or parent keywords do not run unless at least one embedded page exists at each level of the page context.
When a property is the target of two Declare Expression rules, one context-free and the second with a context, the rule with the context runs, and the system ignores the context-free rule. If two context-free Declare Expression rules reference the same property by using distinct property reference forms, for example workpage.targetproperty and .targetproperty, the rule with the longer reference runs, and the system igonres the rule with the shorter reference.
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.
Embedded properties
Declare expressions do not support displaying values of target properties in user interface if the target property is an embedded property and if the calculation engages forward chaining. Declare expressions always display property values if the calculation uses backward chaining. During forward chaining, the system might render the UI before populating the clipboard, and the properties are not visible in the UI. To show updated values, define refresh conditions in the UI to get new values from the server when the values change. For more information, see Defining refresh conditions for UI areas.
Declarative Network Analysis gadget
In Dev Studio, click
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 log additional details about tracked property changes by configuring log levels for log categories. For more information, see Managing log categories.
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:
- Use this feature on flow actions or harnesses that use the SmartFrames layout and JSP tags.
- 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.
- Select the Enable Expression Calculation? box on the HTML tab of the Flow Action form or Harness form.
- 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 hasResult 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
Pega Community
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 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
. You can use this code to debug your application or to examine how rules are implemented.Previous topic Specifying pages and classes for a declare expression Next topic Declare Expression form - Completing the Change Tracking tab