Obj-Save method

Use this method to request that the system save a clipboard page to the PegaRULES database or, if the page belongs to an external class, an external database.

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.

Note: In most situations, it is recommended that you use flow processing or activity APIs such as Save or UpdateWorkObject instead. Using Obj-Save skips common processing such as validation, creating history, and keeping the properties that track last update information current.

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:

Parameter Description
WriteNow Normally, leave this box cleared.

Select the box to cause the system to write this page's data to the database as this method executes. If selected, when the activity executes, the system performs an immediate write-through (database commit) of the page to the database.

Clear the WriteNow check box in any activity of type Trigger, Utility, Notify, Assign, or Route, and in situations where you want to mark a page to be saved, but want the system to perform the database commit later.

Do not select this box for activities that support flow execution. The locking and database commit operations for flows are correctly supported by standard activities associated with specific flow shapes. See Understanding locking and transactions during flow executions and PDN article 18986 Troubleshooting: "Save Failed: A Commit cannot be performed".

WithErrors

Select this box if the instance is to be saved even when it contains messages, indicating validation errors.

Although allowed, saving invalid instances can seriously affect the results or correct operation of your application. Many activities assume that a newly opened instance from the database is valid.
OnlyIfNew Select to cause only an insert operation, not insert or update. If the activity is operating in batch mode, it does an insert instead of a defaulted update.

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 PDN 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

Methods and instructions by function