Overview of the Data Validation Framework

What the Data Validation Framework Provides

• A common model in which data validation is done in OpenPetra.
  • Although the way how data validation is done differs on server and client side due to the different nature of these sides, there is still a common model (the Validation Framework) behind it.
• It supports a variety of situations in the most effective manner.
• It makes the raising of data validation errors and the handling of those as painless and easy for the software engineers as possible.
• It supports both automatic and manual data validation
  • Automatic Data Validation
  • Manual Data Validation
    • Form/UserControl authors can add an arbitrary amount of manual data validations to a Form/UserControl, augmenting the automatic data validation. Most of the documentation of the Data Validation Framework in this wiki relates to that process.
• It ensures that data validation errors are brought to the attention of the users in a standardised way.
• All data validation warning/error messages can be translated.
  • All data validation warnings/errors have a unique 'Error Code' that makes it possible to identify what warning/error the user is faced with. This is especially important for support staff as they will be able to identify the warning/error even if they aren't able to read the warning/error message (as it might well be displayed to the user in a language that the support staff doesn't understand).

Client Side

Validation Scope

Field-level Validation

Data Validation is run when a user leaves a Control whose DataColumn that the Control is bound to has associated Data Validation code.

• Automatically generated and (optionally) manually written code performs the validation of the data that the Control is bound to. Multiple errors/warnings can be recorded for a single DataColumn.
• In case the Data Validation fails,
  • an instance of TVerificationResult is created for each Data Validation error/warning. This/these are then added to the Collection of Data Validation errors/warnings of the Form that hosts the Control (FPetraUtilsObject.VerificationResultCollection).
  • automatically generated code will display a ToolTip near the Control. The ToolTip text explains what is wrong (this text comes from the associated TVerificationResult).

Record-level Validation

Data Validation is run when a user changes to a different record in a Grid.

• Automatically generated and (optionally) manually written code performs the validation of the data of the current record. All DataColumns may be checked for data validation errors/warnings. Multiple errors/warnings can be recorded for a single DataColumn.
• Automatically generated code handles the system data constraint exception that arises if the user edits a record in such a way as to violate the primary key unique constraint. Read more about the Duplicate Record Protection code here.
• In case the Data Validation of a record fails,
  • an instance of TVerificationResult is created for each Data Validation error/warning. This/these are then added to the Collection of Data Validation errors/warnings of the Form that hosts the Grid (FPetraUtilsObject.VerificationResultCollection).
  • automatically generated code will display a MessageBox, potentially listing several data validation errors/warnings that pertain to the current record. The text of the MessageBox explains what is wrong (the texts come from the TVerificationResult[s] that pertain to the current record).
  • after the user chooses OK in that MessageBox automatically generated code will prevent the user from navigating to another record in that Grid if there was at least one TVerificationResult recorded for the pertaining record that constituted an error rather than a warning.

Form-level Validation

Data Validation is run when the user presses the 'Save' button or chooses Menu 'File' -> 'Save', or when the user closes a Form and the Form contained changed data.

• Automatically generated code in the 'SaveChanges' Method causes automatically generated and (optionally) manually written data validation code to be run on all parts of the Form that the user has been to (e.g. various UserControls that got delay-loaded by switching to various TabPages).
• In case the Collection of Data Validation errors/warnings of the Form (FPetraUtilsObject.VerificationResultCollection) contains data validation errors or warnings,
  • automatically generated code will display a MessageBox, listing all Data Validation errors/warnings that are recorded for the Form. The text of the MessageBox explains what is wrong (the texts come from all the TVerificationResult[s] that are recorded for the Form);
  • after the user chooses OK in that MessageBox the data saving operation of the Form is cancelled by auto-generated code.
    • Exception: If all TVerificationResults in the FPetraUtilsObject.VerificationResultCollection were warnings and not errors, the saving is allowed to go ahead after the user chooses 'OK' in the MessageBox.

Tab-level Validation (On Screens with Tabs)

Data Validation needs to be done manually by the programmer when the user tries to switch to another Tab.

• In case the Collection of Data Validation errors/warnings of the Form (FPetraUtilsObject.VerificationResultCollection) contains errors or warnings for the UserControl that holds all the content of the TabPage,
  • all validation messages that pertain to that UserControl need to be shown in a MessageBox to the user by the programmer. This needs to be done in the same manner as it is done by the auto-generated code in the other Data Validation scopes.
  • after the user chooses OK in that MessageBox the Tab-switching operation is to be cancelled by the programmer.
    • Exception: If all TVerificationResults that pertain to that UserControl were warnings and not errors, the Tab-switching needs to be allowed to go ahead by the programmer after the user chooses 'OK' in the MessageBox.

Data Validation Error Notifications to the User

Intrusive Notifications

These kind of notifications take the input focus away from the Controls in which the user is changing data. They should be used only when the user tries to save data in a Form or when the user tries to switch to a different TabPage and when at least one data validation error/warning is present.

MessageBoxes

• 1..n TVerificationResults are displayed in a meaningful manner in a single MessageBox (rather than in a series of MessageBoxes).

Future Plan: Standard Dialog with a Grid

