Understanding object locking

A Process Commander requestor can lock an open instance if all of the following are true:

• The instance belongs to a concrete class that has Allow Locking? checked in the class rule and
• The instance has ever been saved and committed to the PegaRULES database.
• The requestor has an access role that conveys the privilege needed.

Properties identified on the Locking tab of the Class rule form together define the lock identity. (If the Locking tab contains no property names, the properties that form a lock definition are the same as those that form the external key, on the Database tab.) All classes in one class group (which corresponds to one database table) have the same properties in the lock definition.

Viewing locks — Standard reports

To view locks held by your own requestor session, select View > System > Locks > My Locks.

To view all locks held by any requestor, select View > System > Locks > All Locks; and then drill down to identify the details of the locked object. Hold the mouse pointer over a row of the drill-down detail to identify the Operator ID of the requestor holding the lock.

These two reports present instances of the System-Locks class, corresponding to the pr_sys_locks table of the PegaRULES database.

Viewing locks — In an activity or flow

Locks are acquired by activities, using one of three methods — Obj-Open, Obj-Open-by-Handle, and Obj-Refresh-and-Lock. Optionally, each of these methods can store detailed results in a page of class System-Locks. If a method failed to acquire a lock because the object is already locked, information on this page identifies the current requestor session that holds the lock. By convention, this page is named LockInfo in standard rules.

As a debugging aid, the standard section rule System-Locks.LockInfo and the standard harness rule Work-.LockInfo can present information from that page to an application user. The LockInfo page contains these properties:

• pxExpireDateTime
• pxLockHandle
• pxOwnerID
• pxUpdateOperator
• pxCreateDateTime

A lock string uniquely identifies a lock. For instances that belong to classes not associated with a class group, the text string consists of the class name concatenated with the key parts of the object (determined on the Keys area of the Basics tab of the Class form, or the Locking tab of the Class form).

For an object that is within the scope of a class group, the lock string consists of the class group name concatenated with the value of the key properties identified on the Keys tab of the Class Group form. For example, for the Sample Work application, the class group is named PegaSample and work objects in the PegaSample-Task class are identified with a W- prefix. The lock string for work object W-43 is thus:

PEGASAMPLE-TASK W-43

Generally, a Thread that acquires a lock retains it until the instance is saved again with a Commit method (which may complete an Obj-Save or Obj-Delete method). However the system automatically expires locks held longer than a specified timeout period. You can change the default timeout interval of 120 minutes to a longer or shorter period. This value is stored in the Data-Admin-System data instance.

An expired or "soft" lock remains held by a requestor session until the session releases it or until the requestor session ends, but a soft lock can be stolen — broken and acquired — by another requestor who opens the instance. In that case, any updates by the first user that are not committed are lost.

A requestor can only release locks held by its own session, or by another requestor session that has the same Operator ID.
A Commit method releases all the locks held by a requestor Thread that were acquired with the ReleaseOnCommit box checked when the object was opened.

When a user signs off, any locks held by that requestor are released.

In contrast, locks are not released when a user closes an Internet Explorer session by clicking the Windows close box (rather than by logging out). The locks may be needed by another Thread of the same operator, or by another operator or process. Encourage users to log off through a button or link rather than closing the window.

To test whether a work object is locked, an activity can call the standard activity Work-.WorkLock, which tries to lock the work object. If it fails to acquire a lock, the SuccessInfo parameter is negative, indicating that the work object is already locked. The FailureInfo parameter provides additional detail.

To test whether a lock is held on a page already on your own clipboard, call the function rule isPageLocked(tools, pagename).

To test whether an object other than a work object is locked, use one of several methods in the PublicAPI LockManagerInterface.

To add detailed lock manager information to the Pega log, set the Logging Level Settings tool with this category to Debug:

com.pega.pegarules.engine.database.LockManagerImpl