More about Declare Expression rules

Do not change the value of a property computed by a Declare Expression rule through the Property-Set method, application of a model, or user input into a form. As you develop your application, Process Commander 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.

At runtime, the system does neither detects nor prevents the value of a target property from changing through user input, through the Property-Set method, or by model. If the value changes thorough 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.

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 a with model rule), 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 runtime 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.

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.

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.

The contents of the selection lists on the Expressions tab depend on property alias rules and alias function 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 the Options button () 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 prlogging.xml file to log additional details about tracked property changes. See Pega Developer Network article PRKB-18112 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 runtime. For an example, see Pega Developer Network article PRKB-21249 Declarative rules require access to correct input property rules.

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 work object 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.

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 task of completing complex input forms in your application.

To implement this capability:

1. For best results, use this feature on flow action rules or harness rules that use the SmartFrames layout and JSP tags rather than declaratives.
2. Include the target property as a display-only field on the runtime presentation of a flow action rule or of an entire harness rule. In most cases, selected ComputedValue as the Format value for the target property.
3. Include at least one input to the expression as another field on the same flow action form or flow action form. Don't place the input in the flow action form and the target in the harness form or vice versa.
4. Select the Enable Expression Calculation? box on the HTML tab of the Flow Action form or Harness form.
5. Test.

This feature is based on AJAX technology.

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 runtime 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 Pega Developer Network article PRKB-20805 Troubleshooting: Declarative Expression does not execute when a decision rule provides no return value.

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 prlogging.xml file) to include the category shown here:

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

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

When you save a Declare Expressions rule, the system converts the rule to Java source code. As a learning or debugging aid, you can review this Java code.

Click the Show Java toolbar button () to see the system-generated Java code that implements the rule. The window presents a read-only preview of the Java that implements this rule instance. This Java code is not identical to the Java that is executed at runtime, which includes Java code inlined from other rule instances and reflects rules in the requestor's RuleSet list.

If your system is upgraded from a Process Commander system before V5.3, you can preserve V5.2 execution and results of Declare Expression rules if this capability is important to your application. This approach removes support of context free expressions, and is not recommended for new development, except as advised by Pegasystems Global Support. To preserve V5.2 function:

1. Include this line in the prconfig.xml file:

<env name="Compatibility/InfEngImpl" value="52" />

2. Stop and restart (or redeploy) the system.

To support execution of 5.3 features including context-free expressions, use the following values:

<env name="Compatibility/InfEngImpl" value="53" />