Declarative processing — Concepts and terms

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 objects 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 Process Commander developers with database experience. Unlike the other rule types described here, Declare Index rules are part of the SysAdmin category.

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

See About the Declarative Network display.

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.

Internally, Process Commander uses an inference engine and an internal data structure known as the dependency 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, and so start backward chaining.)

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 dependency 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:

• When used if no value present
• When used, if property is missing
• Whenever used

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:

• VerifyProperty flow action
• VerifyPropertywithListing flow action
• PromptGoalSeekProperty HTML rule
• VerifyProperty activity

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

Debugging

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

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.

When searching for declarative rules, the system:

• Filters candidate rules based on a requestor's RuleSet list of RuleSets and Versions
• Searches through ancestor classes in the class hierarchy for candidates when no matching rule is found in the starting class

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, Rules Inspector, 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.

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

• A context-bound expression with a page context key: The Applies-To class is Data-Transaction, the page context is .Item() and the page context class is Data-Item. The expression is ".Tax = .Cost * .05" and the circumstance is ".State = MA". The input, output, and circumstance properties are all defined on Data-Item. When the application runs, the page context is an instance of .Item() embedded on a top-level page of class Data-Transaction. For instance, setting MyDataTransaction.item(2).Cost, the expression uses MyDataTransaction.item(2) as the page context. The relevant circumstance property is MyData Transaction.item(2).State.
• A context-free expression: The Applies-To class is Data-Item, the expression is .Tax = Cost * .05", and the circumstance is ".State = MA". The input, output, and circumstance properties are all defined on Data-Item. When the application runs, the page context is an instance of Data-Item, which can be a top-level page or embedded in any page structure. For instance, setting MyDataObject.ADataItem.Cost, the expression uses MyDataObject.ADataItem as the page context and the relevant circumstance property is MyDataObject.State. Setting MyDataItem.Cost, the expression uses MyDataItem as the page context and the relevant circumstance property is MyDataItem.State.

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 circumstance are only checked during expression evaluation. The passage of time alone does not cause re-evaluation of declarative rules.