Press "Enter" to skip to content

Declare Trigger & Declare On Change in Pega

14

Introduction

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‘ (http://myknowpega.com/2017/05/17/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.

Conditions

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 admin@org.com 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.

Tracer

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

    Hi,

    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

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

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

Leave a Reply

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

error: Content is protected !!