Press "Enter" to skip to content

Obj and RDB methods in Pega



In this post, you will see different obj methods and rdb methods and how to use them in a activity.

I will be post the key difference at the end of the post ๐Ÿ™‚

We will discuss the following methods

  1. Obj-Browse
  2. RDB-List
  3. Obj-Open / Obj-Open-By-Handle
  4. RDB-Open
  5. Obj-Save
  6. RDB-Save
  7. Obj-Delete / Obj-Delete-By-Handle
  8. RDB-Delete

Before that letโ€™s discuss some basics ๐Ÿ™‚

  • We know, in Pega we persist the data in database.

So, how do you communicate with the database?

  • you need a language and its Structured Query Language – SQL.

So you think everyone should be certified in SQL language to establish the communication between pega and database systems.

No No. Remember, Pega always makes it simple for developers.

  • Pega builds its own query(exception – RDB methods). All you need to do is provide some valid input to pega system through Obj methods.
  • There may be some complex query, where you may be forced to use RBD methods.
  • you need to know some SQL basics to work on RDB methods.

Note: Prefer using report definition, in case you can achieve your complex reporting requirement using report definition.

A post on report definition will peep soon ๐Ÿ˜‰

So how the preference should be?

1) Always try using Obj methods

2) For complex query fetching, try report definition.

3) If you can’t achieve your requirement using the above two choices, then go with RDB methods.

What is a Connect-SQL rule?

I planned to make a separate post on Connect-SQL. So here I will touch some basics.

  • We know SQL query helps in communication between Pega application and backend database.
  • Pega provides connect-SQL rule to run complex SQL queries or call store procedures against the database.

Letโ€™s see how we can create a new SQL rule

Step 1: Create a new Connect-SQL rule.

Package Name โ€“ This is required, but no restricted. You can specify any key value here.

Step 2: Fill all the details and click on create button. Analyze the tabs available.

Open โ€“ RDB-Open; Delete โ€“ RDB-Delete; Save โ€“ RDB-Save; Browse โ€“ RDB-List

For demonstration purpose, I am going to use my work table


Before we go through the methods, we need to know ย how we perist data in Pega.

  • Only concrete classes can be mapped to database table. So whenever we persist the concrete class instance, a record gets saved or updated in database table.

Let’s say, I can have a concrete class – OIKGGB-MyKnowPega-Work

This class is mapped to ‘pc_oikggb_myknowpega_work’

Step 1: Open the class – OIKGGB-MyKnowPega-Work

Step 2: Click on the test connectivity button, to check the mapping.

Now let’s check the class instances.

Step 3: Click on App explorer and click on the class, you will see the instances on the right work area.

  • You can open any instance and view all properties saved under the instance in clipboard.
  • Click on A-1 and check in the clipboard – please note those three properties – Age, Customername, Phonenumber

Now Let’s check the same instance in Database table.

Step 4: Open the table – pc_oikggb_myknowpega_work.

You can see the same instance is persisted in the db.

here, if you see only few columns are exposed – Customername and phonenumber and not age.

so where age will be saved?!!

  • The answer ‘Age’ is compressed and stored as binary data in column ‘pzpvstream’

We call it as blob ๐Ÿ™‚

What is BLOB?

BLOB – Binary Large OBject

  • Blob helps in storing a particular instance effectively in database.

In pega, properties can be grouped in some complex structures. We call it as aggregate properties. But DB table save instance properties as discrete Columns. So in order to save these aggregate properties within the instance we can compress it and save it in pzpvstream column.

please visit the PDN link for more info

These basics are enough :). We can jump into activity methods.

1. Obj-Browse

  • This method helps in searching the class instances and get the required properties in some page.

When do we use this method?

  • Whenever we need to browse some database table and get some results.
  • When this method gets executed, Pega system forms a SQL query and search the database table.

For example: If you need to get the customer name and customer phone number for the case IDโ€™A-1โ€™ then you can use obj-browse method with where condition pyID=โ€™A-1โ€™

  • This method can be used to fetch one or more rows from database table.

