You are here: Reference > Rule types > Declare Expressions > Declarative processing - Concepts and terms

Declarative processing — Concepts and terms

Declarative processing simplifies your application and reduces the number of activities you need to create. The declarative processing facilities support operation of five rule types:

On the Application Explorer and Records Explorer displays, four of these rule types belong to the Decision category. Declare Index rules support reporting and belong to the SysAdmin category. Data Page rules belong to the Technical category.

Additional rule types contain "Rule-Declare-" in the rule type name, but are not supported by this facility. For example, the Rule-Declare-DecisionTree rule type is considered a decision rule, not a declarative rule. See Decision rules — Concepts and Terms.

Basics

A declarative rule describes a computational relationship among property values that is expected to be valid "always" or "often" or "as needed." In practice, declarative rules are evaluated automatically when needed to satisfy certain conditions. These rule types differ in processing to offer you specific meanings of "often" or "as needed."

The primary benefit of declarative processing is that the system, rather than the developer, controls when computations are processed. Relationships between property values can be expressed directly, without the need to create activities and design the application to run the activities often.

Declare Expression rules

A Declare Expression rule defines a computational relationship among properties, such as:

         Area is computed as Length multiplied by Width

After you save a Declare Expression rule, you can be certain that thereafter the value of the Area property, when accessed on the clipboard, is equal to the product of the values in the Length and Width properties. Any change to a Length or Width value, regardless of how the change occurs, causes immediate recomputation of the value of the Area property. This works even if the update to Length happens indirectly.

Constraints rules

A Constraints rule records an expected relationship between property values, such as:

 ActualExpense("December") is never greater than BudgetExpense("December").

As with expressions, the system monitors whether the constraint is met each time either value changes. If the constraint becomes false, the system adds a message on the page containing the left-hand property (ActualExpense(), in this case), marking the page as not valid. Pages that are not valid cannot be saved to the database.

Declare Trigger rules

A Declare Trigger rule identifies processing to occur automatically when an instance of a specific class is saved or deleted. (An activity with an Activity Type of Trigger performs the processing.) For example, you can maintain the total month-to-date dollar value of new work items with a Declare Trigger rule. Each time a new object is resolved, the trigger rule executes; the trigger activity runs and updates the total. (Because this processing occurs in the current user requestor, make sure that the design saves the total in a separate object, and that locking ensures that only one user can update the total at a time.)

Declare OnChange rules

A Declare OnChange rule causes computation to occur when the value of certain "watched" properties change. This may cause more frequent updating than a Declare Expression rule. A Declare OnChange rule starts an activity that can perform more complex or comprehensive computations than can be defined by expressions.

Declare Index rules

A Declare Index rule creates or deletes new objects in concrete classes derived from the Index- base class. Like other declarative rules, the rule operates automatically and as needed.

However, index objects support specific data-access needs rather than computation. Accordingly, Declare Index rules are best designed by database administrators or Pega Platform developers with database experience. Unlike the other rule types described here, Declare Index rules are part of the SysAdmin category.

The Declarative Network display

You can view a graphical presentation of the relationships among property values defined through Declare Expression rules.

See About the Declarative Network display.

Declarative rules are not referenced

In general, no other rules explicitly reference declarative rules. Your use of a property that's referenced in an expression or constraint rule causes the expression or constraint rule (and perhaps many other rules) to run.

The inference engine and declarative network

Internally, Pega Platform uses an inference engine and the declarative network to support declarative processing. Two properties A and B are linked in the network if the value of A depends on the value of B.

Inference engine processing operates invisibly in the moment between activity step executions. The step most recently executed may have changed a property value (and cause forward chaining, defined below), or may have updated the database (and cause Declare OnChange processing). The next step may need a property value that is not yet defined, which causes backward chaining to start.

Forward chaining

Forward chaining provides the automatic propagation of changes in one property value to cause recomputations of another property's value.

For those Declare Expression rules with Whenever inputs change in the Calculate Value field, the system creates an internal declarative network, identifying which properties have values that may depend on which other properties.

For example, if the Area property depends on the Length and Width property, and the Volume depends on the Area and Depth property, forward chaining causes the Volume property to be recomputed each time Length, or Width, or Depth changes value.

Informally, the term forward chaining can apply to other automatic propagation of changes, such as by Declare Trigger and Declare OnChange rules. When these execute, they may in turn cause additional automatic processing to occur, and so on.

Backward chaining

Backward chaining executes Declare Expression rules when a value is needed for a property, rather than when inputs change. For example, a value may be needed because the property appears as a source in a Property-Set method or as an input to a computation.

Backward chaining applies to Declare Expression rules with the Calculate Value field set to one of the following:

If the formula Area = Length times Width is set up for backward chaining with the Whenever used option, then each time the system accesses the Area property for a value, the Declare Expression rule recomputes. This recomputation may occur more often, or less often, than the inputs Length and Width change values.

