Declare Trigger in Pega
This is more like a continuation blog article on Declarative processing. I would recommend you to visit my another blog article on Declare expression rules.
I already about some basics about declarative processing and RAG networks.
We also saw there are different declarative rules available and Declare trigger is one of those.
In the blog article, we will see in detail about Declare trigger rule.
This article was created using Pega '24 version.
Unlike Declare expression where we set value for a single property, Declare Trigger rules focus on executing an activity in response to any business events.
Just like other declarative rules, both these rules get invoked automatically and they don’t need any manual invocation.
The primary difference between Declare Trigger and Declare OnChange are Declare triggers listen to persistence events like (Save/Delete), while Declare On change listens to any property update in a clipboard, but both can execute an activity.
Declare Trigger:
“Imagine the Customer Onboarding scenario, where the case goes through different stages and different status. We have a requirement to track the different status change and as soon as the status is updated, we need to notify the case managers”.
To solve this requirement, we can create a declare trigger and track the property (case status) changes in the work history audit trail and also send an email via ab. We will discuss about it shortly.
Fires at updating/creating or deleting an instance
What is a Declare trigger?
– Declare Trigger comes under decision category and implements forward chaining.
– When an instance of a specific class is created, updated, or 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:
- Triggers
- 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 and commit.
How deferred save and commit works in Pega?
Commit refers to saving an instance into database table. Commit can be referred to as the Database transaction.
Let’s consider a scenario, when in the work flow you need to capture and update the case details and send out an email via background processing. Updating case details and queueing can be considered as a single transaction. Say, if updating case details fails, then queueing should also fail!!
In such a situation, we should not keep committing to the database on updating cases and then again should not commit to queueing. We should have only one commit. In this case, we can defer save the instances (case and queue) and do a single commit at the end.
In activity steps, we have the Obj-Save and Commit methods that can support committing database transactions.
As you can see in the below picture, we do two deferred save and one final commit.
When the case is updated, it adds an entry to the deferred list.
a) Queueing an entry also should be a deferred save which adds an entry to the deferred list
b) Database commit – This will commit all the previous deferred saves.
How do we add an entry into deferred save?
Obj-Save with write now unchecked. This will just save an entry to the deferred list and wait for a commit action to be performed to get committed to the database.
Then how do we commit the deferred saves?
Obj–save with write now parameter checked.
Instance committed to the database as soon as the Obj-save step ends. When write now is enabled, the deferred save will not be saved into the deferred list instead directly gets committed to the database.
Obj-save with write now unchecked.
Then the commit method can be executed in the following steps.
Note: You can save as many instance to deferred list without committing, but when the commit occurs, it checks all the instance in the deferred list and commits everything to the database as a single transaction.
Let’s go back to the options.
1. Deleted – The declare trigger gets executed whenever an instance is deleted with Obj-Delete method. It doesn’t matter if the write-now parameter is checked or unchecked the trigger activity always gets executed.
2. Saved – The declare trigger gets executed whenever an instance is saved with Obj-save method. It doesn’t matter if the write-now parameter is checked or unchecked the trigger activity always 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 or 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.
We have an OOTB Declare trigger that helps with copying the case status to old case status – StatusElapsedCalculation.
You can also create a new case and check the different status of the properties under pyWorkPage.
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 the child requestor. The trigger activity can use only the primary page. If you need any commit operation, then do it manually using the commit method.
For demo purposes, I am going to use a simple activity that logs the case status on execution.
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 If we want to track a property, which is available in the CustomerDetails embedded page property, then we need to specify the page context as shown below:
Let’s Save the Declare trigger rule. Now it is time to test the rule.
How to test a Declare trigger rule?
Scenario: Imagine the Customer Onboarding scenario, where the case goes through different stages and different status. We have a requirement to track the different status change and as soon as the status is updated, we need to notify the case managers.
Step 1: Create a trigger activity, but instead of notifying customers, I will keep it simple to just add a log entry.
Note: In the trigger activity you can perform whatever your actions as the activity steps.
Make sure in the security tab, update the type as Trigger.
Step 2: Create a new declare trigger as shown with the below configuration.
No need to refer to this declare trigger rule at any place. Automatically this will be triggered on a save.
Step 3: Open the tracer and test this in the user portal.
You can see declare trigger gets executed on the deferred save of the instance.
Note: From the tracer you can already see a lot of OOTB triggers getting executed. You can also explore the different Declare triggers.
How to implement field-level auditing?
Field-level auditing can be implemented by a declare trigger rule auditing the property changes within the case.
You can go to the Case Designer -> Settings -> Auditing -> Enable field audit
Step 1: First step enable the field audit toggle button
Step 2: Enable the property which you need to monitor as field-level auditing.
We will select the case status field.
Step 3: Click on Save. On Save, a declare trigger along with its supporting rules are created.
Rules created –
- pyTrackSecurityChanges – Declare trigger rule
- pyTrackSecurityChanges – Data transform rule
Declare trigger rule
You can also open and check the Declare trigger rule configuration.
Data Transform rule
Step 4: Create a new case, complete the customer details and check the audit tab.
We can verify the audit trail history.
What are the Things to remember when you use trigger & Onchange rules?
– Both these rules run on the server side.
– When both the rules get 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.
