Press "Enter" to skip to content

What is Declare index in Pega?

20

Introduction

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.

Scenario:

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.

  1. Warnings will always belong to a rule instance.

So Pega made the Rule pzInsKey as one of the key  – pxInsIndexedKey

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

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

  1. Indexes

Indexes tab

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

(Embed-Warning)                                              (Index-Warning)

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

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

  1. Create a new Index class – Include 3 key properties

pXInsIndexedInskey, pxIndexcount & pxIndexPurpose are the three key properties

  1. Create new properties that we need to expose in Index table

Create those properties under Index class.

  1. Create a new database table instance and map the Class with the Index table created in DB.
  2. 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.

 

  1. Muthu Muthu

    Hi
    I have a requirement like the work party have contact, follower_1, Follower_2 like that. I want to write a index table only for follower entry. How to restrict the contact entry. pls help me.

    Regards
    Muthu

    • Premkumar G Premkumar G

      Sorry for the late reply. I was out of town.
      I don’t think you can configure this in declare Index rule!. In the workparty rule, using data transform you can copy only the followers to new page list property (not pyWorkParty) and then create a declare index for that pagelist property. This will come at the expense of creating a dedicated table.

      Hope other people will share their views here!

  2. mahesh mahesh

    Very confusing still

    • Premkumar G Premkumar G

      Hi Mahesh, please feel free to comment your questions below 🙂

  3. Manasa Manasa

    Hi Prem,
    Can you post session on Debugging tools.

    • Premkumar G Premkumar G

      Okay Manasa, I’ll try to post it soon. I’ve noted it down. Stay tuned 🙂

  4. Vinod Vinod

    Hi Bro,
    Thanks for u r valuable information, can you please post information about PEGADB, how to access this db, How to see the DB columns etc..

    • Premkumar G Premkumar G

      Thanks Vinod 🙂 . I will make a note on your request !!

  5. pradeep pradeep

    Hi prem,
    can u post session tickets

    • Premkumar G Premkumar G

      Sure Pradeep. I will try to make a post on tickets soon 🙂

  6. pradeep pradeep

    hi prem,
    please tell me the default activity used to create work object?

    • Premkumar G Premkumar G

      Hi pradeep,

      You can make use of 2 OOTB activities sequentially.
      CreateWorkPage – creates a new workpage (pyWorkPage)
      AddWork – Creates a new workitem.

      You can also use some OOTB activities to initiate starter flows.

      Access Designer Studio -> Process & Rules -> Processes -> APIs
      You can see a bunch of OOTB activities. Check out the history tab to find the use and description of OOTB rules.

      Also i would recommend you to start the tracer when you create a new workobject. You can verify all the OOTB activities supporting workobject creation

    • pradeep reddy pradeep reddy

      thank u very much prem

      • Premkumar G Premkumar G

        You are most welcome, Pradeep. 🙂

  7. vinod kumar vinod kumar

    keep the information in short way mention its definition and uses in first rows

    • Premkumar G Premkumar G

      Okay, Vinod. Sure. 🙂

  8. pradeep reddy pradeep reddy

    Hi prem ,
    please tell me about what is meant by UIresponsiveness

    • Premkumar G Premkumar G

      Pega applications can be used in either laptop, tablet or mobile. UI responsiveness means displaying the same content in all devices using different styles and display. Different layouts, formats support UI responsiveness.

  9. surabhi surabhi

    why dont we expose the blob properties and call them in report definition instead? why to make a new column in a new table and map the properties in a new exposed column? i didnt understand the reason for creating declare index.

    • Premkumar G Premkumar G

      Hi Surabhi, I think you are confused about declare index rule. Declare index rule is created only for aggregate properties (page, pagelist etc).
      Say for example – pyWorkPage.Address.Street1, pyWorkPage.Address.Street2 are two properties in the clipboard
      Here Address is an aggregate (page) property. If you need to expose single value properties like street1 and Street2, then you can use declare index.
      You cannot expose the aggregate property directly in the database, you need another pointer (table ) to expose the single values that come under aggregate properties

Leave a Reply

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

error: Content is protected !!