Think of why the rule is given such a name 🙂 We all might have come across the term Index.
Take a text book, in the first page you will see an index. ‘What is the main purpose of it?’
Yes, you are right 🙂 It contains page numbers to access the topics quickly. So instead of going and searching page by page, you can directly use index and find the topic.
- Quicker access
- Saves time
Okay, cool! Now I am going to relate the term index with Pega.
Pega can store the data either in the clipboard memory or in the database tables.
Clipboard memory – Some data, we just need it for temporary purpose to process the requests
Database memory – Some data, like customer information can be used in future for reference
Okay. Now come to database. (I am going to touch the basics alone)
Database -> Schema -> Database table
We store each individual data (Customer name, phone number, etc.,) in separate columns, in some dedicated database table.
Say for example, I need to persist the below data in DB table.
- Customer name, Age, Phone number are single value properties and can be easily stored in separate columns 🙂
- But what about Street, City & State. Yes, they are single value properties but comes under a page property ‘Address’.
Is there a way to persist the record? Yes, we can.
We use BLOB column in tables ‘pzPvStream’ to store those aggregate values.
What is BLOB?
- Binary Large Object. Collection of binary data stored under single entity (column).
- They are efficient and flexible mechanism used by PRPC to compress the data.
- They can contain any amount of information comprising of simple single value properties to complex page list structures.
So when we save a case which contains some page properties (like policy, address), all those data get compressed and stored inside BLOB.
Don’t think I am speaking out of syllabus on Declare Index 😉
Those are just basic operation on how Pega stores the data.
Now, I have a requirement to take a report on the customer data. Customer data are stored in customer table.
The report column should contain Customer name, Age, Street, City.
Note: We can use report definition to get the data from BLOB at the expense of performance. RDB queries cannot use BLOB Data.
- Customer name & Age are exposed columns.
- Street & City are stored in BLOB.
Say, you have got millions of record in the table. You need to decompress heavy data to get the results.
As a result, totally it is time consuming. You need to sit and wait for few seconds, while the report gets loaded.
Pega provides a solution for this performance issue, which is ‘DECLARE INDEX’
What is a Declare Index rule?
- It comes under SysAdmin category.
Think about how the index page in a book serves us. Like the same, Index tables can be used to store the data that are embedded in aggregate properties.
We can directly refer to that index table, instead of decompressing the blob and checking the details inside blob.
- It helps in creating index for the properties (state, city, etc.) embedded in aggregate properties (address).
What do you mean by creating Index here?
- We are going to create a new table!!!
Yes. A new table with exposed columns as Street, City, State.
You should get a question here 🙂
- I can create a DB table manually and save those details, then ‘Why in the world would we need these declare Index rules?!’
The answer is simple. Declarative processing!
Yes. It updates those tables automatically at the back end. They can delete rows or insert rows in the Index tables.
We will see all these interesting stuffs, later in the post 🙂
- They improve the database performance (No decompression from BLOB).
Let me reveal you some Interesting Index, Pega use in their designer studio.
Step 1: Designer studio -> Application -> Guardrails -> Warning details
You can see reports displaying the rules with warnings.
Step 2: Consider any rule Instance. Do you know which property in the rule instance holds the warning details?
Open any rule from the warning details report (use the link in rule column).
- Go to other action button. Open view XML & search ‘pxWarnings’ (collapse other fields).
- You can see that the warning details are stored in a pagelist property ‘pxWarnings’.
You can open the pagelist property and check it 🙂
Note: All the rule instances will be stored in a table ‘pr4_rule_vw’. You can check the table in rules schema. ‘Data-Rule-Summary’ class is mapped to this table.
Step 3: Now use Live UI and check the report definition rendered for warning details landing page.
Section name – pzGuardrailsDetailedApp
Report definition name – pxRuleWarningsInApp
You can see the report definition is querying the pr4_rules_vw table (Data-Rule-Summary class) and joining with Index-Warning class. (table name = ?? ) Wait 🙂
Let’s check how Pega is implemented using Declare Index.
Step 1: Identify the Index class.
Note: Always the Index classes should inherit from Index- as pattern inheritance.
Open the class ‘Index-Warning’ and check the test connection.
You can see the Index_warnings class mapped to pr_index_warnings table.
Let’s analyze the Index_Warnings class:
- Concrete class
- Keys – 3 keys 😀
Keys identify unique instance for a particular concrete class.
What is a key?
For reference, let me show the key for any work class.
Because every work item (Instance of the work class) is differentiated by keys pyID (Ex: S-1 etc.,).
So you will get a question now. ‘Why 3 keys for declare Index class?!’ 🙂
Pega played wisely here
As we can see in this warnings example, tell me how you will identify the warnings.
- Warnings will always belong to a rule instance.
So Pega made the Rule pzInsKey as one of the key – pxInsIndexedKey
- But we know that each rule instance can contain more than 1 warning (so what, pxWarnings is a page list property).
So Pega introduced another key – pxIndexCount
- Do you think these 2 keys are enough to uniquely identify a Index row. NO. There may be some situation, where you need to expose more than one aggregate property in a particular class.
Spoiler: Pega index the Custom-Fields too in the rule class. It means there are two aggregare properties Indexed in rule class. So you need an additional key to differentiate both. So Pega introduced 3 rd key – pxIndexPurpose ( this will be inherited from declare index rule name )
Step 2: Identify the database table instance
Search Index-warning in search box and open the database table instance.
You can see Pega made the database table instance mapped to pr_index_warnings table.
Step 3: Identify the database table pr_index_warnings in DB.
- Pega exposed the required columns need for reporting purpose.
- You can see the first two rows belongs to same rule. They are differentiated by pxIndexCount
Step 4: identify the declare Index rule
- Search and open the declare index rule ‘Warnings’
You have a single main tab here.
Source page context – Specify the page or page list property we need to expose.
Note: For Pagelist omit the subscript. You can see how pega used in this rule. pxWarnings()
Source page context class – Specify the page definition of embedded property.
In our example, you can see the page definition for ‘pxWarnings’ page list.
Index class to write – Specify the Index class we saw before.
- Pega used Index-warning class.
Properties for indexing and mapping – before you need to create all the single value properties, we are going to expose in the index tables.
You can see the properties in Index-Warnings class.
- After creating all properties in Index class, we need to map those properties with values from the source class
Properties in Source class —————–> Properties in Index class
- So you can visualize the role of Declare index from the 4 steps J
Yes Declare Index rule helps in updating the Index table with values from source class.
Here the declare index updates the warning table with the value from rule class.
Indexing condition –
You can use a when rule and enable it.
When true – New indexes get added. Normal behavior as if no conditions added
When false – No new indexes are added. It also deletes existing indexes.
Note: You can leave this blank for normal behavior
Index even if source class property is blank –
Example – consider address as source values. If the user provided only city value and Street & state are blank
- True – Index gets created even if few source properties are blank. In the above case it will fire
- False – index gets created only when all the source property has value. In the above case it will not fire
All rules are ready now.
When the declare rules will be triggered?
- First think about when the warnings can be added to the Index table?
Yes you can commit it whenever the rule instance is committed to database.
- Think what will happen, If we delete the rule instance?
The warnings should be cleared from the Index table.
- What happens, If we update the warnings in the rule instance?
The warnings should be updated in the Index table
So It’s basically a forward chaining 🙂
- Whenever an instance is commited saved/deleted, then the declare Index will fire and update the index table.
Note: Declare Index will not update, If none of the source properties change. There is no need right 🙂
Don’t worry about these triggering, Pega rule engine masters it 🙂
Its happy time to test what we learned
Step 1: Create a new activity rule
(Activity always have a default ‘moderate’ warning & suggests to use data transform)
Step 2: Go to other action button – View XML & get the pzInsKey of the activity rule.
Step 3: Open the database and write down the query to browse the PR_Index_Warnings table to get the warnings for that activity rule.
Note: Use where clause to browse using using pxInsIndexedKey = pzInskey
Yes :). We got the warning committed today.
Step 4: Now justify the warning & check in the rule.
Step 5: Use the same query to refresh the data. You can see the warning updated.
what are the things to remember when implementing a new Declare Index?
- Create a new Index table.
If you don’t have the privilege to create a new table, seek DBA team advice and get it done.
- Create a new Index class – Include 3 key properties
pXInsIndexedInskey, pxIndexcount & pxIndexPurpose are the three key properties
- Create new properties that we need to expose in Index table
Create those properties under Index class.
- Create a new database table instance and map the Class with the Index table created in DB.
- Finally create declare Index rule and configure all the details
I will end the post here 🙂
How to code a new declare index rule and use it?
Visit my next post on step by step tutorial.