What are the method parameters?

PageName โ€“ You can specify a page to contain the search results. Whatever class you specify, System defaults the class to Code-Pega-List.

ObjClass โ€“ This is a key field. We know classes will be mapped to database table. Pega system uses this class to identify which table we need to browse the results.

Here we specify โ€˜OIKGGB-MyKnowPega-Workโ€™which is mapped to pc_oikggb_myknowpega_work table.

MaxRecords โ€“ You can specify any number of results to return.

If left blank โ€“ default value is 10,000

GetRowKey โ€“ When selected, this will be used to get the value of the primary key in the corresponding database table. Default selected.

RowKey โ€“ This is applicable, only when you select GetRowKey โ€“ true.

You can specify the primary of the database table. Default all internal table primary key will be pzInsKey.

UseLightweightList โ€“ This is a key aspect in performance.

When to use LightWeightList?

In some scenario, you may need to browse the records and use it only for display purpose. In such case, You can check this option. Please follow the below link for more details

Logic โ€“ In some scenario, you need to use more than one field in where condition.

Say for example, you need to fetch the cases, where customer type = โ€œplatinumโ€ or Place = โ€œIndiaโ€.

  • In such scenario, you can specify the logical condition here A OR B and use the label in each condition.
  • If left blank, always AND condition is applied for all fields.

You can add many rows. Each row can refer to a field in the class instance.

Label โ€“ If more than one condition is required, then you can label each condition and use in the logic field.

Select โ€“ In some scenario, you need to fetch the value of the fields, which are used in where conditions. You can check this box.

Field โ€“ You can specify the properties you need to fetch and those properties you need to use in where condition.

Condition โ€“ You can ee a picklist with variety of conditions for where clause.

Value โ€“ You can specify the where clause value.

Sort โ€“ You can sort the results based on any field. No Sorting / Ascending/ Descending

Okay now letโ€™s test.

We need to browse all amazon sales case ( pyID starts with โ€˜A-โ€˜ and Age is not null) and get the values โ€“ Customer name, phonenumber and pyID

Step 1: Create a new test activity.

Step 2: Add a obj-Browse method.

You get an error message for Age field in where condition.

โ€œOnly exposed properties can be selected in where clausesโ€

  • Remove the age is where condition. We can use only condition pyID starts with โ€˜A-โ€˜

Step 3: Trace open the rule and run the activity.

Click on the SQL and check the trace event. You can see pega forms a SQL query.

There you can see pzpvstream is used, because Age is a blob property and not exposed column.

Step 4: Open the clipboard and check the results.

You can see, the Obj-Browse method is used to fetch the 4 properties โ€“ Age, CustomerName, PhoneNumber, pyID.

ย What are the things to remember when you use Obj-Browse method?

  • Max records โ€“ Try providing appropriate value here based on your requirement. This can contribute performance.
  • Use light weight list, when you want to use the search results only for display purpose

System creates the following SQL Query

Select * From <> Where <> Order By <>

  • Click on the GetCaseDetails (Code-Pega-List) page, to know the result count and SQL query.

ย 2. RDB-List

This method use a Connect-SQL rule to fetch the results.

RDB-List ->> Connect-SQL ->> Browse tab->> SQL Query.

When do we use this method?

  • Always try using Obj-browse method to get the search results.

In some situation, you need to browse more than one table and Obj-Browse method donโ€™t support more than one instance in a single step. In such situation, you can use RDB-List method.

  • When you need to execute some complex search query, then go with RDB-List

What are the method parameters?

RequestType โ€“ Specify the request type of the Connect-SQL rule ( We can call it as rule name)

Access โ€“ Package name of the Connect-SQL rule

ClassName โ€“ Specify the class that include the Connect-SQL rule

MaxRecords โ€“ You can specify the max record count to fetch.

