Object locking

Locks are implemented separately from the locking mechanism supplied by the database software (such as Oracle) that supports the PegaRULES database. Locks are exclusive to one Thread, and operate system-wide in a multinode system.

Basics

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

  • The instance belongs to a concrete class that has Allow Locking selected 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 that is defined on the General 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 Configure > Case Management > Tools > Work Admin > My Locks.

To view all locks held by any requestor, select Configure > Case Management > Tools > Work Admin All Locks, and 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, or 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

The lock string

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

Expired ("soft") locks

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

Releasing locks

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

Lock information is held in the memory of each node, rather than in the database, for improved performance. However, even in a multinode 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)

This method 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 do not match, the system generates a SECU007 security alert and lists the corresponding requestor ID and user name in the logs.

Testing for locks

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.

Debugging

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