Freeside:3:Documentation:Developer/FS/svc acct

From Freeside
< Freeside:3:Documentation:Developer‎ | FS
Revision as of 05:41, 10 February 2015 by Jeremyd (talk | contribs) (Edit via perl MediaWiki framework (1.13))

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

NAME

FS::svc_acct - Object methods for svc_acct records

SYNOPSIS

 use FS::svc_acct;

 $record = new FS::svc_acct \%hash;
 $record = new FS::svc_acct { 'column' => 'value' };

 $error = $record->insert;

 $error = $new_record->replace($old_record);

 $error = $record->delete;

 $error = $record->check;

 $error = $record->suspend;

 $error = $record->unsuspend;

 $error = $record->cancel;

 %hash = $record->radius;

 %hash = $record->radius_reply;

 %hash = $record->radius_check;

 $domain = $record->domain;

 $svc_domain = $record->svc_domain;

 $email = $record->email;

 $seconds_since = $record->seconds_since($timestamp);

DESCRIPTION

An FS::svc_acct object represents an account. FS::svc_acct inherits from FS::svc_Common. The following fields are currently supported:

svcnum
Primary key (assigned automatcially for new accounts)
username; _password
generated if blank
_password_encoding
plain, crypt, ldap (or empty for autodetection)
sec_phrase
security phrase
popnum
Point of presence (see FS::svc_acct_pop)
uid; gid; finger
GECOS
dir
set automatically if blank (and uid is not)
shell; quota; slipip
IP address
seconds; upbytes; downbyte; totalbytes; domsvc
svcnum from svc_domain
pbxsvc
Optional svcnum from svc_pbx
radius_Radius_Attribute
Radius-Attribute (reply)
rc_Radius_Attribute
Radius-Attribute (check)

METHODS