BrowsePage โ€“ You can specify a page to contain the search results. If left blank, the search results will be included in the step page.

ApplyDeclaratives โ€“ Normally declarative rules get executed, when you update some properties ( declare expression or on change) in the clipboard pages. You can conditionally skip the declarative processing.

RunInParallel โ€“ You can execute the Connect-SQL rule to execute in parallel.

Let’s test the method.

Step 1: You can make use of Connect-SQL rule created before โ€“ UpdateCase

Step 2: Update browse tab with the SQL query.

You see instead of providing the table name, I used the class name!! Why??

We know pega concrete classes can be mapped to database table ( both internal and external). So instead of hardcoding the table name, you can provide the class name ๐Ÿ™‚

Step 3: Use the same test activity and include a RDB-List method.

Step 4: Trace open the rule and run the activity.

You can see the query. Class replaced by the table name.

Step 5: Check in the clipboard.

You can see GetWorkDetails contain the search results ๐Ÿ™‚

What are the things to remember when you use RDB-List method?

  • You can specify any value in Access parameter. Normally if we use the database name there โ€“ ORACLE, MSSQL etc
  • When you use โ€˜RunInParallelโ€™ a new requestor session copying the access group and clipboard is created. You can use Connect-Wait method later to access the results
  • pxSQLStatementPre/Post properties contain the SQL query.

3. Obj-Open

  • This method is used to open any instance stored in the internal or external database table.

When do we use this method?

  • Whenever we need to open any particular class instance, from an activity.

Note: Only concrete classes can have intances.

just think like you need some key to open any object in the database.

pzInsKey– represents the primary key of Internal data tables.

Normally pzInsKey = < pxObjClass + pyID>

What are the method parameters?

OpenClass – identify the class instance, which we need to open ( concrete class)

Lock – some instances support locking.

Why do we need locking?

Say for example, you created a purchase request case. Agent 1 starts to update the case. In this time space, we shouldn’t allow other people to update the case.

we will see more about Pega locking architecture in different lesson ๐Ÿ™‚

True – This instance will be locked. Other requestors cannot obtain lock till it is released. Use this only when you need to update the instance.

False – Use this option, when you need to just open the case and no update is required.

ReleaseOnCommit – You can release the lock, once you commit your changes. So that other requestors can obtain the lock and work on the case.

True – Lock will be released, once instance is commited in database.

False – lock willl not be release, when the instance is commited in database.

LockInfoPage – Say for example I have acquired the lock on case ‘A-1’. Now when you try to acquire the lock on A-1, you will there thrown error.

  • The error will contain the lock details like – Requestor who holds the lock, lock expiry date etc.
  • You can specify a page here to hold all the lock details.

Property name & value – This is the key part. you need to specify the key to open the instance.

How to identify the key for any instance?

Step 1: Open the class of the instance – OIKGGB-MyKnowPega-Work

Step 2: Check the keys for the class instance.

  • You can the instance Keys – pyID. So you need to open the instance using pyID.

Property Name – .pyID

Property value – “A-1”

Let’s test the method ๐Ÿ™‚

Step 1: Create a new test activity.

Step 2: Use Obj-Open method. Provide the required parameters as shown below.

Note: A-1 case is created already!

Step 3: trace open the rule and run the activity.

Remember to check the DB Query option in tracer settings.

Step 4: Run the activity and check the tracer.

  • You can see our Pega forms the SQL query.
ย select pzPVStream , pxCommitDateTime from public.pc_OIKGGB_MyKnowPega_Work where pzInsKey = โ€˜OIKGGB-MYKNOWPEGA-WORK A-1โ€™

Step 5: Check the clipboard. You will see the case instance A-1 details are populated in ActivePage.

We have opened the case instance ๐Ÿ™‚

What are the things to remember when you use Obj-Open method?

  • Obj-Open method always open the instance in the step page specified.

a)ย ย ย ย ย  If the specified step page is not available, then a new page gets created and the instance is opened in the new page

