Press "Enter" to skip to content

Locking mechanism in Pega



In this post we will see in detail about locking mechanism in Pega.

What is locking?

Let’s take a simple example.  2 clerks working in a bank tried to update the same bank account for two different transactions. They both retrieved the bank account at the same time and started applying the transactions. Clerk 1 applied transaction 1 details and Clerk 2 applied transaction 2 details on their saved copy. This may result in data loss. Since Clerk 2 entered the details in his saved copy, it overrides the transaction details entered by Clerk 1 as if transaction 1 never happened.

This data loss can be prevented by introducing Locking mechanism.

So when Clerk 1 needs to update the bank account, he can acquire lock on the case and starts updating the transaction details. Clerk 2 cannot work on the case, when it is locked by someone else. He has to wait until the lock is released by Clerk 1.

Releasing lock – Once clerk 1 completed updating the transaction details, he can release the lock. This will enable other users to work on the case.

Locking mechanism is not only specific to Pega. You can see many softwares support locking mechanism.

Note: Databases support different levels of locking. Locking can be on a database tables or table columns or table rows.

Now let’s come to our Pega. We know  all the case details can be persisted to database tables.

Say, you have a sales case and you open the case and update the customer name. When you save the case, the customer name value gets persisted to database.

Here internally we acquired the database table (work table) row locking on the case and updated the customer details value.

Only database locking is enough to work in Pega?!….. No.

  • We know how a Pega application saves the data. Data can be saved in memory ( clipboard) and can be persisted in the database at later point of time.  So you need some additional locking mechanism.
  • Locking mechanism in Pega is different from database locking mechanism.

We will deep dive 🙂

How to implement locking mechanism in Pega?

Here I will walk you with my Sales case application.

  1. Configure locking in the class instance or class group

Some basics – Only concrete classes can have instances.  Sales case belongs to a concrete class.

Classes can belong to a class group. We will see about classes and class groups in a separate post!!

a) When a class belongs to a class group / is a class group – Configure locking in the class group rule instance.

b) When a class does not belong to a class group – Configure locking in the class rule instance. You get a new locking tab in the class instance :).

So what is there in the locking tab?

Lock definition – you can specify array of properties that can be used to form a lock key.

Why do we need a lock key?

  • This is similar to keys in a class instance. It helps in identifying unique class instance to lock.
  • It means say you got 2 sales cases – S-1 & S-2. Both cannot have same lock key. If they have same lock key, we may end up locking both the cases when we update a single case.

Note: In some complex requirement, two or more cases are related and cannot be updated parallel. In such cases, you can add your own complex lock properties.

If you leave blank, then the lock keys will be the same as class keys.

For work classes – we have ‘pyID’ as the default key. You can use the same as lock key to distinguish different cases.

Note: default the locking array will be blank.

pxLockHandle – property holds the lock key for this case instance.

pxLockHandle – pxObjClass + Lock key array ( if null , class key)


Allow locking – Mostly we select this option. If selected, user can  save/delete the instance only when he holds a lock on the instance.

Note: when a class does not belong to a class group, you can configure the same in locking tab in the class instance rule.

What are the ways you can acquire lock in Pega?

a) Using activity methods

  • Obj-Open, Obj-Open-By-Handle & Obj-Refresh and Lock

b) Use standard OOTB activities

  • Work-.WorkLock , Work-.AcquireWorkObject, Assign-.AcquireWorkObject  used in requesting a lock on a work item

Note: Whenever you try to perform any action on a assignment, Pega tries to obtain the lock using standard activities.

What really happens when you acquire a lock?

Step 1: Create a test activity and use Obj-Open method.

Step 2: Trace open the rule. Check DB query.

Step 3: Run the activity. You will see an insert query on pr_sys_locks table.

  • Click on the SQL updates, you will get the query.

  • Let’s check the database table pr_sys_locks

  • You can see a corresponding entry in the database table.

So, whenever you obtain a lock, you can see an entry in the pr_sys_locks table.

  • You can also see all locks by clicking on the class on the left panel.