If the system needs a value for Area through backward chaining, but Length has no value, the chaining may continue using a Declare Expression rule for Length, and so on. Alternatively, the application can prompt a user to enter a value.

Example

Standard rules support experimentation with backward chaining. These flow actions try to find a value for the pyResolutionCost property:

These rules apply to the Work- class. The Property-Seek-Value method is the foundation of backward-chained processing.

Debugging

Note: To produce detailed output from the inference engine, use the Set Logging Level tool to set logging for the following class to DEBUG:

com.pega.pegarules.engine.infengine.InferenceEngine

Locatable pages

A capability called locatable pages reduces the need for pages to be explicitly named in the rule. Locatable pages can be used with Constraints rules and Declare Expression rules.

References to properties on a locatable page use the locate keyword in lowercase as a prefix or initial portion of the page name, as in:

locateCustomer.OrderAmount

At runtime, the system uses backward chaining and an activity with type Locate to find and (if necessary) add the proper page to the clipboard. This eliminates the need for the developer creating the when condition rule to specify the page.

Rule resolution

When searching for declarative rules, the system:

Using time- and circumstance-qualified declarative rules

You can use time-qualified and circumstance-qualified rule resolution features with Declare-OnChange, Declare-Expression, and Declare-Constraints rules. The tools and utilities associated with declarative rules such as the Declarative Network display, Tracer, and System Management Application are not limited or altered by the use of declarative rule qualifications.

As with all circumstance-qualified rules, the base and circumstanced instances of declarative rules have the same keys. Because declarative rules can be executed at any time as a result of property references and changes, declarative rules run within their own page context during evaluation and not within the context of a Primary page. Therefore, a circumstance property reference in a declarative rule is evaluated relative to the rule's page context and not the current Primary page.

For Declare-Constraints and Declare-OnChange rules, the key parts are Applies-To class and Purpose. The base and circumstance-qualified instances must all have the same page context references.

For Declare-Expression, the key parts are Applies-To class and Target Property. Page Context is also used as a key when using a Page List or Page Group property. The base and circumstance-qualified instances of a Declare-Expression must have matching change-tracking and context execution strategies. In other words, the base instance and its circumstance-qualified instances must all be forward chaining or all backward chaining, and must all be context-bound or all context-free.

The following examples illustrate how context-bound and context-free expressions work when using circumstance-qualified expressions.

When qualified declare rules are re-evaluated

Declare-Expression rules set to use the "calculate value whenever inputs change" option, and all Declare-Constraints and Declare-OnChange rules use forward chaining to keep their output properties current.

In most cases, a declare rule's circumstance properties and input properties are re-evaluated in similar fashion. When a circumstance property's value changes, the declarative network re-evaluates the expression or constraint. However, if a circumstance property reference uses a top-level page name, changing that property's value does not cause the declarative network to re-evaluate the expression or constraint.

Circumstance resolution occurs when the rule is evaluated, not when an input property changes. For example, assume a Property-Set step changes an expression input and the circumstance property (in that order). During forward chaining, the expression uses the new circumstance value, even though the input property was changed when the circumstance property had a different value.

Declare-Expression rules invoked by Goal Seek or with any other "calculate value" options use backward chaining. In this case, the expression is calculated only on demand. Therefore, changes to input properties and circumstance values do not cause the expression to be re-evaluated automatically. The circumstance is checked only when the expression is invoked.

Time-qualified circumstances are only checked during expression evaluation. The passage of time alone does not cause re-evaluation of declarative rules.

Context-free expression rules

A context-free expression rule is a Declare Expression rule that applies to an embedded page or pages. It computes the value of a target property in every page of that class that appears on the clipboard, regardless of the name, class or content of higher-level pages above the embedded page. Using context-free expressions can reduce the number of Declare Expression rules you need to build and maintain in your application.

A Declare Expression rule that is not context-free is called context-bound.

For example, if a computation among properties in a page of class Embed-Rating is always true, regardless of which higher-level objects contain this page, a context-free expression is appropriate.

Similarly, a computation such as Age = CurrentYear - BirthYear is valid regardless of whether the page that contains the three properties (Age, CurrentYear, BirthYear) is at a top level, or embedded in the pages of a page list Policyholder.Children(), or even in a page list PolicyHolder.Children().Children().

To create a context-free expression:

By its nature, a context-free expression executes in more contexts than a similar Declare Expression rule that executes only in the context of a specific top-level page name. In some cases, this additional processing can affect system performance.

Two statistics in the Rule Execution Counts area of the Full Details display of the Performance tool let you assess the performance of Declare Expression rules:

When a property is the target of two Declare Expression rules — one context free and the second with a context, the second takes precedence over the context free rule, which is ignored.

If two context free Declare Expression rules reference the same property using distinct property reference forms (for example workpage.targetproperty and .targetproperty), the rule with the longer reference is executed; the rule with the shorter reference is ignored.