​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. The defaulted 30mins expiration period can be changed by below two approaches:

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 a 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. Be noted, if latter user updates the record in Optimistic locking, system can display a message for the first user indicating there was a change (see below sample image). However, system can'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.

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

4-2. If Pessimistic locking is configured, when child case is locked, parent case is also locked by the same user automatically and other user can't perform against both parent case and child case. Similarly, when parent case is locked, child case is also locked by the same user automatically and other user can't perform against both parent case and child case. 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 this settings so it eliminates the relationship between parent case and child case locking. This way, both cases can be performed independently. To do this, check "Allow other users to access parent case when the child case is opened" checkbox.

• Optimistic locking:

1. When parent case is performed by user A, child case can be performed by user B.
2. When child case is performed by user A, parent case can be performed by user B.

• Pessimistic locking:

- "Allow other users to access parent case when the child case is opened" checkbox is not checked (default setting):

1. When parent case is performed by user A, both parent case and child case are locked by user A. Thus, neither of parent case and child case can be performed by user B.
2. When child case is performed by user A, both parent case and child case are locked by user A. Thus, neither of parent case and child case can be performed by user B.

- "Allow other users to access parent case when the child case is opened" checkbox is checked:

1. When parent case is performed by user A, child case can be performed by user B (*1).
2. When child case is performed by user A, parent case can be performed by user B (*2).

*1: Be noted, even if the checkbox is checked, child case's final step still needs the parent case to be unlocked because "pxCoveredCountOpen" property gets updated per child case resolution (Work-.Resolve is triggered and it requires parent case locking). Prior steps before resolution can be performed independently. When other user is performing a parent case, if you try to peform child case's final step, you will see below error on screen.

*2: Be noted, if you configure parent case to resolve open child cases as below, parent case's final step will need the child case to be unlocked as system tries to resolve both cases. When other user is performing child case, if you try to resolve parent case, you will see below error.

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,