Note: for specific case related locks you can navigate Designer studio -> Case management -> tools -> Work admin -> All locks / My locks and check the locks.

Open the ‘System-Locks’ class rule form.

  • You can see pxLockHandle as the keys. It means System-Locks cannot have more than one instance with the same lock handle :).
  • So when the other user (different requestor) tries to obtain a lock on the same case, insert query fails and throws error.
  • Also lock is exclusive to one Pega thread. When the same requestor tries to same object through different pega thread, then you will be presented with the release lock button.

What are the ways you can release lock in Pega?

a) Use activity methods

Normally locks are released, when you commit the changes to database. This can be controlled using activity methods

In the Obj-Open, Obj-Open-By-Handle methods, you can check ‘ReleaseOnCommit’ option to release the lock when the instance is committed.

Note: Always enable this option, when you open the case. In some rare situation, we uncheck this option.

Page-Unlock method can be used to release a lock on an object.

b) When the requestor logs out / system restart

Whenever the requestor logs out or the system restarts ( obviously it wipes out all requestors) locks are released.

c) Use standard OOTB activity

  • ReleaseLock to unlock a work item

d) Locks return to ‘Soft lock’ state, when the lock expires. This is controlled by locking timeout

What is locking timeout?

  • If the lock is not released – may be user didn’t log off /closed the browser directly, then the lock stays with the requestor ID.
  • So other users cannot work on the case. In order to avoid this, Pega provides a locking timeout.
  • After this locking timeout, the acquired lock will be treated as expired lock or soft lock.

How to configure locking timeout in Pega?

a) System wide locking timeout

System Locking timeout can be configured in system data instance.

Designer studio -> System -> General -> System, Nodes, Requestors

  • You can click on the edit icon in line with system name drop down, to open the system data instance.

The lock timeout is default 30 minutes.

If the lock is not released after 30 minutes, then it goes to soft lock.

b) Case wide locking timeout

You can have specific locking timeout for individual cases.

Case designer -> Settings -> locking

I updated the locking timeout to 5 minutes. Let’s test it.

Step 1: Create a new case and acquire the lock.

Step 2: Check the pr_sys_locks table.

pxExpireDateTime – holds the locking expiring time. You can see the time is set to only +5 minutes.

Let’s wait for some time and try to acquire the lock for S-2 from different user.

  •  I acquired the lock and able to update the case. No locking error. Check in the database table.

What are the types of locking?

a) Default locking – Only one operator can work on a case at the same time. The other operator can work on the case only when the first operator completes updating the case.

b) Optimistic locking – This is introduced in Pega 7. Two or more operators can open and work on the case at the same time.

Say Operator 1 & operator 2 opened the case and started updating it. When Operator 1 commits the case, then Operator 2 gets a modal dialog to refresh. On refresh, the data is retrieved fresh with operator 1 changes 🙂

We will test how optimistic locking works.

Step 1: Configure optimistic locking in Sales case.

Step 2: login using operator 1 – Create a new case S-3. Login using operator 2 and open the same assignment. It means both operators are working on the case at the same time.

Step 3: Operator  1 submits the case first. When operator 2 submits he will get a conflict message with refresh button.

You can explore the activity ‘pzShowConflicts’ which is responsible to support optimistic locking functionality.

Locking strategy for sub cases

  • Locking strategy for a sub case is inherited from parent case ( default or optimistic)
  • You also have an option to control locking on the parent case when the child case is opened.

a) When it is checked – Parent case is not locked. Parent and child cases can be worked individually.

b) When it is not checked – Parent case is locked when you work on child case.

  • You can explore Work-.DetermineLockString activity which determines the pxLockhandle.

For Parent case – pxLockHandle – pzInsKey

For Child case – pxLockHandle – pxCoverInsKey.

So when you lock the child case, then both the parent case is locked

Parent case pxLockHandle = Child case pxLockHandle

Let me end this post here :). Hope I covered all the basics about locking mechanism in Pega !!

