Like most Visual Basic-driven programming, RE:VBA is essentially event-driven. Event-driven programming means most of the programs you write will process as specific actions occurring within The Raiser's Edge. Events are always the starting points for procedures. Macros are procedures that are not event-driven. These events can be system-generated, such as the Form Load event or a Timer control event, or user-generated, such as the Click event on a command button. Essentially, events allow you to determine when your applications will process.
Where are Batch Events in the Visual Basic Editor?
In addition to top-level data objects, RE:VBA lets you access and control processes. To access the events available for your use in The Raiser's Edge 7, select System, RE7 Objects, Active Batch, BatchVBARecord.
Events in Batch
There are four events in Batch that allow you to access gift or constituent records before they are committed to the database. You can also "create" exceptions for gifts or constituents that you do not want to commit to the database along with an exception message to assist your end-users. You can even make changes to a record that was previously an exception and force Batch to "try again."
Scenario: The following applies to a gift batch. You want to set a rule for gifts that are $2,500 or more. You want to ensure these larger gifts have the Letter Type "Hand Written Thank You." Before the gifts are committed, the system needs to check the gift amounts and make sure the corresponding letter is correct. After the gifts are committed, you want to export an Excel spreadsheet containing the names of all the constituents along with their gift date, type, amount, and fund.
Listed below are the events associated with committing records in Batch:
This event fires once before the records begin to commit to the database. This allows you to pass information to another database or verify that some specific business rules for your organization were met. BeforePost event passes sBatchName, a string that represents the batch number of the processing batch. It also passes lBatchType, which will tell you if this is a constituent batch or a gift batch. The last parameter is bCancel, which, if set to True, will discontinue the entire committing process.
Scenario: In this portion of the VBA code for the above scenario you might want to check the lBatchType. If the batch type is gift, you could have the code check the gift amounts and letter types execute in the BeforePostRecord event.
Before each row is committed to the database, the BeforePostRecord fires. This allows you to access the underlying data object after it is created but before it is added to the database. You can pass some of this information to a separate database or you can verify that some specific business rules have been met. If they haven't been met, you can stop the record from being committed to the database.
The parameter oDataObject is passed so you can access the entire object model for the record to be accessed. You can change information, use VB to make a calculation and add that information to the record, or check to make sure all of the information is entered according to your business rules. For those records that do not meet your business rules you can set bCancel equal to True. By doing this you could have the record post as an exception, you could revert back to the data entry screen, or you could even have the "system" correct the violation of the business rule.
Scenario: In the above example is where the gift amount would be checked. If it were over $2,500, the application would also check to make sure there is a Letter Type of "Hand Written Thank You." You would set the parameter of bCancel =True if you wanted the record to not post and become an exception. In this example, if the gift was > $2,500 and the letter was not "Hand Written Thank You," you would want to set bCancel=True. By using sExceptionMessage equal to "Incorrect Letter Type-Hand Written Thank You Required" you could put a custom exception message on the exception report. You could configure the Cancel operation so the user would revert back to the data entry screen and the user could correct the letter type. Any time a record is flagged as an exception the HandleException event will fire.
This allows you to possibly "fix" the cause of an exception and try the commit again. This occurs when bTryAgain is set to true. It is very important that the cause of the exception is corrected when you go back to BeforePostRecord to avoid getting stuck in a loop.
The AfterPost event executes after the entire commit process is complete. This allows you to "clean up" any objects or connections to other databases that you were using while the batch was being committed.
For more information about Batch Events, select Help, RE:VBA/API Help from the menu bar in The Raiser's Edge 7. On the Search tab, type "batch event" in the keyword search field.