new HASHREF
Creates a new account. To add the account to the database, see "insert".
search_sql STRING
Class method which returns an SQL fragment to search for the given string.
label [ END_TIMESTAMP [ START_TIMESTAMP ] ]
Returns the "username@domain" string for this account.
END_TIMESTAMP and START_TIMESTAMP can optionally be passed when dealing with history records.
label_long [ END_TIMESTAMP [ START_TIMESTAMP ] ]
Returns a longer string label for this acccount ("Real Name <username@domain>" if available, or "username@domain").
END_TIMESTAMP and START_TIMESTAMP can optionally be passed when dealing with history records.
insert [ , OPTION => VALUE ... ]
Adds this account to the database. If there is an error, returns the error, otherwise returns false.
The additional fields pkgnum and svcpart (see FS::cust_svc) should be defined. An FS::cust_svc record will be created and inserted.
The additional field usergroup can optionally be defined; if so it should contain an arrayref of group names. See FS::radius_usergroup.
The additional field child_objects can optionally be defined; if so it should contain an arrayref of FS::tablename objects. They will have their svcnum fields set and will be inserted after this record, but before any exports are run. Each element of the array can also optionally be a two-element array reference containing the child object and the name of an alternate field to be filled in with the newly-inserted svcnum, for example [ $svc_forward, 'srcsvc' ]
Currently available options are: depend_jobnum
If depend_jobnum is set (to a scalar jobnum or an array reference of jobnums), all provisioning jobs will have a dependancy on the supplied jobnum(s) (they will not run until the specific job(s) complete(s)).
(TODOC: FS::queue and freeside-queued)
(TODOC: new exports!)
delete
Deletes this account from the database. If there is an error, returns the error, otherwise returns false.
The corresponding FS::cust_svc record will be deleted as well.
(TODOC: new exports!)
replace OLD_RECORD
Replaces OLD_RECORD with this one in the database. If there is an error, returns the error, otherwise returns false.
The additional field usergroup can optionally be defined; if so it should contain an arrayref of group names. See FS::radius_usergroup.
queue_fuzzyfiles_update
Used by insert & replace to update the fuzzy search cache
suspend
Suspends this account by calling export-specific suspend hooks. If there is an error, returns the error, otherwise returns false.
Called by the suspend method of FS::cust_pkg (see FS::cust_pkg).
unsuspend
Unsuspends this account by by calling export-specific suspend hooks. If there is an error, returns the error, otherwise returns false.
Called by the unsuspend method of FS::cust_pkg (see FS::cust_pkg).
cancel
Called by the cancel method of FS::cust_pkg (see FS::cust_pkg).
If the auto_unset_catchall configuration option is set, this method will automatically remove any references to the canceled service in the catchall field of svc_domain. This allows packages that contain both a svc_domain and its catchall svc_acct to be canceled in one step.
check
Checks all fields to make sure this is a valid service. If there is an error, returns the error, otherwise returns false. Called by the insert and replace methods.
Sets any fixed values; see FS::part_svc.
set_password
Set the cleartext password for the account. If _password_encoding is set, the new password will be encoded according to the existing method (including encryption mode, if it can be determined). Otherwise, config('default-password-encoding') is used.
If no password is supplied (or a zero-length password when minimum password length is >0), one will be generated randomly.
_check_system
Internal function to check the username against the list of system usernames from the system_usernames configuration value. Returns true if the username is listed on the system username list.
_check_duplicate
Internal method to check for duplicates usernames, username@domain pairs and uids.
If the global_unique-username configuration value is set to username or username@domain, enforces global username or username@domain uniqueness.
In all cases, check for duplicate uids and usernames or username@domain pairs per export and with identical svcpart values.
radius
Depriciated, use radius_reply instead.
radius_reply
Returns key/value pairs, suitable for assigning to a hash, for any RADIUS reply attributes of this record.
Note that this is now the preferred method for reading RADIUS attributes - accessing the columns directly is discouraged, as the column names are expected to change in the future.
radius_check
Returns key/value pairs, suitable for assigning to a hash, for any RADIUS check attributes of this record.
Note that this is now the preferred method for reading RADIUS attributes - accessing the columns directly is discouraged, as the column names are expected to change in the future.
radius_password
Returns a key/value pair containing the RADIUS attribute name and value for the password.
snapshot
This method instructs the object to "snapshot" or freeze RADIUS check and reply attributes to the current values.
forget_snapshot
This methos instructs the object to forget any previously snapshotted RADIUS check and reply attributes.
domain [ END_TIMESTAMP [ START_TIMESTAMP ] ]
Returns the domain associated with this account.
END_TIMESTAMP and START_TIMESTAMP can optionally be passed when dealing with history records.
cust_svc
Returns the FS::cust_svc record for this account (see FS::cust_svc).
email [ END_TIMESTAMP [ START_TIMESTAMP ] ]
Returns an email address associated with the account.
END_TIMESTAMP and START_TIMESTAMP can optionally be passed when dealing with history records.
acct_snarf
Returns an array of FS::acct_snarf records associated with the account.
cgp_rpop_hashref
Returns an arrayref of RPOP data suitable for Communigate Pro API commands.
decrement_upbytes OCTETS
Decrements the upbytes field of this record by the given amount. If there is an error, returns the error, otherwise returns false.
increment_upbytes OCTETS
Increments the upbytes field of this record by the given amount. If there is an error, returns the error, otherwise returns false.
decrement_downbytes OCTETS
Decrements the downbytes field of this record by the given amount. If there is an error, returns the error, otherwise returns false.
increment_downbytes OCTETS
Increments the downbytes field of this record by the given amount. If there is an error, returns the error, otherwise returns false.
decrement_totalbytes OCTETS
Decrements the totalbytes field of this record by the given amount. If there is an error, returns the error, otherwise returns false.
increment_totalbytes OCTETS
Increments the totalbytes field of this record by the given amount. If there is an error, returns the error, otherwise returns false.
decrement_seconds SECONDS
Decrements the seconds field of this record by the given amount. If there is an error, returns the error, otherwise returns false.
increment_seconds SECONDS
Increments the seconds field of this record by the given amount. If there is an error, returns the error, otherwise returns false.
recharge HASHREF
 Increments usage columns by the amount specified in HASHREF as
 column=>amount pairs.

