Press "Enter" to skip to content

How to configure declare expression in Pega

45

Introduction

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:

  1. Declare Expression
  2. Declare Trigger
  3. Declare Onchange
  4. Constraints
  • 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:

  1. Expressions
  2. Change Tracking

Expressions tab:

  • 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.

  1. Target Property data

Before checking this, we need to be aware of two mechanisms involved in declare expressions:

  1. Forward chaining
  2. 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.

  1. Whenever inputs change – Forward chaining.
  2. 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.
  3. 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.
  4. Whenever used – Backward chaining. When the target property is referred, it re-computes the value again.
  5. 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.

  1. 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.

  1. 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:

  1. Total – for each product
  2. Subtotal

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.
  1. Karthik Karthik

    PRPC debugging tools LIKE TRACER,CLIPBOARD AND SYSTEM MANAGEMENT APPLICATION BRIEF OVERVIEW

    • Premkumar G Premkumar G

      Thanks Karthik noted. Will try to post it soon.

  2. bhagiradha bhagiradha

    worth full information

    • Premkumar G Premkumar G

      Thank you so much, Bhagiradha.

  3. Himasekhar Reddy Pucha Himasekhar Reddy Pucha

    Hii PremKumar,

    Can you please Explain the scenario of when user enters DOB Field How to calculate age Automatically

    • Premkumar G Premkumar G

      Step 1: Create a declare expression for property Age.

      Step 2 : Use forward chaining, whenever the input change.

      Step 3: Write down the expression to calculate the difference in year between DOB and current year. Use expression builder.

      I hope that I explained all these in the post. Please look into it.
      If you are any doubts further, then please feel free to leave a comment. 🙂 😊

    • Himasekhar Reddy Pucha Himasekhar Reddy Pucha

      Hii Prem Kumar,

      I am Unable to Write expression Kindly share Expression

      • Premkumar G Premkumar G

        @DateTime.DateTimeDifference(.DOB,@DateTime.CurrentDateTime(),”Y”)

  4. Ramana Ramana

    Well done boss.
    It is nice exploration….And very useful.

    • Premkumar G Premkumar G

      Thank you so much for your appreciation, Ramana. 🙂
      It means a lot to me and I’m glad that you are finding it useful. 🙂

  5. Sruthi Sruthi

    Hi,
    Thanks for your posts. This has been really informative.Could you also post some information on Dclare Indexes and Obj methods as well?

    • Premkumar G Premkumar G

      Thank you so much for your appreciation, Sruthi. 🙂
      Okay, I will try to post them soon. 🙂
      Stay tuned. 🙂

    • Sruthi Sruthi

      Sure thanks 🙂

    • Sruthi Sruthi

      Thanks for your post on Declare Index.

      Could you post info in detail regarding Rule Availability and Rule Resolution?

      Thanks
      Sruthi

      • Premkumar G Premkumar G

        Yeah sure. Rule availability is coming next 🙂

    • Sruthi Sruthi

      Great work. Thanks 🙂

      • Premkumar G Premkumar G

        You are welcome, Sruthi. 🙂

  6. Upendra Upendra

    Hi PremKumar..

    It is worth full information

    • Premkumar G Premkumar G

      Thank you so much for your appreciation, Upendra. 🙂

  7. Upendra Upendra

    Hi Prem,
    i am unable get Age using the following expression @DateTime.DateTimeDifference(.DOB,@DateTime.CurrentDateTime(),”Y”).

    In this Case
    DOB property type is DateTime and
    Age is Integer

    • Premkumar G Premkumar G

      Hi Upendra,
      DateTimeDifference returns result in ‘double’ data type. You are able to set it to integer property.

      Please check the expression – Age = (value of) = Expression. Kindly double check it. It should work 🙂

  8. Raghav Raghav

    Good one, please continue 🙂

    • Premkumar G Premkumar G

      Thank you so much, Raghav. Glad that you like it. 🙂

  9. Mohith Reddy Mohith Reddy

    Hi Prem,

    Could you please explain about Locate Page Expression and Locate Page Activity in the Pages and classes Tab ? if possible with an example

    • Premkumar G Premkumar G

      Hi Mohith,

      Sorry for the late reply! You can see two options in pages & classes tab – Locate page expression and activity.
      Say for example, You use a declare expression rule, that makes use of property available in some other user page like “PolicyDetails”
      We can make sure that this page is available in the clipboard for declare expression processing.

      Check a sample activity ‘Locate’. You can populate all the required values.
      In some situation, we don’t want to populate the page ( available already), then you can make use of this expression field to conditionally run the locate activity when the expression returns true 🙂

      Don’t worry much. We don’t use it often

  10. Apurva Apurva

    Nice post Prem. Looking forward to see more on Performance tools.

    • Premkumar G Premkumar G

      Thank you so much, Apurva. 🙂
      Yeah you will see them soon. 🙂

  11. Naren Venkataraman Naren Venkataraman

    Hi Prem
    Why would we need to use Property-Seek-value method, if we have set ‘Whenever used’ in change tracking tab.

    BTW thank you for your work, its better than referring PDN.

  12. saiee saiee

    Very clearly and neatly explained.Its very useful.Thanks a lot Prem.

    • Premkumar G Premkumar G

      Thank you so much for you appreciation and you are welcome, Saiee. 🙂
      Glad to hear that you find it useful. 🙂

  13. Rupesh Rupesh

    Hi Prem,

    Without the Property-seek-value activtiy method , we cannot run backward chaining declare expression rule ?.

    Thanks
    Rupesh M

    • Premkumar G Premkumar G

      no no. declare expression rules run declaratively. We can also force the declare expression rule to run proceduraly using property-seek-value method

  14. saiee saiee

    Hi prem,
    I just need a clarification as declare expression will trigger automatically.why do we need to use property seek method to invoke it manually?can you please explain?thanks in advance…

    • Premkumar G Premkumar G

      Hi Saiee, valid question :). there may be some situation, where you need to show a prompt to the user to enter the missing values.
      Say for example, you are in a feedback back. when you enter particular data, a pop up may arise to enter additional relevant data. It is kind of backward chaining to get the missing values.

      So Through property-seek-value, we can force backward chaining and throw some prompt for user to enter missing values.

      If everything happens at the back-end, then we may not provide the capability to enter the missing values!!
      Hope you are clear now 🙂

    • saiee saiee

      Thanks a lot Prem..Understood the concept.

      • Premkumar G Premkumar G

        You are most welcome, Saiee. 🙂

  15. Tejaswi Tejaswi

    Thanks a lot Prem for detailed post on DE

    • Premkumar G Premkumar G

      You are welcome, Tejaswi. 🙂

  16. Pradeep Pradeep

    Hi Prem,
    I need some clarification in backward chaining.
    Target property is T.
    when T = A + B + E // here we know A & B but not E
    E= C +D // here we know C + D

    Is it like when T used, In (A + B + E) calculation, as E(null) is dependent to T
    First it will calculate E(C + D) and then calculates T
    and so on it will check no. of dependencies and then calculates T(Target property)

    Correct if am wrong in understanding

    • Premkumar G Premkumar G

      Exactly Pradeep. Happy that you understood correctly 😊

  17. Kartheek Kartheek

    Hi Prem,

    I want How to call Decession Table in Declare Expressions for city and state properties

    • Premkumar G Premkumar G

      Hi Kartheek,
      In the expressions tab drop-down, you have an option to set the value from the “result of decision table” , “result of decision tree”, “result of map value”

  18. Naga1812 Naga1812

    Nice Explanation..Can you please give a post on TRACER?

    • Premkumar G Premkumar G

      Thank you so much, Naga. Yeah, I’ve taken a note of that topic and I’ll post about it soon. Stay tuned. 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *

error: Content is protected !!