The Obj-Save method uses properties on the page to derive the internal key under which it will be saved. This method can create a new database instance or overwrite a previous instance with that key.

You must update the following properties manually if you use the Obj-Save method:

• pxUpdateDateTime
• pxUpdateOperator
• pxUpdateOpName
• pxUpdateSystemID
• pxUpdateOrgUnit (only in the Work- class)
• pxUpdateCounter (only in the Work- class)

If you use the Obj-Save method, you can use apply the pxDefaultUpdateProperties data transform to update the pxUpdateDateTime, pxUpdateOperator, pxUpdateOpName, and pxUpdateSystemID properties.

Obj-Save method overview

An object that is stored in the PegaRULES database is persistent. The object is available to other users, and remains after the requestor session that created it ends.

This method does not always cause the object to be written immediately to the database. Often, developers use this method to perform a " deferred write" operation. In such cases, later execution of the Commit method, in the same Thread, completes the database update.

Select the WriteNow parameter to force this page (and only this page) to be written to the database as part of the Obj-Save method. Unlike the Commit method, the Obj-Save method does not operate on all previously marked-for-commit objects, only on the current page, and does not release locks.

You can reverse the effect of an Obj-Save method — if it has not yet been committed — with the Obj-Save-Cancel or the Rollback method.

Cautions

• In all but rare situations, do not save a page that contains messages and so is marked as invalid.
• When you use the Obj-Save method in an activity with Activity Type of Trigger, Utility, Notify, Assign, or Route, do not check the WriteNow check box. Leave locking and committing changes to work items and assignments to standard activities that support flow execution. See Understanding locking and transactions in flow executions.
• Do not use Obj-Delete method on instances in a class derived from the Index- base class. Use only Declare Index rules to change these instances.
• When using Obj-Save (for example, with an external database table), the page cannot contain any property corresponding to an auto-increment database column, even if that column is the primary key.

Parameters

This method has three parameters:

Results

First, the system examines the page's pxObjClass property to determine its class. It uses the corresponding Rule-Obj-Class instance to find the Database Table name, Lock Key format, and so on.

The system determines whether a lock is already present on the instance. If the current session does not hold a lock (and the instance belongs to a lockable class) the method fails.

If the WriteNow check box is selected, the system then deletes any old instance with that key and adds a new one. No locks are released. If the WriteNow check box is cleared, the system adds this page to the set of deferred-write pages for this requestor.

Properties with a null value (or equivalently "") are ignored (not saved) by this method.

Fail and Warn conditions

These situations cause the method status to be Fail or Warn :

• If the page contains messages (validation errors), then unless the WithErrors box is selected, processing halts and the page is not saved.
• You cannot save a page that is locked by another requestor.
• You cannot save a page that your session does not hold a lock on (if the page belongs to a lockable class), unless the object is new, never yet saved.
• You cannot save pages of any class derived from the Code- base class or the Embed- base class. Such pages exist only on the clipboard.

Troubleshooting

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. Your activity can display this HTML rule using the Show-Page method.

The Pega log entry " Obj-Save is trying to write to a non-existent column " indicates that two incompatible schemas are installed for the PegaRULES database. See the Pega Community article Troubleshooting: "Obj-Save is trying to write to a non-existent column".

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 method fails, the next Commit method will also fail unless one of the following is performed successfully before the Commit method is attempted:

• Another deferred Obj-Delete (or Obj-Save) method is performed on the instance
• An Obj-Save-Cancel is performed
• A Rollback method is performed