We would like to replace the use of MessageBoxes for the purpose of displaying intrusive notifications with a standard dialog that would contain a Grid and an OK Button. 1..n TVerificationResults could be displayed in that Grid in a much nicer way than is currently possible with pure text (e.g. showing an error or warning icon for each TVerificationResult line in the grid, providing hyperlinks to a help topic for certain TVerificationResults, ...).

Less Intrusive Notifications

These kind of notifications do not take the input focus away from the Controls in which the user is changing data.

ToolTips

• We use ToolTips to notify the user of Data Validation errors/warnings. One ToolTip at any given time is shown for a Control on the Form if the user leaves a Control that has associated data validation and that data validation fails.
  • The ToolTip is shown near the Control that failed its data validation.
    • The position of that tool-tip is automatically determined and cannot be altered.
    • In case one wants to suppress such a ToolTip for a specific reason then this can be done in a manual data validation Method by setting the SuppressValidationToolTip Property of the corresponding TVerificationResult to true. Note: The data validation on that Field still happens on record change/saving of data, it is just the pop-up that gets suppressed through that! (Example: Method 'ValidateGLDetailManual' in csharp/ICT/Petra/Shared/lib/MFinance/validation/GL.Validation.cs.)

Idea for the Future: Bottom-Docked Panel in Which Error Messages Would be Displayed

A hidden Panel would be docked to the bottom of every Form. It would be shown automatically when at least one data verification error/warning would be raised by any context in the Form and would be hidden again automatically once all the data verification errors/warnings in the Form are resolved.

• Individual data verification errors/warnings could be displayed as LinkLabels on which the user can click. Clicking those would set the input focus to the offending Control.
• The height of the Panel would be determined by the number of the data verification errors/warnings and would not exceed a maximum height.
  • A vertical scrollbar would be shown if there are more the data verification errors/warnings to be shown that fit on the maximum height of the Panel.

WinForms Generator Support for Data Validation

The WinForms Generator creates all the program code that is necessary to automatically and consistently deal with the handling of the Data Validation for any type of Form or UserControl that is defined by a YAML file.

Code is generated for:

• the calling of the auto-generated Data Validation Method(s);
• the calling of the manual Data Validation Method(s) in the *.ManualCode.cs file;
• the handling of duplicate records so that a helpful Data Validation MessageBox is displayed with a hint indicating which data is duplicated;
• the evaluation of TVerificationResult objects stored in the TVerifcationResultCollection of the Form (held in FPetraUtilsObject.VerificationResultCollection) - these objects are created automatically or manually if a Data Validation fails;
• the showing of Data Validation ToolTips and MessageBoxes as appropriate and in various contexts (e.g. when the user wants to leave a Control, when the user wants to leave a record in a Grid, when the user wants to save data in a Form or close a Form which has unsaved data in it);
• the prevention of updating/saving of data if Data Validation errors are present in various situation (updating/saving is allowed to go ahead if only warnings are recorded, though).

The auto-generated code also makes the Controls that are to be validated and the translated Labels of those Controls accessible to both the automatically generated and the manual Data Validation code. The Controls are needed for setting the input focus to the first Control for which Data Validation failed, the Labels are important as this allows the validation messages that are shown to the user to contain the Text of the Labels of Controls as they appear to the user in their selected language.

Control for Which Data Validation Must Be Done

Date TextBox (TtxtPetraDate Control [dtp in YAML])

This Control must always be validated - either through Automatic Data Validation or through manual Data Validation! The reason for that is that although the Control in itself 'knows' if a text entered in the Control is valid or not, the Control can only return null for its Date Property to signalise that. However, the Control's Date Property is also null if the Text is cleared, and thus it's not possible to tell whether the Date is valid by just inspecting the Date Property, or - if null isn't allowed for a Date (AllowEmpty-Property set to false) - if the Data Validation problem arises because the user entered a text that cannot be parsed, that isn't allowed (e.g. because of date range), or because the user simply entered no text at all! Please also note that if Data Validation is not run on the Control, an 'undefined' date will be saved to the DB if an invalid date was entered, but the Control will still display the invalid date, and the user will not notice that there is a problem and that the date he/she was trying to enter wasn't saved.

Validation: The Date TextBox needs to be validated with a call to Method 'TSharedValidationControlHelper.IsNotInvalidDate'. Example:

VerificationResult = TSharedValidationControlHelper.IsNotInvalidDate(ARow.DateOfBirth,
    ValidationControlsData.ValidationControlLabel, AVerificationResultCollection, false,
    AContext, ValidationColumn, ValidationControlsData.ValidationControl);

That way all possible Data Validation errors that the Control can handle are processed by the Data Validation Framework (incl. date range checks).

Note: Please don't use Method 'TDateChecks.IsNotUndefinedDateTime' - if that would be used, Data Validation would only check whether a date can be parsed and whether a date is not null, but no other Data Validation errors would be captured!

THE FOLLOWING SECTIONS ARE WORK IN PROGRESS

Server Side

Datastore 'SubmitChanges' Methods

At the moment our auto-generated '...SubmitChanges' Methods in the openPETRA Datastore return a TVerificationResultCollection, but that should be changed to Exceptions being thrown instead - see DB Discussions!

General

Use of Centralised Error Code System

See Central Place for Maintenance of Unique Error Codes.

Help File Integration

TODO