See ya soon in my next post.

  1. Sharad Sharad

    Like always.. very nice explanation. Thank you.

    Keep going.. really appreciate your efforts.

    • Premkumar G Premkumar G

      Thank you so much for your appreciation, Sharad. 🙂
      You are most welcome. 🙂

  2. Hari Hari

    Thank you for sharing the info prem. very informative.
    would it be possible for you to talk on Data- Class and its importance and why do we need Data- Layer.
    Also when you move into a project that is in production for say around 5yrs how do we start in understanding the class structure. Any inputs would be of great help.

  3. Azzu Azzu

    Nice info bro….thank you very much

    • Premkumar G Premkumar G

      Thank you so much, Azzu. 🙂
      You are welcome. 🙂

  4. Sanjukta Sanjukta

    Can you please provide answer for my query….

    When 2 users working on same work item and committed @same time..Whose changes will be get reflect?

  5. karthik karthik

    really super and good explained.

    • Premkumar G Premkumar G

      Thank you so much for your appreciation, Karthik. 🙂

  6. sarath sarath

    Very Nice Post Prem. Thanks for giving locking mechanism in detail.
    Can you explain more about how the locking is done using standard OOTB activites.. work-.WorkLock,Work-.AcquireWorkObject and Assign-.AcquireWorkObject with examples/scenario

    • Premkumar G Premkumar G

      Hi sarath, I will try to make a separate post on Pega API s

  7. Mohit Mohit

    Hi Prem,

    could you please tell this….How many records are inserted into the locks table if two operators open the same case in Optimistic locking approach ? or how does optimistic locking work internally ?

    Thanks in advance

    • Premkumar G Premkumar G

      Hi Mohit,
      Nice question, I will update the post.

      When you use Optimistic locking, you wont have any entries in the pr_sys_locks table. 😀
      So anyone can work on the case.
      Only when someone commits their changes – ‘pzShowConflicts’called from FinishAsssignment checks if the changes are commited recently and provide a option to refresh

      Thanks again 🙂

  8. Lavanya Lavanya

    Nice Explanation bro…U r doing such amazing work….

    • Premkumar G Premkumar G

      Thank you so much for your appreciation, Lavanya. 🙂

  9. satvika satvika

    Hi Prem,

    I understood the concept, but when i tried changing the default time from 30 to 5 min in a case designer settings tab, during runtime, created a new case and checked in pr_sys_lock table but the pxexpiredatetime is still showing difference of 30 min when compared with pxcreatedatetime, my change is not reflecting. Could you please tell me where might be the issue?

    • Premkumar G Premkumar G

      Hi Satvika,
      The only reason can be, you didn’t save the case designer 😀 . Can you please check and come back.

  10. Raju Raju

    Prem this is nice,
    My question how manually(custum) handle locks for cover(Parent) and covered (Child) objects

    • Premkumar G Premkumar G

      Hi Raju,
      You can always extend the ‘DetermineLockString’activity in the corresponding classes and customize the activity to set ‘pxLockHandle’

  11. Sanjukta Sanjukta

    Nice post well explained…..

    Here I have one query…..

    If two users get lock on a single work item and both have updated some info and submitted at same time. Then whose changes will update ?

    • Premkumar G Premkumar G

      Hi Sanjukta,
      I think you are confused a bit.

      In default locking, no two users can acquire the lock on the single work item.
      In Optimistic locking, technically both users can work on the case at the same time ( without locks), but when anyone commits, then the other users get an refresh option before committing. ( First commit first served :D)


  12. sriram sriram

    worth reading and sharing this.
    thanks for investing your precious time for all these posts.

    • Premkumar G Premkumar G

      Thank you Sriram and you are most welcome. 🙂

  13. jagadish jagadish

    Very Good Detailed Explanation Prem. Eagerly waiting for your post on Case Management, File Listeners

    • Premkumar G Premkumar G

      Thank you so much, Jagadish. 🙂
      Stay tuned as new posts are on the way. 😀

  14. Raj Raj

    Hi Prem,

    It was very useful post and well explained on how locking mechanism works in Pega platform. Have query on Data Import utility of Pega 7, whether the locking mechanism be extended so that when two or more imports are done at same time on a customer mart by operators with administrator privilege, there are high chances of customer data by import first get overridden by second import.

  15. RamanaReddy RamanaReddy

    Nice Explanation…..Keep it up

    • Premkumar G Premkumar G

      Thank you so much, Ramana Reddy. 🙂

  16. Eshwanth Kalash Eshwanth Kalash

    Hi Prem,

    I’m very new to PEGA, did my CSA like a month ago. I do have access to the environment which PDN provides you when you enroll for online training. I have question regarding on how do you query SQL statements. is it possible for me to get access to Query Runner. PDN says that i need to have Access role PegaDATA:DatabaseAdministrator added to my roles if i had to have database administration features. Is there any help that you can provide which Im unable to find it in PDN.

    Thanks in advance.

    Eshwanth Kalash

  17. Nitesh Nitesh

    Very good article. you have explained it very diligently.

    • Premkumar G Premkumar G

      Thank you so much for your appreciation, Nitesh. 🙂

  18. Lakshmi Lakshmi

    Nice explanation Prem, Really helping us. Tq so much!!! 🙂

    • Premkumar G Premkumar G

      Glad to hear that you are finding my posts helpful, Lakshmi. 🙂
      Thank you so much and you are most welcome. 🙂

  19. Sai Venu Sai Venu

    Thanks very much, really your explanation is awesome

    • Premkumar G Premkumar G

      You are welcome, Sai Venu. 🙂
      Thank you. 🙂

  20. SreeLatha SreeLatha

    Hi Prem,

    U R doing Such A Great Work.. Can You please clarify My Doubt..

    Is data will commit if it is optimistic lock, If Yes then How??

  21. Mayur Nabeda Mayur Nabeda

    Hi Prem,

    Can you please elaborate the topic Report Definition in Pega.
    Thanks in advance.

  22. Purushotham Duddela Purushotham Duddela

    Hi Prem,

    soon we will forget PDN if you post such beautiful solutions with nice explanation

    • Premkumar G Premkumar G

      Dear Purushotham Duddela,

      Ha ha ha 😀 You are praising me quite a lot. 😀
      But anyway thank you so much for your appreciation. 😀

      Premkumar G

  23. Azzu Azzu

    AS Usual awesome bro…The gap b/w new postings are bit high. Could you please post the topics asap and i am waiting for SSO topic posting……Once again you are doing Awesome job….:)

    • Premkumar G Premkumar G

      Thank you so much for your appreciation, Azzu. 🙂
      Yeah bro, I am not posting new stuffs often these days due to hectic work bro. I’ll try my best to post often for sure.
      I’ll post about it soon. Stay tuned. 🙂
      Thank you once again. 🙂

  24. satyvir satyvir

    @PRem :- In case of Optimistic locking, when operator 2 get Refresh option. After he click on Refresh. Is operator 2 changes will be present or it will be change.

    • Premkumar G Premkumar G

      Hi Satyvir,
      Operator 2 changes will be present. No one wants their updates to get lost. On click of submit, new changes are updated. 😊

  25. Suresh Suresh

    Good Job Prem. Very good explanation.

    • Premkumar G Premkumar G

      Thank you so much, Suresh. 🙂

  26. Varun Varun

    Hi Prem,
    The locking mechanism is very well explained above. I have a question on Optimistic locking error section. while I was working I found that if I use save-Action on my button then I am able to see the Optimistic locking error section “pzShowConflict (Work- Section rule )” if 2 ppl are trying to save simultaneously. But instead of save action if I call DoSave activity on my save button (which calls the pzShowconflict activity). Though the .pyCaseUpdateInfo values required for the pzShowConflict section to be displayed are set on the clipboard we wont be able to c the pzShowConflict section on the screen . Can you tell me if am missing anything else to display the section on the screen. The error message is also set on the clipboard pyCaseupdateInfo.pyNewMessage (this case was updated this specific person on this date). only thing I am not able to see is that section to refresh the harness so that the user view the error.

  27. Ravi Ravi

    One of the requirement in my application is I want to configure as optimistic locking but when second user’s logs in I want to show the warning message user1 is working on it.

    in case of optimistic prpc is not inserting the lock handle in system-locks how do you we achieve this.

  28. Ravikiran Ravikiran

    Very nice explanation Prem, thank you.

    • Premkumar G Premkumar G

      Thank you so much, Ravikiran. 🙂
      You are welcome. 🙂

  29. Ravikiran Ravikiran

    Need some new post on Case management

    • Premkumar G Premkumar G

      Yeah, I’ll post about it soon, Ravikiran. 🙂

  30. Imran Imran

    Excellent. Explained beautifully. I look forward to reading more topics

    • Premkumar G Premkumar G

      Thank you so much for your heartfelt appreciation, Imran. 🙂
      New posts are on the way. Stay tuned. 🙂

  31. Abdul Razi Abdul Razi

    Prem Bhai you are great.
    I appreciate for the patience you take in explaining cleary.
    Great Job. nycly done.

    • Premkumar G Premkumar G

      Thank you so much for your heartfelt appreciation, Abdul. 😀

  32. Vinod Kumar Bavandla Vinod Kumar Bavandla

    Hi Prem,

    If optimistic locking is enabled, I don’t see lock instance in system locks table when I opened a case. My doubt is when lock would be acquired in optimistic locking and see lock instance in system locks table ?

    Thank you

  33. Sreenivas Sreenivas

    You know the art and methodology of explaining/teaching something !!

    Kudos Prem !!

  34. Soumik Ghosh Soumik Ghosh

    prem, simply awesome, need some more post which can cover other parts of pega like PLA, PAL, WORK ITEM, CASE MANAGEMENT, VARIOUS REAL LIFE PROJECT PROBLEMS ETC.

  35. Deepa Deepa


    Have a query on this.
    When we use split join shape in a flow,how the lock mechanism handled.
    Could you please elaborate on this.

  36. Monika Monika

    Hi Prem,
    Thanks a lot for sharing your knowledge. The concepts are presented extraordinarily with real time examples. I personally gained lot of knowledge from your posts. Looking forward for more concepts.

  37. Chetan Chetan


    I have similar situation, where I need to allow multiple users to update same object. in case management structure, i.e under one work cover there are multiple covered objects. I need to allow multiple covered object to work parallelly / independently.

    here, all covered objects are updating in same table record. at some extent I have enable them to open and save at same moment of time to on same object. but during coverted object submission ( flow action submission ), it forcefully taking lock on cover object to resolve case dependency and triggering next object. but if multiple covered object try to submit at one moment of time. only first user can acquire lock on cover object and other users has to wait till first operator releases lock. I have tried to use ReleaseLock, delete record entry from pr_sys_locks, but then also second operator do not get lock on cover object. it seems, pega is keeping lock entry in cache ( it believe ). could you please help me ?

  38. Mrinal Mrinal

    pdn is nothing compared to your posts
    incredible u are 🙂

  39. satish satish

    can u explain one sample project end to end explanation

  40. Alpana Alpana

    I am so happy i found this page. 🙂 Thanku for sharing.

  41. VJ VJ

    Very Nice explanation.. Keep up the good work.

    Can you create a post against, pxcoverdcount and pxcoverdcountopen

  42. Mohan Mohan

    Very nice explanation…Thanks prem

  43. Karan Gupta Karan Gupta

    Hi Prem,

    Thanks for covering almost every bit, really a nice post.
    I just have a small doubt. Suppose there’s optimistic locking in a case type and two users are making changes in exactly the same field. User 1 submits the case and User 2 gets a conflict message. At this, User 2 refreshes the case. So now in this field, changes of which of the two user will get reflected? User 1 or User 2?

  44. Ramakrishna Ramakrishna

    Very Informative and clearly explained. Thanks for sharing. Appreciate your effort and work on this. This will be helpful for all.

    • Premkumar G Premkumar G

      Thank you so much for your appreciation, Ramakrishna and you are most welcome. 🙂

  45. Praveena Praveena

    Hi Prem,

    In Application we have different data tables and we can also edit the records in that data table. Do we have any locking option on this to restrict other operators when I am editing data table records ?

  46. prasad prasad

    Good explaination and presentation and neatly explained each combination,really helpful

  47. Raydark Raydark

    Hi Premkumar,

    That was really nice post.

    I am new to pega and have a doubt.
    In pega we have assignments, an assignment is assigned to the operator. In this case no other operator can take action on work item right? So in which scenario does this locking comes in picture? Does work object need to be in some shared group or pool then only locking system works?

    Thanks in advance.
    Keep up the good work and keep sharing knowledge.

  48. Chandan Chandan

    Nice article. One thing you can add in this article, lets say parent case P-1 created 2 child cases C-1,C-2. C-1 is routed to Operator1 and C-2 routed to Operator2. ‘Donot lock parent case’ checkbox is not selected. So both C-1 and C-2 will have lockhandle of parent case. Now operator1 is working on C-1, then operator2 cant work on C-2 workitem simultaneously as both have same parentcaselock handle.

  49. Laxmi Laxmi

    Hi Prem,
    Please help me to on this doubt .
    When we checkout a rule,which lock is applied to the rule(optimistic or default)?

    Thanks And Regards

  50. Praveen Mohan Praveen Mohan

    Your blog is very informative.

  51. Narasimha Narasimha

    Nice Post.
    Can you please explain difference between soft lock and hard lock

    • Premkumar G Premkumar G

      Hi Narasimha,
      Assume you locked a case A, as soon as you lock, it enters the state hard lock. It means when i try to access, then i get an error message saying it was locked by you.
      Now say, you kept the system idle, and the lock timeout has expired, now the lock enters the state soft lock. In this state i can acquire the lock on the case.

  52. Kumar Kumar

    Hi Prem,

    In optimistic locking, Lets say User1 updated one of the Filed called EmpSalary as 20000 for Case-1, and user 2 updated the same field with 30000 for same case Case-1. Now if user1 submits the case first. And when user2 refreshes the case, which value will be present for EmpSalary Field?

    20000 or 30000?


    • Premkumar G Premkumar G

      Hi Kumar,
      Sorry that I didn’t mention bit clearly on the story! On clicking refresh, data entered from user 1 will be shown. To your question, it will be 20000

  53. Charan narra Charan narra

    Hi preM nice explanation. Here my question is i have 3 users user 1 work on the case he submitted. Now user 2 open the case he got message like lock is held by user1 then user 2 foreclosed the case.,next user 3 will open the case he got error message like lock is held by user 2. How it’s possible. Any lock cache is there,? If cache is there how much time it will hold the lock..Pls clarify this.

  54. Charan narra Charan narra

    Hi bro please clarify above question

  55. Balaji T Balaji T

    Hi Prem
    Your are awesome.
    I have few Questions on Optimistic locking.
    I have created a Parent case with Optimistic locking mechanism. And I have added a child case without selecting ‘do not lock parent case when child case is opened’. Now user 1 created Parent case P1 and also created 2 child cases C1 and C2 . So , if C1 is open by User 2 and other user tried to open C2 what will happen? As per my understanding of optimistic locking C2 also available for open because the parent case P1 is in Optimistic locking mechanism. Please correct me if i am wrong.

    Next Question is if in the above C2 is available to perform , then User 3 opened and now user 2 submited C1, now dose user 3 will get conflict message with refresh button about the parent case locking ?

    Thanks in Advance

  56. manasa manasa

    Hi Prem

    Thank you very for the explanation

    can you please provide us with the search bar so that we can search for the topic which we are interested to learn

Leave a Reply

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

error: Content is protected !!