We think of submit rules as application-level triggers that react to changes in a DataSet. Unlike triggers in the database, these triggers can perform advanced logic such as geometric network tracing.
The submit rule processing that occurs during IDataServices.Submit is basically a loop. The entire process is surrounded by a database transaction. At the "top" of the loop are pre-submit rules which execute before writing changes to the database. At the "bottom" of the loop are post-submit rules that execute after the changes write to the database. If there are additional changes made by the post-submit rules, then the pre-submit rules will once again have a chance to execute (think: validation on changes made by post-submit rules). When there are no more "pending" changes then the cycle stops and the results are returned to the calling application.
The following provides some detail on different parts of the "submit" processing loop:
- The IDataServices.Submit method takes a DataSet that contains data changes (inserts, updates, and deletes). Generally, this DataSet only contains a small amount of data. For example, for submitting a new call this DataSet will only contain a single DataTable (RX_CALLS) and a single "Added" record. There is some initial processing on the DataSet to add missing tables and relationships that our submit rules depend on and expect to exist in the DataSet.
- The pre-submit rules execute before the changes in the DataSet are written to the database. This is a good opportunity to assign values that should be set on a record before it is written to the database (beyond simple default values). This is also a good opportunity to provide validation (you can throw a SubmitRuleException (or just RuleException, either is fine) with Cancel set to true. This aborts the transaction and sends the exception back to the calling application (providing a good message in the exception).
- Any changes in the (pending) DataSet are written to the database. Responder processes inserts, updates, and deletes (in that order). Inserts and updates are performed in parent-to-child table referential order (as the parent record must be inserted before the child record in order to maintain referential integrity in the database). Deletes are performed in child-to-parent table referential order - the exact opposite of inserts and deletes.
- The post-submit rules execute after the changes in the DataSet are written to the database. These rules are more complex in that there are two DataSets to work with:
- The "Completed" DataSet contains the changes there were written to the database (in step #3). This DataSet is available so that it is possible to react to changes that have been written to the database. This is what post-submit rules trigger against - that is, the condition and PerformAction will be passed a DataRow from the "Completed" DataSet. Do not write to this DataSet - the changes will be ignored and may cause problems with other rules.
- The "Pending" DataSet is an identical copy of the "Completed" DataSet with ApplyChanges method called. This DataSet represents, as the name implies, the changes that have yet to be written to the database. Post-Submit rules must modify the "Pending" DataSet, in order, to changes to the database. Use the SubmitContext.FindPendingRow() to find the equivalent "pending" DataRow from the "completed" DataRow.
- The "Completed" vs. "Pending" DataSets is the source of a lot of confusion and complexity of writing post-submit rules. However, this is necessary in order to distinguish between what has already been written to the database and what has yet to be written to the database.
- If there are any changes to the "pending" DataSet then the processing continues back to the pre-submit rules. Otherwise, if there are no changes then continue to the next step. There is a maximum number of times we'll allow the loop to continue in order to prevent a rogue rule from causing an infinite loop. Even so, you must take care when writing submit rules to prevent this situation.
- There is some processing that occurs before returning the calling application. This includes some processing to send information to prediction services and firing IP Multicast events to notify external applications about a data-change (for automatic-refresh purposes). [At 930r2 and later, we now incorporate PubSub in our solution. This processing includes submitting all changes (unless filtered) to PubSub. This is another reason why all changes made by submit rules should be performed against the DataSet, as they can be included in our data-change publication (to PubSub) to keep all client applications (namely, Responder Explorer) in sync with the latest changes without requiring a "refresh".