b)ย ย ย ย ย  If the step page is already available, existing page is replaced by the new instance.

c)ย ย ย ย ย ย  If the step page is empty, then the primary page will be considered the step page to open the instance.

  • If you check lock option, then the case can only be opened when the case is not locked by other user. If it is locked, then we will get an error message.
  • If the instance you try to open is not available, then the system throws error

ย 4. Obj-Open-By-Handle

  • This method is used to open any instance using Handle

When do we use this method?

  • This method is the same as โ€˜Obj-Openโ€™ method.

Use this method, only when you know the unique handle of the instance. Otherwise always use Obj-Open

Unique Handle = pzInsKey of the database table instance.

What are the method parameters?

InstanceHandle โ€“ pzInsKey of the instance.

You can open any case and identify the pzInsKey in the clipboard.

pzInsKeyย = pxObjClassย + pyID

Lock, ReleaseOncommit, LockInfoPage โ€“ Same as Obj-Open method parameters.

  • You can test the method like the same using Obj-Open method.
  • Pega forms the same type of query.

ย select pzPVStream , pxCommitDateTime from public.pc_OIKGGB_MyKnowPega_Work where pzInsKey = โ€˜OIKGGB-MYKNOWPEGA-WORK A-1โ€™

What are the differences between Obj-Open and Obj-Open-By-Handle method?

  • Obj-Open method requires the instance class and instance primary key as input parameter, where as Obj-Open-By-Handle requires only handle as its method parameter.
  • Prefer using Obj-open method. When you are sure of pzInsKey, then go with Obj-Open-By-Handle.

But there is no restriction like we should always use particular method ๐Ÿ™‚

5. RDB-Open

  • This method is used to retrieve a single row from the database table

When do we use this method?

  • When there is some complex query and you need to return only single row from the database, you can use RDB-Open method.

Actually we use it very very rare ๐Ÿ˜‰

  • If you are very sure, that the result count will be 1, then use this method.

Even if the SQL query where clause returns more than one row, only first record will be opened in the step page.

  • If the SQL query returns no row, then you will be thrown wit run time exception.

What are the method parameters?

RequestType โ€“ Specify the request type of the Connect-SQL rule ( We can call it as rule name)

Access โ€“ Package name of the Connect-SQL rule

ClassName โ€“ Specify the class that include the Connect-SQL rule

RunInParallel โ€“ You can execute the Connect-SQL rule to execute in parallel.

Step 1: Open the same connect-SQL

Step 2: Update the Open tab with SQL query, use pyID like โ€˜AB-โ€˜.

Here the query is not right, because it will return 0 rows

Step 3: Use the RDB-Open method.

Step 4: Run the activity and check in the tracer.

Step 5: Now update the Connect-SQL query to fetch pyID=โ€™A-1โ€™

Step 6: Now again run the activity and check no error. Open the clipboard.

You can see the details are populated in step page โ€“ ActivePage

What are the things to remember when you use RDB-Open method?

  • You this method, only when you need to access a single instance

Differences between Obj-Open and RDB-Open method:

  1. Obj-Open requires pyID value where clause โ€“ pyID(primary key), whereas RDB-Open can use any exposed column in where condition.
  2. Obj-Open decompress the blob and populate all the details in the step page that includes all the embedded properties too. RDB-open can fetch only the exposed columns, you cannot access blob fields. This is a major drawback in RDB methods.
  3. Internal PegaRules database โ€“ Always use Obj-Open method.

Remember, you can map pega classes to external table. In such case, you can use Obj-Open method.

If the external tables are not mapped to pega classes, then you can use RDB-Open method.

I will end this post here.

