Submit rules are a quick, easy way to help control the logic flow and add additional functionality to Responder™. Responder™ submit rules allow you to react to changes in the DataSets and perform simple to advanced actions based on the changes you see. Out of the box, there are quite a few submit rules that Responder™ uses. Most of these are required, but some of them can be enabled or disabled depending on your specific needs. However, even with this customization, you may find yourself needing additional functionality. Luckily, it is fairly easy and straightforward to create your own submit rules and integrate them into your Responder™ workflow.
Pre-Submit vs. Post-Submit: When Should Your Rule Do Its Thing?
The first thing that you will need to decide is whether your submit rule will be a pre-submit rule or a post-submit rule. Pre-submit rules fire before changes in the DataSet are written to the database. This means they allow you to perform validation on this data, allowing the transaction to be cancelled if there is an issue with the data, or to add extra information to the DataSet that is not auto-generated. Post-submit rules, conversely, are executed after the changes in the DataSet are written to the database.
In general, post-submit rules will be more complex as there are two datasets to work with. First, there is the Completed DataSet, which has the changes that were just written to the database. This DataSet is what post-submit rules trigger against, but is read-only and not used for making further edits. That is the job of the second DataSet, the Pending DataSet. This is an identical copy of the Completed DataSet, except that you can make changes as necessary to this DataSet and send it back to the database, where it will go through the submit rule process again. That being said, it is only necessary to work with the Pending DataSet if you plan on altering any of the data. If you only plan on looking at the committed data, then the Completed DataSet is all that you will need to use.
Construct Conditions: What Causes Your Rule to Fire?
Once you have decided on the kind of Responder™ submit rules you want to make, you will need to decide what will cause your submit rule to fire. This is known as the Construct Condition, and you will need to override the ConstructCondition method from the RX library. This method returns a DataRowCondition that uses combinations of “and” and “or” logic to determine whether or not to fire the submit rule.
There are many different conditions that can be checked in the Construct Condition. The main one that will be used will be the TableNameCondition, which checks if the tablename of the DataSet matches the specific table that you are looking for. Once you have the specific table you are looking for, you can check if the row in the DataSet has been changed in some way (RowStateCondition), if the value in a column has been changed (ColumnValueChangedCondition), if the value in a column equals a certain value (ColumnValueCondition), or even compare two columns to each other (CompareColumnsCondition), among other options. A Construct Condition can be as simple as looking for an incident device that has been modified:
… or as complex as finding when an incident for a device has been confirmed, whether it is for a new incident or if an old one was modified.
Perform Actions: What is Your Rule Going to Do?
With the Construct Condition created, you can now get into the heart of the submit rule to actually add your logic. To do this, you will be overriding another RX library method, this time the PerformAction method.
This is the method where you will actually be working with the DataSet and be able to perform any custom actions you need to. If you decided that you will be creating a pre-submit rule, then the DataSet you will be seeing and working with is the data that is going to be sent to the database. In the case of a post-submit rule, the DataSet will consist of the data that was already sent to the database.
Take special care with exceptions and logging when coding the Perform Action. When it comes to exceptions, submit rules ignore them and log them as errors by default. This keeps Responder™ running smoothly without interrupting any other operations. However, if you need to raise an exception and terminate the process, you can use a SubmitRuleException and set the “Cancel” property to true. This will stop the process from executing, abort the database transaction, and raise the exception to the calling application. It should be noted, though, that this can impact any submit rules that would fire after your custom ones.
If using your own exceptions, you may also choose to implement your own logging system. For the most part, the default logging will get the job done, but if you do this, make sure that there is proper error handling for you log file. Not having this will result in your submit rules not firing as expected.
Storing Files: What Needs to Go Where?
At this point, if you want to create additional Responder™ submit rules, you can just follow the same steps. All submit rules will need to get created under the same project and solution, but each will be its own class. Once all submit rules have been created, build your solution. This will produce a .dll file and a .pdb file. The .dll file will hold all of the information that you need for your submit rules. If you plan on doing any debugging, then you will need to keep the .pdb file, as it is used for debugging purposes. If not, then you can disregard the .pdb file. Take the .dll, and .pdb if necessary, and store these in the folder on your system that houses all of the Responder™ Server information. If your code uses a custom configuration file, this will also be stored in this same location.
Responder™ Configuration: What Needs to Get Changed?
After all of the files associated with your custom submit rules have been stored in the correct folder, you will need to configure Responder™ to use them. In the same folder, you will find a file titled SubmitRulesConfig.xml. This is where you will put a reference to your custom submit rules. You will need to add an xml snippet for each submit rule you have created. This snippet will contain a reference to the project name and the name of the submit rule. This file has sections for pre-submit rules and post-submit rules, so each submit rule will need to get placed in the correct section, based on what you decided earlier. Once all of your submit rules have been added to the xml file, the last step is to restart Responder™ Windows Service. Once this has been restarted, your submit rules will be ready to use.
Final Thoughts on Custom Responder™ Submit Rules
Custom submit rules are a great tool to help out with day-to-day work. They are easy to make, and you can make as many as you want. They are very flexible, and can be added at any time. By creating your own submit rules, you can customize Responder™ to work exactly the way that you want it to, and hopefully this guide will help get you moving in the right direction.