httemplate/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_ship_first_%2D_name">ship_first - name</A></STRONG><BR>
 100 <DD>
 101 <DT><STRONG><A NAME="item_ship_last_%2D_name">ship_last - name</A></STRONG><BR>
 102 <DD>
 103 <DT><STRONG><A NAME="item_ship_company_%2D_%28optional%29">ship_company - (optional)</A></STRONG><BR>
 104 <DD>
 105 <DT><STRONG><A NAME="item_ship_address1">ship_address1</A></STRONG><BR>
 106 <DD>
 107 <DT><STRONG><A NAME="item_ship_address2_%2D_%28optional%29">ship_address2 - (optional)</A></STRONG><BR>
 108 <DD>
 109 <DT><STRONG><A NAME="item_ship_city">ship_city</A></STRONG><BR>
 110 <DD>
 111 <DT><STRONG><A NAME="item_ship_county_%2D_%28optional%2C_see_FS%3A%3Acust_ma">ship_county - (optional, see <A HREF=".././FS/cust_main_county.html">the FS::cust_main_county manpage</A>)</A></STRONG><BR>
 112 <DD>
 113 <DT><STRONG><A NAME="item_ship_state_%2D_%28see_FS%3A%3Acust_main_county%29">ship_state - (see <A HREF=".././FS/cust_main_county.html">the FS::cust_main_county manpage</A>)</A></STRONG><BR>
 114 <DD>
 115 <DT><STRONG><A NAME="item_ship_zip">ship_zip</A></STRONG><BR>
 116 <DD>
 117 <DT><STRONG><A NAME="item_ship_country_%2D_%28see_FS%3A%3Acust_main_county%2">ship_country - (see <A HREF=".././FS/cust_main_county.html">the FS::cust_main_county manpage</A>)</A></STRONG><BR>
 118 <DD>
 119 <DT><STRONG>ship_daytime - phone (optional)</STRONG><BR>
 120 <DD>
 121 <DT><STRONG>ship_night - phone (optional)</STRONG><BR>
 122 <DD>
 123 <DT><STRONG>ship_fax - phone (optional)</STRONG><BR>
 124 <DD>
 125 <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>
 126 <DD>
 127 <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>
 128 <DD>
 129 <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>
 130 <DD>
 131 <DT><STRONG><A NAME="item_payname_%2D_name_on_card_or_billing_name">payname - name on card or billing name</A></STRONG><BR>
 132 <DD>
 133 <DT><STRONG><A NAME="item_tax_%2D_tax_exempt%2C_empty_or_%60Y%27">tax - tax exempt, empty or `Y'</A></STRONG><BR>
 134 <DD>
 135 <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>
 136 <DD>
 137 </DL>
 138 <P>
 139 <HR>
 140 <H1><A NAME="methods">METHODS</A></H1>
 141 <DL>
 142 <DT><STRONG><A NAME="item_new">new HASHREF</A></STRONG><BR>
 143 <DD>
 144 Creates a new customer.  To add the customer to the database, see <A HREF="#insert">insert</A>.
 145 <P>Note that this stores the hash reference, not a distinct copy of the hash it
 146 points to.  You can ask the object for a copy with the <EM>hash</EM> method.</P>
 147 <P></P>
 148 <DT><STRONG><A NAME="item_insert">insert</A></STRONG><BR>
 149 <DD>
 150 Adds this customer to the database.  If there is an error, returns the error,
 151 otherwise returns false.
 152 <P>There is a special insert mode in which you pass a data structure to the insert
 153 method containing FS::cust_pkg and FS::svc_<EM>tablename</EM> objects.  When
 154 running under a transactional database, all records are inserted atomicly, or
 155 the transaction is rolled back.  There should be a better explanation of this,
 156 but until then, here's an example:</P>
 157 <PRE>
 158   use Tie::RefHash;
 159   tie %hash, 'Tie::RefHash'; #this part is important
 160   %hash = (
 161     $cust_pkg =&gt; [ $svc_acct ],
 162     ...
 163   );
 164   $cust_main-&gt;insert( \%hash );</PRE>
 165 <P></P>
 166 <DT><STRONG><A NAME="item_delete_NEW_CUSTNUM">delete NEW_CUSTNUM</A></STRONG><BR>
 167 <DD>
 168 This deletes the customer.  If there is an error, returns the error, otherwise
 169 returns false.
 170 <P>This will completely remove all traces of the customer record.  This is not
 171 what you want when a customer cancels service; for that, cancel all of the
 172 customer's packages (see <A HREF=".././FS/cust_pkg.html#cancel">cancel in the FS::cust_pkg manpage</A>).</P>
 173 <P>If the customer has any packages, you need to pass a new (valid) customer
 174 number for those packages to be transferred to.</P>
 175 <P>You can't delete a customer with invoices (see <A HREF=".././FS/cust_bill.html">the FS::cust_bill manpage</A>),
 176 or credits (see <A HREF=".././FS/cust_credit.html">the FS::cust_credit manpage</A>).</P>
 177 <P></P>
 178 <DT><STRONG><A NAME="item_replace_OLD_RECORD">replace OLD_RECORD</A></STRONG><BR>
 179 <DD>
 180 Replaces the OLD_RECORD with this one in the database.  If there is an error,
 181 returns the error, otherwise returns false.
 182 <P></P>
 183 <DT><STRONG><A NAME="item_check">check</A></STRONG><BR>
 184 <DD>
 185 Checks all fields to make sure this is a valid customer record.  If there is
 186 an error, returns the error, otherwise returns false.  Called by the insert
 187 and repalce methods.
 188 <P></P>
 189 <DT><STRONG><A NAME="item_all_pkgs">all_pkgs</A></STRONG><BR>
 190 <DD>
 191 Returns all packages (see <A HREF=".././FS/cust_pkg.html">the FS::cust_pkg manpage</A>) for this customer.
 192 <P></P>
 193 <DT><STRONG><A NAME="item_ncancelled_pkgs">ncancelled_pkgs</A></STRONG><BR>
 194 <DD>
 195 Returns all non-cancelled packages (see <A HREF=".././FS/cust_pkg.html">the FS::cust_pkg manpage</A>) for this customer.
 196 <P></P>
 197 <DT><STRONG><A NAME="item_bill">bill OPTIONS</A></STRONG><BR>
 198 <DD>
 199 Generates invoices (see <A HREF=".././FS/cust_bill.html">the FS::cust_bill manpage</A>) for this customer.  Usually used in
 200 conjunction with the collect method.
 201 <P>The only currently available option is `time', which bills the customer as if
 202 it were that time.  It is specified as a UNIX timestamp; see
 203 <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
 204 functions.</P>
 205 <P>If there is an error, returns the error, otherwise returns false.</P>
 206 <P></P>
 207 <DT><STRONG><A NAME="item_collect">collect OPTIONS</A></STRONG><BR>
 208 <DD>
 209 (Attempt to) collect money for this customer's outstanding invoices (see
 210 <A HREF=".././FS/cust_bill.html">the FS::cust_bill manpage</A>).  Usually used after the bill method.
 211 <P>Depending on the value of `payby', this may print an invoice (`BILL'), charge
 212 a credit card (`CARD'), or just add any necessary (pseudo-)payment (`COMP').</P>
 213 <P>If there is an error, returns the error, otherwise returns false.</P>
 214 <P>Currently available options are:</P>
 215 <P>invoice_time - Use this time when deciding when to print invoices and
 216 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>
 217 for conversion functions.</P>
 218 <P>batch_card - Set this true to batch cards (see <A HREF=".././FS/cust_pay_batch.html">the cust_pay_batch manpage</A>).  By
 219 default, cards are processed immediately, which will generate an error if
 220 CyberCash is not installed.</P>
 221 <P>report_badcard - Set this true if you want bad card transactions to
 222 return an error.  By default, they don't.</P>
 223 <P></P>
 224 <DT><STRONG><A NAME="item_total_owed">total_owed</A></STRONG><BR>
 225 <DD>
 226 Returns the total owed for this customer on all invoices
 227 (see <A HREF=".././FS/cust_bill.html">the FS::cust_bill manpage</A>).
 228 <P></P>
 229 <DT><STRONG><A NAME="item_total_credited">total_credited</A></STRONG><BR>
 230 <DD>
 231 Returns the total credits (see <A HREF=".././FS/cust_credit.html">the FS::cust_credit manpage</A>) for this customer.
 232 <P></P>
 233 <DT><STRONG><A NAME="item_balance">balance</A></STRONG><BR>
 234 <DD>
 235 Returns the balance for this customer (total owed minus total credited).
 236 <P></P>
 237 <DT><STRONG><A NAME="item_invoicing_list_%5B_ARRAYREF_%5D">invoicing_list [ ARRAYREF ]</A></STRONG><BR>
 238 <DD>
 239 If an arguement is given, sets these email addresses as invoice recipients
 240 (see <A HREF=".././FS/cust_main_invoice.html">the FS::cust_main_invoice manpage</A>).  Errors are not fatal and are not reported
 241 (except as warnings), so use check_invoicing_list first.
 242 <P>Returns a list of email addresses (with svcnum entries expanded).</P>
 243 <P>Note: You can clear the invoicing list by passing an empty ARRAYREF.  You can
 244 check it without disturbing anything by passing nothing.</P>
 245 <P>This interface may change in the future.</P>
 246 <P></P>
 247 <DT><STRONG><A NAME="item_check_invoicing_list_ARRAYREF">check_invoicing_list ARRAYREF</A></STRONG><BR>
 248 <DD>
 249 Checks these arguements as valid input for the invoicing_list method.  If there
 250 is an error, returns the error, otherwise returns false.
 251 <P></P></DL>
 252 <P>
 253 <HR>
 254 <H1><A NAME="version">VERSION</A></H1>
 255 <P>$Id: cust_main.html,v 1.1 2001-07-30 07:36:03 ivan Exp $</P>
 256 <P>
 257 <HR>
 258 <H1><A NAME="bugs">BUGS</A></H1>
 259 <P>The delete method.</P>
 260 <P>The delete method should possibly take an FS::cust_main object reference
 261 instead of a scalar customer number.</P>
 262 <P>Bill and collect options should probably be passed as references instead of a
 263 list.</P>
 264 <P>CyberCash v2 forces us to define some variables in package main.</P>
 265 <P>There should probably be a configuration file with a list of allowed credit
 266 card types.</P>
 267 <P>CyberCash is the only processor.</P>
 268 <P>No multiple currency support (probably a larger project than just this module).</P>
 269 <P>
 270 <HR>
 271 <H1><A NAME="see also">SEE ALSO</A></H1>
 272 <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>
 273 <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>,
 274 <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>,
 275 <A HREF=".././FS/UID.html">the FS::UID manpage</A>, schema.html from the base documentation.</P>
 276
 277 </BODY>
 278
 279 </HTML>