Understanding object locking

A PRPC 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> Process and Rules > Tools > Work Admin > My Locks.

To view all locks held by any requestor, select> Process and Rules > Tools > Work Admin > 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 System-Locks.LockInfo and the standard harness 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 items in the PegaSample-Task class are identified with a W- prefix. The lock string for work item 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.

Except as described below, a requestor can only release locks held by its own session.
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 a browser 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.

Releasing locks of other sessions

In releases before V6.3, a requestor could force the release of locks held by any session with the same Operator ID as the current session. In V6.3+, lock information is held in the memory of each node, rather than in the database, for improved performance. However, even in a multinode V6.3+ system, a requestor can force the release of locks held by any session with the same Operator ID and same user name (pyUserName) through the PublicAPI method:

LockManager.unlock(StringMap, boolean)

which communicates through the system pulse across all nodes. On each node, the system searches existing requestors (including passivated ones)  using  the supplied requestor ID . If a session is found, the system checks that the user names (pyUserName) also match before attempting to terminate the other session. If a session is found that matches the requestor ID, but the user names don't match, the system generates a SECU007 security alert and lists the corresponding requestor ID and user name in the logs.

Unauthorized (suspicious) attempt to terminate user session. Attempt made to terminate a user session (H73B84CC3B4980B0B17872B3E9E709AA1) where the given user name ([email protected]) and the session user name ([email protected])  does not match.

To test whether a work item is locked, an activity can call the standard activity Work-.WorkLock, which tries to lock the work item. If it fails to acquire a lock, the SuccessInfo parameter is negative, indicating that the work item 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 item 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