In this post we will see how to configure a declare expression rule in Pega.
- It is mainly used in computing property value based on expression.
- This rule comes under declarative category.
- It executes declarative and hence there is no need to call these rules manually. We can just configure the rules and no need to care where to refer the rule.
- Declarative rules can be called as business rule and can be delegated to business users.
The main four types of declarative rules are:
- Declare Expression
- Declare Trigger
- Declare Onchange
- All these declarative rules target a single property, either to obtain its value or to validate the value.
Let’s start with a simple example.
“Imagine in a form you have Date of Birth & Age field. When an user enters DOB field, we need to automatically compute Age value. This can be achieved by using a declare expression rule targeting Age property. We can use expression to find the difference in year between DOB and current date”.
What is a declare expression rule?
- Computes value based on expression.
- Rule gets triggered automatically based on two methods – Forward chaining / backward chaining. We will discuss these methods shortly.
- Comes under decision category.
How to configure a Declare Expression rule?
First we will go with simple example as Total = quantity * cost.
Configuring Total value based on quantity and cost.
This is our user screen. We need to automatically calculate Total.
Step 1: Create a new declare expression rule with target property as “TotalCost”.
Leave Page context as empty.
Purpose of Page context:
- Mostly leave this empty if the declare expression fires in any top level page or context free.
- If it needs to fire in a embedded page. Add the page as Lineitem().
We will discuss in detail at the end with an example.
Step 2: Build the expression to calculate TotalCost from quantity and cost.
Pega provides some inbuilt function to use. Default forward chaining is applied.
Step 3 : Verify the user screen by varying the quantity and cost.
Configuring Declare Expression rule:
If you look at declare expression rule there are 2 main tabs:
- Change Tracking
- We can have multiple expressions to calculate the single property.
- ‘If‘ follows ‘If-else‘ logic.
Scenario: Imagine you are in an online purchasing website. They provide discount based on the quantity of products you buy.
If quantity is 0-5, then 10% discount ; if quantity is 5-10, then 20% discount. If quantity is greater than 10, then 30% discount.
Here we can have Declare expression for discount property as shown below:
- You can use + icon to add multiple ‘if‘ conditions.
- You can use ‘Actions‘ icon to add AND/OR logic for ‘If‘ conditions. In the above example, you can check for range 5-10. You can add condition either above or below as shown below:
- If all the ‘If‘ conditions fail, then otherwise value will be set. Be careful in setting it.
- Set property to values depend on the property type.
Property type – Text
Property type – Integer
Declare expression can set values from the result of decision table/decision tree/map value etc.,.
- Don’t forget that tracking is done for all properties mentioned in the right hand side i.e. in ‘If’ expressions, properties used in those decision rules.
- Declare expression fires even if any one of the property gets updated.
Change Tracking tab:
- Used to specify the tracking mechanism, additional properties it depend on and the context behavior.
- Target Property data
Before checking this, we need to be aware of two mechanisms involved in declare expressions:
- Forward chaining
- Backward chaining
What is forward chaining?
- All the example scenarios we saw above belongs to forward chaining.
- Whenever input changes, target property gets calculated.
Total price = Cost * Quantity
Here, whenever Cost or Quantity change Declare expression fire and Total price gets calculated based on the expression in the declare expression rule.
Note: Property value updated by activity java step do not trigger forward chaining, while backward chaining works.
What is backward chaining?
- It is exactly opposite to forward chaining. There are many ways by which backward chaining gets triggered.
Let’s take the same example,
Total price = Cost * Quantity
Whenever Total price is null/referred, the declare expression fires and check for the input source properties. (Cost * Quantity).
Imagine Cost is calculated as,
Cost = Base price – Discount
Now, the declare expression tries to capture the cost value, if it is null.
It is like going backward & backward, till you get all the required input values to calculate the target property.
- It uses Goal seek pattern, which means use expression to determine what values are missing to determine the goal.
- Use Property-Seek method in an activity to execute backward chaining.
- Whenever inputs change – Forward chaining.
- When used, if no value present – Backward chaining. If the target property we refer is null, then the declare expression fires to calculate the value. Once the target property is non null, then it never fires unless its value is null again.
- When used, if property is missing – Backward chaining. If the target property we refer is not available in the clipboard, then the expression fires to calculate the value. Once the value is set in clipboard, it never fires again.
- Whenever used – Backward chaining. When the target property is referred, it re-computes the value again.
- When applied by a Rule collection – Declare expression fires when it gets invoked by a collection rule.
Collection rule reference
Here the declare expression for Age property should be as “when applied by a rule collection”.
6. When invoked procedurally – Target property is computed only when invoked by collection rule. More or less it is the same as above. Maximum we don’t use 5 & 6.
- Additional Dependencies
- You can specify any additional properties to be tracked.
- If not null changes to any property triggers the declare expression rule.
Note: This applies only for forward chaining – Whenever inputs change.
- Context Execution Behaviour
a) Only when the top-level page is of the Applies To class
- I will explain it with the above example. Here the declare expression created with applies to class as ‘Purchase Request’ work class – XYZ-PREM-Work-PurchaseRequest.
- This declare expression fires only when we are in case workpage.
- Imagine we have the same properties quantity, discount & Total cost in a repeating grid data page which is different from the applies to class. Declare expression never fires.
b) When the top – level page is of the Applies To class or one of the following
The same as of above. But in addition to Applies to class, we can provide additional classes too. So, the declare expression fires in all those classes.
Here the declare expression fires when in purchase request case or in Customer data class.
c) Regardless of any page it contain
We make this declare expression as context-free. It means it can fire on any page of any Applies to class.
This option can make the declare expression execute more often. Try to use it optimally.
How to Property – Seek method?
Step 1 : Create a test activity with the below steps.
Goal property – Declare expression target property.
Missing Reference property – Will hold the missing property for computing the goal property.
Step 2: Create a declare expression with Target property data as “whenever used”.
Here we used the sample with backward chaining configuration.
We need to have both quantity and TotalCost in clipboard to compute discount.
Here, we don’t have any property in the clipboard.
Step 3: Run the activity.
Though both properties missing the cost property records the first missing property.
We can use HTML stream to throw popup for user to input the value.
Step 4: Try setting different values and analyze the result.
Sample example using grid:
Requirement: We have a shopping cart repeating grid. Each row can represent a product. After each product is entered with quantity & cost, the total cost should be calculated automatically as
Total cost of each product = Quantity * Cost of each product.
Also the Subtotal for the purchase should be calculated automatically based on the total amount for each product.
Sub total = sum of each product total
How to implement this?
Step 1: Create properties.
- Create a Pagelist property ‘LineItem’ of Applies to class as Purchase request work class with context as “XYZ-Data-Customer”.
- Create individual properties Cost, Quantity, TotalCost under XYZ-Data-Customer class.
Step 2: Include a repeating grid in the section with source as ‘LineItem’ property and add the properties.
Add Subtotal property in a separate layout below the grid.
Step 3: We need to create 2 declare expressions:
- Total – for each product
a) Go the TotalCost property from App explorer and create a new DE.
Set Page context as ‘LineItem()’
b) Configure the expression as Quantity * Cost
Now we need to create a DE for Subtotal property.
Follow the same step a).
c) Configure Subtotal = Sum of (LineItem().TotalCost)
Now both the declare expressions are ready.
Step 4: Test the same in user portal.
It works like a charm 🙂
What are the things to be considered while configuring Declare expression?
- Make sure to check the “Enable expression calculation” checkbox in the harness or flow action, where the form is included.
When this check box is selected, pega adds a text file ‘expression_calculation.js’ in the HTML content which is responsible for calculating expression in the client side.
- Check at which page context, the declare expression has to run.
- After creating a declare expression, you cannot set the property value manually. But exceptionally, if you create an activity to set the property value manually before creating the declare expression. It is not recommended.
- Designer studio -> Process & rules -> Business rules -> declarative network. You can see all declarative networks within the application.
- You can debug declare expression by enabling it in tracer settings.