NAME
Business::ISP::User - Perl module for ISP user operations.
SYNOPSIS
# Initialize and populate a new Business::ISP::User
use Business::ISP::User;
my $user = Business::ISP::User->new({ username => 'username' });DESCRIPTION
This module is used for all client information gathering, manipulation and storage functions within the Business::ISP:: collection of modules, and the ISP accounting system.
METHODS
new ({ username => USERNAME })
Instantiates a new Business::ISP::User object.
The optional parameter USERNAME is a scalar string, and is passed in within a hash reference. If present, will attempt to configure itself with the user's information.
If USERNAME is not specified, a new generic, unconfigured user object will be returned.
Calling new() without any parameters is useful for generating an empty object that can access class methods through itself.
build_db_user ( USERNAME )
Retrieves all user information from the MySQL database, and configures the object.
Should really only be called by new().
The mandatory parameter USERNAME is a scalar string.
Returns undef upon failure, and 0 upon success.
client_info ({ client_info => CLIENT_INFO })
Sets and gets the client's personal information.
CLIENT_INFO is an optional parameter, and if present, will update the client's information with the data set in The user object itself will be updated.
The format of the data is that of the 'user_info' hashref as documented in Business::ISP::Vars. This parameter must be passed in within a hash reference.
If the parameter is not passed in, a hash reference of the current user's info is returned.
If the parameter is passed in, this method will die() via Business::ISP::Sanity if the param contains illicit data. Otherwise, the return will be success (0).
add_client ({ error => $error, client_info => CLIENT_INFO })
Adds a new client to the database.
There are two mandatory params, passed in within a hash reference.
error is an Business::ISP::Error object. CLIENT_INFO is a hash reference type as defined in Business::ISP::Vars.
Returns the Business::ISP::Error object upon Sanity failure, or if trying to create a client who has the same username as someone else.
Returns 0 upon success.
delete_client({ username => USERNAME })
Deletes a client record.
USERNAME is a mandatory parameter, passed in within a hash reference.
Returns 1 upon success, and 0 if the user could not be found/deleted.
add_plan ({ plan_info => PLAN_INFO, error => ERROR , start_date => DATE })
Adds a new account plan for the pre-configured user object that calls us.
PLAN_INFO and ERROR are both mandatory parameters, ERROR is an Business::ISP::Error.
DATE is an optional parameter, and must be in the form YYYY-MM-DD. This param is primarily only used with the Conversion utility. It sets the plan start date to DATE, as opposed to using today's date.
All params must be passed in within a hash reference.
See the plans.sql schema file for a description of PLAN_INFO.
Returns 0 upon success, and ERROR upon failure.
_init_plans
This method is called internally to configure the object with it's account plans.
Takes no parameters, returns 0 upon success.
username_to_login( PLAN, USERNAME )
Used only by functions that need to find RADIUS database information. It converts the account username to the specific plan login_name to perform the search.
PLAN is a hashref containing the user plan in question. USERNAME is a scalar string containing the overall account username. Both parameters are mandatory.
Returns the username as a scalar.
get_plans
Retrieves a list of all the current user object's plans. It first re-initializes the plans, in case they have changed since last access.
Takes no parameters.
Returns an array where each element is a hashref containing the key, value pairs for each plan.
If the user has no existing account plans, returns an empty array.
get_plan_ids
Takes no parameters.
Returns an array containing the current users plan ids.
get_plan ( ID )
Retrieves the data associated with an individual plan.
ID is (should be) a mandatory scalar integer parameter which represents the id number of the plan. However, if called with no parameters, will return the id of the very last plan created. Useful for testing.
Returns a hashref of the indivitual plan data if the plan exists, else returns undef.
get_plan_status( ID )
ID is a mandatory integer value representing a user plan.
Returns a string representing the status of the account plan, as either 'active' or 'hold'.
Returns undef if no plan is found by ID.
change_plan_status({ plan_id => ID, operator => OP, error => ERROR })
Modifies the active/non-active status of a users account plan.
All three parameters are mandatory, and are passed in within a hash reference.
OP is the name of the operator performing the task. ID is the id of the plan itself, and ERROR is an Business::ISP::Error object.
plan_password({ plan_id => ID, new_password => PASSWD })
Parameters are passed in within a hash reference.
ID is a mandatory integer representing the plan to take action on.
PASSWD is a string scalar.
If PASSWD is omitted, the existing account plan password is returned.
If PASSWD is supplied, the plan referenced by ID will have the password changed.
Returns the password.
delete_plan ( ID, OPERATOR )
Deletes an individual client account plan.
ID is a mandatory scalar integer that represents the plan id in the database.
OPERATOR is an optional parameter that will be used as the operator name for the notes.
Returns 1 if the ID parameter is not passed in, or if the plan by that id does not exist. Returns 0 upon success.
plan_hours ({ id => ID, quantity => QTY, error => ERROR })
Used to add or subtract to the number of hours remaining in a client's account plan, if the plan is PlanA.
All three parameters are mandatory, and are passed in within a hash reference.
Supply a negative integer as QTY to subtract from the total, or 0 to simply return the current balance of hours. ERROR is Business::ISP::Error object.
An Business::ISP::Error will be returned immediately if the plan 'id' is invalid.
Returns 1 on failure, and returns the updated number of hours remaining in the client account plan upon success.
NOTE: the hours balance will be negative if the balance is in the client's favour!!
modify_plan_expiry ({ id => ID, quantity => QTY, error => ERROR })
Performs the same function as plan_hours(), but operates on the expiry date for plans that are not based on hours.
It takes the same parameters as plan_hours(), however, in this case, QTY represents the number of months to add/remove from the existing expiry date.
Upon failure, returns are identical to plan_hours(), but on success, returns the new expiry date in YYYY-MM-DD format.
An Business::ISP::Error object will be returned immediately if the plan 'id' is invalid.
plana_deduction({ error => ERROR, month => MONTH })
This method is responsible for maintaining the remaining hours that a PlanA user has remaining, by deducting the used hours from the previous month.
If 'plana_deduct_enable' is set to true in the configuration file, any user who didn't use up to their minimum hours (plana_min_hours in the config file) will have that time deducted as well.
The ERROR paramater is mandatory, and is an Business::ISP::Error object.
MONTH is a scalar string in the format YYYY-MM. If it is provided, the month specified will be operated on, as opposed to the default of last month.
Returns an array reference that contains a hashref of the results as its first parameter, and if there were errors, the error object will be pushed onto the returned arrayref.
Note that only the problematic PlanA users will be skipped, the valid ones will all be processed.
add_notes({ operator => OP, note => NOTE, tag => TAG, date => DATE })
This method adds notes/tickets for the client.
All parameters are passed in within a hash reference.
NOTE is a mandatory parameter as a scalar blob of text.
OP is optional, and specifies the name of the operator making the call.
TAG is optional, and is used for classification purposes.
DATE is optional, and must be passed in as 'YYYY-MM-DD HH:MM:SS' if present.
Returns 1 if the mandatory note parameter is not present.
Returns 0 upon completion and success.
get_notes({ id => NOTE_ID });
Retrieves the notes associated with the client account.
Returns an array reference if called without any parameters. Each element in the array reference is a hash reference containing the note information. The fields in each note are: id, note, operator, tag, date, username.
If called with the scalar string NOTE_ID (which is the id of the record in the database), get_notes() will return a hashref of the single note requested.
The parameters are to be passed in as a hash reference.
Returns undef if notes don't exist for the client.
delete_notes ({ id => ID })
Deletes an individual note from a client account.
ID is a mandatory scalar integer that represents the plan id in the database, and must be passed in within a hash reference.
Returns 1 if the ID parameter is not passed in. Returns 0 upon success.
write_plan_changes({ id => ID, plan => PLAN, change => CHANGE, error => ERROR })
Updates a client's plan in the database.
Takes four mandatory params within a hash reference:
ID is the id of the plan to change. PLAN is the plan information that include the desired changes. ERROR is an Business::ISP::Error object.
CHANGE is the plan item(s) that are to be updated. If a scalar value is passed in, only that item will be changed. If CHANGE is passed in as an array reference, all of the items within the array will be updated.
Returns 0 on success, or dies with a DBI::Errstr upon failure.
get_client_list
Call this when you want to retrieve a list of all existing client usernames.
It can be used as the iterator for get_plans().
Takes no parameters, returns an array in which each element is a unique client username (upon success).
plan_members( { plan_name => PLAN, status => STATUS, return_id => BOOL } )
Fetches a list of usernames (or plan ids) that belong to a specified plan type.
PLAN is a scalar of one of the defined account plan names (eg plana). This parameter is mandatory.
STATUS is a scalar that represents the status of the account (eg. active, delete, onhold etc). This parameter is optional. If it is not supplied, 'active' will be the default.
The 'return_id' parameter is optional. If set to true a true value, then the return will be an array reference of the plan ids that match the value in the plan_name parameter.
The parameters must be passed in within a hash reference.
Returns an array reference that contains the list of usernames if return_id is either not present, or set to a false value.
get_monthly_login_totals( { plan => PLAN } )
Gathers up the client's monthly login information ( bandwidth up/down/, time duration ).
PLAN is the hashref representing the user's plan that you want to operate on.
Business::ISP::RADIUS is a prerequisite for using this method.
Returns an array reference of hash references.
See Business::ISP::RADIUS::monthly_login_totals() for further details.
get_month_hours_used({ plan => PLAN, month => MONTH })
Returns the total number of hours used for a month.
PLAN is the hashref of the plan to retrieve stats for, as retrieved by get_plan().
The default is to operate on the current month's data.
MONTH is a month in the format YYYY-MM. This will override the default with the month you specify.
The parameters must be passed in within a hashref.
See Business::ISP::RADIUS::month_hours_used() for further details.
plan_classification({ plan => PLAN })
PLAN is the user account plan hashref, after being retrieved via get_plan(). The parameters are passed in within a hash reference.
Returns the class that the plan name belongs to.
last_plan_update( ID )
This method is used to update the last_update field in a users plan when a change to the plan occurs.
ID is the scalar integer of the plan to update.
Returns 0 upon success, and undef upon failure.
radius_password ({ password => PASSWD })
Returns the current user object's RADIUS password.
If the optional param PASSWD is passed in, the password will be updated prior to being returned. The parameter is passed in within a hash reference.
Returns undef if a password is not found.
AUTHOR
Steve Bertrand, steveb@cpan.org
SEE ALSO
perl(1).