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.
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:
If you use the Obj-Save method, you can use apply the pxDefaultUpdateProperties data transform to update the pxUpdateDateTime, pxUpdateOperator, pxUpdateOpName, and pxUpdateSystemID properties.
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.
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.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 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. |
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.
These situations cause the method status to be Fail or Warn:
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".
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: