When to use database transaction APIs

PolicyCenter groups all related entity instance changes together in a group called a bundle. Gosu provides APIs to manipulate entity data in bundles. These APIs also provide the ability to change how to save business data object modifications to the database. Saving to the database all related changes to current objects is called committing the bundle.

For many programming tasks in Gosu, you do not need to know details of how database transactions work. For example, after rule set execution, the application commits the bundle.

If errors prevent the entire commit action from safely completing, Gosu commits no data changes to the database. In certain cases, after an error occurs, Gosu retains the bundle. Depending on application context, the bundle is preserved, for example to let a user fix validation errors. In contrast, in a web service implementation, a commit failure typically results in discarding the temporary bundle and returning an error to the web service client.

The most important types of database transaction APIs provide the functionality to:

Add an entity instance to a bundle
Run code in a new bundle
Commit a bundle explicitly, if necessary

Warning: Using database transaction APIs has significant effects on application logic and data integrity. Using APIs incorrectly can adversely affect other application logic that tracks when to commit changes or undo recent data changes.

The following table lists typical requirements for using the main database transaction APIs.

Code context	Create a new bundle with `runWithNewBundle`?	Add entity instances to bundles before changing data?	Commit bundle explicitly for data changes?	Notes
Code that only reads properties	No	No	No	If you do not change entity data, you do not need to use any database transaction APIs.
Rule sets	No	Yes, for database query results. See the Note column.	No	Important: It is dangerous and unsupported for rule set code to explicitly commit any bundle. Some rule sets, such as validation rules or pre-setup rules, have a main object that is already in the current writable bundle. If you change only that main entity and its subobjects, your Gosu rule set code does not typically require special database transactions.
PCF code in: List views View screens Edit screens	No	Yes, for database query results.	No	Important: In most PCF code, it is dangerous to create additional bundles or explicitly commit bundles.Typical PCF widgets handle database transactions automatically. For example, after you enter Edit mode, the application creates a new bundle. After you click the Save button, the application commits the bundle with any data updates. In general, use the default PCF behaviors. In wizard user interface flow, you can optionally configure steps to commit the latest changes. Even in those cases your Gosu code does not explicitly commit the bundle.
PCF pages with asynchronous actions	Yes	Yes, for database query results.	No. The `runWithNewBundle` API method commits the bundle.	In unusual cases in PCF files, you might need more advanced bundle management. For example, rare self-contained code must change the database independent of success of the primary user action. Use the `runWithNewBundle` API method to create a new bundle for your entity data changes.
Plugin implementation code	No, in most cases. Plugin method arguments that are intended to be modified are in a writable current bundle. Startable plugins require creating a new bundle. Message reply plugins use a different mechanism for using bundles.	Yes, for database query results. Plugin method arguments that are intended to be modified are in a current bundle that is writable.	No, in most cases. For startable plugins, the `runWithNewBundle` API method commits the bundle.	If the application expects changes to plugin method arguments, the application sets up a current bundle.
Workflow code	No.	Yes, for database query results	No	The bundle for workflow actions is the bundle that the application uses to load the Workflow entity instance.
Custom batch processes	Yes	Yes, for database query results	No. The `runWithNewBundle` API method commits the bundle.	Use the `runWithNewBundle` API method to create a new bundle for your entity data changes.
Custom work queues	Yes	Yes, for database query results	No. The `runWithNewBundle` API method commits the bundle.	Use the `runWithNewBundle` API method to create a new bundle for your entity data changes. Warning: Custom work item code has access to a current bundle. However, using this bundle for your own business data changes is unsupported.
Web services	Yes, if the operation modifies data.	Yes, for database query results	No. The `runWithNewBundle` API method commits the bundle.	Use the `runWithNewBundle` API method to create a new bundle for your entity data changes.