Commit method

Use this method to commit all uncommitted database changes. This method writes all the instances specified by one or more earlier Obj-Save methods to the PegaRULES database (for internal classes) and to external databases (for external classes).

Basics

The Commit method operates on Thread pages that can operate across multiple instances. After an object instance is saved into the database, it is persistent.

Use the Rollback method or the Obj-Save-Cancel method to cancel a previous Obj-Save before commit.

CAUTION:
Do not use the Commit method in an activity that has an Activity Type of Utility, Route, Assign, Notify, or Integrator. Flow processing performs commits automatically when the flow ends and when an assignment is created or completed. To avoid interference with this approach, do not use Commit in the flow-related activities in your application. (When you save an activity that uses Commit, if the Applies To key part of the activity is derived from the Work- base class, a warning message appears).

Most database updates require that the requestor hold a lock on the object. Typically a requestor acquires this lock when the requestor first opens the object with the Obj-Open, Obj-Open-By-Handle, or Obj-Refresh-and-Lock method. Note these two exceptions:

  • A lock is not required for the first-ever commit operation of a newly created object.
  • A lock is not required for objects of classes that don't support locking.

Parameters

The Commit method has no parameters.

Results

The system commits all deferred write operations (including deletes) for this requestor in the queue to the database. If any of the writes fail, they all fail.

Commit operations can trigger the execution of Declare Trigger rules. The system updates indexes as required by executing Declare Index rules.

All locks held by the requestor Thread (except those that were acquired with the ReleaseOnCommit box not selected in the Obj-Open method) are released.

Any clipboard pages which hold objects retrieved through linked property processing are deleted, as potentially stale.

Checking the method status

This method updates the pxMethodStatus property. See How to test method results using a transition.

When a deferred — that is, non-immediate — Obj-Save or Obj-Delete method fails, the next Commit method will also fail unless one of the following is performed successfully before the Commit method is attempted again:

  • Another deferred Obj-Delete (or Obj-Save) method is performed on the instance
  • An Obj-Save-Cancel is performed
  • A Rollback method is performed
CAUTION:
If during the database save, any of the four properties listed below contain a value that is wider than the corresponding database column, the Commit method fails. The system associates the message Database-ColumnTruncated with the property in error. (This message begins "Property Zzzzz has been truncated...")
  • pxObjClass
  • pxInsName
  • pzInsKey
  • pyClassName

If any property other than these four properties contains a value that is longer than the width of the database column, the system associates a warning message Database-BadTableMapping-KeyPropertyTooBig with the property and returns a warning status. The database is updated and data for the column is truncated to fit. The system changes the last character of the truncated value to a plus sign (+) character, as a more enduring indication of this problem in case the warning message is missed or ignored.

Java EE two-phase Commit support

In a Java EE application server setting, the JTA transaction aspects of this method depend on how the Pega Platform system is deployed. If your system is deployed appropriately in the Enterprise tier of a Java EE application server, a Commit operation can be processed as a full Java Transaction API (JTA) transaction. This is useful when objects are saved to more than one database,

For example a single Commit operation may update both the PegaRULES database and an external database (made visible through the External Database Table wizard).

Troubleshooting deferred write operations

As a debugging aid, the standard HTML rule @baseclass.DeferredOps interrogates system internals and presents an ordered list of deferred (uncommitted) database operations for the current Thread. In a step immediately before a Commit method, your activity can display this HTML rule using the Show-Page method, to see what will be committed.

Design consideration and notes

  • When you include the Commit method in an activity, design the processing so that the Commit method occurs only after errors are intercepted, checked, and corrected. If a Commit method fails, it is unlikely that processing can continue in any reasonable way, so it is important to include a transition in the Commit step that checks the status.
  • Even when processing can continue after Commit failure, design your activity (after debugging and fixing the cause of the failure) to collect any required user input that corrects the problems, and re-perform any Obj-Save methods that preceded the Commit call.

Performance statistics

Three statistics in the Full Details display of the Performance tool report on Commit operations from your requestor session

  • Elapsed time writing to the database (property Code-Pega-PAL.pxCommitElapsed )
  • Database Commit Count (property Code-Pega-PAL.pxCommitCount )
  • Database Rows Committed (property Code-Pega-PAL.pxCommitRowCount )

Additional resources

For more information about JTA operation, see Distributed Transactions and PegaRULES Process Commander, a file on Pega Community.