Press "Enter" to skip to content

Declare Trigger & Declare On Change in Pega



In this post we will see how to configure a declare trigger and declare on change rule in Pega.

  • Unlike Declare expression where we set value for a single property, Trigger & On change rules focus on executing an activity in response to any business events.
  • Both theses rules get invoked automatically and they don’t need any manual invocation.
  • The primary difference between these two are Declare triggers listen to persistence events like (Save/Delete), while Declare On change listens to any property update in a clipboard.

Declare Trigger:

“Imagine a scenario, where you are a buying a property. Buying a property involves many people to approve and adjust the total cost. Broker can set the amount to 10 lakhs, but this amount can be adjusted by the owner and any other related parties involved. We have a requirement to track the total cost at each stage and who have updated the cost”.

In Pega, we can create a case and the case can be routed to multiple assignee. Assignee can update the case with the revised amount.

To solve this requirement, we can create a declare trigger and track the property (total cost) changes in the work history audit trail. We will discuss it deeply below.

Fires at update / create or delete a case

Declare On Change:

“Imagine the shopping cart in a website. Whenever we add some special products, the business policy may involve complex calculation to determine the subtotal amount and may involve adding a gift. This complex calculation may involve some java steps and functions and can be achieved by using an activity”.

To solve this requirement, you can create a Declare on change to monitor the properties and execute an activity when the property changes.

Fires at change in a property

What is a Declare trigger?

  • It comes under decision category.
  • It implements forward chaining.
  • When an instance of a specific class is created, updated, deleted, it can execute an activity.
  • Declare triggers can automatically update the history of a workitem, when certain property change. We will see about this later in the post.

How do we configure a Declare trigger rule?

  • Create a new declare rule from decision category.

There are two important tabs in a declare trigger rule:

  1. Triggers
  2. Pages & Classes

Triggers tab

a) Trigger when an instance is

We have five options here

Before explaining this, I need to explain the basic of deferred save/delete.

How commit works in Pega?

  • In activity, you might have come across the methods, ‘Obj-Save’ and ‘Commit’.

You can commit in 2 ways:

  1. Obj–save with write now parameter checked.

Instance committed to database as soon as the step ends.

2. Obj-save with write now unchecked. Commit can be done in the following steps.

After the Obj-save step, the instance gets saved in deferred list and not committed to database.

  • You can save many instance to deferred list without committing.
  • When a commit occurs, it check all the instance in the deferred list and commits to database.

Let’s go back to the options.

  1. Deleted – The declare trigger gets executed whenever an instance is deleted with Obj-Delete method. No matter how you check, write now or not triggers gets executed.
  2. Saved – The declare trigger gets executed whenever an instance is saved with Obj-save method. No matter how you check, write now or not triggers gets executed.
  3. Committed Save – The declare trigger gets executed, whenever an instance is saved and committed in database. Obj-save with write now checked, Commit method to commit the deferred saved instances (Obj-saved with write now not checked).
  4. Committed Delete – The declare trigger gets executed, whenever an instance is deleted and committed in database. Obj-delete with write now checked, Commit method to commit the deferred deleted instances (Obj-deleted with write now not checked).
  5. Saved and One of the properties was modified – The declare trigger gets executed, whenever instance is saved and One of the properties listed below is modified.

You can list the properties here to monitor. We also have an option copy the values to a different property.

Why do we use this?

Imagine you are in a form updating cost value. You updated to cost = 100 and declare trigger gets executed. It copies Cost value to Oldvalues.Cost

So now, Cost=Oldvalues.Cost =100

Again, when you change the value (cost=200) and you need to know what is the previous value, you can directly refer from Oldvalues.cost which is still 100.

b) Condition – You can specify a ‘when‘ rule here.

When‘ rule true  – Activity gets executed.

When‘ rule false – Activity never gets executed.

c) Trigger activity

Name – Specify the name of the activity. Remember to specify the activity type as trigger. You can also specify parameters for the activity.

Execute –

  1. Immediately – The activity gets executed in the same requestor immediately before the commit completes. Trigger activity cannot perform any commit operations because they are already running in database commits.
  2. In Background On Copy – The activity gets executed in child requestor. The trigger activity can use only the primary page. If you need any commit operation, then do it manually using commit method.

Pages & Classes tab

Pages and classes – Enter the name of the page referred in the triggers tab. This is normally the same for all rules.

Page context data – We know that we can watch properties in the declare trigger rule.

  • If the property we watch is a single value property available in the top level class, then leave it empty.
  • If those properties are available inside an embedded page, then you can specify the Page context and page class. Imagine we are tracking a property, ‘Cost’ which is available in the LineItem page list property, then we need to specify the page context as shown below:

How to test a Declare trigger rule?

