Close popover
Kensho Tsuchihashi (KenshoTsuchihashi)
Project Delivery Leader
Pegasystems Inc.
KenshoTsuchihashi Member since 2010 137 posts
Posted: October 10, 2020
Last activity: November 18, 2020

Pega lock mechanism


In this post, I am summarizing how Pega object locking works. If you find any information incorrect please let me know so I will update it.

First of all, Pega uses both database level lock and Pega level lock. Both locking are record basis and not entire table basis.

Pega level locking and database level locking

1. Pega level lock

When someone opens an assignment, the state becomes "Perform" mode and lock is obtained by the system. The lock information is inserted into "PR_SYS_LOCKS" table in the database and it is managed there. In this period, no other user can open the same assignment. When user submits or cancel the assignment, the state becomes "Review" mode and lock is released. The record is deleted from the table. 

Lock diagram

When someone tries to open an assignment that is already locked by other user, a message is shown as below. There is no way to unlock it.

error message locked by other session

If you try to open an assignment that is locked by yourself in other session, a different message is shown as below. This doesn't happen a lot but it could when you log in to the system using the same ID from different browser or terminal. In this case, you are given an option to forcibly log out other session. Be noted, Pega locks are exclusive to one thread.

error message locked by the same ID

Locks can be also released when user logs out, or system restart. In other word, if user leaves assignments open and closes a browser by clicking the Windows close box, locks remain held by the requestor and prevents others from updating the work objects, for the next 30mins (see below "soft lock"), or until next system restart. A JavaScript event or function cannot detect the closing of the browser window. Hence, it is encouraged that user always do logging out operation properly. This rule applies to SSO environment too.


2. Soft lock

Lock is effective for 30mins and then expires. After expiration, the lock becomes "soft lock" and other user can steal it thereafter. When other user opens the soft locked assignment, no warning is displayed and user is not aware of its soft lock state. In the database, the same record in PR_SYS_LOCKS table is updated by the new user. Lock before expiration is sometimes referred to as "hard lock" as opposed to soft lock. The defaulted 30mins expiration period can be changed by below two approaches:

(1) If you want to change it per individual case type, update Case Type rule.

Case Type

(2) If you want to apply the change system-wide, update Data-Admin-System (pega) instance.


* If you update both of them, Case Type rule takes precedence over Data-Admin-System instance.


3. Pessimistic locking vs Optimistic locking

The Pega level object locking explained above is called "Pessimistic locking", as opposed to "Optimistic locking". Optimistic locking is introduced in Pega 7. In my opinion, Optimistic locking is not recommended from data integrity perspectives.

Pessimistic Locking vs Optimistic Locking

  • "Allow one user" means Pessimistic Locking.
  • "Allow multiple users" means Optimistic Locking.
No Type Description Default Recommended
1 Pessimistic locking (Default locking) Pega level object locking using PR_SYS_LOCKS table. This approach prevents other users from overwriting data by locking the work object exclusively. A single user is allowed to open an assignment, and in that sense, this is a safer solution. Yes Yes
2 Optimistic locking This approach doesn't use PR_SYS_LOCKS table. Multiple users can open the same assignment at the same time. Whoever saves data latter overwrites data. Be noted that if latter users try to save or submit with updated data, they will be notified that someone else has already updated earlier. They need to reload the section to display the latest information first, and then re-enter their own updates. No Not really

* ​Below is the message notified for latter users. They can't submit or save new data until they refresh the section.

Notified of update message


4. Lock mechanism with case hierarchy

Case hierarchy affects lock mechanism in a certain way.

(1) A child case type inherits the locking strategy of its parent case type. For example, if parent case is configured to use Pessimistic locking, then child case will also use Pessimistic locking. It is not possible to use different locking between parent / child cases.

Child case inherits parent case locking

(2) If Pessimistic locking is used, when child case is locked, parent case is also locked by itself. This is because parent case holds child case status, such as "pxCoveredCount" and "pxCoveredCountOpen" and these data need to be updated per child case update accordingly. This is the default behavior but it is possible to change the settings so it won't lock parent case when child case is locked although I wouldn't really recommend it for the data consistency.

Case hierarchy setting


5. Allow locking settings at Class Group / Class level

I explained how to set Pessimistic Locking or Optimistic Locking above but actually there is one more prerequisite setting in a lower level - Class Group or Class form. For Work instance, locking must be enabled at Class Group form. For Non-Work (≈Data) instance, locking must be enabled at Class form.

(1) Work (Class Group)

When you define a case type, this checkbox is turned on by default. You can always keep it checked. By checking this off, Pega level lock is disabled but you can also turn it off by using Optimistic locking. Therefore, there is no advantage in check this off.

Allow locking in Class Group form

(2) Data (Class)

Unlike Work, Data has "Locking" tab in the Class form. When you define a data type and configure local data storage, this checkbox gets turned on by itself. When it is checked, Data instance locking works in similar manner as Work and PR_SYS_LOCKS table is used. The difference between Work and Data is, Data instance is not locked when assignment is opened, but it is locked when data row is being edited (ex. inline row editing). If you check this off, it behaves like Optimistic Locking.

Allow locking in Class form

* If Allow locking is checked for Data instance, when someone starts editing the record, lock is obtained. A message is shown as below if you try to update a locked instance.

Lock for Data instance


6. Controlling lock in an activity

When end user operates on screen, object locking is managed by the system automatically, but when we use activity, lock must be controlled by developer with care.

In Obj-Open method or Obj-Open-By-Handle method, there are two checkboxes - "Lock" and "ReleaseOnCommit". If you check "Lock", lock is obtained in this method. If you check "ReleaseOnCommit", lock is released when Commit method is executed. When you are planning to update the instance, check both of them. In most cases, check / uncheck both of them. In the unusual case, you may want to check only "Lock", and not "ReleaseOnCommit", to retain the lock after Commit (perhaps because additional changes are expected). Then you should manually release lock later using the Page-Unlock method etc (*).

Obj-Open method with lock

Another method, Obj-Refresh-And-Lock also can obtain a lock. While Obj-Open and Obj-Open-By-Handle grabs data from database every time, Obj-Refresh-And-Lock is used when you already have a page on clipboard. If the object is not locked, this method acquires a lock and ensures that the version you have on a clipboard page is the same as or newer than the version currently in the database. If the object is locked, this method has no effect.

* I wouldn't recommend to implement programmatic solution but if you need to manually release a lock, do so using either of below approach.

No Approach Type
1 Pege-Unlock Method
2 Work-Cover-.WorkUnlock Activity
3 System-Locks.ReleaseLock Activity




***Edited by Moderator: Pooja to update platform capability tag, add developer knowledge share tag***
Pega Platform 8.4.1 Case Management Developer Knowledge Share