is_rechargeable
Returns true if this svc_account can be "recharged" and false otherwise.
seconds_since TIMESTAMP
Returns the number of seconds this account has been online since TIMESTAMP, according to the session monitor (see FS::Session).
TIMESTAMP is specified as a UNIX timestamp; see "time" in perlfunc. Also see Time::Local and Date::Parse for conversion functions.
last_login_text
Returns text describing the time of last login.
psearch_cdrs OPTIONS
Returns a paged search (FS::PagedSearch) for Call Detail Records associated with this service. For svc_acct, "associated with" means that either the "src" or the "charged_party" field of the CDR matches the "username" field of the service.
get_cdrs (DEPRECATED)
Like psearch_cdrs, but returns all the FS::cdr objects at once, in a single list. Arguments are the same as for psearch_cdrs.
clone_suspended
Constructor used by FS::part_export::_export_suspend fallback. Document better.
clone_kludge_unsuspend
Constructor used by FS::part_export::_export_unsuspend fallback. Document better.
check_password
Checks the supplied password against the (possibly encrypted) password in the database. Returns true for a successful authentication, false for no match.
Currently supported encryptions are: classic DES crypt() and MD5
crypt_password [ DEFAULT_ENCRYPTION_TYPE ]
Returns an encrypted password, either by passing through an encrypted password in the database or by encrypting a plaintext password from the database.
The optional DEFAULT_ENCRYPTION_TYPE parameter can be set to crypt (classic UNIX DES crypt), md5 (md5 crypt supported by most modern Linux and BSD distrubtions), or (eventually) blowfish (blowfish hashing supported by OpenBSD, SuSE, other Linux distibutions with pam_unix2, etc.). The default encryption type is only used if the password is not already encrypted in the database.
ldap_password [ DEFAULT_ENCRYPTION_TYPE ]
Returns an encrypted password in "LDAP" format, with a curly-bracked prefix describing the format, for example, "{PLAIN}himom", "{CRYPT}94pAVyK/4oIBk" or "{MD5}5426824942db4253f87a1009fd5d2d4".
The optional DEFAULT_ENCRYPTION_TYPE is not yet used, but the idea is for it to work the same as the /crypt_password method.
domain_slash_username
Returns $domain/$username/
virtual_maildir
Returns $domain/maildirs/$username/

CLASS METHODS

search HASHREF
Class method which returns a qsearch hash expression to search for parameters specified in HASHREF. Valid parameters are
domain
; domsvc:; unlinked:; agentnum:; pkgpart
Arrayref of pkgparts
pkgpart
; where
Arrayref of additional WHERE clauses, will be ANDed together.
order_by
; cust_fields

SUBROUTINES

send_email
This is the FS::svc_acct job-queue-able version. It still uses FS::Misc::send_email under-the-hood.
check_and_rebuild_fuzzyfiles; rebuild_fuzzyfiles; all_username; append_fuzzyfiles USERNAME; reached_threshold
Performs some activities when svc_acct thresholds (such as number of seconds remaining) are reached.

BUGS

The $recref stuff in sub check should be cleaned up.

The suspend, unsuspend and cancel methods update the database, but not the current object. This is probably a bug as it's unexpected and counterintuitive.

insertion of RADIUS group stuff in insert could be done with child_objects now (would probably clean up export of them too)

_op_usage and set_usage bypass the history... maybe they shouldn't

SEE ALSO

FS::svc_Common, edit/part_svc.cgi from an installed web interface, export.html from the base documentation, FS::Record, FS::Conf, FS::cust_svc, FS::part_svc, FS::cust_pkg, FS::queue, freeside-queued), FS::svc_acct_pop, schema.html from the base documentation.