Now it’s time to test our own declare trigger rule.

Scenario: Track the total cost property values in each page in the page list LineItem.

Step 1: We are going to use the same screen we discussed in ‘Declare Expressions‘ ( lesson.

This screen is built using a Repeating grid with ‘LineItem’ as source.

Step 2: Create a simple Declare trigger rule that copies Total Cost to a new property for tracking purpose.

Remember to specify the page context as ‘LineItem()’.

Step 3: Test in user portal. So, whenever Total cost property in the grid gets updated and saved, the value is copied to new property ‘OldTotalCost’.

Set Total cost = ‘14’, start the tracer and save the form.

You can see declare trigger gets executed on the deferred save of the instance.

Now, let’s check the clipboard if the OldTotalCost is set to ‘14’.

Guess what? We got it correctly 🙂

How to implement field level auditing?

  • Field level auditing can be implemented by a declare trigger rule auditing the property changes within the case.

Designer studio -> Process & rules -> Work Management – > Field level auditing

Step 1: Select the case type and then select the property, which we need to monitor. Here the same property Subtotal.

Step 2: Click on Submit. On submitting a declare trigger along with its supporting rules are created.

Rules created –

  1. pyTrackSecurityChanges – Declare trigger rule
  2. pyTrackSecurityChanges – Data transform rule

Declare trigger rule

Data Transform rule

Step 3 : Set the Subtotal to 25. Save the form. Now again change the Subtotal to 50. Save it again.

We can verify the audit trail history.

What is a Declare Onchange?

  • It comes under decision category.
  • It implements forward chaining.
  • When a value of a specific property changes, then it can execute an activity.
  • Generally, it is used to do complex mathematical calculation. It can also track a status of the work item.

How do we configure a Declare Onchange rule?

  • Create a new declare rule from decision category.

Similar to Declare trigger, here also we have two main tabs:

  1. OnChange properties
  2. Pages & Classes

OnChange Properties tab

Properties To Watch

You can List as many properties as you want. The properties can be in top level page or embedded page.


When – Specify a ‘when’ rule.

Choose action – You have two options:

  1. Call activity – You can call an activity of type Onchange.
  2. Suspend work Object.

What is suspend workobject?

  • Imagine a scenario, when an unexpected business exception scenario occurs.

For an electric bill paying application, the bill amount should never come below 0 – means negative.

We can have a Declare onchange rule to check the Billamount property changes.

Specify the ‘when’ rule to check, if the bill amount is less than 0. If yes, then you can suspend workobject.

  • What actually means is that we are suspending all the assignments for the workitem. The assignment owner will be notified by an email. No one can work on the item till the reviewer approves.
  • The status of the workitem gets changed to ‘Pending – PolicyOverride’ and a new assignment is created in ‘Assign-Suspend’ class.
  • The flow identified in the rule moves the assignment to the reviewer.
  • The Reviewer can either allow or deny the process.
  • Pega provides sample rules which you can customize in your own application.

How to configure suspend workobject?

Step 1 : Create a Declare onchange rule. Specify the target property say – Subtotal.

Step 2: Specify a ‘when’ rule, that checks if subtotal is negative.

Step 3: Configure the rule form with standard flow and message rule.

Step 4: Create a work item in user portal and test the same.

Step 5: Now submit the case.

  • The default routing activity in policy override flow routes this assignment ‘Assign-Suspend’ to operator ID. He/she can review it and decide either to allow or deny the exception.
  • On denying the workitem is resolved.
  • You can customize the router activity ‘ToPolicyOverrideOperator’ to suit your requirement.

Huh let’s come back to the tab.

After specifying call activity, we have two choices. If the ‘when’ evaluates to true to one can run one activity and if it evaluates to run to one can run different activity.

Pages & Classes tab

Same like declare trigger rule. We discussed above.

How to test a Declare Onchange rule?

Scenario – We are going to track the subtotal property. Whenever the total purchase is above 10,000, we are going to add a gift watch in the cart.

Step 1: Create a new declare Onchange rule that monitors Subtotal property.

Step 2: Create a ‘when’ rule – SubTotalAboveTenK

Step 3 : Create a new activity of type Onchange and add it in rule with, when evaluates to true.

Step 4: Save the rule form and check it in user portal. Remember to include refresh strategy in the grid.

After updating, the subtotal greater than 10, 000.


We have successfully implemented both the scenarios.

What are the Things to remember when you use trigger & Onchange rules?

  • Both these rules run on server side.
  • When both the rules gets executed, a clipboard page called ‘pyDeclarativeContext’ of class ’Code-Pega-DeclarativeContext’ is created and contains ‘pyChangeProperties’ value list property. This property contains the changed property, which results in triggering the declare rule. This page exists only when the rule runs and gets removed.
  • Declare expression & constraints rules do not execute within on change activities.
  • Use tracer to debug, remember to check Declare trigger, Declare Onchange checkbox in the Events to trace settings option in the tracer.
  1. bhagiradha bhagiradha

    good explanation

    • Premkumar G Premkumar G

      Thanks Bhagi 😊

  2. Sai Sai

    Post about index rule.

    • Premkumar G Premkumar G

      Will post it soon, Sai 🙂

  3. Ramana Ramana

    Super Macha

    • Premkumar G Premkumar G

      Thanks Ramana 🙂

  4. ramana ramana

    good explanation keep going on.

    • Premkumar G Premkumar G

      Thanks Ramana. I will keep on sharing my Pega knowledge 🙂

  5. Rupesh Rupesh

    Hi Prem,

    Can you please help me to understand the below points.

    a)For Declare Trigger we have options like a)immeditely b)In Background on Copy

    for Immeditely option you have mentioned some point like “they are already running in the data base commits “-> what does it mean

    b)we have two rules like “FinishPolicyOverride” and “PolicyOverrideStarts”-> Is this two rules are pega rules or you have created them .

    can you please share the images of the rules if possible.

    Rupesh M

  6. Bharath Bharath


    I have used one property in declarative rules, I want to know know how many times its got triggered, so how can I achieve this, please help me

    • Premkumar G Premkumar G

      Hi Bharath,
      Try to make use of Field level auditing functionality to maintain the property history.

      Process & Rules -> Work Management -> Field Level Auditing

  7. Giraj Giraj

    Hi Prem,

    Good article.
    In trigger One question is if page context is .Lineitem() and selected option is Committed Saved.
    If the page is embedded like this pyWorkPage.lineitem then when it will fire.
    Because Lineitem will directly not commits here as pyworkpage and lineitem class is different.

  8. Preethika Preethika

    Hi Bro,

    Your way of explanation is really awesome. you are doing a great job:)

    BTW , u have mentioned trigger and on change rules run on server side.
    what is the difference between client and server side.

    can u throw some light on this .

    Thanks in advance. 🙂

    • Premkumar G Premkumar G

      Hi Preethika,

      For every action you do in user portal, your client (browser) sends a HTTP request to the server. The server sends the response and build UI from the server response.
      Now in some cases, you can skip server processing, you can handle things in client using Javascripts loaded in the browser. Declare expressions can run on client side

  9. Nandini Nandini


    The content looks awesome, Thanks for writing..

    I want to understand how this declarative processing works, what is the component that listens to the changes and will the declarative rules run in current requestor context or is there any other configuration, what will be the requestor type for declarative processing etc.

    It would be helpful if these are explained.

    Thanks for your time in advance.

  10. Suhasini Suhasini

    Hi Prem,

    Nice Explanation. I have small doubt, In Declare Onchange suppose I have given two properties(p1,p2) to watch andonchanage activity.Iin the onchange activity I am reffering p2 with chanaged value so again onchange activity will triggered. Can we refer the properties P1,P2 in onchange activity?. If we are referring the properties multiple times it will trigger the activity multiple times(Infinity loop). is this is recommended?

    • Premkumar G Premkumar G

      Yes Suhasini, you should be cautious in that!!. As you mentioned, you will end up in infinity loop. Always do not update the declare change watching properties inside declare change activity rule

  11. Suhasini Suhasini

    Hi Prem,
    Continuation for the above question. if we refer a property to watch property inside a declare onchnage activity, it will not became infinity loop it seems. there is a way to control it seems. I have verified , but no where i didn’t get any information regarding this. can you please let me know if u have any idea on this.

  12. Bharath Bharath

    Hi prem,

    When we call the commit method in activity then it commits the all the instances in the deferred list right. But I would like to save the only one instance in that deferred list once I called the commit method. How can I achieve this thing.

  13. Krishna Krishna

    Thanks alot Prem.. 🙂 Really useful.
    It would be better if Forward and Backward chaining is also explained here.

  14. Sam Nguyen Sam Nguyen

    Hi Prem,

    Great work!!

    For the implementing field level auditing, just a quick question about having more attributes like SubTotal within the same case. Will there be additional data transform and declare trigger rules created accordingly or…?


  15. Nalini Nalini

    Hi Prem,
    Well explained. I have small doubt in declare trigger. Is it recommended to use obj-save in declare trigger activity ? Because there are some scenarios where i have to save the business logic to data base when this activity triggers. In this scenario will the declare trigger activity gets executed within the trigger activity ?

  16. Siva Siva

    Can you please elaborate this. Still i am not able to understand Client Side and Server Side concepts. Confusing.

Leave a Reply

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

error: Content is protected !!