htdocs/docs/man/FS/cust_main.html

   1 <HTML>
   2 <HEAD>
   3 <TITLE>FS::cust_main - Object methods for cust_main records</TITLE>
   4 <LINK REV="made" HREF="mailto:perl@packages.debian.org">
   5 </HEAD>
   6
   7 <BODY>
   8
   9 <A NAME="__index__"></A>
  10 <!-- INDEX BEGIN -->
  11
  12 <UL>
  13
  14         <LI><A HREF="#name">NAME</A></LI>
  15         <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  16         <LI><A HREF="#description">DESCRIPTION</A></LI>
  17         <LI><A HREF="#methods">METHODS</A></LI>
  18         <LI><A HREF="#version">VERSION</A></LI>
  19         <LI><A HREF="#bugs">BUGS</A></LI>
  20         <LI><A HREF="#see also">SEE ALSO</A></LI>
  21 </UL>
  22 <!-- INDEX END -->
  23
  24 <HR>
  25 <P>
  26 <H1><A NAME="name">NAME</A></H1>
  27 <P>FS::cust_main - Object methods for cust_main records</P>
  28 <P>
  29 <HR>
  30 <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  31 <PRE>
  32   use FS::cust_main;</PRE>
  33 <PRE>
  34   $record = new FS::cust_main \%hash;
  35   $record = new FS::cust_main { 'column' =&gt; 'value' };</PRE>
  36 <PRE>
  37   $error = $record-&gt;insert;</PRE>
  38 <PRE>
  39   $error = $new_record-&gt;replace($old_record);</PRE>
  40 <PRE>
  41   $error = $record-&gt;delete;</PRE>
  42 <PRE>
  43   $error = $record-&gt;check;</PRE>
  44 <PRE>
  45   @cust_pkg = $record-&gt;all_pkgs;</PRE>
  46 <PRE>
  47   @cust_pkg = $record-&gt;ncancelled_pkgs;</PRE>
  48 <PRE>
  49   $error = $record-&gt;bill;
  50   $error = $record-&gt;bill %options;
  51   $error = $record-&gt;bill 'time' =&gt; $time;</PRE>
  52 <PRE>
  53   $error = $record-&gt;collect;
  54   $error = $record-&gt;collect %options;
  55   $error = $record-&gt;collect 'invoice_time'   =&gt; $time,
  56                             'batch_card'     =&gt; 'yes',
  57                             'report_badcard' =&gt; 'yes',
  58                           ;</PRE>
  59 <P>
  60 <HR>
  61 <H1><A NAME="description">DESCRIPTION</A></H1>
  62 <P>An FS::cust_main object represents a customer.  FS::cust_main inherits from
  63 FS::Record.  The following fields are currently supported:</P>
  64 <DL>
  65 <DT><STRONG><A NAME="item_key">custnum - primary key (assigned automatically for new customers)</A></STRONG><BR>
  66 <DD>
  67 <DT><STRONG><A NAME="item_agent">agentnum - agent (see <A HREF=".././FS/agent.html">the FS::agent manpage</A>)</A></STRONG><BR>
  68 <DD>
  69 <DT><STRONG><A NAME="item_referral">refnum - referral (see <A HREF=".././FS/part_referral.html">the FS::part_referral manpage</A>)</A></STRONG><BR>
  70 <DD>
  71 <DT><STRONG><A NAME="item_first_%2D_name">first - name</A></STRONG><BR>
  72 <DD>
  73 <DT><STRONG><A NAME="item_last_%2D_name">last - name</A></STRONG><BR>
  74 <DD>
  75 <DT><STRONG><A NAME="item_number">ss - social security number (optional)</A></STRONG><BR>
  76 <DD>
  77 <DT><STRONG><A NAME="item_company_%2D_%28optional%29">company - (optional)</A></STRONG><BR>
  78 <DD>
  79 <DT><STRONG><A NAME="item_address1">address1</A></STRONG><BR>
  80 <DD>
  81 <DT><STRONG><A NAME="item_address2_%2D_%28optional%29">address2 - (optional)</A></STRONG><BR>
  82 <DD>
  83 <DT><STRONG><A NAME="item_city">city</A></STRONG><BR>
  84 <DD>
  85 <DT><STRONG><A NAME="item_county_%2D_%28optional%2C_see_FS%3A%3Acust_main_co">county - (optional, see <A HREF=".././FS/cust_main_county.html">the FS::cust_main_county manpage</A>)</A></STRONG><BR>
  86 <DD>
  87 <DT><STRONG><A NAME="item_state_%2D_%28see_FS%3A%3Acust_main_county%29">state - (see <A HREF=".././FS/cust_main_county.html">the FS::cust_main_county manpage</A>)</A></STRONG><BR>
  88 <DD>
  89 <DT><STRONG><A NAME="item_zip">zip</A></STRONG><BR>
  90 <DD>
  91 <DT><STRONG><A NAME="item_country_%2D_%28see_FS%3A%3Acust_main_county%29">country - (see <A HREF=".././FS/cust_main_county.html">the FS::cust_main_county manpage</A>)</A></STRONG><BR>
  92 <DD>
  93 <DT><STRONG><A NAME="item_phone">daytime - phone (optional)</A></STRONG><BR>
  94 <DD>
  95 <DT><STRONG>night - phone (optional)</STRONG><BR>
  96 <DD>
  97 <DT><STRONG>fax - phone (optional)</STRONG><BR>
  98 <DD>
  99 <DT><STRONG><A NAME="item_payby_%2D_%60CARD%27_%28credit_cards%29%2C_%60BILL">payby - `CARD' (credit cards), `BILL' (billing), `COMP' (free), or `PREPAY' (special billing type: applies a credit - see <A HREF=".././FS/prepay_credit.html">the FS::prepay_credit manpage</A> and sets billing type to BILL)</A></STRONG><BR>
 100 <DD>
 101 <DT><STRONG><A NAME="item_issuer">payinfo - card number, P.O., comp issuer (4-8 lowercase alphanumerics; think username) or prepayment identifier (see <A HREF=".././FS/prepay_credit.html">the FS::prepay_credit manpage</A>)</A></STRONG><BR>
 102 <DD>
 103 <DT><STRONG><A NAME="item_paydate_%2D_expiration_date%2C_mm%2Fyyyy%2C_m%2Fyy">paydate - expiration date, mm/yyyy, m/yyyy, mm/yy or m/yy</A></STRONG><BR>
 104 <DD>
 105 <DT><STRONG><A NAME="item_payname_%2D_name_on_card_or_billing_name">payname - name on card or billing name</A></STRONG><BR>
 106 <DD>
 107 <DT><STRONG><A NAME="item_tax_%2D_tax_exempt%2C_empty_or_%60Y%27">tax - tax exempt, empty or `Y'</A></STRONG><BR>
 108 <DD>
 109 <DT><STRONG><A NAME="item_taker">otaker - order taker (assigned automatically, see <A HREF=".././FS/UID.html">the FS::UID manpage</A>)</A></STRONG><BR>
 110 <DD>
 111 </DL>
 112 <P>
 113 <HR>
 114 <H1><A NAME="methods">METHODS</A></H1>
 115 <DL>
 116 <DT><STRONG><A NAME="item_new">new HASHREF</A></STRONG><BR>
 117 <DD>
 118 Creates a new customer.  To add the customer to the database, see <A HREF="#insert">insert</A>.
 119 <P>Note that this stores the hash reference, not a distinct copy of the hash it
 120 points to.  You can ask the object for a copy with the <EM>hash</EM> method.</P>
 121 <P></P>
 122 <DT><STRONG><A NAME="item_insert">insert</A></STRONG><BR>
 123 <DD>
 124 Adds this customer to the database.  If there is an error, returns the error,
 125 otherwise returns false.
 126 <P>There is a special insert mode in which you pass a data structure to the insert
 127 method containing FS::cust_pkg and FS::svc_<EM>tablename</EM> objects.  When
 128 running under a transactional database, all records are inserted atomicly, or
 129 the transaction is rolled back.  There should be a better explanation of this,
 130 but until then, here's an example:</P>
 131 <PRE>
 132   use Tie::RefHash;
 133   tie %hash, 'Tie::RefHash'; #this part is important
 134   %hash = {
 135     $cust_pkg =&gt; [ $svc_acct ],
 136   };
 137   $cust_main-&gt;insert( \%hash );</PRE>
 138 <P></P>
 139 <DT><STRONG><A NAME="item_delete_NEW_CUSTNUM">delete NEW_CUSTNUM</A></STRONG><BR>
 140 <DD>
 141 This deletes the customer.  If there is an error, returns the error, otherwise
 142 returns false.
 143 <P>This will completely remove all traces of the customer record.  This is not
 144 what you want when a customer cancels service; for that, cancel all of the
 145 customer's packages (see <A HREF=".././FS/cust_pkg.html#cancel">cancel in the FS::cust_pkg manpage</A>).</P>
 146 <P>If the customer has any packages, you need to pass a new (valid) customer
 147 number for those packages to be transferred to.</P>
 148 <P>You can't delete a customer with invoices (see <A HREF=".././FS/cust_bill.html">the FS::cust_bill manpage</A>),
 149 or credits (see <A HREF=".././FS/cust_credit.html">the FS::cust_credit manpage</A>).</P>
 150 <P></P>
 151 <DT><STRONG><A NAME="item_replace_OLD_RECORD">replace OLD_RECORD</A></STRONG><BR>
 152 <DD>
 153 Replaces the OLD_RECORD with this one in the database.  If there is an error,
 154 returns the error, otherwise returns false.
 155 <P></P>
 156 <DT><STRONG><A NAME="item_check">check</A></STRONG><BR>
 157 <DD>
 158 Checks all fields to make sure this is a valid customer record.  If there is
 159 an error, returns the error, otherwise returns false.  Called by the insert
 160 and repalce methods.
 161 <P></P>
 162 <DT><STRONG><A NAME="item_all_pkgs">all_pkgs</A></STRONG><BR>
 163 <DD>
 164 Returns all packages (see <A HREF=".././FS/cust_pkg.html">the FS::cust_pkg manpage</A>) for this customer.
 165 <P></P>
 166 <DT><STRONG><A NAME="item_ncancelled_pkgs">ncancelled_pkgs</A></STRONG><BR>
 167 <DD>
 168 Returns all non-cancelled packages (see <A HREF=".././FS/cust_pkg.html">the FS::cust_pkg manpage</A>) for this customer.
 169 <P></P>
 170 <DT><STRONG><A NAME="item_bill">bill OPTIONS</A></STRONG><BR>
 171 <DD>
 172 Generates invoices (see <A HREF=".././FS/cust_bill.html">the FS::cust_bill manpage</A>) for this customer.  Usually used in
 173 conjunction with the collect method.
 174 <P>The only currently available option is `time', which bills the customer as if
 175 it were that time.  It is specified as a UNIX timestamp; see
 176 <EM>perlfunc/``time''</EM>).  Also see <A HREF="../Time/Local.html">the Time::Local manpage</A> and <A HREF="../Date/Parse.html">the Date::Parse manpage</A> for conversion
 177 functions.</P>
 178 <P>If there is an error, returns the error, otherwise returns false.</P>
 179 <P></P>
 180 <DT><STRONG><A NAME="item_collect">collect OPTIONS</A></STRONG><BR>
 181 <DD>
 182 (Attempt to) collect money for this customer's outstanding invoices (see
 183 <A HREF=".././FS/cust_bill.html">the FS::cust_bill manpage</A>).  Usually used after the bill method.
 184 <P>Depending on the value of `payby', this may print an invoice (`BILL'), charge
 185 a credit card (`CARD'), or just add any necessary (pseudo-)payment (`COMP').</P>
 186 <P>If there is an error, returns the error, otherwise returns false.</P>
 187 <P>Currently available options are:</P>
 188 <P>invoice_time - Use this time when deciding when to print invoices and
 189 late notices on those invoices.  The default is now.  It is specified as a UNIX timestamp; see <EM>perlfunc/``time''</EM>).  Also see <A HREF="../Time/Local.html">the Time::Local manpage</A> and <A HREF="../Date/Parse.html">the Date::Parse manpage</A>
 190 for conversion functions.</P>
 191 <P>batch_card - Set this true to batch cards (see <A HREF=".././FS/cust_pay_batch.html">the cust_pay_batch manpage</A>).  By
 192 default, cards are processed immediately, which will generate an error if
 193 CyberCash is not installed.</P>
 194 <P>report_badcard - Set this true if you want bad card transactions to
 195 return an error.  By default, they don't.</P>
 196 <P></P>
 197 <DT><STRONG><A NAME="item_total_owed">total_owed</A></STRONG><BR>
 198 <DD>
 199 Returns the total owed for this customer on all invoices
 200 (see <A HREF=".././FS/cust_bill.html">the FS::cust_bill manpage</A>).
 201 <P></P>
 202 <DT><STRONG><A NAME="item_total_credited">total_credited</A></STRONG><BR>
 203 <DD>
 204 Returns the total credits (see <A HREF=".././FS/cust_credit.html">the FS::cust_credit manpage</A>) for this customer.
 205 <P></P>
 206 <DT><STRONG><A NAME="item_balance">balance</A></STRONG><BR>
 207 <DD>
 208 Returns the balance for this customer (total owed minus total credited).
 209 <P></P>
 210 <DT><STRONG><A NAME="item_invoicing_list_%5B_ARRAYREF_%5D">invoicing_list [ ARRAYREF ]</A></STRONG><BR>
 211 <DD>
 212 If an arguement is given, sets these email addresses as invoice recipients
 213 (see <A HREF=".././FS/cust_main_invoice.html">the FS::cust_main_invoice manpage</A>).  Errors are not fatal and are not reported
 214 (except as warnings), so use check_invoicing_list first.
 215 <P>Returns a list of email addresses (with svcnum entries expanded).</P>
 216 <P>Note: You can clear the invoicing list by passing an empty ARRAYREF.  You can
 217 check it without disturbing anything by passing nothing.</P>
 218 <P>This interface may change in the future.</P>
 219 <P></P>
 220 <DT><STRONG><A NAME="item_check_invoicing_list_ARRAYREF">check_invoicing_list ARRAYREF</A></STRONG><BR>
 221 <DD>
 222 Checks these arguements as valid input for the invoicing_list method.  If there
 223 is an error, returns the error, otherwise returns false.
 224 <P></P></DL>
 225 <P>
 226 <HR>
 227 <H1><A NAME="version">VERSION</A></H1>
 228 <P>$Id: cust_main.html,v 1.3 2001-04-23 12:40:31 ivan Exp $</P>
 229 <P>
 230 <HR>
 231 <H1><A NAME="bugs">BUGS</A></H1>
 232 <P>The delete method.</P>
 233 <P>The delete method should possibly take an FS::cust_main object reference
 234 instead of a scalar customer number.</P>
 235 <P>Bill and collect options should probably be passed as references instead of a
 236 list.</P>
 237 <P>CyberCash v2 forces us to define some variables in package main.</P>
 238 <P>There should probably be a configuration file with a list of allowed credit
 239 card types.</P>
 240 <P>CyberCash is the only processor.</P>
 241 <P>No multiple currency support (probably a larger project than just this module).</P>
 242 <P>
 243 <HR>
 244 <H1><A NAME="see also">SEE ALSO</A></H1>
 245 <P><A HREF=".././FS/Record.html">the FS::Record manpage</A>, <A HREF=".././FS/cust_pkg.html">the FS::cust_pkg manpage</A>, <A HREF=".././FS/cust_bill.html">the FS::cust_bill manpage</A>, <A HREF=".././FS/cust_credit.html">the FS::cust_credit manpage</A>
 246 <A HREF=".././FS/cust_pay_batch.html">the FS::cust_pay_batch manpage</A>, <A HREF=".././FS/agent.html">the FS::agent manpage</A>, <A HREF=".././FS/part_referral.html">the FS::part_referral manpage</A>,
 247 <A HREF=".././FS/cust_main_county.html">the FS::cust_main_county manpage</A>, <A HREF=".././FS/cust_main_invoice.html">the FS::cust_main_invoice manpage</A>,
 248 <A HREF=".././FS/UID.html">the FS::UID manpage</A>, schema.html from the base documentation.</P>
 249
 250 </BODY>
 251
 252 </HTML>