​Hi,

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

First of all, Pega uses both database level lock and Pega level lock. Database level lock is shorter durations (typically milliseconds), while Pega level lock is much longer (depends on user's operation, but probably a few minutes). You can turn off Pega level lock using Optimistic locking strategy (explained later) but you can't turn off database level lock. It is enabled in the infrastructure layer. From here on, I will explain about Pega level lock.

1. Pega level lock basics

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. 

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.

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.

Locks can be also released when user logs out, or system restart. In other words, 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 vs Hard 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 the user will not be even 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.

2-1. How things work

Below are the steps how hard lock / soft lock work in Pessimistic Locking strategy.

2-1-1. At 9:00am, user A opens an assignment in Perform mode. System inserts a new record into PR_SYS_LOCKS table. Since the default expiration period is 30mins, 9:30am is set to pxExpireDateTime property. For pxOwnerId property, user A's requestor ID is stored. User A leaves his desk with assignment screen open.

2-1-2. Until 9.30am, no one can steal lock on this case.

2-1-3. At 9:31am, lock gets expired. The record in PR_SYS_LOCKS table still remains (it doesn't get deleted by itself), but user A's lock is no longer "hard-lock". User B can now steal the lock. When user B opens an assignment at 9:31am, system updates pxExpireDateTime and pxOwnerId property of the same record. The expiration time is now set to 10:01am.

2-1-4. User A comes back to his desk at 9:45am. If he clicks Save or Submit button, he will see an error message on screen (as shown in the screenshot below) because he has already lost lock on this case. Regardless of user B's situation (whether user B still has a lock or already submitted), this behavior will be the same.

2-1-4-1. If user A clicks Save button, below message is displayed.

2-1-4-2. If user A clicks Submit button, below message is displayed.

Q: After user A opens an assignment, if he clicks Save button, does the expiration time (pxExpireDateTime) get extended?

A: No, the expiration time is fixed at the beginning.

Q: If lock is expired and stolen by user B, user A will see an error message when he clicks Save or Submit button. How about when no one steals a lock but expired? For example, user A opens an assignment at 9:00am and clicks Save button at 9:31am. Will user A still see the error message because lock is expired?

A: No, the error appears only when the lock is stolen (updated) or released (deleted). If no one steals the lock, his lock record still exists in PR_SYS_LOCKS table as "soft-lock" state. User A should be able to save or submit without any issue.

2-2. How to change the expiration period

The default expiration period is 30mins, but you can change it. There are two places you can do this.

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

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

* I would recommend that you take Case Type rule approach because it is a little complex to manage multiple environments by Data-Admin-System approach. For example, if you export and import Data-Admin-System instance from Dev to Prod, the production level will also be updated from 5 to 2 wrongly, so you shouldn't. For someone to remember to update Data-Admin-System instance manually per environment is also painful. Case Type is a rule instance and it is migrated thru R-A-P without any complexities.

3. Pessimistic locking vs Optimistic locking

The Pega level object locking explained above is called "Pessimistic locking", as opposed to "Optimistic locking". In other words, Pessimistic locking means Pega level lock + database level lock while Optimistic locking means database level lock only (*). Optimistic locking approach was introduced in Pega 7. The default setting is Pessimistic locking.

• "Allow one user" means Pessimistic Locking.
• "Allow multiple users" means Optimistic Locking.

* Technically speaking, even Optimistic locking will acquire a lock for a very short period of time when user clicks "Save" or "Submit" button. The duration is in milliseconds and closed to database level lock quickness. If you want to turn off Pega level lock completely, the only approach is to disable locking from Class Group (explained later in #5), but this is not recommended. Also, usually you don’t have to worry too much about collision if update occurs only from UI. If business requirements include update from service in the background and you want to avoid collision, you can build retry functionality using Queue Processor.

Personally I prefer Pessimistic locking from data consistency perspectives. If I were an end user, I would want to work on my assignment exclusively without worrying about potential that someone may steal and update the record in the middle of work. The disadvantage of Pessimistic locking is all other users must wait until the first user submits or cancels the assignment.

In Optimistic locking, when you click Save or Submit, system compares the last updated date time between one on memory (pyWorkPage) and database. If it is identical, that means there are no changes after you open the assignment, so no error. If one in database is newer, that means someone has already updated in the meantime and system displays a message (see below sample image). If you are using an activity to update a work object, make sure to update pxUpdateDateTime and pxUpdateCounter. Without these, system won't know it is updated. For example, if you use Obj-Save method, it doesn't update these properties. Use Process API such as Work-.UpdateWorkObject etc.

This message doesn't tell you which exact properties are updated. If there are many properties on screen, it may be painful to find out the differences (it could be even no differences, someone might have just saved it with no changes). Which locking strategy to choose is up to the nature of your application and you are advised to discuss which approach is more suitable with business users.

4. Lock mechanism with case hierarchy

Case hierarchy affects lock mechanism in a certain way. I have posted a separate article. Please see https://support.pega.com/discussion/lock-mechanism-case-hierarchy.

5. Allow locking settings at Class Group / Class level

I explained how to configure 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.

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

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

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

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 (*).

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.

Thanks,