Adding a Validation Script to a Field

Follow these steps to add a validation script to an entity field:

1. Identify the field in an entity that requires additional validation beyond what is provided by the GE (including validation for Required fields and range validation for date/time and numeric fields).
   • For example, one of the requirements for the Motor Loaner System is to ensure that any Vehicle Identification Number (VIN) entered by a user is in the appropriate format: it contains exactly 17 alphanumeric characters and does not include the I, O, and Q letters. See BPR10: Enforce VIN Number Accuracy and About the Data Quality Design for the Sample Application for details.
   • If there are a number of fields in a particular entity that require additional validation, you should consider consolidating all of these validation rules in an entity object rather than writing individual validation scripts for each field. See Developing Entity Plug-in Objects for details.
      
2. Open the Fields record for this field from its parent's Entities record.
   • If the field does not exist yet, then add a new field to your entity. See Defining Entity Fields for more information.
   • For example, open the Entities record for the Vehicles entity and double-click the VIN field to open its Fields record.
      
3. Click the Validation tab.
4. On the Options sub-tab, change the Validation Type from Standard to Standard + Script or Script Only. This adds a Script sub-tab.
   • Standard + Script: This selection indicates that the system applies both the standard GE validation and the validation specified on the Script sub-tab for this field. When selected, the validation script supplements the standard generic entity (GE) validation.
   • Script Only: This selection indicates that the system will not apply the standard GE validation. It only applies the validation logic specified on the field's Script sub-tab. When selected, the validation script replaces the GE validation.
   • For the VIN validation (and all of the validation scripts in the sample application), the developer selected Standard + Script to build on the standard GE validation rules.
     
     
5. Click the Script tab to view the blank Script control.
6. Click the buttons in the Script toolbar to review the set of intrinsic Available Objects that you can use directly in the script, the set of available object you can reference within the script, and any available examples. 
   
    
   • For Field Validation Scripts, the following objects are defined and available for use:
     • oResult: This corresponds to the Aptify.Framework.BusinessLogic.GenericEntity.ValidationScriptResult class. It is used to return the results of the validation test and display a message to the user if validation fails. See the Aptify Software Development Kit (SDK) for more information on this class.
     • geRecord: This corresponds to the Aptify.Framework.BusinessLogic.GenericEntity.AptifyGenericEntityBase class. When writing a validation script, you can use this object to pass in the current value for the field that the script is validating. See the Aptify SDK for more information on this class.
       
       
   • Field Validation Scripts can include references to the following .NET assemblies in the Global Assembly Cache (GAC Reference) or in the Aptify Object Repository (Repository Reference):
     • System: .NET framework assembly.
     • System.Data: .NET framework assembly.
     • System.XML: .NET framework assembly.
     • Bootfiles.IAptifyDataServices: This assembly corresponds to the Aptify.Framework.DataServices namespace, which forms Aptify's Data Services Layer and which is responsible for accessing data from the database. See the Aptify SDK for more information on this namespace. Note that Bootfiles identifies the Object Package for this assembly in Aptify Object Repository.
     • Bootfiles.AptifyAttributeManagement: This assembly corresponds to the Aptify.Framework.AttributeManagement namespace, which contains classes that are responsible for creating, retrieving, and changing code level attributes. See the Aptify SDK for more information on this namespace. Note that Bootfiles identifies the Object Package for this assembly in Aptify Object Repository.
     • Bootfiles.AptifyGenericDataServices: This assembly corresponds to the Aptify.Framework.DataServices.DataAction class, which is the main Data Services Layer class used for all synchronous data access for applications developed within Aptify. The DataAction component also manages connections and data caching intrinsically. This class is not bound to a specific database engine. Hence, the Generic nomenclature. Through configuration information, the generic Data Services Layer binds to a specific database engine. The default implementation is for Microsoft SQL Server which is contained in the assembly, AptifySQLDataServices. See the Aptify SDK for more information on this class. Note that Bootfiles identifies the Object Package for this assembly in Aptify Object Repository.
     • Bootfiles.AptifyUtility: This assembly corresponds to a set of classes in the Aptify.Framework.Application namespace. The objects in this namespace provide a set of utility functions that are used primarily to access meta-data associated with entities. See the Aptify SDK for more information on this namespace. Note that Bootfiles identifies the Object Package for this assembly in Aptify Object Repository.
     • Startup.Generic Entity Base: This assembly corresponds to the Aptify.Framework.BusinessLogic.GenericEntity.AptifyGenericEntityBase class. This is the base class for the Aptify Generic Entity, the main business object in Aptify. See the Aptify SDK for more information on this class. Note that Startup identifies the Object Package for this assembly in Aptify Object Repository.
     • Bootfiles.AptifyExceptionManagement: This assembly corresponds to the Aptify.Framework.ExceptionManagement namespace, which contains classes that can be used to manage the persisting of and display of Exceptions throughout an application. See the Aptify SDK for more information on this namespace. Note that Bootfiles identifies the Object Package for this assembly in Aptify Object Repository.
       
       
7. Using VB.NET syntax, write a script that provides the validation required for this field.
   • As you type within the script control, IntelliSense automatically displays a set of available options to assist you with completing an object reference, as illustrated below. 
     
      
   • The full text of the VIN validation script is shown in Figure 10.11. The following describes the general design of this script:
     • Define an all-caps regular expression that is 17 characters long and does not contains I, O, or Q using the System.String class.
     • Use the methods in Aptify.Framework.BusinessLogic.GenericEntity.AptifyGenericEntityBase (by using the geRecord available object) to pass in the value entered by the user for the VIN field to a temporary field and convert the value to all upper case characters.
     • Use System.Text.RegularExpressions.Match to match the VIN value entered by the user against the regular expression.
     • If the user input matches the regular expression, then the value passes the validation test. The last step in this case is to call oResult.Success=True to indicate successful validation. (oResult is the available object for Aptify.Framework.BusinessLogic.GenericEntity.ValidationScriptResult).
     • If the user input does not match the regular expression, then the value fails the validation test. In this case, the script calls oResult.Success=False and uses oResult.Message to populate a pop-up dialog that notifies the user that the validation failed and the record could not be saved.
     • Note that the sample script also includes code to handle situations where the script fails for unexpected reasons (lines 28 to 32).
       
       
8. Click OK when finished to save and close the Fields record.
9. Save and close the field's Entities record.
10. Open a record in that entity and test the validation you just defined.
    • For example, enter an invalid VIN number that is not 17 characters long and attempt to save the record. A validation message should appear indicating that the value entered is not valid.