4 use vars qw( @ISA $conf $Debug $import );
10 use Business::CreditCard;
11 use FS::UID qw( getotaker dbh );
12 use FS::Record qw( qsearchs qsearch dbdef );
15 use FS::cust_bill_pkg;
18 use FS::part_referral;
19 use FS::cust_main_county;
21 use FS::cust_main_invoice;
22 use FS::cust_credit_bill;
23 use FS::cust_bill_pay;
24 use FS::prepay_credit;
27 use FS::part_bill_event;
28 use FS::cust_bill_event;
30 @ISA = qw( FS::Record );
37 #ask FS::UID to run this stuff for us later
38 $FS::UID::callback{'FS::cust_main'} = sub {
40 #yes, need it for stuff below (prolly should be cached)
45 my ( $hashref, $cache ) = @_;
46 if ( exists $hashref->{'pkgnum'} ) {
47 # #@{ $self->{'_pkgnum'} } = ();
48 my $subcache = $cache->subcache( 'pkgnum', 'cust_pkg', $hashref->{custnum});
49 $self->{'_pkgnum'} = $subcache;
50 #push @{ $self->{'_pkgnum'} },
51 FS::cust_pkg->new_or_cached($hashref, $subcache) if $hashref->{pkgnum};
57 FS::cust_main - Object methods for cust_main records
63 $record = new FS::cust_main \%hash;
64 $record = new FS::cust_main { 'column' => 'value' };
66 $error = $record->insert;
68 $error = $new_record->replace($old_record);
70 $error = $record->delete;
72 $error = $record->check;
74 @cust_pkg = $record->all_pkgs;
76 @cust_pkg = $record->ncancelled_pkgs;
78 @cust_pkg = $record->suspended_pkgs;
80 $error = $record->bill;
81 $error = $record->bill %options;
82 $error = $record->bill 'time' => $time;
84 $error = $record->collect;
85 $error = $record->collect %options;
86 $error = $record->collect 'invoice_time' => $time,
87 'batch_card' => 'yes',
88 'report_badcard' => 'yes',
93 An FS::cust_main object represents a customer. FS::cust_main inherits from
94 FS::Record. The following fields are currently supported:
98 =item custnum - primary key (assigned automatically for new customers)
100 =item agentnum - agent (see L<FS::agent>)
102 =item refnum - Advertising source (see L<FS::part_referral>)
108 =item ss - social security number (optional)
110 =item company - (optional)
114 =item address2 - (optional)
118 =item county - (optional, see L<FS::cust_main_county>)
120 =item state - (see L<FS::cust_main_county>)
124 =item country - (see L<FS::cust_main_county>)
126 =item daytime - phone (optional)
128 =item night - phone (optional)
130 =item fax - phone (optional)
132 =item ship_first - name
134 =item ship_last - name
136 =item ship_company - (optional)
140 =item ship_address2 - (optional)
144 =item ship_county - (optional, see L<FS::cust_main_county>)
146 =item ship_state - (see L<FS::cust_main_county>)
150 =item ship_country - (see L<FS::cust_main_county>)
152 =item ship_daytime - phone (optional)
154 =item ship_night - phone (optional)
156 =item ship_fax - phone (optional)
158 =item payby - `CARD' (credit cards), `BILL' (billing), `COMP' (free), or `PREPAY' (special billing type: applies a credit - see L<FS::prepay_credit> and sets billing type to BILL)
160 =item payinfo - card number, P.O., comp issuer (4-8 lowercase alphanumerics; think username) or prepayment identifier (see L<FS::prepay_credit>)
162 =item paydate - expiration date, mm/yyyy, m/yyyy, mm/yy or m/yy
164 =item payname - name on card or billing name
166 =item tax - tax exempt, empty or `Y'
168 =item otaker - order taker (assigned automatically, see L<FS::UID>)
170 =item comments - comments (optional)
180 Creates a new customer. To add the customer to the database, see L<"insert">.
182 Note that this stores the hash reference, not a distinct copy of the hash it
183 points to. You can ask the object for a copy with the I<hash> method.
187 sub table { 'cust_main'; }
189 =item insert [ CUST_PKG_HASHREF [ , INVOICING_LIST_ARYREF ] ]
191 Adds this customer to the database. If there is an error, returns the error,
192 otherwise returns false.
194 CUST_PKG_HASHREF: If you pass a Tie::RefHash data structure to the insert
195 method containing FS::cust_pkg and FS::svc_I<tablename> objects, all records
196 are inserted atomicly, or the transaction is rolled back. Passing an empty
197 hash reference is equivalent to not supplying this parameter. There should be
198 a better explanation of this, but until then, here's an example:
201 tie %hash, 'Tie::RefHash'; #this part is important
203 $cust_pkg => [ $svc_acct ],
206 $cust_main->insert( \%hash );
208 INVOICING_LIST_ARYREF: If you pass an arrarref to the insert method, it will
209 be set as the invoicing list (see L<"invoicing_list">). Errors return as
210 expected and rollback the entire transaction; it is not necessary to call
211 check_invoicing_list first. The invoicing_list is set after the records in the
212 CUST_PKG_HASHREF above are inserted, so it is now possible to set an
213 invoicing_list destination to the newly-created svc_acct. Here's an example:
215 $cust_main->insert( {}, [ $email, 'POST' ] );
223 local $SIG{HUP} = 'IGNORE';
224 local $SIG{INT} = 'IGNORE';
225 local $SIG{QUIT} = 'IGNORE';
226 local $SIG{TERM} = 'IGNORE';
227 local $SIG{TSTP} = 'IGNORE';
228 local $SIG{PIPE} = 'IGNORE';
230 my $oldAutoCommit = $FS::UID::AutoCommit;
231 local $FS::UID::AutoCommit = 0;
236 if ( $self->payby eq 'PREPAY' ) {
237 $self->payby('BILL');
238 my $prepay_credit = qsearchs(
240 { 'identifier' => $self->payinfo },
244 warn "WARNING: can't find pre-found prepay_credit: ". $self->payinfo
245 unless $prepay_credit;
246 $amount = $prepay_credit->amount;
247 $seconds = $prepay_credit->seconds;
248 my $error = $prepay_credit->delete;
250 $dbh->rollback if $oldAutoCommit;
251 return "removing prepay_credit (transaction rolled back): $error";
255 my $error = $self->SUPER::insert;
257 $dbh->rollback if $oldAutoCommit;
258 return "inserting cust_main record (transaction rolled back): $error";
261 if ( @param ) { # CUST_PKG_HASHREF
262 my $cust_pkgs = shift @param;
263 foreach my $cust_pkg ( keys %$cust_pkgs ) {
264 $cust_pkg->custnum( $self->custnum );
265 $error = $cust_pkg->insert;
267 $dbh->rollback if $oldAutoCommit;
268 return "inserting cust_pkg (transaction rolled back): $error";
270 foreach my $svc_something ( @{$cust_pkgs->{$cust_pkg}} ) {
271 $svc_something->pkgnum( $cust_pkg->pkgnum );
272 if ( $seconds && $svc_something->isa('FS::svc_acct') ) {
273 $svc_something->seconds( $svc_something->seconds + $seconds );
276 $error = $svc_something->insert;
278 $dbh->rollback if $oldAutoCommit;
279 return "inserting svc_ (transaction rolled back): $error";
286 $dbh->rollback if $oldAutoCommit;
287 return "No svc_acct record to apply pre-paid time";
290 if ( @param ) { # INVOICING_LIST_ARYREF
291 my $invoicing_list = shift @param;
292 $error = $self->check_invoicing_list( $invoicing_list );
294 $dbh->rollback if $oldAutoCommit;
295 return "checking invoicing_list (transaction rolled back): $error";
297 $self->invoicing_list( $invoicing_list );
301 my $cust_credit = new FS::cust_credit {
302 'custnum' => $self->custnum,
305 $error = $cust_credit->insert;
307 $dbh->rollback if $oldAutoCommit;
308 return "inserting credit (transaction rolled back): $error";
312 #false laziness with sub replace
313 my $queue = new FS::queue { 'job' => 'FS::cust_main::append_fuzzyfiles' };
314 $error = $queue->insert($self->getfield('last'), $self->company);
316 $dbh->rollback if $oldAutoCommit;
317 return "queueing job (transaction rolled back): $error";
320 if ( defined $self->dbdef_table->column('ship_last') && $self->ship_last ) {
321 $queue = new FS::queue { 'job' => 'FS::cust_main::append_fuzzyfiles' };
322 $error = $queue->insert($self->getfield('last'), $self->company);
324 $dbh->rollback if $oldAutoCommit;
325 return "queueing job (transaction rolled back): $error";
330 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
335 =item delete NEW_CUSTNUM
337 This deletes the customer. If there is an error, returns the error, otherwise
340 This will completely remove all traces of the customer record. This is not
341 what you want when a customer cancels service; for that, cancel all of the
342 customer's packages (see L<FS::cust_pkg/cancel>).
344 If the customer has any uncancelled packages, you need to pass a new (valid)
345 customer number for those packages to be transferred to. Cancelled packages
346 will be deleted. Did I mention that this is NOT what you want when a customer
347 cancels service and that you really should be looking see L<FS::cust_pkg/cancel>?
349 You can't delete a customer with invoices (see L<FS::cust_bill>),
350 or credits (see L<FS::cust_credit>), payments (see L<FS::cust_pay>) or
351 refunds (see L<FS::cust_refund>).
358 local $SIG{HUP} = 'IGNORE';
359 local $SIG{INT} = 'IGNORE';
360 local $SIG{QUIT} = 'IGNORE';
361 local $SIG{TERM} = 'IGNORE';
362 local $SIG{TSTP} = 'IGNORE';
363 local $SIG{PIPE} = 'IGNORE';
365 my $oldAutoCommit = $FS::UID::AutoCommit;
366 local $FS::UID::AutoCommit = 0;
369 if ( qsearch( 'cust_bill', { 'custnum' => $self->custnum } ) ) {
370 $dbh->rollback if $oldAutoCommit;
371 return "Can't delete a customer with invoices";
373 if ( qsearch( 'cust_credit', { 'custnum' => $self->custnum } ) ) {
374 $dbh->rollback if $oldAutoCommit;
375 return "Can't delete a customer with credits";
377 if ( qsearch( 'cust_pay', { 'custnum' => $self->custnum } ) ) {
378 $dbh->rollback if $oldAutoCommit;
379 return "Can't delete a customer with payments";
381 if ( qsearch( 'cust_refund', { 'custnum' => $self->custnum } ) ) {
382 $dbh->rollback if $oldAutoCommit;
383 return "Can't delete a customer with refunds";
386 my @cust_pkg = $self->ncancelled_pkgs;
388 my $new_custnum = shift;
389 unless ( qsearchs( 'cust_main', { 'custnum' => $new_custnum } ) ) {
390 $dbh->rollback if $oldAutoCommit;
391 return "Invalid new customer number: $new_custnum";
393 foreach my $cust_pkg ( @cust_pkg ) {
394 my %hash = $cust_pkg->hash;
395 $hash{'custnum'} = $new_custnum;
396 my $new_cust_pkg = new FS::cust_pkg ( \%hash );
397 my $error = $new_cust_pkg->replace($cust_pkg);
399 $dbh->rollback if $oldAutoCommit;
404 my @cancelled_cust_pkg = $self->all_pkgs;
405 foreach my $cust_pkg ( @cancelled_cust_pkg ) {
406 my $error = $cust_pkg->delete;
408 $dbh->rollback if $oldAutoCommit;
413 foreach my $cust_main_invoice ( #(email invoice destinations, not invoices)
414 qsearch( 'cust_main_invoice', { 'custnum' => $self->custnum } )
416 my $error = $cust_main_invoice->delete;
418 $dbh->rollback if $oldAutoCommit;
423 my $error = $self->SUPER::delete;
425 $dbh->rollback if $oldAutoCommit;
429 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
434 =item replace OLD_RECORD [ INVOICING_LIST_ARYREF ]
436 Replaces the OLD_RECORD with this one in the database. If there is an error,
437 returns the error, otherwise returns false.
439 INVOICING_LIST_ARYREF: If you pass an arrarref to the insert method, it will
440 be set as the invoicing list (see L<"invoicing_list">). Errors return as
441 expected and rollback the entire transaction; it is not necessary to call
442 check_invoicing_list first. Here's an example:
444 $new_cust_main->replace( $old_cust_main, [ $email, 'POST' ] );
453 local $SIG{HUP} = 'IGNORE';
454 local $SIG{INT} = 'IGNORE';
455 local $SIG{QUIT} = 'IGNORE';
456 local $SIG{TERM} = 'IGNORE';
457 local $SIG{TSTP} = 'IGNORE';
458 local $SIG{PIPE} = 'IGNORE';
460 my $oldAutoCommit = $FS::UID::AutoCommit;
461 local $FS::UID::AutoCommit = 0;
464 my $error = $self->SUPER::replace($old);
467 $dbh->rollback if $oldAutoCommit;
471 if ( @param ) { # INVOICING_LIST_ARYREF
472 my $invoicing_list = shift @param;
473 $error = $self->check_invoicing_list( $invoicing_list );
475 $dbh->rollback if $oldAutoCommit;
478 $self->invoicing_list( $invoicing_list );
481 #false laziness with sub insert
482 my $queue = new FS::queue { 'job' => 'FS::cust_main::append_fuzzyfiles' };
483 $error = $queue->insert($self->getfield('last'), $self->company);
485 $dbh->rollback if $oldAutoCommit;
486 return "queueing job (transaction rolled back): $error";
489 if ( defined $self->dbdef_table->column('ship_last') && $self->ship_last ) {
490 $queue = new FS::queue { 'job' => 'FS::cust_main::append_fuzzyfiles' };
491 $error = $queue->insert($self->getfield('last'), $self->company);
493 $dbh->rollback if $oldAutoCommit;
494 return "queueing job (transaction rolled back): $error";
499 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
506 Checks all fields to make sure this is a valid customer record. If there is
507 an error, returns the error, otherwise returns false. Called by the insert
515 #warn "BEFORE: \n". $self->_dump;
518 $self->ut_numbern('custnum')
519 || $self->ut_number('agentnum')
520 || $self->ut_number('refnum')
521 || $self->ut_name('last')
522 || $self->ut_name('first')
523 || $self->ut_textn('company')
524 || $self->ut_text('address1')
525 || $self->ut_textn('address2')
526 || $self->ut_text('city')
527 || $self->ut_textn('county')
528 || $self->ut_textn('state')
529 || $self->ut_country('country')
530 || $self->ut_anything('comments')
531 || $self->ut_numbern('referral_custnum')
533 #barf. need message catalogs. i18n. etc.
534 $error .= "Please select a advertising source."
535 if $error =~ /^Illegal or empty \(numeric\) refnum: /;
536 return $error if $error;
538 return "Unknown agent"
539 unless qsearchs( 'agent', { 'agentnum' => $self->agentnum } );
541 return "Unknown refnum"
542 unless qsearchs( 'part_referral', { 'refnum' => $self->refnum } );
544 return "Unknown referring custnum ". $self->referral_custnum
545 unless ! $self->referral_custnum
546 || qsearchs( 'cust_main', { 'custnum' => $self->referral_custnum } );
548 if ( $self->ss eq '' ) {
553 $ss =~ /^(\d{3})(\d{2})(\d{4})$/
554 or return "Illegal social security number: ". $self->ss;
555 $self->ss("$1-$2-$3");
559 # bad idea to disable, causes billing to fail because of no tax rates later
560 # unless ( $import ) {
561 unless ( qsearchs('cust_main_county', {
562 'country' => $self->country,
565 return "Unknown state/county/country: ".
566 $self->state. "/". $self->county. "/". $self->country
567 unless qsearchs('cust_main_county',{
568 'state' => $self->state,
569 'county' => $self->county,
570 'country' => $self->country,
576 $self->ut_phonen('daytime', $self->country)
577 || $self->ut_phonen('night', $self->country)
578 || $self->ut_phonen('fax', $self->country)
579 || $self->ut_zip('zip', $self->country)
581 return $error if $error;
584 last first company address1 address2 city county state zip
585 country daytime night fax
588 if ( defined $self->dbdef_table->column('ship_last') ) {
589 if ( scalar ( grep { $self->getfield($_) ne $self->getfield("ship_$_") }
591 && scalar ( grep { $self->getfield("ship_$_") ne '' } @addfields )
595 $self->ut_name('ship_last')
596 || $self->ut_name('ship_first')
597 || $self->ut_textn('ship_company')
598 || $self->ut_text('ship_address1')
599 || $self->ut_textn('ship_address2')
600 || $self->ut_text('ship_city')
601 || $self->ut_textn('ship_county')
602 || $self->ut_textn('ship_state')
603 || $self->ut_country('ship_country')
605 return $error if $error;
607 #false laziness with above
608 unless ( qsearchs('cust_main_county', {
609 'country' => $self->ship_country,
612 return "Unknown ship_state/ship_county/ship_country: ".
613 $self->ship_state. "/". $self->ship_county. "/". $self->ship_country
614 unless qsearchs('cust_main_county',{
615 'state' => $self->ship_state,
616 'county' => $self->ship_county,
617 'country' => $self->ship_country,
623 $self->ut_phonen('ship_daytime', $self->ship_country)
624 || $self->ut_phonen('ship_night', $self->ship_country)
625 || $self->ut_phonen('ship_fax', $self->ship_country)
626 || $self->ut_zip('ship_zip', $self->ship_country)
628 return $error if $error;
630 } else { # ship_ info eq billing info, so don't store dup info in database
631 $self->setfield("ship_$_", '')
632 foreach qw( last first company address1 address2 city county state zip
633 country daytime night fax );
637 $self->payby =~ /^(CARD|BILL|COMP|PREPAY)$/
638 or return "Illegal payby: ". $self->payby;
641 if ( $self->payby eq 'CARD' ) {
643 my $payinfo = $self->payinfo;
645 $payinfo =~ /^(\d{13,16})$/
646 or return "Illegal credit card number: ". $self->payinfo;
648 $self->payinfo($payinfo);
650 or return "Illegal credit card number: ". $self->payinfo;
651 return "Unknown card type" if cardtype($self->payinfo) eq "Unknown";
653 } elsif ( $self->payby eq 'BILL' ) {
655 $error = $self->ut_textn('payinfo');
656 return "Illegal P.O. number: ". $self->payinfo if $error;
658 } elsif ( $self->payby eq 'COMP' ) {
660 $error = $self->ut_textn('payinfo');
661 return "Illegal comp account issuer: ". $self->payinfo if $error;
663 } elsif ( $self->payby eq 'PREPAY' ) {
665 my $payinfo = $self->payinfo;
666 $payinfo =~ s/\W//g; #anything else would just confuse things
667 $self->payinfo($payinfo);
668 $error = $self->ut_alpha('payinfo');
669 return "Illegal prepayment identifier: ". $self->payinfo if $error;
670 return "Unknown prepayment identifier"
671 unless qsearchs('prepay_credit', { 'identifier' => $self->payinfo } );
675 if ( $self->paydate eq '' || $self->paydate eq '-' ) {
676 return "Expriation date required"
677 unless $self->payby eq 'BILL' || $self->payby eq 'PREPAY';
680 $self->paydate =~ /^(\d{1,2})[\/\-](\d{2}(\d{2})?)$/
681 or return "Illegal expiration date: ". $self->paydate;
682 if ( length($2) == 4 ) {
683 $self->paydate("$2-$1-01");
685 $self->paydate("20$2-$1-01");
689 if ( $self->payname eq '' ) {
690 $self->payname( $self->first. " ". $self->getfield('last') );
692 $self->payname =~ /^([\w \,\.\-\']+)$/
693 or return "Illegal billing name: ". $self->payname;
697 $self->tax =~ /^(Y?)$/ or return "Illegal tax: ". $self->tax;
700 $self->otaker(getotaker);
702 #warn "AFTER: \n". $self->_dump;
709 Returns all packages (see L<FS::cust_pkg>) for this customer.
715 if ( $self->{'_pkgnum'} ) {
716 values %{ $self->{'_pkgnum'}->cache };
718 qsearch( 'cust_pkg', { 'custnum' => $self->custnum });
722 =item ncancelled_pkgs
724 Returns all non-cancelled packages (see L<FS::cust_pkg>) for this customer.
728 sub ncancelled_pkgs {
730 if ( $self->{'_pkgnum'} ) {
731 grep { ! $_->getfield('cancel') } values %{ $self->{'_pkgnum'}->cache };
733 @{ [ # force list context
734 qsearch( 'cust_pkg', {
735 'custnum' => $self->custnum,
738 qsearch( 'cust_pkg', {
739 'custnum' => $self->custnum,
748 Returns all suspended packages (see L<FS::cust_pkg>) for this customer.
754 grep { $_->susp } $self->ncancelled_pkgs;
757 =item unflagged_suspended_pkgs
759 Returns all unflagged suspended packages (see L<FS::cust_pkg>) for this
760 customer (thouse packages without the `manual_flag' set).
764 sub unflagged_suspended_pkgs {
766 return $self->suspended_pkgs
767 unless dbdef->table('cust_pkg')->column('manual_flag');
768 grep { ! $_->manual_flag } $self->suspended_pkgs;
771 =item unsuspended_pkgs
773 Returns all unsuspended (and uncancelled) packages (see L<FS::cust_pkg>) for
778 sub unsuspended_pkgs {
780 grep { ! $_->susp } $self->ncancelled_pkgs;
785 Unsuspends all unflagged suspended packages (see L</unflagged_suspended_pkgs>
786 and L<FS::cust_pkg>) for this customer. Always returns a list: an empty list
787 on success or a list of errors.
793 grep { $_->unsuspend } $self->suspended_pkgs;
798 Suspends all unsuspended packages (see L<FS::cust_pkg>) for this customer.
799 Always returns a list: an empty list on success or a list of errors.
805 grep { $_->suspend } $self->unsuspended_pkgs;
810 Cancels all uncancelled packages (see L<FS::cust_pkg>) for this customer.
811 Always returns a list: an empty list on success or a list of errors.
817 grep { $_->cancel } $self->ncancelled_pkgs;
822 Returns the agent (see L<FS::agent>) for this customer.
828 qsearchs( 'agent', { 'agent' => $self->agentnum } );
833 Generates invoices (see L<FS::cust_bill>) for this customer. Usually used in
834 conjunction with the collect method.
836 Options are passed as name-value pairs.
838 The only currently available option is `time', which bills the customer as if
839 it were that time. It is specified as a UNIX timestamp; see
840 L<perlfunc/"time">). Also see L<Time::Local> and L<Date::Parse> for conversion
841 functions. For example:
845 $cust_main->bill( 'time' => str2time('April 20th, 2001') );
847 If there is an error, returns the error, otherwise returns false.
852 my( $self, %options ) = @_;
853 my $time = $options{'time'} || time;
858 local $SIG{HUP} = 'IGNORE';
859 local $SIG{INT} = 'IGNORE';
860 local $SIG{QUIT} = 'IGNORE';
861 local $SIG{TERM} = 'IGNORE';
862 local $SIG{TSTP} = 'IGNORE';
863 local $SIG{PIPE} = 'IGNORE';
865 my $oldAutoCommit = $FS::UID::AutoCommit;
866 local $FS::UID::AutoCommit = 0;
869 # find the packages which are due for billing, find out how much they are
870 # & generate invoice database.
872 my( $total_setup, $total_recur ) = ( 0, 0 );
873 my( $taxable_setup, $taxable_recur ) = ( 0, 0 );
874 my @cust_bill_pkg = ();
876 foreach my $cust_pkg (
877 qsearch('cust_pkg', { 'custnum' => $self->custnum } )
880 #NO!! next if $cust_pkg->cancel;
881 next if $cust_pkg->getfield('cancel');
883 #? to avoid use of uninitialized value errors... ?
884 $cust_pkg->setfield('bill', '')
885 unless defined($cust_pkg->bill);
887 my $part_pkg = qsearchs( 'part_pkg', { 'pkgpart' => $cust_pkg->pkgpart } );
889 #so we don't modify cust_pkg record unnecessarily
890 my $cust_pkg_mod_flag = 0;
891 my %hash = $cust_pkg->hash;
892 my $old_cust_pkg = new FS::cust_pkg \%hash;
896 unless ( $cust_pkg->setup ) {
897 my $setup_prog = $part_pkg->getfield('setup');
898 $setup_prog =~ /^(.*)$/ or do {
899 $dbh->rollback if $oldAutoCommit;
900 return "Illegal setup for pkgpart ". $part_pkg->pkgpart.
906 ##$cpt->permit(); #what is necessary?
907 #$cpt->share(qw( $cust_pkg )); #can $cpt now use $cust_pkg methods?
908 #$setup = $cpt->reval($setup_prog);
909 $setup = eval $setup_prog;
910 unless ( defined($setup) ) {
911 $dbh->rollback if $oldAutoCommit;
912 return "Error eval-ing part_pkg->setup pkgpart ". $part_pkg->pkgpart.
913 "(expression $setup_prog): $@";
915 $cust_pkg->setfield('setup',$time);
916 $cust_pkg_mod_flag=1;
922 if ( $part_pkg->getfield('freq') > 0 &&
923 ! $cust_pkg->getfield('susp') &&
924 ( $cust_pkg->getfield('bill') || 0 ) < $time
926 my $recur_prog = $part_pkg->getfield('recur');
927 $recur_prog =~ /^(.*)$/ or do {
928 $dbh->rollback if $oldAutoCommit;
929 return "Illegal recur for pkgpart ". $part_pkg->pkgpart.
934 # shared with $recur_prog
935 $sdate = $cust_pkg->bill || $cust_pkg->setup || $time;
938 ##$cpt->permit(); #what is necessary?
939 #$cpt->share(qw( $cust_pkg )); #can $cpt now use $cust_pkg methods?
940 #$recur = $cpt->reval($recur_prog);
941 $recur = eval $recur_prog;
942 unless ( defined($recur) ) {
943 $dbh->rollback if $oldAutoCommit;
944 return "Error eval-ing part_pkg->recur pkgpart ". $part_pkg->pkgpart.
945 "(expression $recur_prog): $@";
947 #change this bit to use Date::Manip? CAREFUL with timezones (see
948 # mailing list archive)
949 my ($sec,$min,$hour,$mday,$mon,$year) =
950 (localtime($sdate) )[0,1,2,3,4,5];
952 #pro-rating magic - if $recur_prog fiddles $sdate, want to use that
953 # only for figuring next bill date, nothing else, so, reset $sdate again
955 $sdate = $cust_pkg->bill || $cust_pkg->setup || $time;
957 $mon += $part_pkg->getfield('freq');
958 until ( $mon < 12 ) { $mon -= 12; $year++; }
959 $cust_pkg->setfield('bill',
960 timelocal($sec,$min,$hour,$mday,$mon,$year));
961 $cust_pkg_mod_flag = 1;
964 warn "\$setup is undefined" unless defined($setup);
965 warn "\$recur is undefined" unless defined($recur);
966 warn "\$cust_pkg->bill is undefined" unless defined($cust_pkg->bill);
968 if ( $cust_pkg_mod_flag ) {
969 $error=$cust_pkg->replace($old_cust_pkg);
970 if ( $error ) { #just in case
971 $dbh->rollback if $oldAutoCommit;
972 return "Error modifying pkgnum ". $cust_pkg->pkgnum. ": $error";
974 $setup = sprintf( "%.2f", $setup );
975 $recur = sprintf( "%.2f", $recur );
977 $dbh->rollback if $oldAutoCommit;
978 return "negative setup $setup for pkgnum ". $cust_pkg->pkgnum;
981 $dbh->rollback if $oldAutoCommit;
982 return "negative recur $recur for pkgnum ". $cust_pkg->pkgnum;
984 if ( $setup > 0 || $recur > 0 ) {
985 my $cust_bill_pkg = new FS::cust_bill_pkg ({
986 'pkgnum' => $cust_pkg->pkgnum,
990 'edate' => $cust_pkg->bill,
992 push @cust_bill_pkg, $cust_bill_pkg;
993 $total_setup += $setup;
994 $total_recur += $recur;
995 $taxable_setup += $setup
996 unless $part_pkg->dbdef_table->column('setuptax')
997 && $part_pkg->setuptax =~ /^Y$/i;
998 $taxable_recur += $recur
999 unless $part_pkg->dbdef_table->column('recurtax')
1000 && $part_pkg->recurtax =~ /^Y$/i;
1006 my $charged = sprintf( "%.2f", $total_setup + $total_recur );
1007 my $taxable_charged = sprintf( "%.2f", $taxable_setup + $taxable_recur );
1009 unless ( @cust_bill_pkg ) {
1010 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
1014 unless ( $self->tax =~ /Y/i
1015 || $self->payby eq 'COMP'
1016 || $taxable_charged == 0 ) {
1017 my $cust_main_county = qsearchs('cust_main_county',{
1018 'state' => $self->state,
1019 'county' => $self->county,
1020 'country' => $self->country,
1021 } ) or die "fatal: can't find tax rate for state/county/country ".
1022 $self->state. "/". $self->county. "/". $self->country. "\n";
1023 my $tax = sprintf( "%.2f",
1024 $taxable_charged * ( $cust_main_county->getfield('tax') / 100 )
1028 $charged = sprintf( "%.2f", $charged+$tax );
1030 my $cust_bill_pkg = new FS::cust_bill_pkg ({
1037 push @cust_bill_pkg, $cust_bill_pkg;
1041 my $cust_bill = new FS::cust_bill ( {
1042 'custnum' => $self->custnum,
1044 'charged' => $charged,
1046 $error = $cust_bill->insert;
1048 $dbh->rollback if $oldAutoCommit;
1049 return "can't create invoice for customer #". $self->custnum. ": $error";
1052 my $invnum = $cust_bill->invnum;
1054 foreach $cust_bill_pkg ( @cust_bill_pkg ) {
1056 $cust_bill_pkg->invnum($invnum);
1057 $error = $cust_bill_pkg->insert;
1059 $dbh->rollback if $oldAutoCommit;
1060 return "can't create invoice line item for customer #". $self->custnum.
1065 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
1069 =item collect OPTIONS
1071 (Attempt to) collect money for this customer's outstanding invoices (see
1072 L<FS::cust_bill>). Usually used after the bill method.
1074 Depending on the value of `payby', this may print an invoice (`BILL'), charge
1075 a credit card (`CARD'), or just add any necessary (pseudo-)payment (`COMP').
1077 Most actions are now triggered by invoice events; see L<FS::part_bill_event>
1078 and the invoice events web interface.
1080 If there is an error, returns the error, otherwise returns false.
1082 Options are passed as name-value pairs.
1084 Currently available options are:
1086 invoice_time - Use this time when deciding when to print invoices and
1087 late notices on those invoices. The default is now. It is specified as a UNIX timestamp; see L<perlfunc/"time">). Also see L<Time::Local> and L<Date::Parse>
1088 for conversion functions.
1090 batch_card - This option is deprecated. See the invoice events web interface
1091 to control whether cards are batched or run against a realtime gateway.
1093 report_badcard - This option is deprecated.
1095 force_print - This option is deprecated; see the invoice events web interface.
1100 my( $self, %options ) = @_;
1101 my $invoice_time = $options{'invoice_time'} || time;
1104 local $SIG{HUP} = 'IGNORE';
1105 local $SIG{INT} = 'IGNORE';
1106 local $SIG{QUIT} = 'IGNORE';
1107 local $SIG{TERM} = 'IGNORE';
1108 local $SIG{TSTP} = 'IGNORE';
1109 local $SIG{PIPE} = 'IGNORE';
1111 my $oldAutoCommit = $FS::UID::AutoCommit;
1112 local $FS::UID::AutoCommit = 0;
1115 my $balance = $self->balance;
1116 warn "collect customer". $self->custnum. ": balance $balance" if $Debug;
1117 unless ( $balance > 0 ) { #redundant?????
1118 $dbh->rollback if $oldAutoCommit; #hmm
1122 foreach my $cust_bill (
1123 qsearch('cust_bill', { 'custnum' => $self->custnum, } )
1126 #this has to be before next's
1127 my $amount = sprintf( "%.2f", $balance < $cust_bill->owed
1131 $balance = sprintf( "%.2f", $balance - $amount );
1133 next unless $cust_bill->owed > 0;
1135 # don't try to charge for the same invoice if it's already in a batch
1136 #next if qsearchs( 'cust_pay_batch', { 'invnum' => $cust_bill->invnum } );
1138 warn "invnum ". $cust_bill->invnum. " (owed ". $cust_bill->owed. ", amount $amount, balance $balance)" if $Debug;
1140 next unless $amount > 0;
1142 foreach my $part_bill_event (
1143 sort { $a->seconds <=> $b->seconds
1144 || $a->weight <=> $b->weight
1145 || $a->eventpart <=> $b->eventpart }
1146 grep { $_->seconds <= ( $invoice_time - $cust_bill->_date )
1147 && ! qsearchs( 'cust_bill_event', {
1148 'invnum' => $cust_bill->invnum,
1149 'eventpart' => $_->eventpart,
1153 qsearch('part_bill_event', { 'payby' => $self->payby,
1154 'disabled' => '', } )
1156 warn "calling invoice event (". $part_bill_event->eventcode. ")\n"
1158 my $cust_main = $self; #for callback
1159 my $error = eval $part_bill_event->eventcode;
1162 my $statustext = '';
1166 } elsif ( $error ) {
1168 $statustext = $error;
1173 #add cust_bill_event
1174 my $cust_bill_event = new FS::cust_bill_event {
1175 'invnum' => $cust_bill->invnum,
1176 'eventpart' => $part_bill_event->eventpart,
1177 '_date' => $invoice_time,
1178 'status' => $status,
1179 'statustext' => $statustext,
1181 $error = $cust_bill_event->insert;
1183 #$dbh->rollback if $oldAutoCommit;
1184 #return "error: $error";
1186 # gah, even with transactions.
1187 $dbh->commit if $oldAutoCommit; #well.
1188 my $e = 'WARNING: Event run but database not updated - '.
1189 'error inserting cust_bill_event, invnum #'. $cust_bill->invnum.
1190 ', eventpart '. $part_bill_event->eventpart.
1201 $dbh->commit or die $dbh->errstr if $oldAutoCommit;
1208 Returns the total owed for this customer on all invoices
1209 (see L<FS::cust_bill/owed>).
1215 $self->total_owed_date(2145859200); #12/31/2037
1218 =item total_owed_date TIME
1220 Returns the total owed for this customer on all invoices with date earlier than
1221 TIME. TIME is specified as a UNIX timestamp; see L<perlfunc/"time">). Also
1222 see L<Time::Local> and L<Date::Parse> for conversion functions.
1226 sub total_owed_date {
1230 foreach my $cust_bill (
1231 grep { $_->_date <= $time }
1232 qsearch('cust_bill', { 'custnum' => $self->custnum, } )
1234 $total_bill += $cust_bill->owed;
1236 sprintf( "%.2f", $total_bill );
1241 Applies (see L<FS::cust_credit_bill>) unapplied credits (see L<FS::cust_credit>)
1242 to outstanding invoice balances in chronological order and returns the value
1243 of any remaining unapplied credits available for refund
1244 (see L<FS::cust_refund>).
1251 return 0 unless $self->total_credited;
1253 my @credits = sort { $b->_date <=> $a->_date} (grep { $_->credited > 0 }
1254 qsearch('cust_credit', { 'custnum' => $self->custnum } ) );
1256 my @invoices = sort { $a->_date <=> $b->_date} (grep { $_->owed > 0 }
1257 qsearch('cust_bill', { 'custnum' => $self->custnum } ) );
1261 foreach my $cust_bill ( @invoices ) {
1264 if ( !defined($credit) || $credit->credited == 0) {
1265 $credit = pop @credits or last;
1268 if ($cust_bill->owed >= $credit->credited) {
1269 $amount=$credit->credited;
1271 $amount=$cust_bill->owed;
1274 my $cust_credit_bill = new FS::cust_credit_bill ( {
1275 'crednum' => $credit->crednum,
1276 'invnum' => $cust_bill->invnum,
1277 'amount' => $amount,
1279 my $error = $cust_credit_bill->insert;
1280 die $error if $error;
1282 redo if ($cust_bill->owed > 0);
1286 return $self->total_credited;
1289 =item apply_payments
1291 Applies (see L<FS::cust_bill_pay>) unapplied payments (see L<FS::cust_pay>)
1292 to outstanding invoice balances in chronological order.
1294 #and returns the value of any remaining unapplied payments.
1298 sub apply_payments {
1303 my @payments = sort { $b->_date <=> $a->_date } ( grep { $_->unapplied > 0 }
1304 qsearch('cust_pay', { 'custnum' => $self->custnum } ) );
1306 my @invoices = sort { $a->_date <=> $b->_date} (grep { $_->owed > 0 }
1307 qsearch('cust_bill', { 'custnum' => $self->custnum } ) );
1311 foreach my $cust_bill ( @invoices ) {
1314 if ( !defined($payment) || $payment->unapplied == 0 ) {
1315 $payment = pop @payments or last;
1318 if ( $cust_bill->owed >= $payment->unapplied ) {
1319 $amount = $payment->unapplied;
1321 $amount = $cust_bill->owed;
1324 my $cust_bill_pay = new FS::cust_bill_pay ( {
1325 'paynum' => $payment->paynum,
1326 'invnum' => $cust_bill->invnum,
1327 'amount' => $amount,
1329 my $error = $cust_bill_pay->insert;
1330 die $error if $error;
1332 redo if ( $cust_bill->owed > 0);
1336 return $self->total_unapplied_payments;
1339 =item total_credited
1341 Returns the total outstanding credit (see L<FS::cust_credit>) for this
1342 customer. See L<FS::cust_credit/credited>.
1346 sub total_credited {
1348 my $total_credit = 0;
1349 foreach my $cust_credit ( qsearch('cust_credit', {
1350 'custnum' => $self->custnum,
1352 $total_credit += $cust_credit->credited;
1354 sprintf( "%.2f", $total_credit );
1357 =item total_unapplied_payments
1359 Returns the total unapplied payments (see L<FS::cust_pay>) for this customer.
1360 See L<FS::cust_pay/unapplied>.
1364 sub total_unapplied_payments {
1366 my $total_unapplied = 0;
1367 foreach my $cust_pay ( qsearch('cust_pay', {
1368 'custnum' => $self->custnum,
1370 $total_unapplied += $cust_pay->unapplied;
1372 sprintf( "%.2f", $total_unapplied );
1377 Returns the balance for this customer (total_owed minus total_credited
1378 minus total_unapplied_payments).
1385 $self->total_owed - $self->total_credited - $self->total_unapplied_payments
1389 =item balance_date TIME
1391 Returns the balance for this customer, only considering invoices with date
1392 earlier than TIME (total_owed_date minus total_credited minus
1393 total_unapplied_payments). TIME is specified as a UNIX timestamp; see
1394 L<perlfunc/"time">). Also see L<Time::Local> and L<Date::Parse> for conversion
1403 $self->total_owed_date($time)
1404 - $self->total_credited
1405 - $self->total_unapplied_payments
1409 =item invoicing_list [ ARRAYREF ]
1411 If an arguement is given, sets these email addresses as invoice recipients
1412 (see L<FS::cust_main_invoice>). Errors are not fatal and are not reported
1413 (except as warnings), so use check_invoicing_list first.
1415 Returns a list of email addresses (with svcnum entries expanded).
1417 Note: You can clear the invoicing list by passing an empty ARRAYREF. You can
1418 check it without disturbing anything by passing nothing.
1420 This interface may change in the future.
1424 sub invoicing_list {
1425 my( $self, $arrayref ) = @_;
1427 my @cust_main_invoice;
1428 if ( $self->custnum ) {
1429 @cust_main_invoice =
1430 qsearch( 'cust_main_invoice', { 'custnum' => $self->custnum } );
1432 @cust_main_invoice = ();
1434 foreach my $cust_main_invoice ( @cust_main_invoice ) {
1435 #warn $cust_main_invoice->destnum;
1436 unless ( grep { $cust_main_invoice->address eq $_ } @{$arrayref} ) {
1437 #warn $cust_main_invoice->destnum;
1438 my $error = $cust_main_invoice->delete;
1439 warn $error if $error;
1442 if ( $self->custnum ) {
1443 @cust_main_invoice =
1444 qsearch( 'cust_main_invoice', { 'custnum' => $self->custnum } );
1446 @cust_main_invoice = ();
1448 my %seen = map { $_->address => 1 } @cust_main_invoice;
1449 foreach my $address ( @{$arrayref} ) {
1450 #unless ( grep { $address eq $_->address } @cust_main_invoice ) {
1451 next if exists $seen{$address} && $seen{$address};
1452 $seen{$address} = 1;
1453 my $cust_main_invoice = new FS::cust_main_invoice ( {
1454 'custnum' => $self->custnum,
1457 my $error = $cust_main_invoice->insert;
1458 warn $error if $error;
1461 if ( $self->custnum ) {
1463 qsearch( 'cust_main_invoice', { 'custnum' => $self->custnum } );
1469 =item check_invoicing_list ARRAYREF
1471 Checks these arguements as valid input for the invoicing_list method. If there
1472 is an error, returns the error, otherwise returns false.
1476 sub check_invoicing_list {
1477 my( $self, $arrayref ) = @_;
1478 foreach my $address ( @{$arrayref} ) {
1479 my $cust_main_invoice = new FS::cust_main_invoice ( {
1480 'custnum' => $self->custnum,
1483 my $error = $self->custnum
1484 ? $cust_main_invoice->check
1485 : $cust_main_invoice->checkdest
1487 return $error if $error;
1492 =item default_invoicing_list
1494 Sets the invoicing list to all accounts associated with this customer.
1498 sub default_invoicing_list {
1501 foreach my $cust_pkg ( $self->all_pkgs ) {
1502 my @cust_svc = qsearch('cust_svc', { 'pkgnum' => $cust_pkg->pkgnum } );
1504 map { qsearchs('svc_acct', { 'svcnum' => $_->svcnum } ) }
1505 grep { qsearchs('svc_acct', { 'svcnum' => $_->svcnum } ) }
1507 push @list, map { $_->email } @svc_acct;
1509 $self->invoicing_list(\@list);
1512 =item invoicing_list_addpost
1514 Adds postal invoicing to this customer. If this customer is already configured
1515 to receive postal invoices, does nothing.
1519 sub invoicing_list_addpost {
1521 return if grep { $_ eq 'POST' } $self->invoicing_list;
1522 my @invoicing_list = $self->invoicing_list;
1523 push @invoicing_list, 'POST';
1524 $self->invoicing_list(\@invoicing_list);
1527 =item referral_cust_main [ DEPTH [ EXCLUDE_HASHREF ] ]
1529 Returns an array of customers referred by this customer (referral_custnum set
1530 to this custnum). If DEPTH is given, recurses up to the given depth, returning
1531 customers referred by customers referred by this customer and so on, inclusive.
1532 The default behavior is DEPTH 1 (no recursion).
1536 sub referral_cust_main {
1538 my $depth = @_ ? shift : 1;
1539 my $exclude = @_ ? shift : {};
1542 map { $exclude->{$_->custnum}++; $_; }
1543 grep { ! $exclude->{ $_->custnum } }
1544 qsearch( 'cust_main', { 'referral_custnum' => $self->custnum } );
1548 map { $_->referral_cust_main($depth-1, $exclude) }
1555 =item referral_cust_main_ncancelled
1557 Same as referral_cust_main, except only returns customers with uncancelled
1562 sub referral_cust_main_ncancelled {
1564 grep { scalar($_->ncancelled_pkgs) } $self->referral_cust_main;
1567 =item referral_cust_pkg [ DEPTH ]
1569 Like referral_cust_main, except returns a flat list of all unsuspended (and
1570 uncancelled) packages for each customer. The number of items in this list may
1571 be useful for comission calculations (perhaps after a C<grep { my $pkgpart = $_->pkgpart; grep { $_ == $pkgpart } @commission_worthy_pkgparts> } $cust_main-> ).
1575 sub referral_cust_pkg {
1577 my $depth = @_ ? shift : 1;
1579 map { $_->unsuspended_pkgs }
1580 grep { $_->unsuspended_pkgs }
1581 $self->referral_cust_main($depth);
1584 =item credit AMOUNT, REASON
1586 Applies a credit to this customer. If there is an error, returns the error,
1587 otherwise returns false.
1592 my( $self, $amount, $reason ) = @_;
1593 my $cust_credit = new FS::cust_credit {
1594 'custnum' => $self->custnum,
1595 'amount' => $amount,
1596 'reason' => $reason,
1598 $cust_credit->insert;
1601 =item charge AMOUNT PKG COMMENT
1603 Creates a one-time charge for this customer. If there is an error, returns
1604 the error, otherwise returns false.
1609 my ( $self, $amount, $pkg, $comment ) = @_;
1611 my $part_pkg = new FS::part_pkg ( {
1612 'pkg' => $pkg || 'One-time charge',
1613 'comment' => $comment || '$'. sprintf("%.2f".$amount),
1630 =item check_and_rebuild_fuzzyfiles
1634 sub check_and_rebuild_fuzzyfiles {
1635 my $dir = $FS::UID::conf_dir. "cache.". $FS::UID::datasrc;
1636 -e "$dir/cust_main.last" && -e "$dir/cust_main.company"
1637 or &rebuild_fuzzyfiles;
1640 =item rebuild_fuzzyfiles
1644 sub rebuild_fuzzyfiles {
1646 use Fcntl qw(:flock);
1648 my $dir = $FS::UID::conf_dir. "cache.". $FS::UID::datasrc;
1652 open(LASTLOCK,">>$dir/cust_main.last")
1653 or die "can't open $dir/cust_main.last: $!";
1654 flock(LASTLOCK,LOCK_EX)
1655 or die "can't lock $dir/cust_main.last: $!";
1657 my @all_last = map $_->getfield('last'), qsearch('cust_main', {});
1659 grep $_, map $_->getfield('ship_last'), qsearch('cust_main',{})
1660 if defined dbdef->table('cust_main')->column('ship_last');
1662 open (LASTCACHE,">$dir/cust_main.last.tmp")
1663 or die "can't open $dir/cust_main.last.tmp: $!";
1664 print LASTCACHE join("\n", @all_last), "\n";
1665 close LASTCACHE or die "can't close $dir/cust_main.last.tmp: $!";
1667 rename "$dir/cust_main.last.tmp", "$dir/cust_main.last";
1672 open(COMPANYLOCK,">>$dir/cust_main.company")
1673 or die "can't open $dir/cust_main.company: $!";
1674 flock(COMPANYLOCK,LOCK_EX)
1675 or die "can't lock $dir/cust_main.company: $!";
1677 my @all_company = grep $_ ne '', map $_->company, qsearch('cust_main',{});
1679 grep $_ ne '', map $_->ship_company, qsearch('cust_main', {})
1680 if defined dbdef->table('cust_main')->column('ship_last');
1682 open (COMPANYCACHE,">$dir/cust_main.company.tmp")
1683 or die "can't open $dir/cust_main.company.tmp: $!";
1684 print COMPANYCACHE join("\n", @all_company), "\n";
1685 close COMPANYCACHE or die "can't close $dir/cust_main.company.tmp: $!";
1687 rename "$dir/cust_main.company.tmp", "$dir/cust_main.company";
1697 my $dir = $FS::UID::conf_dir. "cache.". $FS::UID::datasrc;
1698 open(LASTCACHE,"<$dir/cust_main.last")
1699 or die "can't open $dir/cust_main.last: $!";
1700 my @array = map { chomp; $_; } <LASTCACHE>;
1710 my $dir = $FS::UID::conf_dir. "cache.". $FS::UID::datasrc;
1711 open(COMPANYCACHE,"<$dir/cust_main.company")
1712 or die "can't open $dir/cust_main.last: $!";
1713 my @array = map { chomp; $_; } <COMPANYCACHE>;
1718 =item append_fuzzyfiles LASTNAME COMPANY
1722 sub append_fuzzyfiles {
1723 my( $last, $company ) = @_;
1725 &check_and_rebuild_fuzzyfiles;
1727 use Fcntl qw(:flock);
1729 my $dir = $FS::UID::conf_dir. "cache.". $FS::UID::datasrc;
1733 open(LAST,">>$dir/cust_main.last")
1734 or die "can't open $dir/cust_main.last: $!";
1736 or die "can't lock $dir/cust_main.last: $!";
1738 print LAST "$last\n";
1741 or die "can't unlock $dir/cust_main.last: $!";
1747 open(COMPANY,">>$dir/cust_main.company")
1748 or die "can't open $dir/cust_main.company: $!";
1749 flock(COMPANY,LOCK_EX)
1750 or die "can't lock $dir/cust_main.company: $!";
1752 print COMPANY "$company\n";
1754 flock(COMPANY,LOCK_UN)
1755 or die "can't unlock $dir/cust_main.company: $!";
1769 The delete method should possibly take an FS::cust_main object reference
1770 instead of a scalar customer number.
1772 Bill and collect options should probably be passed as references instead of a
1775 There should probably be a configuration file with a list of allowed credit
1778 No multiple currency support (probably a larger project than just this module).
1782 L<FS::Record>, L<FS::cust_pkg>, L<FS::cust_bill>, L<FS::cust_credit>
1783 L<FS::agent>, L<FS::part_referral>, L<FS::cust_main_county>,
1784 L<FS::cust_main_invoice>, L<FS::UID>, schema.html from the base documentation.