.Custom Validation v2019.2

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 any time 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.

If multiple validators are specified on the same table, they will ALL be executed and the messages generated by each will be concatenated together into one message delivered to the User.

Scope

Validators have access to three arrays of data: $data, $params, and $user. For security, a limited set of functions, classes, and keywords are permitted. The editor will highlight disallowed code when you attempt to save it.

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”.

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

An example of a nested array is as follows:

// Save $data:
[
    'RECID' => 'addNew', // for Insert, or an integer for Update
    'COLUMN_2' => 'Foo',
    'COLUMN_3' => 'Bar',
    // ...
]
 

// Delete $data's contents:
[
    1234 => [
        'RECID' => 1234,
        'COLUMN_2' => 'Foo',
        'COLUMN_3' => 'Bar',
        // ...
    ],
    5678 => [
        'RECID' => 5678,
        'COLUMN_2' => 'Foo Too',
        'COLUMN_3' => 'Bar None',
        // ...
    ],
]

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"){

$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

Custom Validation shares a set of common syntax and available functions with the other types of Custom Logic.

Validation functions

setError

Sets a validation error message. Error messages must be addressed by the User before a record is allowed to be altered. Error messages will have a red header bar. 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. Warning messages can be used for informational purposes and can be ignored by the User to allow altering a record after viewing the message. Warning message will have a yellow header bar. If this function is called multiple times, only the message from the last calls is displayed.

$this->setWarning ( string $message );

Error Messages

Once a Custom Validation has been triggered, regardless of what data input method triggers the Validation, a message will be reported back to the User identifying itself as a result of Custom Validation. The first part of the error will display the name of the organization to help identify that the error was a Custom Validation and not one of the standard errors from the application. The message from the Validation will appear after the name.

These two functions setError() and setWarning() can have a number of different returns. In addition to the type of message set, the return will also determine behavior. The following table explains the expected results of using either function and the return values. In the table, "not-false" means any return that is not Boolean false. False-ish values (0, empty string, etc.) do not count.

Function

Return

Result

setError()

false

setError()

not-false

setWarning()

false

setWarning()

not-false

setError() + setWarning()

false

setError() + setWarning()

not-false

What this means is that the return dictates whether the action passes (false: no, not-false: yes)and what dialog type Users get (false: error, not-false: warning). Messages just correspond to the type of return sent.

For all of the following examples, a Custom Validation was written to require a Reference on all Services.

Forms

 If a Custom Validation is triggered while using a given form, the message will appear in the following manner:

Imports

When a Custom Validation is triggered during an Import the message will be output into the Imported Records grid as an Error. The message content from the Error will appear in the 'Error Description' column of the grid.

To see the errors, navigate to Admin > Imports/ Exports : Import Files > Imported Records.

API

Custom Validations returned from the API will return a status of "failure" and the Customer Validation message.