Declare Index – its Configuration, Usage & Execution

Before We Begin

Before entering into the discussion, let’s understand what is a Data Model in PEGA and how efficiently it can be designed in our application.

What is Data Model?

From the OSP dictionary, we would define the Data Model as the process of defining and declaring the data elements.

Every application that we use will have associated data elements. For eg, an order placed in a Swiggy application might have the below data elements,

• Ordered By
• Ordered Date & Time
• Restaurant Name
• Total Price
• Order Placed?
• Delivery Address Info
  • Flat No
  • Address Line 1
  • Address Line 2
  • City/ State
• Items Ordered (this will be repeating)
  • Name
  • Quantity
  • Price

Efficiently handling all the data elements in the system defines the extensibility and maintainability of the application. Hence it’s required to have a powerful data model irrespective of the application/technology that we work on.

Let’s quickly see how best we can define the data model for the above discussed Swiggy application in Pega.

Defining the Data Elements

Defining the data element is the process of configuring Property rules for each of the data elements in Pega. It includes defining attributes like its type, data access, UI control, etc..

Defining the data type should be based on the actual usage of the data elements and it should not be for namesake.

Declaring the Data Elements

Declaring the data elements is the process of structuring the data elements & associating the data elements to the Case/Work Object.

Why do we expose a Property in Pega?

• To keep it simple, exposing a property is nothing but creating a dedicated column for the property in the database table.
• By default, all the elements/attributes will be persisted in a BLOB column (the Storage Stream pzPVStream), in a compressed form. Such properties cannot be used in the selection column of list view (or) reports and can cause slow retrieval and processing in other operations (obj-x methods).
• We expose properties that inherit from Data- and Work- classes for different purposes namely, Reporting, Security, Data manipulations, etc.

How do we expose a Property in Pega?

• Single value properties can be exposed through the optimization wizard as shown below. The optimization wizard will create a new column for the property and copies the value from the BLOB to the newly created column for the existing records.

• If we have access to the database (On-Premise) we can create a column directly in the DB and add it to the external mapping tab of the class rule. External mapping in the class rule is mainly used when the column name and the property names differ or when the class is mapped to an external database.

• External mapping can also be used to expose single value properties inside aggregate properties like a page (or) a list. But this is not the Pega recommended way of exposing the properties when we want more than 3 properties inside a Page/List is to be exposed.

When we want to expose a list of properties from a Page/ List/ Group, then declare index is the recommended way of doing it.

What is Declarative Processing?

Declarative processing is the way of executing the defined operations automatically instead of using custom logic to invoke them. To keep it simple, declarative rules are evaluated automatically when needed to satisfy certain operations. Pega supports the below declarative rules to process the data,

• Constraints rules (Rule-Declare-Constraints rule type)
• Declare Expression rules (Rule-Declare-Expressions rule type)
• Declare Index rules (Rule-Declare-Index rule type)
• Declare OnChange rules (Rule-Declare-OnChange rule type)
• Declare Trigger rules (Rule-Declare-Trigger rule types)

Let’s discuss in detail about Declare Index rule with a business scenario in this post. We will discuss other declarative rules in the upcoming posts.

What is Declare Index?

• Declare index is a rule type in Pega which is used to expose aggregate properties like a Page/List/Group for reporting purpose.
• Declare indexes are rule instances of the class Rule-Declare-Index.
• Declare index can be seen under the SysAdmin category in Records explorer.

• Declare index helps populate the corresponding index table whenever an Insert/Update/Delete operation happens on the work object followed by a commit.

Exposing a Page/List Property

Declare Index is the Pega recommended way of exposing aggregate properties like List/ Page/ Group.

• In most of the scenarios, we will not be creating Index class, table & rule manually. Pega takes care of its creation when we optimize a property in a List/Group.

• When we optimize a property inside a page, Pega exposes it as a single value column and adds it to the external mapping tab of the class rule. To avoid this, we might need to create Index- class, table, rules explicitly, and do the necessary changes.
• Below shown is the syntax of PostgreSQL to create an index table manually following which the Index class and declare index rule should be configured.

create table pegadata.<<table-name>>
(
    pxcommitdatetime timestamp without time zone,
    pxsavedatetime timestamp without time zone,
    pxcreatedatetime timestamp without time zone,
    pxcreateopname character varying(128),
    pxcreateoperator character varying(128),
    pxcreatesystemid character varying(32),
    pxindexcount numeric(18),
    pxindexpurpose character varying(32),
    pxinsindexedclass character varying(96),
    pxinsindexedkey character varying(255),
    pxinsname character varying(128),
    pxobjclass character varying(96) ,
    pxoperatorref character varying(255) ,
    pxupdatedatetime timestamp without time zone,
    pxupdateopname character varying(128) ,
    pxupdateoperator character varying(128) ,
    pylabel character varying(64) ,
    pzinskey character varying(255)  NOT NULL,
    CONSTRAINT <<constraint-name>> PRIMARY KEY (pzinskey)
)

Configuring a Declare Index Rule

• Declare Index Rule type can be seen under SysAdmin category in the Rules explorer.

We can classify configuring a declare index rule into 3 sections,

• Context
• Mapping
• Condition

Context

• This section of the declare index rule has the aggregate property details (Page/List/Group) that are to be indexed.
• The source page context can be any level of property reference. For example,
  • .PageList().EmbeddedPage.AnotherPageList()
  • .EmbeddedPage.PageList()
  • .EmbeddedPage.PageList().AnotherPageList()
• The declare index rule will be fired whenever an operation (Insert/ Update/ Delete) happens on the configured source property.