Please visit the below link for remaining Obj RDB methods ๐Ÿ™‚

  1. jagadish jagadish

    Hi Prem…….can you explain about case management.

    • Premkumar G Premkumar G

      Hi Jagadish,
      Since many people have asked about a post for it, I’ll try my best to post about that as soon as possible. Stay tuned. So sorry for the late response.

  2. pradeep reddy pradeep reddy

    Thank uuuuuuuuuuuu very much prem

    • Premkumar G Premkumar G

      You are most welcome, Pradeep. ๐Ÿ™‚

  3. pradeep reddy pradeep reddy

    Hi prem ,
    please post topics on decisions Table tree mapvalue

    • Premkumar G Premkumar G

      Hi Pradeep,

      I’ll try to post about that topic soon. Stay tuned.

  4. venkatesh R venkatesh R

    can u explain how to persist data in pega?

    • prolay prolay

      u can use obj-save/commit if you want to persists data from activity

  5. Raunak Jaiswal Raunak Jaiswal

    What if I have used RDB-List and browse tab is empty, we have query in all the 3 tabs like in open, save and delete ??

    I mean to say like all the methods Iike rdb- list or open or save or delete will only search their respective tabs like browse, open , save and delete??

    • Premkumar G Premkumar G

      Yes absolutely :). this is why you can re-use the same Connect-SQL rule for different methods ๐Ÿ™‚

  6. Bramha Bramha

    Good Explanation Bro……

    • Premkumar G Premkumar G

      Thank you so much, Bramha. ๐Ÿ™‚

  7. Prashanthi Prashanthi

    Hi Prem,

    Very well explained, thankyou.
    Why it is recommended to use RDB methods instead of Obj methods , while we need to hit external db ?

    • Premkumar G Premkumar G

      say you need to update 1000 of records from a user session. If you go with Obj-methods, then you need to open all records individually and save those records. It may require 1000 DB hits. You can update the same in a single SQL query, in a single DB hit using where clause.

      But pega recommends to use Obj-methods, if the classes are mapped to external DB table. You can make use of commit and rollback.
      Both have advantages and disadvantages.

  8. Navakanth Navakanth

    Thq Very Much Prem. I really appreciate your efforts for making posts like this.
    Can you please elaborate more on RunInParallel option mentioned in RDB-LIST method and also usage of Connect-Wait Method.
    Thx Prem.

    • Premkumar G Premkumar G

      Run in Parallel in Connectors- We use this for parallel processing in the activity. The current requestor spawns a parallel requestor. The connect method gets processed in a parallel requestor whereas the current requestor continues with the next step. You can use Connect-Wait method later in the activity to access results back from the connector.

  9. RayMir RayMir

    Good Expalnation Prem… ๐Ÿ™‚
    There is one option called RunInParallel,Can you elaborate it and when & how it can be used…

    • Premkumar G Premkumar G

      Hi RayMir,
      say, whenever you are working on a process, every action will be handled within your requestor session. say you hit a Connect service from your requestor session, you may not do any action, till you receive response. agree. In order to avoid this, we can use Run in parallel option, where the method gets executed in child requestor session. This is independent of your session. later step you can use wait method to retrieve the results from your child requestor.

      RunInParallel – improves performance. You use this, when you don’t need the response at the moment and can be used later point of time

  10. Gouri Shanker Gouri Shanker

    In obj-browse category. Step 2 2nd SS and step 4 1st SS has small mistake..

    • Premkumar G Premkumar G

      Hi Gouri, Thanks for pointing it out. can you be more specific. It will be really helpful to correct the mistake ๐Ÿ™‚

  11. Sri Lakshmi Sri Lakshmi

    Hi Prem,

    Thanks a lot. Your posts are very helpful.

    I just have small doubt. In the Connect SQL rule, if have written the query as “Select * from TABLE where pzinskey=’PZINSKEY OF THE TABLE’ ” and i’m using it in the RDB-Open method in an activity. After executing the activity, i was able to see all the data including BLOB. But it was mentioned that RDB-Open will not get the BLOB. Can you please clarify.

  12. Ram Ram

    Awesome Friend. Very much helpful ๐Ÿ™‚

    • Premkumar G Premkumar G

      Thank you so much for your appreciation, Ram. ๐Ÿ™‚

  13. Manju Manju

    Excellent post..please share your thoughts on Decision rules.

    • Premkumar G Premkumar G

      Thank you so much, Manju. ๐Ÿ™‚
      I will post about them soon. Stay tuned.

  14. Avik Avik

    Thanks Prem.It was a good read ๐Ÿ™‚

    • Premkumar G Premkumar G

      You are welcome, Avik. ๐Ÿ™‚

  15. sam sam

    Excellent bro can I have your contact number

  16. O Venkatesh O Venkatesh

    Thank you so much Prem

    • Premkumar G Premkumar G

      You are most welcome, Venkatesh. ๐Ÿ™‚

  17. Kumar Kumar

    Hi Prem, can you please post how to connect with personal edition db.

  18. Kumar Kumar

    Good Stuff Prem.keep up the good work.

    • Premkumar G Premkumar G

      Thank you so much, Kumar. ๐Ÿ™‚

  19. Deepak Deepak

    Thanks for your nice article Prem. I was also looking for Obj-Save, RDB-Save, Obj-Delete, RDB-delete methods. Is there some other post for these? Or you will publish those in future? Please let me know

  20. Sonakshi Sonakshi

    I have a query regarding Obj-save method
    If in activity i do a page new and a page of a particular class lets say asn-fw-data-contractor(key of class is contractorid ) and do a property-set to do few changes in property of this class and set the contractorid as 1 and then obj-save with write now checked to commit my changes it works fine but if i do obj-open by handle but do not check lock and repeat same steps for property-set ( no contractorid set) and obj-save it gives me error saying lock is needed to do save commit or delete. The reason is that when i check write now it wants to delete old instances but it cannot as i have opened the same instance ?

  21. Naga Senthil Naga Senthil

    Hi prem,

    First of all thanks for your effort.

    I want to know about Obj-Validate method so could you please share with examples.

  22. Sowjanya kanna Sowjanya kanna

    Hi Prem,
    What are the dif b/w Obj And Rdb Methods

  23. Suresh Suresh

    Hi Prem..

    Obj-open and obj-open-by-handle are two methods which do same work in retrieving of single instance. So what exact difference between these two methods.Can you please clarify with good example

    • Suresh Suresh

      Can you please comment on this

  24. Vishali Vishali

    Hi Prem,
    Awesome Explanation..It is very helpful. I have a small doubt
    If we have 50 columns in DB table what is the fastest development approach to fetch records on-to clipboard?

  25. Jai Jai

    Hi Prem, very nice explanation. “If external tables are not mapped to pega classes, then you can use RDB- Open method.” Could you please elaborate this statement. How can we use RDB query if tables are not mapped to classes? Do we directly hard code table name in the place of class name in the query? Please correct me if my questions are wrong

  26. Barathi Priyan Barathi Priyan

    Hi Prem,

    What is the DB Tool you use to connect with Pega? I use Pgadmin and it is little slow.
    Any suggestions please ?

    Barathi Priyan

  27. Suma Suma

    Hi prem
    Can you pl explain in obj open method which class name we should provide data or work
    And also about parameters
    . What kind of property name and value we can give… What if we take the parameter values from parameters tab its showing error… If I give work class in open class and given property’s from same in the property name and value its showing me error… Please clarify

  28. Masliana Masliana

    Hi Prem,

    Good Prem.
    Can you Explain about search list from Clipboard (Search Activity) ??


  29. Moumita Moumita


    Can you please explain about the light-weight list option in Obj-Browse ? From PDN, what i learnt its efficient and for better performance its used , but it has certain limitations . Can you please explain a bit about this?

  30. shanmuka karnati shanmuka karnati

    Hi prem,
    Thanks for sharing ur knowledge. Could you please make a post on Connect-SQL.

  31. Dendi A Dendi A

    How to try catch connection error or db server time out of using those method?

Leave a Reply

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

error: Content is protected !!