(v1) .Custom Validation v2.1.4.7

Basics

The feature allows the Admin to define customized Validation routines on any table. These routines can be executed before Saving or Deleting records on any table. The validation routines can also target specific records in the table the validation is assigned to.

This Grid will allow Users to add Custom Validation routines to Save and Delete actions on the application data.

• Description: A description field to provide an identifying name for this validation routine.
• Table Name: The Database table name to which this validation is be applied.
• Table Record: The specific RECID number that should be validated. Leave this blank to apply the validation to all records.
• Action: Save or Delete options specifying the table action that should be validated.
• Logic Entry field: All of the logic for the particular validation routine.

Prerequisites

This feature is intended for Administrators and an understanding of PHP language and syntax is required. You must also be aware of language compatibility for the version of PHP installed on the web server. For validation that requires querying other data, an understanding of SQL is necessary, particularly variants specific to your database platform.

Usage

In a typical validation routine, some Boolean condition is tested, and FALSE is returned if it fails. Returning false at anytime during the routine will stop the routine processing and cause the validation to fail, preventing the Save or Delete. Before the return, an error message should be set to provide feedback to the Users.

Scope

Validators are written and executed within a subset of PHP syntax, and at run time they have scope access to three arrays of data $data, $params and $user. For security purposes, only a subset of PHP functions have been whitelisted.

$data

A key/value paired array of data that is being sent to the database.

'Save:' The array contains the actual data that is being saved to the database. There will be a key/value pair for every column that is being passed to the SQL insert or update command, keys matching the actual table column names. The array will always contain a RECID index. For updates, this will be an integer value. For inserts it will be the string “addNew”.

In this example, the "RECID" index in the $data array is used to determine if this Save is adding a new record.

if($data["RECID"] == "addNew"){

'Delete:' The array is a listing of integer RECIDs for all the records that will be deleted from the table. It is an array of arrays the inner level being key/value pairs corresponding to column names and database values for the records that will be deleted.

$params

A key/value paired array of parameters that were passed to the Save or Delete functions. This parameter array will be different from form to form and Grid to Grid. Since the validation happens on the table level, it is not good to rely on this data unless the use-case depends on only validating interactions from a specific source.

In this example, an "isCompletion" index in the $params array from the Service Desk Action form is used to determine if this save is completing the Service Order Action. Since we cannot rely on these indexes always being present, we use the isset() check to look for the existence before checking the value.

if(isset($params["isCompletion"]) && $params["isCompletion"] === true){

$user

A key/value paired array of User information about the currently logged in User. The example below shows options that are available in this array.

$user = [
     'isSysAdmin' => TRUE
     'isCoordinator' => FALSE
     'isCustomerCenterOnly' => FALSE
     'attributes' => [
        'CONTACTS_RECID' => 1
        'NAME' => 'Pcr Demo'
        'FIRST_NAME' => 'Pcr'
        'LAST_NAME' => 'Demo'
        'DEPT_HIERARCHY_RECID' => NULL
        'TENANTS_RECID' => 0
        'EMAIL' => 'demo@pcr.com'
    ]
]

Syntax of Validations and Building Queries

Custom Validation shares a set of common syntax and available functions with the other types of Custom Logic. There are also various built in functions to assist in querying data in order to do the look ups validations require.

Validation functions

setError

Sets a validation error message. This messages output in the UI if the validation logic returns false. If this function is called multiple times, only the message from the last calls is displayed.

$this->setError ( string $message );

setWarning

Sets the validation warning message. This messages output in the UI only if the logic does not return false. If this function is called multiple times, only the message from the last calls is displayed.

$this->setWarning ( string $message );

Content

There's no easy way to monitor Custom Validation for output, especially while writing the code for it, because there's no "real" data to pass through the code when it is being written.

Here are a couple options, one of which is fairly easy but doesn't show the actual data being validated, the other is more involved, but makes it possible to observe actual data that goes through the code that is being written.

Data Dictionary

If only the key names of the $data array are of interest, that is always the database row that is being validated. The columns that belong to the table can be found in the Data Dictionary:

• "Admin > Data Dictionary"

Look up the table that the code is being written for, the column names are the keys that are expected to be seen in that variable, this will enable references to them to be made in the code. For example, SERVICES:

Then write PHP code for the check desired.

if ($data['BILLABLE'] == 0) {
// Set an error because Services aren't Billable, or whatever...
}

This approach doesn't let you view real data, though. 

• Not ALL column/value pairs are always included. Some inserts and updates omit columns that have defaults or are left unaltered in a given process.
  • The User writing the validation should monitor the data in order to observe what is being passed through.

Data Monitoring

If the data that is being checked needs to be seen, so that an idea what it looks like as it's being processed can be viewed, multiple browser tabs will be needed.

1. Custom Validation - see the code being written
   • "Admin > Custom Logic > Validation"
2. Form the Validation runs against (example from above, Service Form)

3. In the Custom Validation code, add this to the top:

   $dataMap = [];
   // Covers undefined variable bug - $data IS defined during execution
   if (!isset($data)) {
   $data = [];
   }
   foreach ($data as $column => $item) {
   // Replace strings for values that don't convert well
   // switch isn't naturally type-strict, so the cases need to be.
   switch (true) {
   case $item === null:
   $item = 'null';
   break;
   case $item === true:
   $item = 'true';
   break;
   case $item === false:
   $item = 'false';
   break;
   case $item === '':
   $item = '{empty string}';
   break;
   }
   $dataMap[] = $column . ' => ' . $item;
   }
   $this->setWarning(implode("<br>", $dataMap));
   return false;

4. Once that's added to the CV code, go to the Form where the CV is applied. Save the record.

The $data variable's contents should be displayed on a dialog message:

This can also be done for $params or $user.