Business::ISP::Sanity - Perl module for Business::ISP:: programs. This module is used to perform validation, verification, authentication and other sanitization checks on data that is input from other modules, or directly from applications.
use Business::ISP::Sanity; # Initialize a Sanity object, and pull in config if # available my $sanity_check = Business::ISP::Sanity->new();
This module is an intermediary sanity checker, which compares attempted input data against pre-programmed data standards. This module will fail-safe (ie. we let Error die()) if any input data fails against the pre-programmed patterns.
This module generally sits somewhere between the user application, and the modules that perform any write operations. We will work hard to ensure that all data is passed through this module in the future, no matter what it is.
Business::ISP::Sanity uses the Business::ISP::Error object heavily to relay error notification, error messages and error traces back to the caller.
This module is relatively generic, and can be adapted with new APIs, even if the new callers are not related to the accounting system.
Initializes a new Business::ISP::Sanity object, and if available, will configure itself from the ISP.conf configuration file.
This method is inhereted from the base class.
This method is responsible for keeping track of accounting operations that can only be run once per a given cycle.
For example, if a database write operation is to happen automatically once per month, this method will log an entry each time it is run. If an attempt is made to run the operation again within the same month, we won't allow it.
All parameters are passed in within a hash reference.
We will identify which process we need to work on by the function name of the caller.
'complete' informs the audit that the operation just completed, and the timestamp needs to be logged. This parameter should only be passed in from the operation after the run is complete. Always send this parameter with the value 1.
'operator' is a string that contains the name of the operator who ran the operation. It defaults to 'system'.
'runtype' is a string specifying whether this is a manual or automatic run. Values are 'auto' and 'manual'. Defaults to 'auto' if not passed in.
'check' performs a simple check whether a process has run. This is for statistics, and should not be called by any automated processes.
Called without 'complete', the return will be 0 if the operation has not run during this run cycle, and if it has, will die via Business::ISP::Error.
Called with 'complete', the return will be 1 if the cycle finished and the audit entry was successfully saved. Will die with an Business::ISP::Error otherwise.
Validates a data structure as defined in Business::ISP::Vars.
TYPE is a scalar string name of the defined type to validate. DATA is the actual data of the type TYPE. ERROR is an Business::ISP::Error object. All parameters are passed in within a hash reference.
Checks include:
- the type is actually a defined type - the type has the correct structure - the type contains all of the proper properties - the properties of the type contains values within the guidelines
The value check can be bypassed by setting 'sanity_value_skip_permitted' to a true value in the configuration file.
The program will die if any of the following are encountered:
- an ERROR is not passed in - the type is not defined - the type has too many properties - the type does not contain all defined properties
If the type is correct thus far but it has invalid values for its properties, the Business::ISP::Error will be returned.
If all checks pass, the return is 1.
Validates the value of a pre-defined element. This method is primarily called by validate_data(), but this is not enforced.
TAG is the name of the property being validated. VALUE is the TAG value. ERROR is an Business::ISP::Error object. All parameters are passed in as a hash reference.
Setting VALIDATE_VALUE_DEBUG will have this method perform diagnostic printing to STDOUT. Setting VALIDATE_VALUE_TRACE allows the profiler to track calls.
Returns:
- die() if an ERROR is not passed in - die() if TAG does not have an Business::ISP::Sanity check internally - returns ERROR if VALIDATE_VALUE_TRACE is enabled, and an error has been flagged - otherwise, returns 1
This method is specifically used when a transaction is a payment. It confirms that the figures are inline with that of a payment.
TRANSAC is an Business::ISP::Transac object that has already been validated against Business::ISP::Sanity::validate_data(). ERROR is an Business::ISP::Error object. The parameters are passed in within a hash reference.
die()s if an ERROR is not passed in.
Returns 0 upon completion. It is up to the caller to handle error conditions. See perldoc Business::ISP::Error.
This method is specifically used when a transaction is a renewal. It confirms that the figures are inline with that of a renewal.
ID is the id of the Business::ISP::User account plan being renewed. QTY is an integer of the number of months/hours for the renewal. AMT is either a two decimal float or an integer that represents the dollar value of each QTY. ERROR is an Business::ISP::Error object. These parameters are passed in as a hash reference.
Either die()s or returns ERROR depending on the severity of any issues. Returns 0 upon success.
Replaces the 'is_word()' function that I hacked into Data::Types. It is used to validate strings to ensure they do not contain invalid, illegal or potential control characters.
Valid characters are: a-zA-Z_ and whitespace.
Takes a single scalar string as the only mandatory parameter. Returns the first invalid character in the string.
Although this is advertised as a public method, it's primary purpose is for use internally within Business::ISP::Sanity.
This is a wrapper for data that needs to be passed to Business::ISP::Var::compare().
TYPE is a mandatory scalar string specifying the Business::ISP::Vars type we need to check, and DATA is a mandatory hashref pointing to the data structure specified by TYPE. ERROR is an Business::ISP::Error object. Parameters are passed within a hash reference.
Returns true on success, executes and dies with Business::ISP::Error->bad_data() on failure.
For auditing, verifies whether the process is a legitimate one.
PROCESS is a string that contains the name of the process we are trying to validate.
Returns either true or false depending on whether the process is legitimate.
Check to see if a table exists in the database.
ERROR is a mandatory Business::ISP::Error object parameter, and TABLE is a mandatory string scalar of the table you want to verify whether it exists.
Returns 0, sets $error->exists() if the table doesn't exist
This method is also primarly for use internally, but it can and does have limited functionality outside of the Business::ISP::Sanity package scope.
Call this method to retrieve the dispatch table that maps individual type property (tag) components to their respective sanity check subroutine.
Returns a hash containing the complete mapping.
Steve Bertrand, <steveb at cpan.org>
<steveb at cpan.org>
Please report any bugs or feature requests to devel at ibctech.ca. I will be notified, and you will receive a response when the bug is fixed.
devel at ibctech.ca
You can find documentation for this module with the perldoc command.
perldoc Business::ISP::Sanity
Copyright 2012 Steve Bertrand, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Business::ISP::ISP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Business::ISP::ISP
CPAN shell
perl -MCPAN -e shell install Business::ISP::ISP
For more information on module installation, please visit the detailed CPAN module installation guide.