Dynacom Technologies

Have you ever wanted to prevent somebody from creating, updating or deleting a record (invoice, customer, etc.) based on a special business rule? For example, let’s say you want to force a 25$ minimum freight fee on every orders entered into Dynacom.

Custom Validations with Synergy are handled through two events: the Validate and the BeforeDelete events. The first one, as its name implies, is called to validate the data in the record. This event will always be invoked before saving a record, but it is also invoked in real-time after the data has been changed. Real-time validation enables us to display the DynaSense information bar as well as give focus to the appropriate control while the user is typing.  Performance-conscious users may disable real-time validation through the application settings, but it is enabled by default.

Handling of the Validate and BeforeDelete events can be configured at two different levels: screen or data object. Screen events are only raised when the user interface is active, and will only be raised for that particular screen. There are a few examples in Dynacom Accounting where multiple screens share the same data object: invoices, orders and credits; tax payments and tax receipts; pay checks and liability adjustments; etc. Data Object events on the other hand are shared across all screens using it, even if it is a custom screen created in Synergy. It is the lowest level at which you can configure events, and it is the only way to handle events for automated tasks and applications calling the data objects externally. Data object-specific events are also available: for example, the invoicing data object raises an event when the credit limit is exceeded to allow you to alter the approval and authorization process (more on this in a future blog entry).

Setting Up the Event Handler
Now, lets go back to our 25$ freight fee minimum example. To set up an event handler, open the Invoicing data object in the designer and select the Validate event in the property toolbox. At the moment, there are no built-in actions that allow you to set a validation error, so you need to add a script action.

Sub Main ()
 If Helper.MemberValue("InvoiHdr.ShipAmnt") < 25 Then
  Set CustomParams.Item("DataValidationError").Value = Helper.CreateDataValidationError("InvoiHdr.ShipAmnt", "The freight fee must be at least 25$")
  CustomParams.Item("Cancel").Value = True
 End If
End Sub

There are two things you should notice in this script. First, the error message is not displayed directly, but instead included in a data validation error that is returned. Next, the “Cancel” parameter is set to true, meaning an error has been set and that we wish to cancel the current process. The same validation process can be applied to any field in the data object, including custom fields and fields in detail sections.

Real-time Validation and the “Final” parameter
I mentioned the real-time validation can be disabled by the user; however I believe that it should never be necessary. Validations should always be designed with performance in mind. However, there are valid cases where achieving instant response is almost impossible. For this reason, the Validate event exposes a “Final” parameter that determines whether this is the last validation before the record is saved. Lengthy or expensive operations should always check if the “Final” parameter is true before executing. Validation errors that are set during the final validation cycle will pop a message box instead of the usual DynaSense validation.

Sub Main()
 If CustomParams.Item("Final").Value Then
  ...
 End If
End Sub

A Word of Caution
You should never display a message box or use any user interface in data object events because these events may be run unattended through the Dynacom Automation Manager Service. Doing so could hang the application or interrupt a batch process. Always use the IDataValidationError interface, returned by Helper.CreateDataValidationError and available with the Validate and BeforeDelete events to send a status message. Otherwise, put your event handlers in the screen instead of the data object if you absolutely need to display a special form or message.

Final Notes
I strongly advise that you do not validate your data any other way. Common patterns seen for validation involve using the LostFocus or KeyPress events of controls. While this may work for the basic scenario where a user is typing information, this will certainly not work if the record is imported from a XML file , if a Synergy action is programmatically creating the record, or if an external application is accessing the data object. As I’ve shown, Synergy offers many different ways to validate data, and there is no reason you shouldn’t be using them.