• Index class field defines the class to which the source property attributes will be written into.
• Index class used in declare index rule should inherit from OOTB class Index- either through pattern or directed inheritance.
• Each Index class should have the below set of keys defined as the primary key constraint,
  • pxInsIndexedKey (Handle of work object)
  • pxIndexCount (Index count – Auto Increment)
  • pxIndexPurpose (Name of the Index)

Mapping

• This section of the declare index rule defines what set of properties from the source page is to be exposed in the index class.

• We can map attributes from Top, Parent, and a Custom/System page as shown in the above screenshot.
• We can also map a constant value to the index property when needed.

Condition

• Even though declare index rules are fired automatically, we can fully control its execution.
• We can evaluate a condition to decide if the operation is eligible to be written into the index table.

• Apart from a condition, we can decide to write an entry into an index table only if all the properties in the source class have not-null values using the option Index even if source class property is blank. This option evaluates all the properties in the source class.
• If a specific property should be evaluated for not-null condition, then a when rule should be created to explicitly evaluate the property.

Let’s look into a business scenario to understand the configuration & usage of the declare index in detail.

Business Scenario

OSP organization has a claims application to process the reimbursement requests submitted by the Customers. The system creates a work object in the system for each claim request submitted.

The customer should fill in his/her product information and the beneficiary details for each claim that he/she submits. OSP expects a report to view the list of claim requests submitted in the system along with the policy information and the beneficiary details for each.

Implementation

• A customer can apply a claim for only one product at a time. Hence product-related information can be grouped under a single Page property inside the work object.

• A customer can have more than one beneficiary for each product. Hence beneficiaries information can be grouped under a List property inside the work object.

• By default, the above created ProductInfo and Beneficiaries will get persisted into the BLOB column of the Claim request work table. Since we have reporting requirements based on this information, we will now expose the information using the declare index.
• ProductInfo being a page property, we must run the DB script to create an index table, index class, and configure the declare index rule by following the steps mentioned above.

create table pegadata.pr_Index_OSP_Data_Product
(
 pxcommitdatetime timestamp without time zone,
    pxsavedatetime timestamp without time zone,
    pxcreatedatetime timestamp without time zone,
    pxcreateopname character varying(128),
    pxcreateoperator character varying(128),
    pxcreatesystemid character varying(32),
    pxindexcount numeric(18),
    pxindexpurpose character varying(32),
    pxinsindexedclass character varying(96),
    pxinsindexedkey character varying(255),
    pxinsname character varying(128),
    pxobjclass character varying(96) ,
    pxoperatorref character varying(255) ,
    pxupdatedatetime timestamp without time zone,
    pxupdateopname character varying(128) ,
    pxupdateoperator character varying(128) ,
    pylabel character varying(64) ,
    policynumber character varying(64) ,
    policystatus character varying(64),
    productname character varying(128) ,
    pzinskey character varying(255)  NOT NULL,
    CONSTRAINT pr_Index_OSP_Data_Product_pk PRIMARY KEY (pzinskey)
)

• Beneficiaries being a List property, we can use Optimization wizard that takes care of creating index table, class, rule.

• The configurations are now ready. Whenever a customer submits a claim in the system, Product details will be written into Index_OSP_Data_Product, and Beneficiaries information will be written into Index_OSP_Data_Beneficiaries which can then be used for Reporting as per the business need.

Execution

• Let’s now create a claim request by providing all the required informations.

• The Product information and Beneficiary details entered by the customer will be available in BLOB of the claim work table as well be exposed in the respective Index tables.

• Now that we have the information in the Product and Beneficiary index tables along with the claim case InsKey, we can directly join this from the work class for any reporting need.

Debugging Declare Index

• Declare index events can be traced using Tracer by enabling the below setting in the tracer.

Index Population for In-flight Cases

In-flight cases are the existing cases in the higher environment (typically production) that are created on the old code base (without the recent changes). Whenever we deploy a DB/ Process/ Flow related changes, it’s always recommended to have a plan (or) strategy for the in-flight cases.

We might have come across a situation where we would have exposed a single value property and ran a column optimization job to handle the column population for the newly exposed columns for the in-flight cases.

How column population job can be executed for the newly created Index rule?💭

• Whenever we deploy our Index rule changes to a higher environment having the privilege to execute DB scripts, Pega by default runs the optimization process of the declare index rule for the in-flight cases.

• We can also use the OOTB activity RecreateIndexesForClass in Code- class to fire the index rule for the in-flight cases. This activity will not create duplicate entries if an entry already exists in the index table.

OOTB Declare Indexes

Pega provides a few OOTB index rules that can be readily used for our business needs. Few examples are,

PartyURI

OOTB index that records all the work party information added to the work object. PartyURI declare index can be readily used to report on the party (Data-Party-*) )related information by joining it with the work object class.

Skills

OOTB index that records all the skills added to Operator ID. Skills declare index can be readily used by the application to fetch the skills list of the logged-in user and implement business logic when needed.

Pointers to Remember

• Declare Indexes in Pega are rule instances of class Rule-Declare-Index.
• Declare Indexes are used to expose aggregate properties like Page/List/Group for reporting purposes.
• Declare Indexes belongs to the declarative network and are fired automatically without any invocation.
• Declare indexes can be extended for Rule-, Data– and Work– classes.
• We can use OOTB activity RecreateIndexesForClass to fire declare index for the in-flight cases.
• OOTB declare indexes PartyURI, Skills, etc.. can be used readily for reporting purposes.
• System-Declare-Changes keeps track of all the declarative rules in the system failing which will not trigger the declarative rules. Revalidation of the rule can help in that case.

Now we are at the end of this post. We hope you got some idea on how to use the declare index to expose aggregate properties like Page/List/Group for reporting needs.

We are glad to publish the article requested by @ RENUKA on “Declare Index”. If you want us to publish any articles of your choice, please fill out this form & we will make sure it gets published.